diff --git a/src/corelib/doc/src/cmake/cmake-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc similarity index 68% rename from src/corelib/doc/src/cmake/cmake-variables.qdoc rename to src/corelib/doc/src/cmake/cmake-configure-variables.qdoc index 1cef1ffd3c..af0452fc6b 100644 --- a/src/corelib/doc/src/cmake/cmake-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -25,6 +25,12 @@ ** ****************************************************************************/ +/* NOTE: The variables documented here are available when running CMake, they +** are not available in a deployment script. Both these and the set of +** deploy-time variables are all members of the cmake-variables-qtcore +** group. +**/ + /*! \group cmake-variables-qtcore \title CMake Variables in Qt6 Core @@ -158,7 +164,55 @@ Set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to true if you want to prevent this. \preliminarycmakevariable -Enables verbose mode of the androiddeployqt deployment tool when it is implicitly called -inside the Qt CMake commands. +Enables verbose mode of the \l androiddeployqt deployment tool when it is called +internally at build time, usually during target finalization. +This variable also changes the default verbosity of install-time deployment +scripts for other platforms (see \l{qt_deploy_runtime_dependencies()}), but it +must be set before the first \c{find_package(Qt6)} call to have that effect. */ + +/*! +\page cmake-variable-QT_DEPLOY_SUPPORT.html +\ingroup cmake-variables +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_SUPPORT +\target cmake-variable-QT_DEPLOY_SUPPORT + +\summary {Name of the file to include for setting up deployment support.} + +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. + +The following example shows one way the variable would be used when installing +an application, along with its runtime dependencies: + +\include cmake-deploy-runtime-dependencies.qdocinc + +\sa qt_deploy_runtime_dependencies(), qt_deploy_qml_imports() +*/ + +/*! +\page cmake-variable-QT_NO_STANDARD_PROJECT_SETUP.html +\ingroup cmake-variables +\ingroup cmake-variables-qtcore + +\title QT_NO_STANDARD_PROJECT_SETUP +\target cmake-variable-QT_NO_STANDARD_PROJECT_SETUP + +\summary {Prevents subsequent calls to qt_standard_project_setup() from making any changes.} + +The \l{qt6_standard_project_setup}{qt_standard_project_setup()} command is +typically called in the top level \c{CMakeLists.txt} file of a project. In some +scenarios, such projects may be absorbed as a child project of a larger project +hierarchy. A parent project may want to prevent any child project from applying +changes to the setup. The parent project can achieve this by setting +\c{QT_NO_STANDARD_PROJECT_SETUP} to true before bringing in the child project +via \l{add_subdirectory()}, \l{FetchContent_MakeAvailable()} or other similar +methods provided by CMake. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()} +*/ + 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..55d467309b --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/* 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 +\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 + +\c{QT_DEPLOY_PREFIX} provides the base directory of the deployment. 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. + +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}}. + +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 +*/ + +/*! +\page cmake-variable-QT_DEPLOY_BIN_DIR.html +\ingroup cmake-variables +\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 + +Projects should use \c QT_DEPLOY_BIN_DIR in their deploy scripts instead of +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}, which +is provided by CMake's \l{GNUInstallDirs} module. + +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_LIB_DIR, + QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +*/ + +/*! +\page cmake-variable-QT_DEPLOY_LIB_DIR.html +\ingroup cmake-variables +\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 + +Projects should use \c QT_DEPLOY_LIB_DIR in their deploy scripts instead of +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}, which +is provided by CMake's \l{GNUInstallDirs} module. + +This variable is not meaningful when deploying into a macOS app bundle and +should not be used for that scenario. + +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, + QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +*/ + +/*! +\page cmake-variable-QT_DEPLOY_PLUGINS_DIR.html +\ingroup cmake-variables +\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 + +Projects should use \c QT_DEPLOY_PLUGINS_DIR in their deploy scripts instead of +hard-coding a particular directory under which to deploy plugins. + +\c QT_DEPLOY_PLUGINS_DIR defaults to the value \c{plugins}. + +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 +*/ + +/*! +\page cmake-variable-QT_DEPLOY_QML_DIR.html +\ingroup cmake-variables +\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 + +Projects should use \c QT_DEPLOY_QML_DIR in their deploy scripts instead of +hard-coding a particular directory under which to deploy QML modules. + +\c QT_DEPLOY_QML_DIR defaults to the value \c{qml}. + +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. + +\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/cmake/qt_deploy_qt_conf.qdoc b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc new file mode 100644 index 0000000000..173c9230f8 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc @@ -0,0 +1,93 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qt_deploy_qt_conf.html +\ingroup cmake-commands-qtcore + +\title qt_deploy_qt_conf +\target qt_deploy_qt_conf + +\summary {Write a qt.conf file at deployment time.} + +\include cmake-find-package-core.qdocinc + +Unlike most other CMake commands provided by Qt, \c{qt_deploy_qt_conf()} can +only be called from a deployment script. It cannot be called directly by the +project. + +\section1 Synopsis + +\badcode +qt_deploy_qt_conf(file_name + [PREFIX prefix] + [DOC_DIR doc_dir] + [HEADERS_DIR headers_dir] + [LIB_DIR lib_dir] + [LIBEXEC_DIR libexec_dir] + [BIN_DIR bin_dir] + [PLUGINS_DIR plugins_dir] + [QML_DIR qml_dir] + [ARCHDATA_DIR archdata_dir] + [DATA_DIR data_dir] + [TRANSLATIONS_DIR translations_dir] + [EXAMPLES_DIR examples_dir] + [TESTS_DIR test_dir] + [SETTINGS_DIR settings_dir] +) +\endcode + +\section1 Description + +Use this command when you need to generate a \c{Using qt.conf}{qt.conf} file +during deployment. The default value of any path supported by \c{qt.conf} can +be overridden with the corresponding \c{..._DIR} option. The command will only +write a path to the generated \c{qt.conf} file if it differs from the default +value. + +This command does not usually need to be called directly. It is used internally +by other higher level commands, but projects wishing to implement more +customized deployment logic may find it useful. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}, + qt_deploy_runtime_dependencies() + +\section1 Example + +\badcode +# The following script must only be executed at install time +set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_custom.cmake") + +file(GENERATE OUTPUT ${deploy_script} CONTENTS " +include(\"${QT_DEPLOY_SUPPORT}\") +qt_deploy_qt_conf(\"\${QT_DEPLOY_BIN_DIR}/qt.conf\") +") + +install(SCRIPT ${deploy_script}) +\endcode + +*/ diff --git a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc new file mode 100644 index 0000000000..1cfee0331e --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qt_deploy_runtime_dependencies.html +\ingroup cmake-commands-qtcore + +\title qt_deploy_runtime_dependencies +\target qt_deploy_runtime_dependencies + +\summary {Deploy Qt plugins, Qt and non-Qt libraries needed by an executable.} + +\include cmake-find-package-core.qdocinc + +Unlike most other CMake commands provided by Qt, \c{qt_deploy_runtime_dependencies()} +can only be called from a deployment script. It cannot be called directly by the +project during the configure stage. + +\section1 Synopsis + +\badcode +qt_deploy_runtime_dependencies( + EXECUTABLE executable + [MACOS_BUNDLE] + [ADDITIONAL_EXECUTABLES files...] + [ADDITIONAL_LIBRARIES files...] + [ADDITIONAL_MODULES files...] + [GENERATE_QT_CONF] + [BIN_DIR bin_dir] + [LIB_DIR lib_dir] + [PLUGINS_DIR plugins_dir] + [QML_DIR qml_dir] + [VERBOSE] + [NO_OVERWRITE] + [NO_APP_STORE_COMPLIANCE] +) +\endcode + +\section1 Description + +\note This command does not usually need to be called directly. It is used + internally by other higher level commands, but projects wishing to + implement more customized deployment logic may find it useful. + +When installing an application, it may be desirable to also install the +libraries and plugins it depends on. When the application is a macOS app bundle +or a Windows executable, \c{qt_deploy_runtime_dependencies()} can be called +from an install-time script to deploy those dependencies. It will install +non-system libraries (both Qt and those provided by the project), plus an +appropriate set of Qt plugins. + +This command only considers runtime dependencies for which linking +relationships exist in the underlying binaries. It does not deploy QML modules, +see \l{qt_deploy_qml_imports()} for that. + +\section1 Arguments + +The \c{EXECUTABLE} option must be provided. The \c{executable} argument should +be the path relative to the base install location. For macOS app bundles, the +\c{MACOS_BUNDLE} option should be given and the \c{executable} argument should +be the path to the executable in the \c{.app/Contents/MacOS} +directory. + +It may also be desirable to install dependencies for other binaries related to +the \c{executable}. For example, plugins provided by the project might have +further dependencies, but because those plugins won't be linked directly to the +executable, \c{qt_deploy_runtime_dependencies()} won't automatically discover +them. The \c{ADDITIONAL_EXECUTABLES}, \c{ADDITIONAL_LIBRARIES}, and +\c{ADDITIONAL_MODULES} arguments can be used to specify additional binaries +whose dependencies should also be deployed (installing the named binaries +themselves is still the project's responsibility). The naming of these keywords +follows CMake's conventions, so Qt plugins would be specified using +\c{ADDITIONAL_MODULES}. + +When installing a Windows application, it is common to need a +\l{Using qt.conf}{qt.conf} file when following CMake's default install +directory structure. If the \c{GENERATE_QT_CONF} option is given, an appropriate +\c{qt.conf} file will be written to the same directory as the \c{executable}. +The paths in that \c{qt.conf} file will be based on the \c{CMAKE_INSTALL_xxxDIR} +variables, whose defaults are provided by CMake's \l{GNUInstallDirs} module. +You can override some of those defaults with the \c{BIN_DIR}, \c{LIB_DIR}, +\c{PLUGINS_DIR}, and \c{QML_DIR} options, all of which are expected to be +relative to the base install location. A \c{qt.conf} file is always written if +\c{executable} is a macOS app bundle, regardless of whether or not +\c{GENERATE_QT_CONF} is provided. The \c{..._DIR} options are also ignored in +that case, since the directory layout of an app bundle is dictated by Apple's +requirements. + +More verbose output about the deployment steps can be enabled by providing the +\c{VERBOSE} option. Alternatively, the \l{QT_ENABLE_VERBOSE_DEPLOYMENT} +variable can be set in the project before the first \c{find_package(Qt6)} call +to make deployment output verbose by default. + +The \c{qt_deploy_runtime_dependencies()} command overwrites existing files by +default (some warnings may still be issued). Use the \c{NO_OVERWRITE} option +to prevent overwriting existing files. Note that this option currently only +affects macOS and Windows deployments. + +By default, if \c{executable} is a macOS app bundle, only Qt plugins and Qt +libraries that comply with Apple's app store requirements are deployed. The +\c{NO_APP_STORE_COMPLIANCE} option can be given to disable that constraint. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}, + qt_deploy_qt_conf(), qt_deploy_qml_imports() + +\section1 Example + +\include cmake-deploy-runtime-dependencies.qdocinc +*/ diff --git a/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc new file mode 100644 index 0000000000..0869f7ed0a --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qt_generate_deploy_app_script.html +\ingroup cmake-commands-qtcore + +\title qt_generate_deploy_app_script +\target qt6_generate_deploy_app_script + +\summary {Generate a deployment script for an application.} + +\include cmake-find-package-core.qdocinc + +\section1 Synopsis + +\badcode +qt_generate_deploy_app_script( + TARGET target + FILENAME_VARIABLE var_name + [NO_UNSUPPORTED_PLATFORM_ERROR] +) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_deploy_app_script() + +\section1 Description + +Installing an executable target with \l{install(TARGETS)} only installs the +target's executable (except for macOS app bundles, which will copy the whole +bundle). You need to explicitly install any other libraries or plugins the +executable depends on yourself. \c{qt_generate_deploy_app_script()} is a +convenience command intended to simplify that process. It expects the +application to follow Qt's recommended install directory structure fairly +closely. That structure is based on CMake's default install layout, as +determined by \l{GNUInstallDirs} (except for macOS app bundles, which follow +Apple's requirements instead). + +The command generates a script whose name will be stored in the variable named +by the \c{FILENAME_VARIABLE} option. That script is only written at CMake +generation time. It is intended to be used with the \l{install(SCRIPT)} command, +which should come after the application's target has been installed using +\l{install(TARGETS)}. + +The deployment script will call \l{qt_deploy_runtime_dependencies()} with a +suitable set of options for the standard install layout. This is currently only +implemented for macOS app bundles and Windows targets. +Calling \c{qt_generate_deploy_app_script()} for any other platform will result +in a fatal error, unless the \c{NO_UNSUPPORTED_PLATFORM_ERROR} option is given. + +For deploying a QML application, use +\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} +instead. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()}, + {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} + +\section1 Example + +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 REQUIRED COMPONENTS Core) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) + +install(TARGETS MyApp + BUNDLE DESTINATION . + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} +) + +qt_generate_deploy_app_script( + TARGET MyApp + FILENAME_VARIABLE deploy_script + NO_UNSUPPORTED_PLATFORM_ERROR +) +install(SCRIPT ${deploy_script}) +\endcode +*/ diff --git a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc new file mode 100644 index 0000000000..6c3fcc3f93 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qt_standard_project_setup.html +\ingroup cmake-commands-qtcore + +\title qt_standard_project_setup +\target qt6_standard_project_setup + +\summary {Setup project-wide defaults to a standard arrangement.} + +\include cmake-find-package-core.qdocinc + +\section1 Synopsis + +\badcode +qt_standard_project_setup() +\endcode + +\versionlessCMakeCommandsNote qt6_standard_project_setup() + +\section1 Description + +This command simplifies the task of setting up a typical Qt application. +It would usually be called immediately after the first \c{find_package(Qt6)} +call, normally in the top level \c{CMakeLists.txt} file and before any targets +have been defined. It does the following things: + +\list +\li The standard CMake variables \c{CMAKE_AUTOMOC}, \c{CMAKE_AUTOUIC} and + \c{CMAKE_AUTORCC} are set to true if they are not already defined. + This enables all Qt-related autogen features by default for subsequently + created targets in the current directory scope and below. +\li CMake's \l{GNUInstallDirs} module is automatically included. This defines + appropriate defaults for variables like \c{CMAKE_INSTALL_BINDIR}, + \c{CMAKE_INSTALL_LIBDIR}, and so on. +\li When targeting Windows, if the \c{CMAKE_RUNTIME_OUTPUT_DIRECTORY} variable + is not already set, it will be set to + \c{${CMAKE_CURRENT_BINARY_DIR}}. +\li When target platforms other than Apple or Windows, \c{CMAKE_INSTALL_RPATH} + will be augmented as described below. +\endlist + +On platforms that support \c{RPATH} (other than Apple platforms), two values +are appended to the \c{CMAKE_INSTALL_RPATH} variable by this command. +\c{$ORIGIN} is appended so that libraries will find other libraries they depend +on in the same directory as themselves. \c{$ORIGIN/} is also appended, +where \c{} is the relative path from \c{CMAKE_INSTALL_BINDIR} to +\c{CMAKE_INSTALL_LIBDIR}. This allows executables installed to +\c{CMAKE_INSTALL_BINDIR} to find any libraries they may depend on installed to +\c{CMAKE_INSTALL_LIBDIR}. Any duplicates in \c{CMAKE_INSTALL_RPATH} are +removed. In practice, these two values ensure that executables and libraries +will find their link-time dependencies, assuming projects install them to the +default locations the \l{install(TARGETS)} command uses when no destination is +explicitly provided. + +The \c{qt_standard_project_setup()} command can effectively be disabled by +setting the \l{QT_NO_STANDARD_PROJECT_SETUP} variable to true. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} + +\section1 Example + +\include cmake-deploy-runtime-dependencies.qdocinc +*/ diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc index 50a19a4e09..59bc163e60 100644 --- a/src/corelib/doc/src/external-resources.qdoc +++ b/src/corelib/doc/src/external-resources.qdoc @@ -105,3 +105,28 @@ \externalpage https://developer.android.com/training/articles/perf-anr \title Android: Keeping your app responsive */ + +/*! + \externalpage https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html + \title GNUInstallDirs +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/command/install.html#targets + \title install(TARGETS) +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/command/install.html#script + \title install(SCRIPT) +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/command/add_subdirectory.html + \title add_subdirectory() +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/module/FetchContent.html#command:fetchcontent_makeavailable + \title FetchContent_MakeAvailable() +*/ diff --git a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc new file mode 100644 index 0000000000..6faf1a3cdf --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc @@ -0,0 +1,22 @@ +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 REQUIRED COMPONENTS Core) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) + +# The following script must only be executed at install time +set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake") + +file(GENERATE OUTPUT ${deploy_script} CONTENTS " +include(\"${QT_DEPLOY_SUPPORT}\") +qt_deploy_runtime_dependencies( + EXECUTABLE \"\${QT_DEPLOY_BIN_DIR}/$\" +) +") + +install(TARGETS MyApp) # Install the target +install(SCRIPT ${deploy_script}) # Add its runtime dependencies +\endcode diff --git a/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc new file mode 100644 index 0000000000..c5a1a40356 --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc @@ -0,0 +1,2 @@ +This variable is defined by the script named by \l QT_DEPLOY_SUPPORT. It should +only be used as part of deployment during installation or a post-build rule. diff --git a/src/corelib/doc/src/includes/cmake-find-package-core.qdocinc b/src/corelib/doc/src/includes/cmake-find-package-core.qdocinc index 4bf3892aa2..66649eec5a 100644 --- a/src/corelib/doc/src/includes/cmake-find-package-core.qdocinc +++ b/src/corelib/doc/src/includes/cmake-find-package-core.qdocinc @@ -1,5 +1,6 @@ -The command is defined in the \c Core component of the \c Qt6 package. Load the package with: +The command is defined in the \c Core component of the \c Qt6 package, which +can be loaded like so: -\code -find_package(Qt6 COMPONENTS Core REQUIRED) +\badcode +find_package(Qt6 REQUIRED COMPONENTS Core) \endcode