From 870c36c2c56e2f063d29af7044a79135ba6743d7 Mon Sep 17 00:00:00 2001
From: Stephen Kelly <stephen.kelly@kdab.com>
Date: Tue, 2 Apr 2013 11:02:51 +0200
Subject: [PATCH] Update the CMake documentation with 2.8.11 specific
information.
Change-Id: I42387a178097598a52b4cd3dbdcd8b093147a740
Reviewed-by: Stephen Kelly <stephen.kelly@kdab.com>
---
doc/src/development/cmake-manual.qdoc | 60 +++++++++++++++++----------
doc/src/modules.qdoc | 2 +-
doc/src/qtmodules.qdoc | 2 +-
doc/src/snippets/cmake/CMakeLists.pro | 26 ++++++------
4 files changed, 52 insertions(+), 38 deletions(-)
diff --git a/doc/src/development/cmake-manual.qdoc b/doc/src/development/cmake-manual.qdoc
index 4b879079..4624b4f2 100644
--- a/doc/src/development/cmake-manual.qdoc
+++ b/doc/src/development/cmake-manual.qdoc
@@ -33,11 +33,12 @@
\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.
+ automates the generation of buildsystems 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 manual details the specifics of how to use Qt 5 with \c{CMake}.
- The minimum version required to use Qt5 is \c{CMake} 2.8.3, but 2.8.9 is recommended.
+ The minimum version required to use Qt5 is \c{CMake} 2.8.3, but 2.8.11 is recommended.
\section1 Getting Started
@@ -45,38 +46,33 @@
and header files shipped with Qt. These libraries and header files can then be used
to build libraries and applications based on Qt.
- The recommended way to use Qt libraries and headers with \c{CMake} 2.8.9 is to use
- the \c{qt5_use_modules} macro.
+ The recommended way to use Qt libraries and headers with \c{CMake} 2.8.11 is to use
+ the \c{target_link_libraries} command. In \c{CMake} 2.8.11 and later versions, this
+ command automatically adds appropriate include directories, compile definitions, the
+ position-independent-code flag, and links to the qtmain.lib library on Windows.
- To build a helloworld executable, typical usage would be:
+ To build a helloworld GUI executable, typical usage would be:
\snippet doc/src/snippets/cmake/CMakeLists.pro 0
- Note that it is necessary to use \c{find_package} to find a Qt module before using the macro.
- See the documentation for the
- \l{CMake find_package Documentation}
- command for the full options it supports.
+ Note that setting the minimum required CMake version to 2.8.11 is required for
+ automatic linking to the qtmain.lib library on Windows.
In order for \c{find_package} to be successful, Qt 5 must be found below the CMAKE_PREFIX_PATH,
or the Qt5<Module>_DIR must be set in the \c{CMake} cache to the location of the
Qt5WidgetsConfig.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.
- The \c{qt5_use_modules} macro encapsulates all of the variable usage required to use a Qt module.
- It automatically finds the modules given to it on the command line if they have not already been found.
-
- \snippet doc/src/snippets/cmake/CMakeLists.pro 1
-
The CMAKE_AUTOMOC setting runs moc automatically when required. For more on this feature see
the \l{CMake AUTOMOC documentation}
\section2 Imported targets
- Imported targets are created for each Qt module. That means that the Qt5<Module>_LIBRARIES contains
- a name of an imported target, rather than a path to a library. 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. 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}:
- \snippet doc/src/snippets/cmake/CMakeLists.pro 2
+ \snippet doc/src/snippets/cmake/CMakeLists.pro 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.
@@ -93,6 +89,21 @@
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.
+ \snippet doc/src/snippets/cmake/CMakeLists.pro 2
+
+ \section2 Using Qt 5 with \c{CMake} older than 2.8.11
+
+ The recommended way to use Qt libraries and headers with \c{CMake} prior to 2.8.11 is to use
+ the \c{qt5_use_modules} macro.
+
+ Note that it is necessary to use \c{find_package} to find a Qt module before using the macro.
+ See the documentation for the
+ \l{CMake find_package Documentation}
+ command for the full options it supports.
+
+ The \c{qt5_use_modules} macro encapsulates all of the variable usage required to use a Qt module.
+ It automatically finds the modules given to it on the command line if they have not already been found.
+
\snippet doc/src/snippets/cmake/CMakeLists.pro 3
\section2 Using Qt 5 with \c{CMake} older than 2.8.9
@@ -112,7 +123,8 @@
If not using the \c{qt5_use_modules} macro, and if using CMake 2.8.9 or later, the
\l{CMake POSITION_INDEPENDENT_CODE Documentation}{POSITION_INDEPENDENT_CODE property} can be set on
- targets using Qt instead, or it can be set globally for all targets:
+ targets using Qt instead, or it can be set globally for all targets. Note that this is not necessary
+ with CMake 2.8.11:
\snippet doc/src/snippets/cmake/CMakeLists.pro 5
@@ -127,11 +139,13 @@
\section2 Module variables
- The result of a \c{find_package} call is that some variables will be populated with
+ 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. All of the package-specific variables have a consistent name with a prefix
- of the name of the package. For example, \c{find_package}(Qt5Widgets) will make the
- following variables available if successfully found:
+ 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}(Qt5Widgets) will make the following variables available if successfully found:
\list
\li Qt5Widgets_VERSION_STRING
diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc
index c7bfe6a6..6ac10c10 100644
--- a/doc/src/modules.qdoc
+++ b/doc/src/modules.qdoc
@@ -43,7 +43,7 @@
qtmain is a helper library that enables the developer to write a
cross-platform main() function on Windows.
- If you do not use \l qmake or other build tools such as CMake, then you
+ If you do not use \l qmake or other build tools such as \l{CMake Manual}{CMake}, then you
need to link against the \c qtmain library.
\section1 License Information
diff --git a/doc/src/qtmodules.qdoc b/doc/src/qtmodules.qdoc
index 2d648d70..51844b95 100644
--- a/doc/src/qtmodules.qdoc
+++ b/doc/src/qtmodules.qdoc
@@ -106,7 +106,7 @@
\snippet doc/src/snippets/code/doc_src_modules.pro 0
On Windows, if you do not use \l qmake
- or other build tools such as CMake, you also need to link against
+ or other build tools such as \l{CMake Manual}{CMake}, you also need to link against
the \c qtmain library.
\section1 Qt Add-Ons
diff --git a/doc/src/snippets/cmake/CMakeLists.pro b/doc/src/snippets/cmake/CMakeLists.pro
index 482f7773..834e075b 100644
--- a/doc/src/snippets/cmake/CMakeLists.pro
+++ b/doc/src/snippets/cmake/CMakeLists.pro
@@ -1,5 +1,5 @@
#! [0]
-cmake_minimum_required(VERSION 2.8.9)
+cmake_minimum_required(VERSION 2.8.11)
project(testproject)
@@ -12,34 +12,34 @@ set(CMAKE_AUTOMOC ON)
find_package(Qt5Widgets)
# Tell CMake to create the helloworld executable
-add_executable(helloworld main.cpp)
+add_executable(helloworld WIN32 main.cpp)
# Use the Widgets module from Qt 5.
-qt5_use_modules(helloworld Widgets)
+target_link_libraries(helloworld Qt5::Widgets)
#! [0]
#! [1]
find_package(Qt5Core)
-# Find the Widgets Sql and Network modules, and
-# use them in helloworld.
-qt5_use_modules(helloworld Widgets Sql Network)
+get_target_property(QtCore_location Qt5::Core LOCATION)
#! [1]
#! [2]
find_package(Qt5Core)
-get_target_property(QtCore_location Qt5::Core LOCATION)
-#! [2]
-
-#! [3]
-find_package(Qt5Core)
-
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]
+
+#! [3]
+find_package(Qt5Widgets)
+
+add_executable(helloworld WIN32 main.cpp)
+
+qt5_use_modules(helloworld Widgets)
#! [3]
#! [4]
@@ -69,7 +69,7 @@ qt5_generate_moc(main.cpp main.moc)
add_executable(helloworld main.cpp main.moc)
#Link the helloworld executable to the Qt 5 widgets library.
-target_link_libraries(${Qt5Widgets_LIBRARIES})
+target_link_libraries(helloworld Qt5::Widgets)
#! [4]
#! [5]
--
GitLab