summaryrefslogtreecommitdiffstats
path: root/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc')
-rw-r--r--src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc307
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
+*/