diff options
author | Kavindra Palaraja <kpalaraja@luxoft.com> | 2019-07-28 18:12:42 +0200 |
---|---|---|
committer | Kavindra Palaraja <kpalaraja@luxoft.com> | 2019-08-02 09:38:19 +0200 |
commit | 428859133de4074deedd5a69c82560da446c2799 (patch) | |
tree | 2c030fd836939da516ee8fed4c1a2dfd861d76c8 | |
parent | d6a01d04f77f15e2847875b37412eb2814d723f9 (diff) | |
download | qtdoc-428859133de4074deedd5a69c82560da446c2799.tar.gz |
Doc: Clean up of CMake Manual
* Use active voice instead of passive voice
* Separate the Variable Reference and Macro Reference pages so that
future content can be added in a more clean and concise way
* Use more tables to improve readability
* Shorten the section titles to be more crisp and clear
Change-Id: Ic617974fec828940d08ac7e31b5a4653601fafcb
Reviewed-by: Kai Koehne <kai.koehne@qt.io>
-rw-r--r-- | doc/src/development/cmake-manual.qdoc | 293 |
1 files changed, 111 insertions, 182 deletions
diff --git a/doc/src/development/cmake-manual.qdoc b/doc/src/development/cmake-manual.qdoc index 6075c31c..173ed050 100644 --- a/doc/src/development/cmake-manual.qdoc +++ b/doc/src/development/cmake-manual.qdoc @@ -25,228 +25,157 @@ ** ****************************************************************************/ - - /*! \page cmake-manual.html \target CMake Manual - \title Building with CMake + \title Build with CMake + \brief Describes how to use CMake in your development projects. + \nextpage CMake Variable Reference - \c {CMake} is a tool that helps simplify the build process for - development projects across different platforms. \c{CMake} - automates the generation of buildsystems such as Makefiles and Visual Studio project - files. + \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}. - The rest of this topic details the specifics of how to use Qt 5 with \c{CMake}. - The minimum version required to use Qt5 is \c{CMake} 3.1.0. + \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 Getting Started + \section1 Get started - The first requirement when using \c{CMake} is to use \c{find_package} to locate the libraries - and header files shipped with Qt. These libraries and header files can then be used - to build libraries and applications based on Qt. + 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. - The recommended way to use Qt libraries and headers with \c{CMake} is to use - the \c{target_link_libraries} command. This - command automatically adds appropriate include directories, compile definitions, the - position-independent-code flag, and links to the qtmain.lib library on Windows. + \section2 Build a GUI executable - To build a helloworld GUI executable, typical usage would be: + To build a helloworld GUI executable, you need the following: \snippet snippets/cmake/examples.cmake 0 - In order for \c{find_package} to be successful, Qt 5 must be found below the CMAKE_PREFIX_PATH, - or the \c{Qt5_DIR} must be set in the \c{CMake} cache to the location of the - \c{Qt5Config.cmake} file. The easiest way to use \c{CMake} is to set the CMAKE_PREFIX_PATH - environment variable to the install prefix of Qt 5. + 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 CMAKE_AUTOMOC setting runs moc automatically when required. For more on this feature see - the \l{CMake AUTOMOC documentation} + 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. Imported target names should be preferred instead of - using a variable like Qt5<Module>_LIBRARIES in CMake commands such as \c{target_link_libraries}. - The actual path to the library can be obtained using the \l{CMake LOCATION Documentation}{LOCATION property}: + 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<Module>_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 - Note however that it is rare to require the full location to the library in \c{CMake} code. Most - \c{CMake} APIs are aware of imported targets and can automatically use them instead of the full path. - - Each module in Qt 5 has a library target with the naming convention Qt5::<Module> which can be used for - this purpose. + 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::<Module>} naming convention. - Imported targets are created with the configurations Qt was configured with. That is, if Qt was - configured with the -debug switch, an imported target with the configuration DEBUG will be created. If - Qt was configured with the -release switch an imported target with the configuration RELEASE will be - created. If Qt was configured with the -debug-and-release switch (the default on windows), then - imported targets will be created with both RELEASE and DEBUG configurations. + 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 CMake build configurations, it may be necessary to set a mapping from your - custom configuration to either the debug or release Qt configuration. + 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 - Plugins are also available as \c IMPORTED targets in CMake. 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{<Module>}\c{_PLUGINS} variable. + 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{<Module>}\c{_PLUGINS} variable. \snippet snippets/cmake/examples.cmake 5 - \section1 Variable Reference - - \section2 Module variables - - The result of a \c{find_package} call is that imported targets will be created for - use with \c{target_link_libraries}, some variables will be populated with - information required to configure the build, and macros will be made available - for use. The name of the imported target for each module matches the name of the module with a - prefix of 'Qt5::', for example Qt5::Widgets. All of the package-specific variables have a - consistent name with a prefix of the name of the package. For example, - \c{find_package(Qt5 COMPONENTS Widgets)} will make the following variables available - if successfully found: - - \list - \li Qt5Widgets_VERSION String describing the version of the module. - \li Qt5Widgets_LIBRARIES List of libraries for use with the target_link_libraries command. - \li Qt5Widgets_INCLUDE_DIRS List of directories for use with the include_directories command. - \li Qt5Widgets_DEFINITIONS List of definitions for use with add_definitions. - \li Qt5Widgets_COMPILE_DEFINITIONS List of definitions for use with the COMPILE_DEFINITIONS target property. - \li Qt5Widgets_FOUND Boolean describing whether the module was found successfully. - \li Qt5Widgets_EXECUTABLE_COMPILE_FLAGS String of flags to be used when building executables. - \endlist - - Equivalents of those variables will be available for all packages found with a \c{find_package} call. Note - that the variables are case-sensitive. - - \section2 Installation variables - - Additionally, several other variables are available which do not relate to a particular package, but to the - Qt installation itself. +*/ - \list - \li QT_VISIBILITY_AVAILABLE Boolean describing whether Qt was built with hidden visibility. - \li QT_LIBINFIX String containing the infix used in library names. - \endlist +/*! + \page cmake-variable-reference.html + \title CMake Variable Reference + \brief Provides a complete reference for CMake variables implemented in Qt. + \nextpage CMake Command Reference + \previouspage CMake Manual - \section1 Macro Reference + \section1 Module variables - \section2 Qt5Core macros + 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. - Macros available when Qt5Core is found. + For example, \c{find_package(Qt5 COMPONENTS Widgets)}, when successful, makes the following + variables available: \table - \header \li Macro \li Description - \row \li qt5_wrap_cpp(outfiles inputfile ... OPTIONS ...) - \li Create moc code from a list of files containing Qt class with - the Q_OBJECT declaration. Per-directory preprocessor definitions - are also added. Options may be given to moc, such as those found - when executing "moc -help". - \row \li qt5_add_resources(outfiles inputfile ... OPTIONS ...) - \li Create code from a list of Qt resource files. - Options may be given to rcc, such as those found - when executing "rcc -help". - \row \li qt5_add_binary_resources(target inputfile ... OPTIONS ... DESTINATION ...) - \li Create an RCC file from a list of Qt resource files. - Options may be given to rcc, such as those found - when executing "rcc -help". - A destination may be given to use a different filename - or path for the RCC file. - \row \li qt5_generate_moc(inputfile outputfile ) - \li Creates a rule to run moc on infile and create outfile. - Use this if for some reason QT5_WRAP_CPP() isn't appropriate, e.g. - because you need a custom filename for the moc file or something similar. - \row \li qt5_use_modules(target [LINK_PUBLIC|LINK_PRIVATE] module ... ) - \li Indicates that the target uses the named Qt 5 modules. The target - will be linked to the specified modules, use the include directories - installed by those modules, use the COMPILE_DEFINITIONS set by those - modules, and use the COMPILE_FLAGS set by the modules. The LINK_PRIVATE - or LINK_PUBLIC specifiers can optionally be specified. If LINK_PRIVATE is specified - then the modules are not made part of the link interface of the target. - See the documentation for - \l{CMake target_link_libraries Documentation}{target_link_libraries} - for more information. - - Note that this macro is only available if using \c{CMake} 2.8.9 or later. - This macro is obsolete. Use target_link_libraries with IMPORTED targets instead. + \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 - \section2 Qt5Widgets macros - - Macros available when Qt5Widgets is found. + For all packages found with \c{find_package}, equivalents of these variables are available; + they are case-sensitive. - \table - \header \li Macro \li Description - \row \li qt5_wrap_ui(outfiles inputfile ... OPTIONS ...) - \li Create code from a list of Qt designer ui files. - Options may be given to uic, such as those found - when executing "uic -help" - \endtable + \section1 Installation variables - \section2 Qt5DBus macros - - Macros available when Qt5DBus is found. + Additionally, there are also variables that don't relate to a particular package, but to the + Qt installation itself. - \table - \header \li Macro \li Description - \row \li qt5_add_dbus_interface(outfiles interface basename) - \li Create the interface header and implementation files with the - given basename from the given interface xml file and add it to - the list of sources - - \row \li qt5_add_dbus_interfaces(outfiles inputfile ... ) - \li Create the interface header and implementation files - for all listed interface xml files - the name will be automatically determined from the name of the xml file - - \row \li qt5_add_dbus_adaptor(outfiles xmlfile parentheader parentclassname [basename] [classname]) - \li Create a dbus adaptor (header and implementation file) from the xml file - describing the interface, and add it to the list of sources. The adaptor - forwards the calls to a parent class, defined in parentheader and named - parentclassname. The name of the generated files will be - <basename>adaptor.{cpp,h} where basename defaults to the basename of the xml file. - If <classname> is provided, then it will be used as the classname of the - adaptor itself. - - \row \li qt5_generate_dbus_interface( header [interfacename] OPTIONS ...) - \li Generate the xml interface file from the given header. - If the optional argument interfacename is omitted, the name of the - interface file is constructed from the basename of the header with - the suffix .xml appended. - Options may be given to qdbuscpp2xml, such as those found when executing "qdbuscpp2xml --help" + \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 - \section2 Qt5LinguistTools macros - - Macros available when Qt5LinguistTools is found. - - \table - \header \li Macro \li Description - \row \li qt5_create_translation( qm_files directories ... sources ... - ts_files ... OPTIONS ...) - \li Out: qm_files - In: Directories sources ts_files - Options: flags to pass to lupdate, such as -extensions to specify - Extensions for a directory scan. - Generates commands to create .ts (via lupdate) and .qm - (via lrelease) - files from directories and/or sources. The ts files are - created and/or updated in the source tree (unless given with full paths). - The qm files are generated in the build tree. - Updating the translations can be done by adding the qm_files - to the source list of your library/executable, so they are - always updated, or by adding a custom target to control when - they get updated/generated. - - \row \li qt5_add_translation( qm_files ts_files ... ) - \li Out: qm_files - In: ts_files - Generates commands to create .qm from .ts - files. The generated - filenames can be found in qm_files. The ts_files - must exist and are not updated in any way. - \endtable +*/ +/*! + \page cmake-command-reference.html + \title CMake Command Reference + \brief Provides a complete reference for CMake commands implemented in Qt. + \contentspage CMake Manual + \previouspage CMake Variable Reference */ + |