diff options
Diffstat (limited to 'src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc')
-rw-r--r-- | src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc new file mode 100644 index 0000000000..ac5094e7cb --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc @@ -0,0 +1,307 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/* NOTE: The variables documented here are available when running a deploy +** script, they are not available at configure time (i.e. when running +** CMake). Both these and the set of configure-time variables are all +** members of the cmake-variables-qtcore group. +**/ + +/*! +\page cmake-variable-qt-deploy-prefix.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_PREFIX +\target cmake-variable-QT_DEPLOY_PREFIX + +\summary {Base location for a deployment.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +\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, 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 +string, the default value will be a dot (.) instead, which is generally the +appropriate value when deploying as part of a post-build rule. This two-step +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} +variables. + +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIBEXEC_DIR, + QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-bin-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_BIN_DIR +\target cmake-variable-QT_DEPLOY_BIN_DIR + +\summary {Prefix-relative subdirectory for deploying runtime binaries on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +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: + +\list +\li Executables on all platforms. +\li DLLs on Windows. +\endlist + +\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. + +\section1 Example + +\include cmake-deploy-runtime-dependencies.qdocinc + +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_LIBEXEC_DIR, + QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-libexec-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_LIBEXEC_DIR +\target cmake-variable-QT_DEPLOY_LIBEXEC_DIR + +\summary {Prefix-relative subdirectory for deploying program executables on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.7 + +On Unix derivatives, projects should use \c QT_DEPLOY_LIBEXEC_DIR in their +deploy scripts to avoid hard-coding a particular directory in which to deploy +helper executables that are local to the project. + +For example, projects using QtWebEngine would deploy the \c QtWebEngineProcess +executable to this directory. + +\c QT_DEPLOY_LIBEXEC_DIR defaults to the value of \c${CMAKE_INSTALL_LIBEXECDIR} +(usually \c{libexec}), which is provided by CMake's \l{GNUInstallDirs} module. +To change the value of \c QT_DEPLOY_LIBEXEC_DIR, ensure that the project sets +\c{CMAKE_INSTALL_LIBEXECDIR} before the \c Core package is found. + +The \c QT_DEPLOY_LIBEXEC_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_LIB_DIR, + QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-lib-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_LIB_DIR +\target cmake-variable-QT_DEPLOY_LIB_DIR + +\summary {Prefix-relative subdirectory for deploying libraries on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +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: + +\list +\li Shared libraries on platforms other than Windows. +\li Import libraries on Windows. +\endlist + +\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, QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-plugins-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_PLUGINS_DIR +\target cmake-variable-QT_DEPLOY_PLUGINS_DIR + +\summary {Prefix-relative subdirectory for deploying Qt plugins on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +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}. 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_LIBEXEC_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-qml-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_QML_DIR +\target cmake-variable-QT_DEPLOY_QML_DIR + +\summary {Prefix-relative subdirectory for deploying QML plugins on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +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}. 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 +require all plugins to be deployed to the \c{PlugIns} subdirectory of the +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_LIBEXEC_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, + QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-translations-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_TRANSLATIONS_DIR +\target cmake-variable-QT_DEPLOY_TRANSLATIONS_DIR + +\summary {Prefix-relative subdirectory for deploying Qt translations on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.5 + +Projects should use \c QT_DEPLOY_TRANSLATIONS_DIR in their deploy scripts to +avoid hard-coding a particular directory under which to deploy translations. + +\c QT_DEPLOY_TRANSLATIONS_DIR defaults to the value \c{translations}. To change +the value of \c QT_DEPLOY_TRANSLATIONS_DIR, set it in the project deployment +script before \c QT_DEPLOY_SUPPORT is included. + +The \c QT_DEPLOY_TRANSLATIONS_DIR path is relative to \l{QT_DEPLOY_PREFIX}. + +This variable is not meaningful when deploying on macOS or Windows. + +\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_LIBEXEC_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-ignored-lib-dirs.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_IGNORED_LIB_DIRS +\target cmake-variable-QT_DEPLOY_IGNORED_LIB_DIRS + +\summary {Directories that are excluded from runtime dependencies search} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.5 + +This variable contains a list of directories that are not taken into account +when searching for runtime dependencies with \l{qt_deploy_runtime_dependencies}. + +Projects may alter this variable before calling +\l{qt_deploy_runtime_dependencies} to control from which directory runtime +dependencies are deployed. + +This variable is ignored if the \c{POST_EXCLUDE_REGEXES} option is specified in +the \l{qt_deploy_runtime_dependencies} call. + +This variable is not meaningful when deploying on macOS or Windows. + +\sa qt_deploy_runtime_dependencies +*/ |