From 37e2fe2b4cc70a85c9cdaccdd94d2284864290ba Mon Sep 17 00:00:00 2001 From: Kai Koehne Date: Tue, 6 Aug 2019 12:03:04 +0200 Subject: CMake: Move documentation into separate project We've now four pages, which logically belong together. So let's move them into one 'qtcmake' module. Change-Id: I3015fc0804d62bcaec2cfbb6b84c6c08fe5f43f8 Reviewed-by: Alexandru Croitor --- doc/config/qtdoc.qdocconf | 6 +- doc/src/cmake/cmake-manual.qdoc | 225 ++++++++++++++++++++++++++++ doc/src/cmake/cmake.pro | 9 ++ doc/src/cmake/qtcmake.qdocconf | 39 +++++ doc/src/cmake/snippets/cmake/examples.cmake | 48 ++++++ doc/src/development/cmake-manual.qdoc | 225 ---------------------------- doc/src/snippets/cmake/examples.cmake | 48 ------ qtdoc.pro | 8 +- 8 files changed, 332 insertions(+), 276 deletions(-) create mode 100644 doc/src/cmake/cmake-manual.qdoc create mode 100644 doc/src/cmake/cmake.pro create mode 100644 doc/src/cmake/qtcmake.qdocconf create mode 100644 doc/src/cmake/snippets/cmake/examples.cmake delete mode 100644 doc/src/development/cmake-manual.qdoc delete mode 100644 doc/src/snippets/cmake/examples.cmake diff --git a/doc/config/qtdoc.qdocconf b/doc/config/qtdoc.qdocconf index 4883371a6..584b95ee3 100644 --- a/doc/config/qtdoc.qdocconf +++ b/doc/config/qtdoc.qdocconf @@ -11,6 +11,7 @@ moduleheader = depends += \ activeqt \ + qtcmake \ qdoc \ qmake \ qtandroidextras \ @@ -85,9 +86,10 @@ exampledirs += \ ../snippets \ ../../examples -# Don't parse files in snippets directory +# Don't parse files in snippets and cmake directories excludedirs += \ - ../src/snippets + ../src/snippets \ + ../src/cmake examplesinstallpath = diff --git a/doc/src/cmake/cmake-manual.qdoc b/doc/src/cmake/cmake-manual.qdoc new file mode 100644 index 000000000..ebd18593a --- /dev/null +++ b/doc/src/cmake/cmake-manual.qdoc @@ -0,0 +1,225 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Stephen Kelly +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page cmake-manual.html + \target CMake Manual + \title Build with CMake + \brief Describes how to use CMake in your development projects. + \nextpage Get started with CMake + + \c{CMake} is a tool to simplify the build process for development projects across different + platforms. \c CMake automatically generates build systems, such as Makefiles and Visual Studio + project files. + + \c{CMake} is a 3rd party tool with its own \l{CMake Documentation}{documentation}. This topic + describes how to use \c{CMake} 3.1.0 with Qt 5. + + + \section1 Table of Contents + + \list + \li \l{Get started with CMake} + \list + \li \l{Build a GUI executable} + \li \l{Imported targets} + \endlist + \li \l{CMake Variable Reference} + \list + \li \l{Module variables} + \li \l{Installation variables} + \endlist + \li \l{CMake Command Reference} + \list + \li \l{Qt5::Core} + \li \l{Qt5::Widgets} + \li \l{Qt5::DBus} + \li \l{Qt5::LinguistTools} + \endlist + \endlist +*/ + +/*! + \page cmake-get-started.html + \title Get started with CMake + \previouspage Build with CMake + \nextpage CMake Variable Reference + + Start with \c{find_package} to locate the libraries and header files shipped with Qt. Then, you + can use these libraries and header files with the \c{target_link_libraries} command to build + Qt-based libraries and applications. This command automatically adds the appropriate include + directories, compile definitions, the position-independent-code flag, and links to the + \c qtmain.lib library on Windows, for example. + + \section2 Build a GUI executable + + To build a helloworld GUI executable, you need the following: + + \snippet snippets/cmake/examples.cmake 0 + + For \c{find_package} to be successful, \c CMake must find the Qt installation in one of the + following ways: + \list 1 + \li Set your \c CMAKE_PREFIX_PATH environment variable to the Qt 5 installation prefix. + This is the recommended way. + \li Set the \c{Qt5_DIR} in the \c CMake cache to the location of the \c{Qt5Config.cmake} + file. + \endlist + + The \c CMAKE_AUTOMOC setting runs moc automatically when required. For more details, see + \l{CMake AUTOMOC documentation}. + + \section2 Imported targets + + Imported targets are created for each Qt module. In \c{CMake}, commands such as + \c{target_link_libraries} use imported target names instead of variables like + \c{Qt5_LIBRARIES}. The actual path to the library can be obtained using the + \l{CMake LOCATION Documentation}{LOCATION property}, as follows: + + \snippet snippets/cmake/examples.cmake 1 + + However, you rarely need the full location to the library as most \c{CMake} APIs can locate + imported targets and use them automatically, instead of the full path. For this purpose, each + module in Qt 5 has a library target with the \b{Qt5::} naming convention. + + Imported targets are created with the same configurations as when Qt was configured. That is: + \list + \li If Qt was configured with the \c -debug switch, an imported target with the DEBUG + configuration is created. + \li If Qt was configured with the \c -release switch, an imported target with the RELEASE + configuration is created. + \li If Qt was configured with the \c -debug-and-release switch, which is the default on + Windows, then imported targets are created with both RELEASE and DEBUG configurations. + \endlist + + If your project has custom \c{CMake} build configurations, you have to map your custom + configuration to either the debug or the release Qt configuration. + + \snippet snippets/cmake/examples.cmake 2 + + In \c{CMake}, plugins are also available as \c IMPORTED targets. The \l{Qt Network}, \l{Qt SQL}, + \l{Qt GUI}, and \l{Qt Widgets} modules have plugins associated. They provide a list of plugins + in the \c{Qt5}\e{}\c{_PLUGINS} variable. + + \snippet snippets/cmake/examples.cmake 5 + +*/ + +/*! + \page cmake-variable-reference.html + \title CMake Variable Reference + \brief Provides a complete reference for CMake variables implemented in Qt. + \contentspage Build with CMake + \nextpage CMake Command Reference + \previouspage Build with CMake + + \section1 Module variables + + When you use \c{find_package}, the resulting imported targets are created for use with + \c{target_link_libraries}. Some variables are populated with information required to configure + the build. For each module, the name of its imported target matches the name of the module with + a "Qt5::" prefix, such as "Qt5::Widgets". All of the package-specific variables have a + consistent name with its package name as prefix. + + For example, \c{find_package(Qt5 COMPONENTS Widgets)}, when successful, makes the following + variables available: + + \table + \header + \li Variable + \li Description + \row + \li \c Qt5Widgets_VERSION + \li A string that describes the module's version. + \row + \li \c Qt5Widgets_LIBRARIES + \li A list of libraries for use with the \c target_link_libraries command. + \row + \li \c Qt5Widgets_INCLUDE_DIRS + \li A list of directories for use with the \c include_directories command. + \row + \li \c Qt5Widgets_DEFINITIONS + \li A list of definitions for use with the \c add_definitions command. + \row + \li \c Qt5Widgets_COMPILE_DEFINITIONS + \li A list of definitions for use with the \c COMPILE_DEFINITIONS target property. + \row + \li \c Qt5Widgets_FOUND + \li A boolean that describes whether the module was found successfully. + \row + \li \c Qt5Widgets_EXECUTABLE_COMPILE_FLAGS + \li A string of flags to use when building executables. + \endtable + + For all packages found with \c{find_package}, equivalents of these variables are available; + they are case-sensitive. + + \section1 Installation variables + + Additionally, there are also variables that don't relate to a particular package, but to the + Qt installation itself. + + \table + \header + \li Variable + \li Description + \row + \li \c QT_VISIBILITY_AVAILABLE + \li On Unix, a boolean that describes whether Qt libraries and plugins were compiled + with \c{-fvisibility=hidden}. This means that only selected symbols are exported. + \row + \li \c QT_LIBINFIX + \li A string that holds the infix used in library names, when Qt is configured with + \c{-libinfix}. + \endtable + +*/ + +/*! + \page cmake-command-reference.html + \title CMake Command Reference + \brief Provides a complete reference for CMake commands implemented in Qt. + \contentspage Build with CMake + \previouspage CMake Variable Reference + + \section2 Qt5::Core + + \annotatedlist cmake-macros-qtcore + + \section2 Qt5::Widgets + + \annotatedlist cmake-macros-qtwidgets + + \section2 Qt5::DBus + + \annotatedlist cmake-commands-qtdbus + + \section2 Qt5::LinguistTools + + \annotatedlist cmake-macros-qtlinguisttools +*/ + diff --git a/doc/src/cmake/cmake.pro b/doc/src/cmake/cmake.pro new file mode 100644 index 000000000..3fd95bd29 --- /dev/null +++ b/doc/src/cmake/cmake.pro @@ -0,0 +1,9 @@ +TEMPLATE = aux + +QMAKE_DOCS = $$PWD/qtcmake.qdocconf + +QTDIR = $$[QT_HOST_PREFIX] +exists($$QTDIR/.qmake.cache): \ + QMAKE_DOCS_OUTPUTDIR = $$QTDIR/doc/cmake +else: \ + QMAKE_DOCS_OUTPUTDIR = $$OUT_PWD/cmake diff --git a/doc/src/cmake/qtcmake.qdocconf b/doc/src/cmake/qtcmake.qdocconf new file mode 100644 index 000000000..a2b36ba1c --- /dev/null +++ b/doc/src/cmake/qtcmake.qdocconf @@ -0,0 +1,39 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) +include($QT_INSTALL_DOCS/global/externalsites.qdocconf) + +project = QtCMake +description = Using Qt with CMake +version = $QT_VERSION + +qhp.projects = qtcmake + +qhp.qtcmake.file = qtcmake.qhp +qhp.qtcmake.namespace = org.qt-project.qtcmake.$QT_VERSION_TAG +qhp.qtcmake.virtualFolder = qtcmake +qhp.qtcmake.indexTitle = Using Qt with CMake +qhp.qtcmake.filterAttributes = qt $QT_VERSION tools cmake +qhp.qtcmake.customFilters.qtcmake.name = Build with CMake +qhp.qtcmake.customFilters.qtcmake.filterAttributes = qt tools cmake +qhp.qtcmake.subprojects = manual +qhp.qtcmake.subprojects.manual.title = Manual +qhp.qtcmake.subprojects.manual.indexTitle = Build with CMake +qhp.qtcmake.subprojects.manual.selectors = fake:page + +sources = cmake-manual.qdoc + +exampledirs = . + +# Instruct Clang not to look for a module header +moduleheader = + +depends += \ + qtdoc \ + qtcore \ + qtnetwork \ + qtsql \ + qtgui \ + qtwidgets \ + qtdbus \ + qtlinguist + +navigation.landingpage = "Build with CMake" diff --git a/doc/src/cmake/snippets/cmake/examples.cmake b/doc/src/cmake/snippets/cmake/examples.cmake new file mode 100644 index 000000000..264f3c05d --- /dev/null +++ b/doc/src/cmake/snippets/cmake/examples.cmake @@ -0,0 +1,48 @@ +#! [0] +cmake_minimum_required(VERSION 3.1.0) + +project(helloworld) + +set(CMAKE_AUTOMOC ON) +set(CMAKE_AUTORCC ON) +set(CMAKE_AUTOUIC ON) + +if(CMAKE_VERSION VERSION_LESS "3.7.0") + set(CMAKE_INCLUDE_CURRENT_DIR ON) +endif() + +find_package(Qt5 COMPONENTS Widgets REQUIRED) + +add_executable(helloworld + mainwindow.ui + mainwindow.cpp + main.cpp + resources.qrc +) + +target_link_libraries(helloworld Qt5::Widgets) +#! [0] + +#! [1] +find_package(Qt5 COMPONENTS Core REQUIRED) + +get_target_property(QtCore_location Qt5::Core LOCATION) +#! [1] + +#! [2] +find_package(Qt5 COMPONENTS Core REQUIRED) + +set(CMAKE_CXX_FLAGS_COVERAGE "${CMAKE_CXX_FLAGS_RELEASE} -fprofile-arcs -ftest-coverage") + +# set up a mapping so that the Release configuration for the Qt imported target is +# used in the COVERAGE CMake configuration. +set_target_properties(Qt5::Core PROPERTIES MAP_IMPORTED_CONFIG_COVERAGE "RELEASE") +#! [2] + +#! [5] +foreach(plugin ${Qt5Network_PLUGINS}) + get_target_property(_loc ${plugin} LOCATION) + message("Plugin ${plugin} is at location ${_loc}") +endforeach() +#! [5] + diff --git a/doc/src/development/cmake-manual.qdoc b/doc/src/development/cmake-manual.qdoc deleted file mode 100644 index ebd18593a..000000000 --- a/doc/src/development/cmake-manual.qdoc +++ /dev/null @@ -1,225 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Stephen Kelly -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page cmake-manual.html - \target CMake Manual - \title Build with CMake - \brief Describes how to use CMake in your development projects. - \nextpage Get started with CMake - - \c{CMake} is a tool to simplify the build process for development projects across different - platforms. \c CMake automatically generates build systems, such as Makefiles and Visual Studio - project files. - - \c{CMake} is a 3rd party tool with its own \l{CMake Documentation}{documentation}. This topic - describes how to use \c{CMake} 3.1.0 with Qt 5. - - - \section1 Table of Contents - - \list - \li \l{Get started with CMake} - \list - \li \l{Build a GUI executable} - \li \l{Imported targets} - \endlist - \li \l{CMake Variable Reference} - \list - \li \l{Module variables} - \li \l{Installation variables} - \endlist - \li \l{CMake Command Reference} - \list - \li \l{Qt5::Core} - \li \l{Qt5::Widgets} - \li \l{Qt5::DBus} - \li \l{Qt5::LinguistTools} - \endlist - \endlist -*/ - -/*! - \page cmake-get-started.html - \title Get started with CMake - \previouspage Build with CMake - \nextpage CMake Variable Reference - - Start with \c{find_package} to locate the libraries and header files shipped with Qt. Then, you - can use these libraries and header files with the \c{target_link_libraries} command to build - Qt-based libraries and applications. This command automatically adds the appropriate include - directories, compile definitions, the position-independent-code flag, and links to the - \c qtmain.lib library on Windows, for example. - - \section2 Build a GUI executable - - To build a helloworld GUI executable, you need the following: - - \snippet snippets/cmake/examples.cmake 0 - - For \c{find_package} to be successful, \c CMake must find the Qt installation in one of the - following ways: - \list 1 - \li Set your \c CMAKE_PREFIX_PATH environment variable to the Qt 5 installation prefix. - This is the recommended way. - \li Set the \c{Qt5_DIR} in the \c CMake cache to the location of the \c{Qt5Config.cmake} - file. - \endlist - - The \c CMAKE_AUTOMOC setting runs moc automatically when required. For more details, see - \l{CMake AUTOMOC documentation}. - - \section2 Imported targets - - Imported targets are created for each Qt module. In \c{CMake}, commands such as - \c{target_link_libraries} use imported target names instead of variables like - \c{Qt5_LIBRARIES}. The actual path to the library can be obtained using the - \l{CMake LOCATION Documentation}{LOCATION property}, as follows: - - \snippet snippets/cmake/examples.cmake 1 - - However, you rarely need the full location to the library as most \c{CMake} APIs can locate - imported targets and use them automatically, instead of the full path. For this purpose, each - module in Qt 5 has a library target with the \b{Qt5::} naming convention. - - Imported targets are created with the same configurations as when Qt was configured. That is: - \list - \li If Qt was configured with the \c -debug switch, an imported target with the DEBUG - configuration is created. - \li If Qt was configured with the \c -release switch, an imported target with the RELEASE - configuration is created. - \li If Qt was configured with the \c -debug-and-release switch, which is the default on - Windows, then imported targets are created with both RELEASE and DEBUG configurations. - \endlist - - If your project has custom \c{CMake} build configurations, you have to map your custom - configuration to either the debug or the release Qt configuration. - - \snippet snippets/cmake/examples.cmake 2 - - In \c{CMake}, plugins are also available as \c IMPORTED targets. The \l{Qt Network}, \l{Qt SQL}, - \l{Qt GUI}, and \l{Qt Widgets} modules have plugins associated. They provide a list of plugins - in the \c{Qt5}\e{}\c{_PLUGINS} variable. - - \snippet snippets/cmake/examples.cmake 5 - -*/ - -/*! - \page cmake-variable-reference.html - \title CMake Variable Reference - \brief Provides a complete reference for CMake variables implemented in Qt. - \contentspage Build with CMake - \nextpage CMake Command Reference - \previouspage Build with CMake - - \section1 Module variables - - When you use \c{find_package}, the resulting imported targets are created for use with - \c{target_link_libraries}. Some variables are populated with information required to configure - the build. For each module, the name of its imported target matches the name of the module with - a "Qt5::" prefix, such as "Qt5::Widgets". All of the package-specific variables have a - consistent name with its package name as prefix. - - For example, \c{find_package(Qt5 COMPONENTS Widgets)}, when successful, makes the following - variables available: - - \table - \header - \li Variable - \li Description - \row - \li \c Qt5Widgets_VERSION - \li A string that describes the module's version. - \row - \li \c Qt5Widgets_LIBRARIES - \li A list of libraries for use with the \c target_link_libraries command. - \row - \li \c Qt5Widgets_INCLUDE_DIRS - \li A list of directories for use with the \c include_directories command. - \row - \li \c Qt5Widgets_DEFINITIONS - \li A list of definitions for use with the \c add_definitions command. - \row - \li \c Qt5Widgets_COMPILE_DEFINITIONS - \li A list of definitions for use with the \c COMPILE_DEFINITIONS target property. - \row - \li \c Qt5Widgets_FOUND - \li A boolean that describes whether the module was found successfully. - \row - \li \c Qt5Widgets_EXECUTABLE_COMPILE_FLAGS - \li A string of flags to use when building executables. - \endtable - - For all packages found with \c{find_package}, equivalents of these variables are available; - they are case-sensitive. - - \section1 Installation variables - - Additionally, there are also variables that don't relate to a particular package, but to the - Qt installation itself. - - \table - \header - \li Variable - \li Description - \row - \li \c QT_VISIBILITY_AVAILABLE - \li On Unix, a boolean that describes whether Qt libraries and plugins were compiled - with \c{-fvisibility=hidden}. This means that only selected symbols are exported. - \row - \li \c QT_LIBINFIX - \li A string that holds the infix used in library names, when Qt is configured with - \c{-libinfix}. - \endtable - -*/ - -/*! - \page cmake-command-reference.html - \title CMake Command Reference - \brief Provides a complete reference for CMake commands implemented in Qt. - \contentspage Build with CMake - \previouspage CMake Variable Reference - - \section2 Qt5::Core - - \annotatedlist cmake-macros-qtcore - - \section2 Qt5::Widgets - - \annotatedlist cmake-macros-qtwidgets - - \section2 Qt5::DBus - - \annotatedlist cmake-commands-qtdbus - - \section2 Qt5::LinguistTools - - \annotatedlist cmake-macros-qtlinguisttools -*/ - diff --git a/doc/src/snippets/cmake/examples.cmake b/doc/src/snippets/cmake/examples.cmake deleted file mode 100644 index 264f3c05d..000000000 --- a/doc/src/snippets/cmake/examples.cmake +++ /dev/null @@ -1,48 +0,0 @@ -#! [0] -cmake_minimum_required(VERSION 3.1.0) - -project(helloworld) - -set(CMAKE_AUTOMOC ON) -set(CMAKE_AUTORCC ON) -set(CMAKE_AUTOUIC ON) - -if(CMAKE_VERSION VERSION_LESS "3.7.0") - set(CMAKE_INCLUDE_CURRENT_DIR ON) -endif() - -find_package(Qt5 COMPONENTS Widgets REQUIRED) - -add_executable(helloworld - mainwindow.ui - mainwindow.cpp - main.cpp - resources.qrc -) - -target_link_libraries(helloworld Qt5::Widgets) -#! [0] - -#! [1] -find_package(Qt5 COMPONENTS Core REQUIRED) - -get_target_property(QtCore_location Qt5::Core LOCATION) -#! [1] - -#! [2] -find_package(Qt5 COMPONENTS Core REQUIRED) - -set(CMAKE_CXX_FLAGS_COVERAGE "${CMAKE_CXX_FLAGS_RELEASE} -fprofile-arcs -ftest-coverage") - -# set up a mapping so that the Release configuration for the Qt imported target is -# used in the COVERAGE CMake configuration. -set_target_properties(Qt5::Core PROPERTIES MAP_IMPORTED_CONFIG_COVERAGE "RELEASE") -#! [2] - -#! [5] -foreach(plugin ${Qt5Network_PLUGINS}) - get_target_property(_loc ${plugin} LOCATION) - message("Plugin ${plugin} is at location ${_loc}") -endforeach() -#! [5] - diff --git a/qtdoc.pro b/qtdoc.pro index 14c8c21de..bb9dc7024 100644 --- a/qtdoc.pro +++ b/qtdoc.pro @@ -1,3 +1,9 @@ load(qt_parts) -SUBDIRS += doc +cmake.file = doc/src/cmake/cmake.pro + +doc.file = doc/doc.pro +doc.depends = cmake + +SUBDIRS += doc cmake + -- cgit v1.2.3