whytofly
/
qt6-bb10
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add documentation for CMake deployment support 

Task-number: QTBUG-98545
Change-Id: Ifd5c0f4ce278c683bb0d3ba6a259ec14a7f24181
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
bb10
Craig Scott 2021-11-24 13:35:41 +11:00 committed by Alexandru Croitor
parent 3ee79be628
commit 22c92f3967
10 changed files with 717 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
src/corelib/doc/src/cmake/cmake-variables.qdoc → src/corelib/doc/src/cmake/cmake-configure-variables.qdoc
View File

@ -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()}
*/

187
src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc Normal file
View File

@ -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
*/

93
src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc Normal file
View File

@ -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
*/

133
src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc Normal file
View File

@ -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{<bundle-name>.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
*/

105
src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc Normal file
View File

@ -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
*/

90
src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc Normal file
View File

@ -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/<reldir>} is also appended,
where \c{<reldir>} 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
*/

25
src/corelib/doc/src/external-resources.qdoc
View File

@ -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()
*/

22
src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc Normal file
View File

@ -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}/$<TARGET_FILE_NAME:MyApp>\"
)
")
install(TARGETS MyApp) # Install the target
install(SCRIPT ${deploy_script}) # Add its runtime dependencies
\endcode

2
src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc Normal file
View File

@ -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.

7
src/corelib/doc/src/includes/cmake-find-package-core.qdocinc
View File

@ -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