diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc index aec582aa00..ba8bc6e9c0 100644 --- a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -262,10 +262,13 @@ must be set before the first \c{find_package(Qt6)} call to have that effect. \cmakevariablesince 6.3 \preliminarycmakevariable +\note The value of this variable should never be modified by project code. -This variable is set by the Core package. It is intended to be used as the first -line of any deployment script. Such scripts do not run during CMake's configure -phase, they are executed during installation or as part of a post-build rule. +This configure-phase variable is set by the Core package. It is intended to be +used as the first line of any deployment script to ensure access to the +deployment APIs provided by Qt. Such deployment scripts do not run during +CMake's configure phase, they are executed during installation or as +part of a post-build rule. The following example shows one way the variable would be used when installing an application, along with its runtime dependencies: diff --git a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc index 4444153243..e693024eb6 100644 --- a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc @@ -45,11 +45,12 @@ \cmakevariablesince 6.3 \preliminarycmakevariable -\c{QT_DEPLOY_PREFIX} provides the base directory of the deployment. The other +\c{QT_DEPLOY_PREFIX} provides the base deployment directory. The other \c{QT_DEPLOY_..._DIR} variables should be treated as relative to this location. The value of \c{QT_DEPLOY_PREFIX} may be relative or absolute, so projects should not assume one or the other in any given situation. A relative path is -expected to be treated as relative to the current working directory. +expected to be treated as relative to the current working directory, as seen +by the build tool (ninja, make, and so on) at install time. The default value is \c{$ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}}, which is the base location CMake uses during installation. If that evaluates to an empty @@ -59,6 +60,13 @@ fallback logic ensures that projects can assume \c{QT_DEPLOY_PREFIX} will not be an empty string, so it can safely be used as part of a path like \c{${QT_DEPLOY_PREFIX}/${QT_DEPLOY_BIN_DIR}}. +To change the value of \c QT_DEPLOY_PREFIX, the project can be configured +with a custom \l CMAKE_INSTALL_PREFIX as described in +\l {Command Line cmake invocation}. + +The \l DESTDIR environment variable can also be used to modify the final +installation, and thus deployment, location. + Projects should rarely need to use this variable. In typical scenarios, deploy scripts should assume that the working directory is already set to the base install location and just use the prefix-relative \c{QT_DEPLOY_..._DIR} @@ -82,7 +90,7 @@ variables. \cmakevariablesince 6.3 \preliminarycmakevariable -Projects should use \c QT_DEPLOY_BIN_DIR in their deploy scripts instead of +Projects should use \c QT_DEPLOY_BIN_DIR in their deploy scripts to avoid hard-coding a particular directory in which to deploy the following types of binaries: @@ -91,8 +99,12 @@ binaries: \li DLLs on Windows. \endlist -\c QT_DEPLOY_BIN_DIR defaults to the value of \c${CMAKE_INSTALL_BINDIR}, which -is provided by CMake's \l{GNUInstallDirs} module. +\c QT_DEPLOY_BIN_DIR defaults to the value of \c${CMAKE_INSTALL_BINDIR} +(usually \c{bin}), which is provided by CMake's \l{GNUInstallDirs} module. +To change the value of \c QT_DEPLOY_BIN_DIR, ensure that the project sets +\c{CMAKE_INSTALL_BINDIR} before the \c Core package is found. + +The \c QT_DEPLOY_BIN_DIR path is relative to \l{QT_DEPLOY_PREFIX}. This variable is not meaningful when deploying into a macOS app bundle and should not be used for that scenario. @@ -119,7 +131,7 @@ should not be used for that scenario. \cmakevariablesince 6.3 \preliminarycmakevariable -Projects should use \c QT_DEPLOY_LIB_DIR in their deploy scripts instead of +Projects should use \c QT_DEPLOY_LIB_DIR in their deploy scripts to avoid hard-coding a particular directory in which to deploy the following types of binaries: @@ -128,12 +140,21 @@ binaries: \li Import libraries on Windows. \endlist -\c QT_DEPLOY_LIB_DIR defaults to the value of \c${CMAKE_INSTALL_LIBDIR}, which -is provided by CMake's \l{GNUInstallDirs} module. +\c QT_DEPLOY_LIB_DIR defaults to the value of \c${CMAKE_INSTALL_LIBDIR} +(usually \c{lib} or \c{lib64}), which is provided by +CMake's \l{GNUInstallDirs} module. +To change the value of \c QT_DEPLOY_LIB_DIR, ensure that the project sets +\c{CMAKE_INSTALL_LIBDIR} before the \c Core package is found. + +The \c QT_DEPLOY_LIB_DIR path is relative to \l{QT_DEPLOY_PREFIX}. This variable is not meaningful when deploying into a macOS app bundle and should not be used for that scenario. +\section1 Example + +\include cmake-deploy-modified-variable-values.qdocinc + \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR */ @@ -152,16 +173,24 @@ should not be used for that scenario. \cmakevariablesince 6.3 \preliminarycmakevariable -Projects should use \c QT_DEPLOY_PLUGINS_DIR in their deploy scripts instead of +Projects should use \c QT_DEPLOY_PLUGINS_DIR in their deploy scripts to avoid hard-coding a particular directory under which to deploy plugins. -\c QT_DEPLOY_PLUGINS_DIR defaults to the value \c{plugins}. +\c QT_DEPLOY_PLUGINS_DIR defaults to the value \c{plugins}. To change the value +of \c QT_DEPLOY_PLUGINS_DIR, set it in the project deployment script +before \c QT_DEPLOY_SUPPORT is included. + +The \c QT_DEPLOY_PLUGINS_DIR path is relative to \l{QT_DEPLOY_PREFIX}. This variable is not meaningful when deploying into a macOS app bundle and should not be used for that scenario. Apple's macOS app bundle guidelines require all plugins to be deployed to the \c{PlugIns} subdirectory of the bundle contents. +\section1 Example + +\include cmake-deploy-modified-variable-values.qdocinc + \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_QML_DIR */ @@ -180,10 +209,14 @@ bundle contents. \cmakevariablesince 6.3 \preliminarycmakevariable -Projects should use \c QT_DEPLOY_QML_DIR in their deploy scripts instead of +Projects should use \c QT_DEPLOY_QML_DIR in their deploy scripts to avoid hard-coding a particular directory under which to deploy QML modules. -\c QT_DEPLOY_QML_DIR defaults to the value \c{qml}. +\c QT_DEPLOY_QML_DIR defaults to the value \c{qml}. To change the value +of \c QT_DEPLOY_QML_DIR, set it in the project deployment script +before \c QT_DEPLOY_SUPPORT is included. + +The \c QT_DEPLOY_QML_DIR path is relative to \l{QT_DEPLOY_PREFIX}. This variable is not meaningful when deploying into a macOS app bundle and should not be used for that scenario. Apple's macOS app bundle guidelines @@ -192,6 +225,10 @@ bundle contents, and all other non-binary files should generally be under the \c{Resources} subdirectory. The different parts of a QML module therefore need to be deployed to different locations within the app bundle. +\section1 Example + +\include cmake-deploy-modified-variable-values.qdocinc + \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR */ diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc index 59bc163e60..4df599fbd8 100644 --- a/src/corelib/doc/src/external-resources.qdoc +++ b/src/corelib/doc/src/external-resources.qdoc @@ -111,6 +111,21 @@ \title GNUInstallDirs */ +/*! + \externalpage https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html + \title CMAKE_INSTALL_PREFIX +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#command-line-cmake-tool + \title Command Line cmake invocation +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/envvar/DESTDIR.html + \title DESTDIR +*/ + /*! \externalpage https://cmake.org/cmake/help/latest/command/install.html#targets \title install(TARGETS) diff --git a/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc new file mode 100644 index 0000000000..6c1f20adb2 --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc @@ -0,0 +1,24 @@ +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +set(CMAKE_INSTALL_BINDIR "mybindir") +set(CMAKE_INSTALL_LIBDIR "mylibdir") + +find_package(Qt6 REQUIRED COMPONENTS Core) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) + +set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake") +file(GENERATE OUTPUT ${deploy_script} CONTENT " + +set(QT_DEPLOY_PLUGINS_DIR \"mypluginsdir\") +set(QT_DEPLOY_QML_DIR \"myqmldir\") + +include(\"${QT_DEPLOY_SUPPORT}\") + +qt_deploy_runtime_dependencies( + EXECUTABLE \"\${QT_DEPLOY_BIN_DIR}/$\" +)") +\endcode diff --git a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc index 5ac43a98b2..3c7fb8d5ee 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc @@ -27,6 +27,8 @@ set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$") set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake") file(GENERATE OUTPUT ${deploy_script} CONTENT " +# Including the file pointed to by QT_DEPLOY_SUPPORT ensures the generated +# deployment script has access to qt_deploy_runtime_dependencies() include(\"${QT_DEPLOY_SUPPORT}\") qt_deploy_runtime_dependencies( EXECUTABLE \"${executable_path}\"