Merge 5.13 into 5.13.1

Change-Id: I8bbadbe6d5bb1e71aa2a10cc4f6d2ba3a4347cde

2 files changed, 180 insertions, 194 deletions

diff --git a/doc/src/development/cmake-manual.qdoc b/doc/src/development/cmake-manual.qdoc
index 6075c31c..0d957b95 100644
--- a/doc/src/development/cmake-manual.qdoc
+++ b/doc/src/development/cmake-manual.qdoc
@@ -25,228 +25,173 @@
 **
 ****************************************************************************/
 
-
-
 /*!
     \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
+/*!
+    \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
 
-    Equivalents of those variables will be available for all packages found with a \c{find_package} call. Note
-    that the variables are case-sensitive.
+    \section1 Module variables
 
-    \section2 Installation 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.
 
-    Additionally, several other variables are available which do not relate to a particular package, but to the
-    Qt installation itself.
+    For example, \c{find_package(Qt5 COMPONENTS Widgets)}, when successful, makes the following
+    variables available:
 
-    \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
+    \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
 
-    \section1 Macro Reference
+    For all packages found with \c{find_package}, equivalents of these variables are available;
+    they are case-sensitive.
 
-    \section2 Qt5Core macros
+    \section1 Installation variables
 
-    Macros available when Qt5Core 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_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.
+   \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 Qt5Widgets macros
-
-    Macros available when Qt5Widgets is found.
+*/
 
-    \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
+/*!
+    \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 Qt5DBus macros
+    \section2 Qt5::Core
 
-    Macros available when Qt5DBus is found.
+    \annotatedlist cmake-macros-qtcore
 
-    \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"
-    \endtable
+    \section2 Qt5::Widgets
 
-    \section2 Qt5LinguistTools macros
+    \annotatedlist cmake-macros-qtwidgets
 
-    Macros available when Qt5LinguistTools is found.
+    \section2 Qt5::DBus
 
-    \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
+    \annotatedlist cmake-commands-qtdbus
 
+    \section2 Qt5::LinguistTools
 
+    \annotatedlist cmake-macros-qtlinguisttools
 */
+
diff --git a/doc/src/platforms/windows.qdoc b/doc/src/platforms/windows.qdoc
index b1617848..98f480cf 100644
--- a/doc/src/platforms/windows.qdoc
+++ b/doc/src/platforms/windows.qdoc
@@ -98,6 +98,9 @@
     applications on Windows.
 
     \list
+        \li \l{OpenSSL Toolkit}: Qt can make use of OpenSSL to support Secure Socket Layer
+           (SSL) communication.
+
         \li \l{ICU}: Qt 5 can make use of the ICU library for enhanced UNICODE and Globalization
            support (see QTextCodec, QCollator::setNumericMode()).
 
@@ -115,36 +118,74 @@
     \section2 SSL
 
     Support for Secure Sockets Layer (SSL) communication is provided by the \l {OpenSSL Toolkit},
-    which must be obtained separately. Download the latest version of the toolkit.
+    which must be obtained separately. Download the latest version of the toolkit that is
+    supported by Qt.
 
+    Qt can be configured to use OpenSSL in three ways:
     \list
-        \li To have Configure pick up OpenSSL automatically, set the following variables to point
-            to where your OpenSSL includes and libraries are located:
+        \li Qt Network loads OpenSSL libraries (DDLs) when first needed, at runtime. If not found,
+            the application continues to run, but fails to handle SSL communication.
 
-            \code
-            /* Assuming your OpenSSL is installed in C:\OpenSSL */
+            All official Qt binary builds use this configuration.
+
+            The OpenSSL libraries are looked up first in the directory of the executable, then in
+            the Windows System directory (usually \c{C:\Windows\system32}), and finally in all
+            directories listed in the \c PATH environment variable.
+
+        \li Qt Network links against the OpenSSL libraries. If they cannot be found at load time,
+            the application fails to start.
+
+        \li Qt Network compiles against a static version of the OpenSSL libs, and OpenSSL becomes
+            part of the Qt5Network library.
+    \endlist
 
-            set INCLUDE=%INCLUDE%;C:\OpenSSL\include
-            set PATH=%PATH%;C:\OpenSSL\bin
-            \endcode
 
-        \li To use linked OpenSSL support, set the following:
+    If you compile Qt yourself, you can configure how Qt uses OpenSSL by setting either the
+    \c{-openssl} / \c{-openssl-runtime} or \c{-openssl-linked} configure flags.
 
-            \code
-            /* Assuming your OpenSSL is installed in C:\OpenSSL */
+    If OpenSSL is not found in the normal compiler include and library directories, you can set
+    either the \c OPENSSL_PREFIX, or \c OPENSSL_INCDIR and \c OPENSSL_LIBDIR configure arguments.
+    If \c OPENSSL_PREFIX is set, \c OPENSSL_INCDIR defaults to \c OPENSSL_PREFIX/include and
+    \c OPENSSL_LIBDIR to \c OPENSSL_PREFIX/lib.
 
-            set INCLUDE=%INCLUDE%;C:\OpenSSL\include
-            set LIB=%LIB%;C:\OpenSSL\lib
+    The actual libraries to link to can be tweaked by setting the \c OPENSSL_LIBS,
+    \c OPENSSL_LIBS_DEBUG, and \c OPENSSL_LIBS_RELEASE configure arguments.
+
+    \list
+        \li To load OpenSSL at runtime, set the \c {-openssl-runtime} configure argument. Qt will
+            try to find \c{openssl/ssl.h} and \c{openssl/opensslv.h} in the default include path of
+            the compiler. You can specify an additional include directory by setting
+            \c OPENSSL_INCDIR.
+
+            For example:
+            \badcode
+            configure -openssl-runtime OPENSSL_INCDIR="C:\Program Files\OpenSSL-Win64\include"
+            \endcode
+
+        \li To link Qt Network against OpenSSL libraries, set the \c{-openssl-linked}
+            configure argument. Use the \c{OPENSSL_PREFIX} variable to let Qt correctly locate
+            and build against your OpenSSL installation:
+
+            For example:
+            \badcode
+            configure -openssl-linked OPENSSL_PREFIX="C:\Program Files\OpenSSL-Win64"
             \endcode
 
-            Then, pass \c -openssl-linked to \c configure:
+        \li To link Qt Network against a static version of the OpenSSL libs, set the
+            \c{-openssl-linked} argument, and set \c{OPENSSL_PREFIX}, or \c{OPENSSL_INCDIR}
+            and \c{OPENSSL_LIBDIR}. In addition, you probably need to set the \c{OPENSSL_LIBS},
+            \c{OPENSSL_LIBS_DEBUG}, \c{OPENSSL_LIBS_RELEASE} configure arguments to let Qt correctly
+            link against your static build of the OpenSSL libraries.
+
+            For example:
 
-            \code
-            configure -openssl-linked
+            \badcode
+            set OPENSSL_DIR=C:\Program Files\OpenSSL-Win64
+            configure -openssl-linked OPENSSL_INCDIR="%OPENSSL_DIR%\include" OPENSSL_LIBDIR="%OPENSSL_DIR%\lib\VC\static" OPENSSL_LIBS="-lWs2_32 -lGdi32 -lAdvapi32 -lCrypt32 -lUser32" OPENSSL_LIBS_DEBUG="-llibssl64MDd -llibcrypto64MDd" OPENSSL_LIBS_RELEASE="-llibssl64MD -llibcrypto64MD"
             \endcode
     \endlist
 
-    See \l {Secure Sockets Layer (SSL) Classes} for instructions on building Qt with SSL support.
+    See \l {Secure Sockets Layer (SSL) Classes} for further instructions on Qt with SSL support.
 
     \section2 ICU