Doc: Explain how to deploy desktop projects with CMake

Pick-to: 6.5
Fixes: QTBUG-101330
Fixes: QTBUG-101334
Change-Id: I2b6c5f2f747c779cdae67a35249e1c2ae6205c41
Reviewed-by: Amir Masoud Abdol <amir.abdol@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>

3 files changed, 157 insertions, 2 deletions

diff --git a/doc/src/cmake/cmake-manual.qdoc b/doc/src/cmake/cmake-manual.qdoc
index f3ffbe76..07ea5e3e 100644
--- a/doc/src/cmake/cmake-manual.qdoc
+++ b/doc/src/cmake/cmake-manual.qdoc
@@ -40,6 +40,11 @@
             \li \l{Cross-compiling}
             \li \l{Specifying a custom toolchain file}
         \endlist
+        \li \l{Deployment}
+        \list
+            \li \l{Deploying a Qt Widgets application}
+            \li \l{Deploying a Qt Quick application}
+        \endlist
         \li \l{Imported targets}
         \li \l{Qt CMake policies}
         \li \l{Qt 5 and Qt 6 compatibility}
@@ -648,7 +653,7 @@
     \page cmake-build-on-cmdline.html
     \title Building projects on the command line
     \previouspage Getting started with CMake
-    \nextpage Imported targets
+    \nextpage Deployment
 
     This page explains how to configure and build existing projects. If you want
     to know how to create a Qt-based CMake project, see the documentation on
@@ -761,11 +766,92 @@
 */
 
 /*!
+    \page cmake-deployment.html
+    \title Deployment
+    \brief Provides an overview of how to deploy Qt projects.
+    \nextpage Imported targets
+    \previouspage Building projects on the command line
+
+    Use Qt's CMake deployment API to deploy Qt projects for desktop platforms.
+    The API supports various target platforms, which you can find in the
+    \l{qt_generate_deploy_app_script}{qt_generate_deploy_app_script()}
+    documentation.
+
+    The deployment process depends on whether your project is a Qt Widgets
+    application or a Qt Quick application. Even if you are planning to deploy
+    only Qt Quick applications, read about deploying Qt Widgets applications
+    first to understand the process.
+
+    \section1 Deploying a Qt Widgets application
+
+    This section shows how to deploy a Qt Widgets application with an example of
+    a simple C++ Qt project.
+
+    \snippet snippets/cmake/deploy_non_qml.cmake basic setup
+
+    You need to instruct CMake to install the application target into the
+    appropriate location. On macOS, bundles are installed directly into
+    \c{${CMAKE_INSTALL_PREFIX}}, on other platforms into the \c{"bin"} directory
+    underneath.
+
+    \snippet snippets/cmake/deploy_non_qml.cmake installation
+
+    Note that \l{qt_standard_project_setup}{qt_standard_project_setup()} pulls
+    in CMake's \c{GNUInstallDirs.cmake}. This is what defines the
+    \c{CMAKE_INSTALL_BINDIR} variable.
+
+    You also need to generate a \e{deployment script}. A deployment script is
+    CMake code that is executed at installation time. This code takes care of
+    collecting runtime dependencies and copies them to the installation
+    directory.
+
+    \snippet snippets/cmake/deploy_non_qml.cmake deployment script
+
+    The \l{qt_generate_deploy_app_script}{qt_generate_deploy_app_script()}
+    command generates the deployment script in the build directory. The file
+    name of the generated script file is stored in the \c{deploy_script}
+    variable. The \c{install(SCRIPT)} call instructs CMake to run the script on
+    installation.
+
+    The project can be installed with \c{cmake --install .} or \c{ninja install}
+    like any other CMake-based project. After installation, the installation
+    directory contains the shared libraries and assets that are necessary to run
+    the application. In other words, the installation produces a self-contained
+    directory, ready to be packaged - for example by \c{cpack}.
+
+    \section1 Deploying a Qt Quick application
+
+    Deploying a Qt Quick project requires a different command to generate the
+    deployment script. The rest of the steps are similar to deploying a
+    Qt Widgets application.
+
+    First, you create the Qt Quick application.
+
+    \snippet snippets/cmake/deploy_non_qml.cmake basic setup
+
+    You install the application as before.
+
+    \snippet snippets/cmake/deploy_non_qml.cmake installation
+
+    To generate the deployment script, you call
+    \l{qt_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}
+    instead of
+    \l{qt_generate_deploy_app_script}{qt_generate_deploy_app_script()}.
+
+    \snippet snippets/cmake/deploy_non_qml.cmake deployment script
+
+    On installation, the application binary will be deployed, including the QML
+    files and the shared libraries and assets of Qt that are used by the
+    project. Again, the resulting directory is self-contained and can be
+    packaged by tools like \c{cpack}.
+*/
+
+/*!
     \page cmake-imported-targets.html
     \title Imported targets
     \brief Provides an overview of the CMake targets imported by Qt.
     \nextpage Qt CMake policies
-    \previouspage Building projects on the command line
+    \previouspage Deployment
 
     Each Qt module that is loaded defines a CMake library target. The target names
     start with \c{Qt6::}, followed by the module name. For example: \c{Qt6::Core}, \c{Qt6::Gui}.
diff --git a/doc/src/cmake/snippets/cmake/deploy_non_qml.cmake b/doc/src/cmake/snippets/cmake/deploy_non_qml.cmake
new file mode 100644
index 00000000..f5405ba9
--- /dev/null
+++ b/doc/src/cmake/snippets/cmake/deploy_non_qml.cmake
@@ -0,0 +1,33 @@
+# Copyright (C) 2023 The Qt Company Ltd.
+# SPDX-License-Identifier: BSD-3-Clause
+
+#! [basic setup]
+cmake_minimum_required(VERSION 3.16)
+
+project(MyApp VERSION 1.0.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(Qt6 REQUIRED COMPONENTS Core)
+qt_standard_project_setup()
+
+qt_add_executable(MyApp main.cpp)
+target_link_libraries(MyApp PRIVATE Qt6::Core)
+#! [basic setup]
+
+#! [installation]
+install(TARGETS MyApp
+    BUNDLE  DESTINATION .
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)
+#! [installation]
+
+#! [deployment script]
+qt_generate_deploy_app_script(
+    TARGET MyApp
+    OUTPUT_SCRIPT deploy_script
+    NO_UNSUPPORTED_PLATFORM_ERROR
+)
+install(SCRIPT ${deploy_script})
+#! [deployment script]
diff --git a/doc/src/cmake/snippets/cmake/deploy_qml.cmake b/doc/src/cmake/snippets/cmake/deploy_qml.cmake
new file mode 100644
index 00000000..12f5ce1d
--- /dev/null
+++ b/doc/src/cmake/snippets/cmake/deploy_qml.cmake
@@ -0,0 +1,36 @@
+# Copyright (C) 2023 The Qt Company Ltd.
+# SPDX-License-Identifier: BSD-3-Clause
+
+#! [basic setup]
+cmake_minimum_required(VERSION 3.16)
+
+project(MyApp VERSION 1.0.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(Qt6 REQUIRED COMPONENTS Core)
+qt_standard_project_setup()
+
+qt_add_executable(MyApp main.cpp)
+qt_add_qml_module(MyApp
+    URI Application
+    VERSION 1.0
+    QML_FILES main.qml MyThing.qml
+)
+#! [basic setup]
+
+#! [installation]
+install(TARGETS MyApp
+    BUNDLE  DESTINATION .
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)
+#! [installation]
+
+#! [deployment script]
+qt_generate_deploy_qml_app_script(
+    TARGET MyApp
+    OUTPUT_SCRIPT deploy_script
+)
+install(SCRIPT ${deploy_script})
+#! [deployment script]