Update the CMake documentation with 2.8.11 specific information.

Change-Id: I42387a178097598a52b4cd3dbdcd8b093147a740
Reviewed-by: Stephen Kelly <stephen.kelly@kdab.com>

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]