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 | 232 |
1 files changed, 171 insertions, 61 deletions
diff --git a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc index 0c9d66812a..ac5094e7cb 100644 --- a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 @@ -32,8 +8,7 @@ **/ /*! -\page cmake-variable-QT_DEPLOY_PREFIX.html -\ingroup cmake-variables +\page cmake-variable-qt-deploy-prefix.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_PREFIX @@ -43,13 +18,14 @@ \include cmake-deploy-var-usage.qdocinc -\preliminarycmakevariable +\cmakevariablesince 6.3 -\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,18 +35,25 @@ 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_LIB_DIR, - QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +\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 +\page cmake-variable-qt-deploy-bin-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_BIN_DIR @@ -80,9 +63,9 @@ variables. \include cmake-deploy-var-usage.qdocinc -\preliminarycmakevariable +\cmakevariablesince 6.3 -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 +74,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. @@ -101,13 +88,51 @@ should not be used for that scenario. \include cmake-deploy-runtime-dependencies.qdocinc -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +\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_LIB_DIR.html -\ingroup cmake-variables +\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 @@ -117,9 +142,9 @@ should not be used for that scenario. \include cmake-deploy-var-usage.qdocinc -\preliminarycmakevariable +\cmakevariablesince 6.3 -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,19 +153,27 @@ 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 + QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR */ /*! -\page cmake-variable-QT_DEPLOY_PLUGINS_DIR.html -\ingroup cmake-variables +\page cmake-variable-qt-deploy-plugins-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_PLUGINS_DIR @@ -150,25 +183,33 @@ should not be used for that scenario. \include cmake-deploy-var-usage.qdocinc -\preliminarycmakevariable +\cmakevariablesince 6.3 -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. -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_QML_DIR +\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 +\page cmake-variable-qt-deploy-qml-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_QML_DIR @@ -178,12 +219,16 @@ bundle contents. \include cmake-deploy-var-usage.qdocinc -\preliminarycmakevariable +\cmakevariablesince 6.3 -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 +237,71 @@ 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_PLUGINS_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 */ |