diff options
Diffstat (limited to 'src/corelib/doc/src/cmake')
32 files changed, 3635 insertions, 0 deletions
diff --git a/src/corelib/doc/src/cmake/cmake-commands.qdoc b/src/corelib/doc/src/cmake/cmake-commands.qdoc new file mode 100644 index 0000000000..e185bab624 --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-commands.qdoc @@ -0,0 +1,17 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group cmake-commands-qtcore +\title CMake Commands in Qt6 Core +\brief Lists CMake commands defined in Qt6::Core. + +The following CMake commands are defined when Qt6::Core is loaded, for instance +with + +\code +find_package(Qt6 REQUIRED COMPONENTS Core) +\endcode + +\sa{CMake Command Reference} +*/ diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc new file mode 100644 index 0000000000..b710ba7275 --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -0,0 +1,587 @@ +// Copyright (C) 2022 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 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 +\brief Lists CMake variables defined in Qt6::Core. + +The following CMake variables are defined when Qt6::Core is loaded, for instance +with + +\badcode +find_package(Qt6 REQUIRED COMPONENTS Core) +\endcode + +\sa{CMake Variable Reference} +*/ + +/*! +\page cmake-variable-android-ndk-host-system-name.html +\ingroup cmake-variables-qtcore + +\title ANDROID_NDK_HOST_SYSTEM_NAME +\target cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME + +\summary {Android-specific architecture of the host system.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +Usually, this variable is set by the Android NDK toolchain file. It is written out as +part of the deployment settings for a target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-variable-android-sdk-root.html +\ingroup cmake-variables-qtcore + +\title ANDROID_SDK_ROOT +\target cmake-variable-ANDROID_SDK_ROOT + +\summary {Location of the Android SDK.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +Specifies the location of the Android SDK when building for the Android platform. +This variable is written out as part of the deployment settings for a target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}. +*/ + +/*! +\page cmake-variable-qt-android-application-arguments.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-manifest-properties + +\title QT_ANDROID_APPLICATION_ARGUMENTS +\target cmake-variable-QT_ANDROID_APPLICATION_ARGUMENTS + +\summary {List of arguments to pass to Android applications.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +Contains a list of arguments to be passed to Android applications. This variable +is written out as part of the deployment settings for a target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-variable-qt-android-deployment-type.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_DEPLOYMENT_TYPE +\target cmake-variable-QT_ANDROID_DEPLOYMENT_TYPE + +\summary {Forces or disables release package signing regardless of the build type.} + +\cmakevariablesince 6.7 +\preliminarycmakevariable +\cmakevariableandroidonly + +When set to \c Release, the \c --release flag is passed to the \c +androiddeployqt tool, regardless of the application build type. When set to +another value, the \c --release flag is never passed to the tool, which +effectively disables release package signing even in Release or RelWithDebInfo +builds. When not set, the default behavior is to use release package signing in +build types other than Debug. + +\sa {androiddeployqt} +*/ + +/*! +\page cmake_variable-qt-android-multi-abi-forward-vars +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_MULTI_ABI_FORWARD_VARS +\target cmake-variable-QT_ANDROID_MULTI_ABI_FORWARD_VARS + +\summary {Allows to share CMake variables in multi-ABI builds.} + +\cmakevariablesince 6.4.2 +\preliminarycmakevariable +\cmakevariableandroidonly + +Allows specifying the list of +CMake variables that need to be forwarded from the main ABI project to +ABI-specific subprojects. Due to the specifics of the Multi-ABI project build +process, there is no generic way to forward the CMake cache variables +that are specified either in the command line or in another similar way. + +A typical use case for the variable is propagating CMake cache variables +specified in the command line. For example, a project has two variables +\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} that affect the +project configuration: +\badcode +cmake_minimum_required(VERSION 3.18) + +project(MyProject LANGUAGES CXX) + +find_package(Qt6 REQUIRED COMPONENTS Core) + +qt_add_executable(MyApp main.cpp) + +if(PROJECT_WIDE_VARIABLE1) + target_sources(MyApp PRIVATE sourcefile1.cpp) +endif() +if(PROJECT_WIDE_VARIABLE2) + target_sources(MyApp PRIVATE sourcefile2.cpp) +endif() +\endcode + +The above contents of \c{CMakeLists.txt} enable you to control how +\c{MyApp} is built by setting the corresponding CMake variables from the +command line: +\badcode +qt-cmake -S<source directory> -B<build directory> \ + -DPROJECT_WIDE_VARIABLE1=ON \ + -DPROJECT_WIDE_VARIABLE2=ON \ + -DQT_ANDROID_MULTI_ABI_FORWARD_VARS="PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2" +\endcode + +When configuring the application for desktop, \c{PROJECT_WIDE_VARIABLE1} and +\c{PROJECT_WIDE_VARIABLE2} are visible in CMake listings and scripts as global +cache variables. This doesn't work for Android Multi-ABI builds because +ABI-specific subprojects do not inherit the cache variables from the main-ABI +project. This issue can be solved by passing the list of required variables to +the \c{QT_ANDROID_MULTI_ABI_FORWARD_VARS} variable, so both +\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} values will be +propagated to the ABI-specific builds. + +The variable can be also defined in the project's CMakeLists.txt: +\badcode +... +qt_add_executable(MyApp main.cpp) +... +if(ANDROID) + set(QT_ANDROID_MULTI_ABI_FORWARD_VARS "PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2") +endif() +... +\endcode + +Set the variable in this way to have a predefined set of +variables that will always be forwarded to ABI-specific projects. + +\note The forwarding is done in the target finalizer, which is implicitly +called when \l{qt6_add_executable}{qt_add_executable()} is used. The +finalization occurs automatically when using CMake 3.19 or later. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()} +*/ + +/*! +\page cmake-variable-qt-android-build-all-abis.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_BUILD_ALL_ABIS +\target cmake-variable-QT_ANDROID_BUILD_ALL_ABIS + +\summary {Enables building multi-ABI packages using the autodetected Qt for Android SDK list.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +Automatically detects available ABIs of Qt for Android and uses them to +build a package. The automatic detection expects the default directory structure +supplied by the Qt installer, with the corresponding naming of the directories. +\include cmake-android-supported-abis.qdocinc +The typical directory structure looks as below: +\badcode +/path/to/Qt/6.x.x + android_armv7 + android_arm64_v8a + android_x86 + android_x86_64 + ... +\endcode +The auto-detected paths can be customized using one of \c{QT_PATH_ANDROID_ABI_<ABI>} variables. + +The variable is set to \c FALSE by default. + +\sa{QT_PATH_ANDROID_ABI_<ABI>} +*/ + +/*! +\page cmake-variable-qt-android-abis.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_ABIS +\target cmake-variable-QT_ANDROID_ABIS + +\summary {List of ABIs that the project packages are built for.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +Specifies a list of ABIs to be used to build the project packages. +\include cmake-android-supported-abis.qdocinc +Each ABI should have the corresponding Qt for Android either installed or +user-built. To specify the path to the Qt for Android ABI, use +the corresponding \c{QT_PATH_ANDROID_ABI_<ABI>} variable. + +\note \c{QT_ANDROID_BUILD_ALL_ABIS} has the higher priority and ignores the +QT_ANDROID_ABIS logic. + +\sa{QT_PATH_ANDROID_ABI_<ABI>}, {QT_ANDROID_BUILD_ALL_ABIS} +*/ + +/*! +\page cmake-variable-qt-path-android-abi.html +\ingroup cmake-variables-qtcore + +\title QT_PATH_ANDROID_ABI_<ABI> +\target cmake-variable-QT_PATH_ANDROID_ABI_<ABI> + +\summary {Set of variables to specify the path to Qt for Android for the corresponding ABI.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +Each variable can be used to specify the path to Qt for Android for the corresponding ABI. +\include cmake-android-supported-abis.qdocinc + +\sa{cmake-variable-QT_ANDROID_ABIS}{QT_ANDROID_ABIS} +*/ + +/*! +\page cmake-variable-qt-android-sign-aab.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_SIGN_AAB +\target cmake-variable-QT_ANDROID_SIGN_AAB + +\summary {Signs the .aab package with the specified keystore, alias, and store password.} +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableandroidonly + +Signs the resulting package. The path of the keystore file, the alias of the key, and passwords +have to be specified by additional environment variables: +\badcode + QT_ANDROID_KEYSTORE_PATH + QT_ANDROID_KEYSTORE_ALIAS + QT_ANDROID_KEYSTORE_STORE_PASS + QT_ANDROID_KEYSTORE_KEY_PASS +\endcode +The mentioned variables are used internally by \l{androiddeployqt}. + +\sa{androiddeployqt} +*/ + +/*! +\page cmake-variable-qt-android-sign-apk.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_SIGN_APK +\target cmake-variable-QT_ANDROID_SIGN_APK + +\summary {Signs the package with the specified keystore, alias, and store password.} +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableandroidonly + +Signs the resulting package. The path of the keystore file, the alias of the key, and passwords +have to be specified by additional environment variables: +\badcode + QT_ANDROID_KEYSTORE_PATH + QT_ANDROID_KEYSTORE_ALIAS + QT_ANDROID_KEYSTORE_STORE_PASS + QT_ANDROID_KEYSTORE_KEY_PASS +\endcode +The mentioned variables are used internally by \l{androiddeployqt}. + +\sa{androiddeployqt} +*/ + +/*! +\page cmake-variable-qt-use-target-android-build-dir.html +\ingroup cmake-variables-qtcore + +\title QT_USE_TARGET_ANDROID_BUILD_DIR +\target cmake-variable-QT_USE_TARGET_ANDROID_BUILD_DIR + +\summary {Enables the use of per-target Android build directories.} + +\cmakevariablesince 6.7 +\preliminarycmakevariable +\cmakevariableandroidonly + +The variable appends the target-specific suffix to the android-build directory. +The variable only takes an effect when it's set in \c CACHE. The variable is +only supported by Qt Creator starting from version 13. +If a single \c CMakeLists.txt contains more than one Android executable and +this option is not set, you will see a warning. To disable the warning, set +\c QT_SKIP_ANDROID_BUILD_DIR_CHECK to \c TRUE. +*/ + +/*! +\page cmake-variable-qt-no-collect-build-tree-apk-deps.html +\ingroup cmake-variables-qtcore + +\title QT_NO_COLLECT_BUILD_TREE_APK_DEPS +\target cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS + +\summary {Prevents collecting of project-built shared library targets during Android deployment.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +During project finalization, the build system collects the locations of +all built shared library targets in the project. +These locations are passed to \l androiddeployqt for deployment consideration when +resolving dependencies between libraries. +To disable this behavior, set this variable to \c TRUE. + +\sa {qt6_finalize_project}{qt_finalize_project()} +\sa {cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS}{QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS} +*/ + +/*! +\page cmake-variable-qt-no-collect-imported-target-apk-deps.html +\ingroup cmake-variables-qtcore + +\title QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS +\target cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS + +\summary {Prevents collecting of imported targets during Android deployment.} + +\cmakevariablesince 6.5 +\preliminarycmakevariable +\cmakevariableandroidonly + +When using CMake version 3.21 or later, the build system collects the locations of +imported shared library targets that might be relevant for deployment. +The collected targets are those that are reachable from the directory scope +of the currently processed executable target. That includes the target's source directory +scope and its parents. +The collected locations are passed to \l androiddeployqt for deployment consideration when +resolving dependencies between libraries. +To disable this behavior, set this variable to \c TRUE. + +\sa {qt6_finalize_project}{qt_finalize_project()} +\sa {cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS}{QT_NO_COLLECT_BUILD_TREE_APK_DEPS} +*/ + +/*! +\page cmake-variable-qt-host-path.html +\ingroup cmake-variables-qtcore + +\title QT_HOST_PATH +\target cmake-variable-QT_HOST_PATH + +\summary {Location of the host Qt installation when cross-compiling.} + +\cmakevariablesince 6.0 + +When cross-compiling, this variable must be set to the install location of Qt for the host +platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc}, +\l{androiddeployqt}, and so on). It's possible to reuse pre-installed tools +when compiling Qt for host systems too, by using \c QT_HOST_PATH that points to +a pre-installed host Qt and setting the \c QT_FORCE_FIND_TOOLS to \c ON. The Qt +versions should match in this case. +*/ + +/*! +\page cmake-variable-qt-no-set-xcode-development-team-id.html +\ingroup cmake-variables-qtcore + +\title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID +\target cmake-variable-QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID + +\summary {Disables providing a fallback team ID during target finalization on iOS.} + +\cmakevariablesince 6.1 + +When finalizing an executable target on iOS, +\l{qt6_finalize_target}{qt_finalize_target()} will populate the target's +\c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM property if it hasn't been set. +To prevent this, set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to \c TRUE. +*/ + +/*! +\page cmake-variable-qt-no-set-xcode-bundle-identifier.html +\ingroup cmake-variables-qtcore + +\title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER +\target cmake-variable-QT_NO_SET_XCODE_BUNDLE_IDENTIFIER + +\summary {Disables providing a fallback app bundle ID during target finalization on iOS.} + +\cmakevariablesince 6.1 + +When finalizing an executable target on iOS, +\l{qt6_finalize_target}{qt_finalize_target()} will populate the target's +\c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER and +\c MACOSX_BUNDLE_GUI_IDENTIFIER properties if they haven't been set. +To prevent this, set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to \c TRUE. +*/ + +/*! +\page cmake-variable-qt-enable-verbose-deployment.html +\ingroup cmake-variables-qtcore + +\title QT_ENABLE_VERBOSE_DEPLOYMENT +\target cmake-variable-QT_ENABLE_VERBOSE_DEPLOYMENT + +\summary {Enables verbose mode of deployment tools.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable + +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{qt6_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-qtcore + +\title QT_DEPLOY_SUPPORT +\target cmake-variable-QT_DEPLOY_SUPPORT + +\summary {Name of the file to include for setting up deployment support.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\note The value of this variable should never be modified by project code. + +This configure-phase variable is set by the Core package. It is intended to be +used as the first line of any deployment script to ensure access to the +deployment APIs provided by Qt. Such deployment 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-modified-variable-values.qdocinc + +\sa {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, + {qt6_deploy_qml_imports}{qt_deploy_qml_imports()} +*/ + +/*! +\page cmake-variable-qt-no-standard-project-setup.html +\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.} + +\cmakevariablesince 6.3 + +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 a project 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 \c 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()} +*/ + +/*! +\page cmake-variable-qt-i18n-languages.html +\ingroup cmake-variables-qtcore + +\title QT_I18N_TRANSLATED_LANGUAGES +\target cmake-variable-QT_I18N_TRANSLATED_LANGUAGES + +\summary {List of languages to be used for project internationalization.} + +\cmakevariablesince 6.7 + +Specifies a list of languages that are used for project +internationalization. The single languages must be compatible with the +string-based \l QLocale constructor. + +The languages in \c QT_I18N_TRANSLATED_LANGUAGES are used to: +\list + \li Set up executable targets for consuming \c{.qm} files. + \li Automatically construct \c{.ts} file names in + \l{qt6_add_translations}{qt_add_translations()}. +\endlist + +This variable can be conveniently set with the +\l {qt6_standard_project_setup}{qt_standard_project_setup()} command. + +By default, translatable strings are considered to be written in \c{en}. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()} +\sa {qt6_add_translations}{qt_add_translations()} +*/ + +/*! +\page cmake-variable-qt-i18n-native-language.html +\ingroup cmake-variables-qtcore + +\title QT_I18N_SOURCE_LANGUAGE +\target cmake-variable-QT_I18N_SOURCE_LANGUAGE + +\summary {Specifies the language of translatable strings.} + +\cmakevariablesince 6.7 + +Specifies the language of translatable strings in the source code. +The language must be compatible with the string-based \l QLocale constructor. + +Together with \c{QT_I18N_TRANSLATED_LANGUAGES}, this variable is used to determine the +names of \c{.ts} files for \l{qt6_add_translations}{qt_add_translations()}. + +This variable can be conveniently set with the +\l {qt6_standard_project_setup}{qt_standard_project_setup()} command. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()} +\sa {qt6_add_translations}{qt_add_translations()} +*/ + +/*! +\page cmake-variable-qt-ios-launch-screen.html +\ingroup cmake-variables-qtcore + +\title QT_IOS_LAUNCH_SCREEN +\target cmake-variable-QT_IOS_LAUNCH_SCREEN + +\summary {Path to iOS launch screen storyboard used by all targets.} + +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableiosonly + +Specifies the path to an iOS launch screen storyboard file that will be used +by all targets within a project. + +\sa {Launch Screens and Launch Images} +*/ 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 +*/ diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc new file mode 100644 index 0000000000..8fe2b0e88f --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc @@ -0,0 +1,637 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group cmake-target-properties-qtcore +\title CMake Target Properties in Qt6 Core +\brief Lists CMake target properties known to Qt6::Core. + +\l{CMake Commands in Qt6 Core}{CMake Commands} know about the following CMake +target properties: + +\sa{CMake Property Reference} +*/ + +/*! +\page cmake-target-property-qt-android-deployment-dependencies.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_DEPLOYMENT_DEPENDENCIES +\target cmake-target-property-QT_ANDROID_DEPLOYMENT_DEPENDENCIES + +\brief Overrides the Qt dependencies added to the target's deployment. + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +By default, \l androiddeployqt will detect the dependencies of your +application. However, since run-time usage of plugins cannot be detected, +there could be false positives, as your application might depend on any +plugin that is a potential dependency. If you want to minimize the size of +your \c APK, it's possible to override the automatic detection using this +property. This should contain a list of all Qt files which need to be +included, with paths relative to the Qt install root. + +\note Only the Qt files specified with this variable are included. Failing +to include all the correct files can result in crashes. It's also important +to make sure the files are listed in the correct loading order. This variable +provides a way to override the automatic detection entirely, so if a library +is listed before its dependencies, it will fail to load on some devices. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-extra-libs.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_EXTRA_LIBS +\target cmake-target-property-QT_ANDROID_EXTRA_LIBS + +\summary {Extra libraries to deploy with the target.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +A list of external libraries that will be copied into your application's +\c libs folder and loaded on start-up. This can be used, for instance, +to enable OpenSSL in your application. For more information, see +\l{Adding OpenSSL Support for Android}. + +When adding extra libraries from the build tree of your project, it's also +necessary to add dependency relations between library and the application +target. Using the following project structure may cause an issue, when deploying +an apk: +\badcode +qt_add_executable(MyApp main.cpp) + +set_target_properties(MyApp PROPERTIES + QT_ANDROID_EXTRA_LIBS + ${CMAKE_CURRENT_BINARY_DIR}/libMyService_${ANDROID_ABI}.so +) + +# MyService library doesn't have any relations with MyApp +qt_add_library(MyService service.cpp) +\endcode + +This leads to uncertainty whether MyService library will be available before +the deployment of MyApp or not. The easiest solution is adding MyService +library to the MyApp dependencies: +\badcode +add_dependencies(MyApp MyService) +\endcode + +When adding per-architecture libraries to a multi-abi project, +list all their paths explicitly, rather than rely on variables like +\c CMAKE_ANDROID_ARCH_ABI to dynamically compute the paths. + +Prefer: + +\badcode +set(libs + ${CMAKE_CURRENT_BINARY_DIR}/libA_x86so + ${CMAKE_CURRENT_BINARY_DIR}/libA_x86_64.so + ${CMAKE_CURRENT_BINARY_DIR}/libA_arm64-v8a.so + ${CMAKE_CURRENT_BINARY_DIR}/libA_armeabi-v7a.so +) +set_target_properties(MyApp PROPERTIES QT_ANDROID_EXTRA_LIBS ${libs}) + +# When targeting precompiled libs +target_link_libraries(${CMAKE_PROJECT_NAME} PUBLIC libA_${ANDROID_ABI}) +\endcode + +over: + +\badcode +set_target_properties(MyApp PROPERTIES + QT_ANDROID_EXTRA_LIBS + ${CMAKE_CURRENT_BINARY_DIR}/libA_${CMAKE_ANDROID_ARCH_ABI}.so) +\endcode + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-extra-plugins.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_EXTRA_PLUGINS +\target cmake-target-property-QT_ANDROID_EXTRA_PLUGINS + +\summary {Extra Qt plugins to deploy with the target.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies a path to C++ plugins or resources that your application has to bundle +but that cannot be delivered through the assets system, such as QML plugins. +With this variable, \l androiddeployqt will make sure everything is packaged +and deployed properly. + +\c QT_ANDROID_EXTRA_PLUGINS must point to the directory where the extra plugin(s) +are built. In addition, the build directory structure must follow a naming +convention similar to Qt plugins, that is, \e {plugins/<plugin name>}. +\c QT_ANDROID_EXTRA_PLUGINS should point to the \e {plugins} part of that path. + +The plugins libraries should have the name format +\e {libplugins_<type>_<name>_<abi>.so}. This will ensure that the correct name +mangling is applied to the plugin library. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-min-sdk-version.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_MIN_SDK_VERSION +\target cmake-target-property-QT_ANDROID_MIN_SDK_VERSION + +\summary {Minimum Android SDK version.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the minimum Android API level for the target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-package-source-dir.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_PACKAGE_SOURCE_DIR +\target cmake-target-property-QT_ANDROID_PACKAGE_SOURCE_DIR + +\summary {Path to a custom Android package template.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the path for a custom Android package template. The Android package +template contains: +\list + \li AndroidManifest.xml file + \li build.gradle file and other Gradle scripts + \li res/values/libs.xml file +\endlist + +The path specified by this variable can contain custom Java classes under +\c src directory. By default, the \l androiddeployqt tool copies the +application template from the Qt for Android installation path into your +project's build directory, then it copies the contents of the path specified +by this variable on top of that, overwriting any existing files. For +instance, you can make a custom \c {AndroidManifest.xml} for your application, +then place this directly into the directory specified by this variable. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-target-sdk-version.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_TARGET_SDK_VERSION +\target cmake-target-property-QT_ANDROID_TARGET_SDK_VERSION + +\summary {Android target SDK version.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the target Android API level for the target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-sdk-build-tools-revision.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_SDK_BUILD_TOOLS_REVISION +\target cmake-target-property-QT_ANDROID_SDK_BUILD_TOOLS_REVISION + +\summary {Revision of Android build tools to use.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the Android SDK build tools revision to use. If this is not set then +CMake will attempt to use the latest installed version. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-version-code.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_ANDROID_VERSION_CODE +\target cmake-target-property-QT_ANDROID_VERSION_CODE +\ingroup cmake-android-manifest-properties + +\summary {Internal Android app version.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the app's version number. This is usually a number that +increments monotonically with each release of your project. + +For more information, see \l{Android: App Versioning}{Android App Versioning}. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-version-name.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_ANDROID_VERSION_NAME +\target cmake-target-property-QT_ANDROID_VERSION_NAME +\ingroup cmake-android-manifest-properties + +\summary {Human-readable Android app version.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the app's version as a human readable string, usually three +numbers, separated by dots. + +For more information, see \l{Android: App Versioning}{Android App Versioning}. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-abis.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_ABIS +\target cmake-target-property-QT_ANDROID_ABIS + +\summary {List of ABIs that packages of a single target are built for.} + +\cmakepropertysince 6.3 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +By setting the \c{QT_ANDROID_ABIS} property for a target, it's possible to control +the list of ABIs that the single target packages are supposed to be built for. +\include cmake-android-supported-abis.qdocinc +The property only affects targets created with +\l{qt6_add_executable}{qt_add_executable()}. + +\sa{cmake-variable-QT_ANDROID_ABIS}{QT_ANDROID_ABIS}, {QT_ANDROID_BUILD_ALL_ABIS} +*/ + +/*! +\page cmake-target-property-qt-qml-root-path.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_QML_ROOT_PATH +\target cmake-target-property-QT_QML_ROOT_PATH + +\summary {Overrides the location of the application's qml directory.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty + +This property is currently only used when generating a deployment settings file +for Android. If the property is set, it specifies the path to the application's +\c{qml} directory. If it is not set, the \c{SOURCE_DIR} property of the target +will be used instead. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-qml-import-path.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_QML_IMPORT_PATH +\target cmake-target-property-QT_QML_IMPORT_PATH + +\summary {Specifies a list of directories to search for QML imports.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty + +This property is currently only used when generating a deployment settings file +for Android. It typically contains just the path to Qt's \c{qml} directory, but +it can be a list that contains other locations to be searched as well. +For application-specific QML imports, use +\l{cmake-target-property-QT_QML_ROOT_PATH}{QT_QML_ROOT_PATH} instead. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-deployment-settings-file.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_DEPLOYMENT_SETTINGS_FILE +\target cmake-target-property-QT_ANDROID_DEPLOYMENT_SETTINGS_FILE + +\summary {Specifies the location of a target's generated deployment settings file.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +This property will be set by +\l{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}. +Projects should not try to set this property themselves, as it will be ignored +and overwritten by that command. +*/ + +/*! +\page cmake-target-property-qt-android-system-libs-prefix.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_SYSTEM_LIBS_PREFIX +\target cmake-target-property-QT_ANDROID_SYSTEM_LIBS_PREFIX + +\summary {Specifies the location of Qt libraries on the target device.} + +\preliminarycmakeproperty +\cmakepropertyandroidonly + +This property can be set to provide a path to Qt libraries on the target device, +when those libraries are installed outside app's native (JNI) library directory. +*/ + +/*! +\page cmake-target-property-qt-android-no-deploy-qt-libs.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_NO_DEPLOY_QT_LIBS +\target cmake-target-property-QT_ANDROID_NO_DEPLOY_QT_LIBS + +\summary {Whether Qt shared libraries are packaged in the APK on Android.} + +\preliminarycmakeproperty +\cmakepropertyandroidonly + +This property can be set to not package Qt shared libraries inside the APK when +deploying the target. Use +\l{cmake-target-property-QT_ANDROID_SYSTEM_LIBS_PREFIX}{QT_ANDROID_SYSTEM_LIBS_PREFIX} +to provide a path to where those libraries will be located on the target device +instead. + +\note Only supported when deploying as an APK. +*/ + +/*! +\page cmake-target-property-qt-no-entrypoint.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title qt_no_entrypoint +\target cmake-target-property-qt_no_entrypoint + +\summary {Specifies to inhibit linking against Qt's entrypoint lib.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty + +On certain platforms, Qt applications link against Qt's entrypoint lib by default. +That library provides implementations of main (or WinMain). + +On targets that must provide their own entry point, set the property \c qt_no_entrypoint to inhibit linking against Qt's entrypoint library. +*/ + +/*! +\page cmake-target-property-qt-resource-prefix.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_RESOURCE_PREFIX +\target cmake-target-property-QT_RESOURCE_PREFIX + +\summary {Specifies the default Qt resource prefix.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty + +When using \l{qt6_add_resources}{qt_add_resources} without a \c PREFIX +argument, then the value of this target property will be used as +resource prefix. +*/ + +/*! +\group cmake-source-file-properties-qtcore +\title CMake Source File Properties in Qt6 Core +\brief Lists CMake file properties used in Qt6::Core. + +\l{CMake Commands in Qt6 Core}{CMake Commands} know about the following CMake +source file properties: + +\sa{CMake Property Reference} +*/ + +/*! +\page cmake-source-file-property-qt-resource-alias.html +\ingroup cmake-source-file-properties-qtcore + +\title QT_RESOURCE_ALIAS +\target cmake-source-file-property-QT_RESOURCE_ALIAS + +\summary {Specifies the Qt resource alias for a file in a resource.} + +\cmakepropertysince 6.0 + +When using the target-based variant of \l{qt6_add_resources}{qt_add_resources} +the property value overrides the runtime path where the resource file is found. + +\sa{The Qt Resource System} +*/ + +/*! +\page cmake-source-file-property-qt-discard-file-contents.html +\ingroup cmake-source-file-properties-qtcore + +\title QT_DISCARD_FILE_CONTENTS +\target cmake-source-file-property-QT_DISCARD_FILE_CONTENTS + +\summary {Specifies that the given files should be empty in the resource file system} + +\cmakepropertysince 6.6 +\preliminarycmakeproperty + +When using the target-based variant of \l{qt6_add_resources}{qt_add_resources} +or \l{qt_add_qml_module}, setting this property to \c TRUE causes the file +contents to be omitted when creating the resource file system. The file name is +retained. + +This is useful if you want to strip QML source code from the binary. + +\note If you omit the QML source code from the binary, the QML engine has to +rely on the compilation units created by \l{qmlcachegen} or \l{qmlsc}. +Those are tied to the specific version of Qt they were built with. If you change +the version of Qt your application uses, they can't be loaded anymore. + +\sa{The Qt Resource System} +*/ + +/*! +\page cmake-target-property-qt-wasm-pthread-pool-size.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_WASM_PTHREAD_POOL_SIZE +\target cmake-target-property-QT_WASM_PTHREAD_POOL_SIZE + +\summary {Internal WebAssembly thread pool size.} + +\cmakepropertysince 6.2.4 +\preliminarycmakeproperty +\cmakepropertywebassemblyonly + +Specifies the number of web workers (threads) to create at application startup. +Qt allocates a pool size of 4 by default. This means the app can use +4 additional threads besides the main thread, without the additional overhead +of creating a new web worker, which may deadlock if the main thread created it +and join()s the thread without returning control to the event loop first. +Translates into the Emscripten compiler setting of PTHREAD_POOL_SIZE. + +For more information, see \l{https://emscripten.org/docs/porting/pthreads.html}{Pthreads support}. +*/ + +/*! +\group cmake-global-properties-qtcore +\title CMake Global Properties in Qt6 Core +\brief Lists CMake global properties used or defined in Qt6::Core. + +\l{CMake Commands in Qt6 Core}{CMake Commands} know about the following global +CMake properties: + +\sa{CMake Property Reference} +*/ + +/*! +\page cmake-global-property-qt-targets-folder.html +\ingroup cmake-properties-qtcore +\ingroup cmake-global-properties-qtcore + +\title QT_TARGETS_FOLDER +\target cmake-global-property-QT_TARGETS_FOLDER + +\brief Sets the FOLDER property for Qt-internal targets. + +\cmakepropertysince 6.5 +\preliminarycmakeproperty + +Name of the \l FOLDER for internal targets that are added by Qt's CMake +commands. + +By default, this property is not set. + +This property only has an effect if CMake's \l USE_FOLDERS property is \c{ON}. + +You can use the \l{qt6_standard_project_setup}{qt_standard_project_setup} +function to enable folder support and initialize the \c{QT_TARGETS_FOLDER}. + +\sa{qt6_standard_project_setup}{qt_standard_project_setup} +*/ + +/*! +\page cmake-target-property-qt-wasm-initial-memory.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_WASM_INITIAL_MEMORY +\target cmake-target-property-QT_WASM_INITIAL_MEMORY + +\summary {Internal WebAssembly initial memory.} + +\cmakepropertysince 6.2.4 +\preliminarycmakeproperty +\cmakepropertywebassemblyonly + +Specifies the initial amount of memory to use, in bytes. Using more will cause the +browser to copy the old heap into a new one. Translates into the +Emscripten compiler setting of INITIAL_MEMORY. +QT_WASM_INITIAL_MEMORY must be a multiple of 65536 bytes. + +For more information, see \l{https://github.com/emscripten-core/emscripten/blob/main/src/settings.js}{Emscripten compiler settings}. +*/ + +/*! +\page cmake-target-property-qt-wasm-maximum-memory.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_WASM_MAXIMUM_MEMORY +\target cmake-target-property-QT_WASM_MAXIMUM_MEMORY + +\summary {Internal WebAssembly maximum memory.} + +\cmakepropertysince 6.7 +\preliminarycmakeproperty +\cmakepropertywebassemblyonly + +Specifies the maximum amount of memory the application can use. Translates into +the Emscripten compiler setting of \c MAXIMUM_MEMORY. The default value +is 4GB, which is the maximum for 32-bit WebAssembly. + +For more information, see the \l{https://github.com/emscripten-core/emscripten/blob/3319a313d3b589624d342b650884caaf8cd9ef30/src/settings.js#L187}{Emscripten compiler settings}. +*/ + + + +/*! +\page cmake-target-property-qt-ios-launch-screen.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_IOS_LAUNCH_SCREEN +\target cmake-target-property-QT_IOS_LAUNCH_SCREEN + +\summary {Path to iOS launch screen storyboard} + +\cmakepropertysince 6.4 +\preliminarycmakeproperty +\cmakepropertyiosonly + +Specifies the path to an iOS launch screen storyboard file. + +\sa {Launch Screens and Launch Images} +*/ diff --git a/src/corelib/doc/src/cmake/cmake-standard-properties.qdoc b/src/corelib/doc/src/cmake/cmake-standard-properties.qdoc new file mode 100644 index 0000000000..a8ece6ba8f --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-standard-properties.qdoc @@ -0,0 +1,24 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page cmake-standard-property-autogen-better-graph-multi-config.html +\ingroup cmake-standard-properties + +\title AUTOGEN_BETTER_GRAPH_MULTI_CONFIG + +\brief Improves the dependency graph for multi-configuration generators when you +set it on a target. + +When this boolean property is enabled, \c{CMake} will generate more per-config targets. +Thus, the dependency graph will be more accurate for multi-configuration +generators and some recompilations will be avoided. + +Since Qt 6.8, this property is enabled by default. For older versions, +you need to enable it manually to use it. +However, \l{qt_extract_metatypes} and \l{qt_add_qml_module} were updated to +support \c{AUTOGEN_BETTER_GRAPH_MULTI_CONFIG} in Qt 6.8, so you will get build +errors, unless you patch the older Qt version to support it. + +See \l{https://cmake.org/cmake/help/latest/prop_tgt/AUTOGEN_BETTER_GRAPH_MULTI_CONFIG.html}{AUTOGEN_BETTER_GRAPH_MULTI_CONFIG} for more information. +*/ diff --git a/src/corelib/doc/src/cmake/policy/qtp0002.qdoc b/src/corelib/doc/src/cmake/policy/qtp0002.qdoc new file mode 100644 index 0000000000..a40344a167 --- /dev/null +++ b/src/corelib/doc/src/cmake/policy/qtp0002.qdoc @@ -0,0 +1,63 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0002.html +\ingroup qt-cmake-policies + +\title QTP0002 +\keyword qt_cmake_policy_qtp0002 + +\summary {Target properties that specify Android-specific paths may contain generator expressions.} + +This policy was introduced in Qt 6.6. It changes the processing of target +properties that specify Android-specific paths: +\list + \li \l QT_QML_IMPORT_PATH + \li \l QT_QML_ROOT_PATH + \li \l QT_ANDROID_PACKAGE_SOURCE_DIR + \li \l QT_ANDROID_EXTRA_PLUGINS + \li \l QT_ANDROID_EXTRA_LIBS +\endlist + +The \c OLD behavior of this policy doesn't allow generator expressions in the +target properties that specify Android-specific paths but implicitly converts +the specified paths to valid JSON strings. + +The \c NEW behavior of this policy allows using generator expressions in the +target properties that specify Android-specific paths, but they must evaluate to +valid JSON strings. + +The following value of the \l QT_ANDROID_EXTRA_PLUGINS property is converted to +a valid JSON string if you set the policy to OLD, but leads to an error if the +policy is set to NEW: +\badcode +set_target_properties( + QT_ANDROID_EXTRA_PLUGINS "\\path\\to\\MyPlugin.so" +) +\endcode +If the policy is set to NEW for the above example, the resulting JSON string in +the deployment settings file will contain escaped symbols instead of path +separators. + +Generator expressions are only supported if the policy is set to NEW, so the +OLD behavior generates a malformed deployment settings file with the following +code: +\badcode +set_target_properties( + QT_ANDROID_EXTRA_PLUGINS "$<TARGET_FILE_DIR:MyPlugin>" +) +\endcode + +This property value works as expected with both OLD and NEW policy values: +\badcode +set_target_properties( + QT_ANDROID_EXTRA_PLUGINS "/path/to/MyPlugin.so" +) +\endcode + +\qtpolicydeprecatedbehavior + +\sa qt_policy, {Qt CMake policies} + +*/ diff --git a/src/corelib/doc/src/cmake/policy/qtp0003.qdoc b/src/corelib/doc/src/cmake/policy/qtp0003.qdoc new file mode 100644 index 0000000000..bf11b6f8b5 --- /dev/null +++ b/src/corelib/doc/src/cmake/policy/qtp0003.qdoc @@ -0,0 +1,46 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0003.html +\ingroup qt-cmake-policies +\since 6.7 +\title QTP0003 +\keyword qt_cmake_policy_qtp0003 + +\summary {Consider the BUILD_SHARED_LIBS value when creating Qt libraries.} + +This policy was introduced in Qt 6.7. The policy affects the default type of the +libraries created using \l {CMake Commands in Qt6 Core}{Qt CMake API}, like +\l {qt_add_library}, \l{qt_add_plugin}, \l{qt_add_qml_module}. + +If the policy is set to \c OLD, the default library type that is selected is +aligned with the Qt build type, either \c shared or \c static. + +If the policy is set to \c NEW, the library type is selected according to the +\l {CMake BUILD_SHARED_LIBS Documentation}{BUILD_SHARED_LIBS} value if it's set. +If \c BUILD_SHARED_LIBS is not set, the default library type falls back to the +Qt build type. + +For example, the following code will use the Qt build type as the default +library type for the \c MyLib target, despite the fact \c BUILD_SHARED_LIBS is +set to \c ON: +\badcode +set(BUILD_SHARED_LIBS ON) +... +qt6_add_library(MyLib sourcefile.h sourcefile.cpp) +\endcode + +If you set the QTP0003 to \c NEW before the \l {qt6_add_library}{qt_add_library} +call, \c BUILD_SHARED_LIBS will affect the library default type and \c MyLib +will be the shared library. +\badcode +set(BUILD_SHARED_LIBS ON) +... +qt_policy(SET QTP0003 NEW) +qt6_add_library(MyLib sourcefile.h sourcefile.cpp) +\endcode + +\sa qt_policy, {Qt CMake policies}, qt_add_library + +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc new file mode 100644 index 0000000000..8215d4c717 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc @@ -0,0 +1,53 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-bigresources.html +\ingroup cmake-commands-qtcore + +\title qt_add_big_resources +\keyword qt6_add_big_resources + +\summary {Compiles big binary resources into object code.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.12 + +\section1 Synopsis + +\badcode +qt_add_big_resources(<VAR> file1.qrc [file2.qrc ...] + [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_big_resources() + +\section1 Description + +Creates compiled object files from Qt resource files using the +\l{Resource Compiler (rcc)}. Paths to the generated files are added to +\c{<VAR>}. + +This is similar to \l qt_add_resources, but directly +generates object files (\c .o, \c .obj) files instead of C++ source code. +This allows to embed bigger resources, where compiling to C++ sources and then +to binaries would be too time consuming or memory intensive. + +\note The \c{file1.qrc} will not be treated as a source file by Qt Creator. It +needs to be added as a source file to a CMake target and have the property +\c{SKIP_AUTORCC} set to \c{ON}. + +\warning This command is not supported when building for iOS, use +\l qt_add_resources instead. +See \l{https://bugreports.qt.io/browse/QTBUG-103497}{QTBUG-103497} for details. + +\section1 Arguments + +You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. +You can find possible options in the \l{rcc}{rcc documentation}. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_add_big_resources +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc new file mode 100644 index 0000000000..12ee5e1aff --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc @@ -0,0 +1,43 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-binary-resources.html +\ingroup cmake-commands-qtcore + +\title qt_add_binary_resources +\keyword qt6_add_binary_resources + +\summary {Creates an RCC file from a list of Qt resource files.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.10 + +\section1 Synopsis + +\badcode +qt_add_binary_resources(target file1.qrc [file2.qrc ...] + [DESTINATION ...] + [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_binary_resources() + +\section1 Description + +Adds a custom \c target that compiles Qt resource files into a binary \c{.rcc} +file. + +\section1 Arguments + +\c{DESTINATION} sets the path of the generated \c{.rcc} file. The default is +\c{${CMAKE_CURRENT_BINARY_DIR}/${target}.rcc}. + +You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. +You can find possible options in the \l{rcc}{rcc documentation}. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_add_binary_resources +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_executable.qdoc b/src/corelib/doc/src/cmake/qt_add_executable.qdoc new file mode 100644 index 0000000000..cc8c924c79 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_executable.qdoc @@ -0,0 +1,114 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-executable.html +\ingroup cmake-commands-qtcore + +\title qt_add_executable +\keyword qt6_add_executable + +\summary {Creates and finalizes an application target of a platform-specific type.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_add_executable(target + [WIN32] [MACOSX_BUNDLE] + [MANUAL_FINALIZATION] + sources...) +\endcode + +\versionlessCMakeCommandsNote qt6_add_executable() + +\section1 Description + +This command performs the following tasks: + +\list +\li Create a CMake target of the appropriate type for the target platform. +\li Link the target to the \c{Qt::Core} library. +\li Handle finalization of the CMake target. +\endlist + +\section2 Target Creation + +On all platforms except Android, an executable target will be created. +All arguments will be passed through to the standard CMake \c{add_executable()} +command, except \c{MANUAL_FINALIZATION} (if present). On Android, a \c{MODULE} +library will be created and any \c{WIN32} or \c{MACOSX_BUNDLE} options will be +ignored. Some target properties will also be set for Android: + +\list +\li The \c{SUFFIX} target property will be set to give the library file name an + architecture-specific suffix. +\li Various \c{<lang>_VISIBILITY_PRESET} target properties will be set to + \c{default} to ensure that the \c{main()} function is visible in the + resultant binary. +\endlist + +\section2 Linking Qt::Core + +Since all Qt applications need to link to the \c{Qt::Core} library, this is done +for you as a convenience. + +\section2 Finalization + +After a target is created, further processing or \e{finalization} steps are +commonly needed. The steps to perform depend on the platform and on various +properties of the target. + +The finalization processing is implemented by two commands: +\l{qt6_finalize_target}{qt_finalize_target()} and +\l{qt6_finalize_project}{qt_finalize_project()}. + +Target finalization can occur either as part of calling \c{qt_add_executable} +or be deferred to sometime after this command returns (but it should still be in +the same directory scope). + +When using CMake 3.19 or later, target finalization is automatically deferred to the +end of the current directory scope. This gives the caller an opportunity to +modify properties of the created target before it is finalized. When using +CMake versions earlier than 3.19, automatic deferral isn't supported. In that +case, target finalization is performed immediately before this command returns. + +Regardless of the CMake version, the \c{MANUAL_FINALIZATION} keyword can be given to +indicate that you will explicitly call \l{qt6_finalize_target}{qt_finalize_target()} +yourself instead at some later time. In general, \c MANUAL_FINALIZATION should +not be needed unless the project has to support CMake 3.18 or earlier. + +Project finalization occurs automatically when using CMake 3.19 or later. +When using an older CMake version, you should call +\l{qt6_finalize_project}{qt_finalize_project()} manually, at the end +of the root \c CMakeLists.txt file. +This is especially important when targeting Android, to collect dependencies +between project targets for deployment purposes. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_set_finalizer_mode}{qt_set_finalizer_mode()}, + {qt6_add_library}{qt_add_library()}, + {qt6_finalize_project}{qt_finalize_project()} + +\section1 Examples + +In the following simple case, finalization is handled automatically. If using a +CMake version earlier than 3.19, finalization will be performed immediately as +part of the call. When using CMake 3.19 or later, finalization will occur at the +end of the current directory scope. + +\snippet cmake-macros/examples.cmake qt_add_executable_simple + +The following example shows a scenario where finalization must be deferred. +The \c OUTPUT_NAME target property affects deployment settings on Android, but +those settings are written out as part of finalizing the target. In order to +support using CMake versions earlier than 3.19, we take over responsibility +for finalizing the target by adding the \c{MANUAL_FINALIZATION} keyword. + +\snippet cmake-macros/examples.cmake qt_add_executable_deferred + +\include cmake-android-qt-finalize-project-warning.qdocinc warning +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_library.qdoc b/src/corelib/doc/src/cmake/qt_add_library.qdoc new file mode 100644 index 0000000000..851a2d6210 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_library.qdoc @@ -0,0 +1,80 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-library.html +\ingroup cmake-commands-qtcore + +\title qt_add_library +\keyword qt6_add_library + +\summary {Creates and finalizes a library.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_add_library(target + [STATIC | SHARED | MODULE | INTERFACE | OBJECT] + [MANUAL_FINALIZATION] + sources... +) +\endcode + +\versionlessCMakeCommandsNote qt6_add_library() + +\section1 Description + +\c{qt_add_library()} is a wrapper around CMake's built-in +\c{add_library()} command. It performs the following tasks: + +\list +\li Create a CMake target of an appropriate library type. +\li Handle finalization of the CMake target. +\endlist + +\section2 Target Creation + +The type of library created can be specified explicitly with one of the +\c STATIC, \c SHARED, \c MODULE, \c INTERFACE or \c OBJECT keywords, just as +one might for \c{add_library()}. If none of these keywords are given, the +library type created depends on how Qt was built. If Qt was built statically, +a static library will be created. Otherwise, a shared library will +be created. Note that this is different to how CMake's \c{add_library()} +command works, where the \c BUILD_SHARED_LIBS variable controls the type of +library created. +Since 6.7, the \c{qt_add_library()} command considers \c BUILD_SHARED_LIBS +when deciding the library type only if the variable is set explicitly and +\l {QTP0003} is set to \c NEW. + +Any \c{sources} provided will be passed through to the internal call to +\c{add_library()}. + +\target qt_add_library finalization +\section2 Finalization + +After a target is created, further processing or \e{finalization} steps may be +needed. The finalization processing is implemented by the +\l{qt6_finalize_target}{qt_finalize_target()} command. + +Finalization can occur either as part of this call or be deferred to sometime +after this command returns (but it should still be in the same directory scope). +When using CMake 3.19 or later, finalization is automatically deferred to the +end of the current directory scope. This gives the caller an opportunity to +modify properties of the created target before it is finalized. When using +CMake versions earlier than 3.19, automatic deferral isn't supported. In that +case, finalization is performed immediately before this command returns. + +Regardless of the CMake version, the \c{MANUAL_FINALIZATION} keyword can be +given to indicate that you will explicitly call +\l{qt6_finalize_target}{qt_finalize_target()} yourself instead at some later +time. In general, \c MANUAL_FINALIZATION should not be needed unless the +project has to support CMake 3.18 or earlier. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()}, QTP0003 + +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_plugin.qdoc b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc new file mode 100644 index 0000000000..d2322086e7 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc @@ -0,0 +1,87 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-plugin.html +\ingroup cmake-commands-qtcore + +\title qt_add_plugin +\keyword qt6_add_plugin + +\summary {Creates a Qt plugin target.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_add_plugin(target + [SHARED | STATIC] + [CLASS_NAME class_name] + [OUTPUT_TARGETS variable_name] + [MANUAL_FINALIZATION] + sources... +) +\endcode + +The \c MANUAL_FINALIZATION option and the ability to set sources +were introduced in Qt 6.5. + +\versionlessCMakeCommandsNote qt6_add_plugin() + +\section1 Description + +Qt plugin targets have additional requirements over and above an ordinary CMake +library target. The \c{qt_add_plugin()} command adds the necessary handling to +ensure these requirements are met. It should be called rather than the built-in +CMake \c{add_library()} command when defining a Qt plugin target. + +By default, the plugin will be created as a \c STATIC library if Qt was built +statically, or as a \c MODULE library otherwise. You can override this default +by explicitly providing the \c STATIC or \c SHARED option. + +Any \c{sources} provided will be passed through to the internal call to +\c{add_library()}. + +\note Non-static plugins are meant to be loaded dynamically at runtime, not +linked to at build time. CMake differentiates between these two scenarios by +providing the \c MODULE library type for dynamically loaded libraries, and +the \c SHARED library type for libraries that may be linked to directly. This +distinction is important for some toolchains (notably Visual Studio), due to +the way symbol exports are handled. It may not be possible to link to +\c MODULE libraries, and generating a \c SHARED library with no exported +symbols can result in build-time errors. If the \c SHARED option is passed to +\c{qt_add_plugin()}, it will therefore create a \c MODULE library rather than a +\c SHARED library. + +Every Qt plugin has a class name. By default, this will be the same as the +\c target, but it can be overridden with the \c CLASS_NAME option. The class +name corresponds to the name of the C++ class that declares the metadata for +the plugin. For static plugins, it is also the name passed to +\l Q_IMPORT_PLUGIN, which imports the plugin into an application and ensures it +is available at run time. + +If the plugin is built statically, \c{qt_add_plugin()} may define additional +internal targets. These facilitate automatic importing of the plugin for any +executable or shared library that links to the plugin. If the project installs +the plugin and intends to make it available for other projects to link to, the +project should also install these internal targets. The names of these targets +can be obtained by providing the \c OUTPUT_TARGETS option, followed by the name +of a variable in which to return the target list. + +\section2 Finalization + +After a target is created, further processing or \e{finalization} steps may be +needed. The finalization processing is implemented by the +\l{qt6_finalize_target}{qt_finalize_target()} command. + +For details and the meaning of the \c{MANUAL_FINALIZATION} option, refer to the +\l{qt_add_library finalization}{finalization documentation} for +\c{qt_add_library}. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()} + +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_resources.qdoc new file mode 100644 index 0000000000..2e713b1b8e --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_resources.qdoc @@ -0,0 +1,110 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-resources.html +\ingroup cmake-commands-qtcore + +\title qt_add_resources +\keyword qt6_add_resources + +\summary {Compiles binary resources into source code.} + +\include cmake-find-package-core.qdocinc + +\section1 Synopsis + +\badcode +qt_add_resources(<VAR> file1.qrc [file2.qrc ...] + [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_resources() + +Since 6.0: + +\badcode +qt_add_resources(<TARGET> <RESOURCE_NAME> + [PREFIX <PATH>] + [LANG <LANGUAGE>] + [BASE <PATH>] + [BIG_RESOURCES] + [OUTPUT_TARGETS <VARIABLE_NAME>] + [FILES ...] [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_resources() + +\section1 Description + +To add resources, you can pass either a variable name or a target as the first +argument of the command. + +When passing a variable name as first argument, \c qt_add_resources creates +source code from Qt resource files using the \l{Resource Compiler (rcc)}. Paths +to the generated source files are added to \c{<VAR>}. + +When passing a target as first argument, the function creates a resource with +the name \c{RESOURCE_NAME}, containing the specified \c{FILES}. The resource is +automatically linked into \c{TARGET}. + +See \l{The Qt Resource System} for a general description of Qt resources. + +\section1 Arguments of the target-based variant + +\c PREFIX specifies a path prefix under which all files of this resource are +accessible from C++ code. This corresponds to the XML attribute \c prefix of the +\c .qrc file format. If \c PREFIX is not given, the target property +\l{cmake-target-property-QT_RESOURCE_PREFIX}{QT_RESOURCE_PREFIX} is used. Since +6.5, \c{PREFIX} is optional. If it is omitted and not specified by +\c{QT_RESOURCE_PREFIX}, \c{"/"} will be used as the default path prefix. + +\c LANG specifies the locale of this resource. This corresponds to the XML +attribute \c lang of the \c .qrc file format. + +\c BASE is a path prefix that denotes the root point of the file's alias. For +example, if \c BASE is \c{"assets"} and \c FILES is +\c{"assets/images/logo.png"}, then the alias of that file is +\c{"images/logo.png"}. + +Alias settings for files need to be set via the \c QT_RESOURCE_ALIAS source file +property. + +\c BIG_RESOURCES can be specified to enable support for big resources. This +directly generates object files (\c .o, \c .obj) instead of C++ source code. +This allows embedding bigger resources, without having to compile generated C++ +sources, which can be too time consuming and memory intensive. + +Note that \c BIG_RESOURCES is not compatible with iOS due to restrictions of +CMake's Xcode project generator. See +\l{https://bugreports.qt.io/browse/QTBUG-103497}{QTBUG-103497} for details. +Also, \c BIG_RESOURCES only works reliably from CMake 3.17 onwards. + +When using this command with static libraries, one or more special targets will +be generated. Should you wish to perform additional processing on these targets, +pass a variable name to the \c OUTPUT_TARGETS parameter. The \c qt_add_resources +function stores the names of the special targets in the specified variable. + +\section1 Arguments of both variants + +You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. +You can find possible options in the \l{rcc}{rcc documentation}. + +\section1 Examples + +Variable variant, using a .qrc file: +\snippet cmake-macros/examples.cmake qt_add_resources + +Target variant, using immediate resources: +\snippet cmake-macros/examples.cmake qt_add_resources_target + +\section1 Caveats + +When adding multiple resources, \c{RESOURCE_NAME} must be unique across all +resources linked into the final target. + +This especially affects static builds. There, the same resource name in +different static libraries conflict in the consuming target. + +\sa {qt6_add_big_resources}{qt_add_big_resources()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc new file mode 100644 index 0000000000..ad95401f4d --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc @@ -0,0 +1,34 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-allow-non-utf8-sources.html +\ingroup cmake-commands-qtcore + +\title qt_allow_non_utf8_sources +\keyword qt6_allow_non_utf8_sources + +\summary {Prevents forcing source files to be treated as UTF-8 for Windows.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_allow_non_utf8_sources(target) +\endcode + +\versionlessCMakeCommandsNote qt6_allow_non_utf8_sources() + +\section1 Description + +When building with some compilers for Windows, targets that link to a Qt library +will use flags that force the compiler to treat its source files as UTF-8. This +is currently implemented for Visual Studio and Intel compilers. You can disable +this behavior on a per-target basis by calling \c{qt_allow_non_utf8_sources()} +and passing the target as the argument. + +\sa {qt6_disable_unicode_defines}{qt_disable_unicode_defines()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc new file mode 100644 index 0000000000..b2415730f5 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc @@ -0,0 +1,55 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-android-add-apk-target.html +\ingroup cmake-commands-qtcore + +\title qt_android_add_apk_target +\keyword qt6_android_add_apk_target + +\summary {Defines a build target that runs androiddeployqt to produce an APK.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable instead. +\cmakecommandandroidonly + +\section1 Synopsis + +\badcode +qt_android_add_apk_target(target) +\endcode + +\versionlessCMakeCommandsNote qt6_android_add_apk_target() + +\section1 Description + +The \c{<target>_make_apk} and \c{<target>_make_aab} custom targets created by +this command take an Android deployment settings file and generate APK and +AAB respectively by running \c{androiddeployqt}. +The location of the settings file is taken from the \c{target}'s +\c{QT_ANDROID_DEPLOYMENT_SETTINGS_FILE} property. This file is typically created by +\l{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}. +The respective Android package will be generated in an \c{android-build} +subdirectory below the CMake build directory of the \c{target}. + +The \c{<target>_make_apk} and \c{<target>_make_aab} targets will be +automatically added as dependencies of the \c{apk} and \c{aab} build targets +respectively, which will be created automatically. Creating of the \c{apk} and +\c{aab} targets can be disabled by setting the \c{QT_NO_GLOBAL_APK_TARGET} and +\c{QT_NO_GLOBAL_AAB_TARGET} variables to \c{TRUE}. + +\sa {qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}, + {qt6_finalize_target}{qt_finalize_target()}, + {qt6_finalize_project}{qt_finalize_project()} + +\section1 Example + +\snippet cmake-macros/examples.cmake qt_android_deploy_basic + +The above commands define the \c{myapp_make_apk}, \c{myapp_make_aab}, \c{apk}, +and \c{aab} build targets which can be used to generate just the +\c{myapp} packages or all APKs and AABs in the project respectively. +*/ diff --git a/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc new file mode 100644 index 0000000000..a29e1f6123 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc @@ -0,0 +1,36 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-android-apply-arch-suffix.html +\ingroup cmake-commands-qtcore + +\title qt_android_apply_arch_suffix +\keyword qt6_android_apply_arch_suffix + +\summary {Configures the target binary's name to include an architecture-specific suffix.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable +or \l qt_add_library instead. +\cmakecommandandroidonly + +\section1 Synopsis + +\badcode +qt_android_apply_arch_suffix(target) +\endcode + +\versionlessCMakeCommandsNote qt6_android_apply_arch_suffix() + +\section1 Description + +The CMake \c{SUFFIX} target property controls the suffix used on the file name +of the target's built binary. This command is a convenience for setting that +property to an architecture-specific value. This is useful when installing +multiple builds for different Android architectures into the same install +location, as it prevents the libraries for different architectures from +overwriting each other. +*/ diff --git a/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc new file mode 100644 index 0000000000..5a7bbdc33f --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc @@ -0,0 +1,82 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-android-generate-deployment-settings.html +\ingroup cmake-commands-qtcore + +\title qt_android_generate_deployment_settings +\keyword qt6_android_generate_deployment_settings + +\summary {Generates the deployment settings file needed by androiddeployqt.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable instead. +\cmakecommandandroidonly + +\section1 Synopsis + +\badcode +qt_android_generate_deployment_settings(target) +\endcode + +\versionlessCMakeCommandsNote qt6_android_generate_deployment_settings() + +\section1 Description + +The \c{androiddeployqt} tool expects a deployment settings file as input. This +command reads CMake variables and properties of the \c{target} to generate such +a file in the target's binary directory. Upon return, the full path to this file +is available in the target's \c{QT_ANDROID_DEPLOYMENT_SETTINGS_FILE} property. + +\section2 CMake Variables + +A number of variables are used while generating the deployment settings file. +Some are provided by Qt, others by CMake or the Android NDK. + +\list +\li \l{cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME}{ANDROID_NDK_HOST_SYSTEM_NAME} +\li \l{cmake-variable-ANDROID_SDK_ROOT}{ANDROID_SDK_ROOT} +\li \c{CMAKE_ANDROID_ARCH_ABI} +\li \c{CMAKE_ANDROID_NDK} +\li \c{CMAKE_SYSROOT} +\li \l{cmake-variable-QT_ANDROID_APPLICATION_ARGUMENTS}{QT_ANDROID_APPLICATION_ARGUMENTS} +\li \l{cmake-variable-QT_HOST_PATH}{QT_HOST_PATH} +\endlist + +\section2 Target Properties + +The properties below will be read from the specified \c{target}. Note that this +command is called as part of target finalization (see +\l{qt6_finalize_target}{qt_finalize_target()}). If you are using +\l{qt6_add_executable}{qt_add_executable()} to create the target and you need to +modify some of these target properties, you need to ensure that target +finalization is deferred. See \l{qt6_add_executable}{qt_add_executable()} for +how to accomplish this. + +\list +\li \l{cmake-target-property-QT_ANDROID_DEPLOYMENT_DEPENDENCIES}{QT_ANDROID_DEPLOYMENT_DEPENDENCIES} +\li \l{cmake-target-property-QT_ANDROID_EXTRA_LIBS}{QT_ANDROID_EXTRA_LIBS} +\li \l{cmake-target-property-QT_ANDROID_EXTRA_PLUGINS}{QT_ANDROID_EXTRA_PLUGINS} +\li \l{cmake-target-property-QT_ANDROID_MIN_SDK_VERSION}{QT_ANDROID_MIN_SDK_VERSION} +\li \l{cmake-target-property-QT_ANDROID_PACKAGE_SOURCE_DIR}{QT_ANDROID_PACKAGE_SOURCE_DIR} +\li \l{cmake-target-property-QT_ANDROID_TARGET_SDK_VERSION}{QT_ANDROID_TARGET_SDK_VERSION} +\li \l{cmake-target-property-QT_ANDROID_VERSION_NAME}{QT_ANDROID_VERSION_NAME} +\li \l{cmake-target-property-QT_ANDROID_VERSION_CODE}{QT_ANDROID_VERSION_CODE} +\li \l{cmake-target-property-QT_QML_IMPORT_PATH}{QT_QML_IMPORT_PATH} +\li \l{cmake-target-property-QT_QML_ROOT_PATH}{QT_QML_ROOT_PATH} +\li \l{cmake-target-property-qt_no_entrypoint}{qt_no_entrypoint} +\endlist + +Upon return, the \c{QT_ANDROID_DEPLOYMENT_SETTINGS_FILE} target property will +contain the location of the generated deployment settings file. + +\sa {qt6_android_add_apk_target}{qt_android_add_apk_target()}, + {qt6_finalize_target}{qt_finalize_target()} + +\section1 Example + +\snippet cmake-macros/examples.cmake qt_android_deploy_basic +*/ 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..45fd8f4c5f --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc @@ -0,0 +1,78 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-deploy-qt-conf.html +\ingroup cmake-commands-qtcore + +\title qt_deploy_qt_conf +\keyword qt6_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. + +\cmakecommandsince 6.3 +\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. + +\section1 Synopsis + +\badcode +qt_deploy_qt_conf(file_path + [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 \l{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. +The default values can be found at \l{Overriding Paths}. + +The \c file_path argument expects an absolute path to the location where the +\c qt.conf file should be written to. The \l{QT_DEPLOY_PREFIX} and \l{QT_DEPLOY_BIN_DIR} +variables can be used to dynamically specify a path relative to the deployment binary directory, +as shown in the example below. This helps avoid hard-coding an absolute path. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}, + {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()} + +\section1 Example + +\badcode +# The following script must only be executed at install time +qt_generate_deploy_script( + OUTPUT_SCRIPT deploy_script + CONTENT " +qt_deploy_qt_conf(\"\${QT_DEPLOY_PREFIX}/\${QT_DEPLOY_BIN_DIR}/qt.conf\" + DATA_DIR \"./custom_data_dir\" + TRANSLATIONS_DIR \"./custom_translations_dir\" +) +") + +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..f64960492a --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc @@ -0,0 +1,198 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-deploy-runtime-dependencies.html +\ingroup cmake-commands-qtcore + +\title qt_deploy_runtime_dependencies +\keyword qt6_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. + +\cmakecommandsince 6.3 +\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. + +\section1 Synopsis + +\badcode +qt_deploy_runtime_dependencies( + EXECUTABLE executable + [ADDITIONAL_EXECUTABLES files...] + [ADDITIONAL_LIBRARIES files...] + [ADDITIONAL_MODULES files...] + [GENERATE_QT_CONF] + [BIN_DIR bin_dir] + [LIBEXEC_DIR libexec_dir] + [LIB_DIR lib_dir] + [PLUGINS_DIR plugins_dir] + [QML_DIR qml_dir] + [VERBOSE] + [NO_OVERWRITE] + [NO_APP_STORE_COMPLIANCE] + [NO_TRANSLATIONS] + [NO_COMPILER_RUNTIME] + [DEPLOY_TOOL_OPTIONS] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_FILES files...] + [POST_EXCLUDE_FILES files...] +) +\endcode + +\section1 Description + +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 Qt libraries plus an appropriate set of Qt plugins. + +On Linux, the command will deploy additional libraries, beyond just those +related to Qt, that are included with the project. However, when executed on +macOS or Windows, the command will use either \c macdeployqt or \c windeployqt, +which will only deploy libraries that are specific to Qt. + +This command only considers runtime dependencies for which linking +relationships exist in the underlying binaries. It does not deploy QML modules, +see \l{qt6_deploy_qml_imports}{qt_deploy_qml_imports()} for that. + +\section1 Arguments + +The \c{EXECUTABLE} option must be provided. + +The \c{executable} argument should be the path to the executable file in the +build directory. For example, \c{${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe}, or more +dynamically \c{$<TARGET_FILE:MyApp>}. Specifying raw target names not wrapped in +a generator expression like \c{<TARGET_FILE:>} is not supported. + +For macOS app bundles, the \c{executable} argument should be a path to the +bundle directory, relative to the base install location. +For example \c{MyApp.app}, or more dynamically +\c{$<TARGET_FILE_NAME:MyApp>.app}. +Specifying raw target names not wrapped in a generator epxression like +\c{<TARGET_FILE_NAME:>} is not supported. + +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} options 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}. +Each value should be a path relative to the base install location. The values +can use generator expressions, same as with the \c{EXECUTABLE} option. +Specifying raw target names not wrapped in a generator epxression like +\c{<TARGET_FILE_NAME:>} is not supported. + +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 parameters in the following +table, all of which are expected to be relative to the base install location. + +\table +\header + \li parameter + \li affected variable + \li notes +\row + \li \c BIN_DIR + \li \l QT_DEPLOY_BIN_DIR + \li +\row + \li \c LIBEXEC_DIR + \li \l QT_DEPLOY_LIBEXEC_DIR + \li since Qt 6.7 +\row + \li \c LIB_DIR + \li \l QT_DEPLOY_LIB_DIR + \li +\row + \li \c PLUGINS_DIR + \li \l QT_DEPLOY_PLUGINS_DIR + \li +\row + \li \c QML_DIR + \li \l QT_DEPLOY_QML_DIR + \li +\endtable + +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. + +On platforms other than macOS, Qt translations are automatically deployed. To +inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use +\l{qt6_deploy_translations}{qt_deploy_translations()} to deploy translations +in a customized way. + +For Windows desktop applications, the required runtime files for the compiler +are also installed by default. To prevent this, specify \c{NO_COMPILER_RUNTIME}. + +Since Qt 6.7, you can use \c{DEPLOY_TOOL_OPTIONS} to pass additional options to +the underlying deployment tool. This only has an effect if the underlying +deployment tool is either macdeployqt or windeployqt. + +On Linux, deploying runtime dependencies is based on CMake's +\c{file(GET_RUNTIME_DEPENDENCIES)} command. The options \c{PRE_INCLUDE_REGEXES}, +\c{PRE_EXCLUDE_REGEXES}, \c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES}, +\c{POST_INCLUDE_FILES}, and \c{POST_EXCLUDE_FILES} are only meaningful in this +context and are forwarded unaltered to \c{file(GET_RUNTIME_DEPENDENCIES)}. See +the documentation of that command for details. + +On Linux, runtime dependencies that are located in system library directories +are not deployed by default. If \c{POST_EXCLUDE_REGEXES} is specified, this +automatic exclusion is not performed. + +The default value of \c{POST_EXCLUDE_REGEXES} is constructed from the value of +\l{QT_DEPLOY_IGNORED_LIB_DIRS}. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}, + {qt6_deploy_qt_conf}{qt_deploy_qt_conf()}, + {qt6_deploy_qml_imports}{qt_deploy_qml_imports()} + +\section1 Example + +The following example shows how to deploy an application \c{MyApp}. + +\include cmake-deploy-runtime-dependencies.qdocinc + +The following example shows how to use the \c{DEPLOY_TOOL_OPTIONS} parameter to +pass different options to macdeployqt and windeployqt. + +\include cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc + +*/ diff --git a/src/corelib/doc/src/cmake/qt_deploy_translations.qdoc b/src/corelib/doc/src/cmake/qt_deploy_translations.qdoc new file mode 100644 index 0000000000..43ff23a35a --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_deploy_translations.qdoc @@ -0,0 +1,76 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-deploy-translations.html +\ingroup cmake-commands-qtcore + +\title qt_deploy_translations +\keyword qt6_deploy_translations + +\summary {Deploy Qt translations needed by an executable.} + +\include cmake-find-package-core.qdocinc + +Unlike most other CMake commands provided by Qt, \c{qt_deploy_translations()} +can only be called from a deployment script. It cannot be called directly by the +project during the configure stage. + +\cmakecommandsince 6.5 +\preliminarycmakecommand +\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. + +\section1 Synopsis + +\badcode +qt_deploy_translations( + [CATALOGS catalogs] + [LOCALES locales] + [LCONVERT lconvert_executable] + [VERBOSE] +) +\endcode + +\section1 Description + +When installing an application, it may be desirable to also install the +translations that belong to the used Qt modules. The \c qt_deploy_translations +command collects the necessary \c{.qm} file from the Qt installation and +compiles them into one \c{qt_${language}.qm} file per language. The \c{.qm} +files are installed into \c{QT_DEPLOY_TRANSLATIONS_DIR}. + +\section1 Arguments + +The \c LOCALES argument specifies for which locales translations should be +deployed. This is a list of language/region combinations as described in +\l{Changing the Target Locale}{Qt Linguist's manual for translators}. Examples +for valid locales are: \c{de}, \c{pl}, or \c{pt_BR}. + +If \c LOCALES is omitted, then all available locales are deployed. + +The \c CATALOGS argument specifies a list of \l{Available +Catalogs}{translation catalogs} to be deployed. If this argument is +omitted, then all catalogs are deployed that belong to any Qt module +that is used in the project via \c{find_package}. + +The \c LCONVERT argument specifies the \c lconvert executable that is used to +combine the catalogs. By default, the Qt installation's \c lconvert is used. + +For debugging purposes, the \c VERBOSE argument can be set to turn on diagnostic +messages. + +\sa QT_DEPLOY_TRANSLATIONS_DIR + +\section1 Example + +The following example deploys Danish and German translations of the Qt +libraries. + +\badcode +qt_deploy_translations( + LOCALES da de +) +\endcode +*/ diff --git a/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc new file mode 100644 index 0000000000..91de52544e --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc @@ -0,0 +1,34 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-disable-unicode-defines.html +\ingroup cmake-commands-qtcore + +\title qt_disable_unicode_defines +\keyword qt6_disable_unicode_defines + +\summary {Prevents some unicode-related compiler definitions being set automatically on a target.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_disable_unicode_defines(target) +\endcode + +\versionlessCMakeCommandsNote qt6_disable_unicode_defines() + +\section1 Description + +In Qt 6, the \c UNICODE and \c{_UNICODE} compiler definitions are set by +default for targets that link against Qt modules. This is in line with the +qmake behavior, but it is a change compared to the CMake API behavior in Qt 5. +Calling \c{qt_disable_unicode_defines()} on a \c target prevents these compiler +definitions from being automatically set. + +\sa {qt6_allow_non_utf8_sources}{qt_allow_non_utf8_sources()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc new file mode 100644 index 0000000000..7ec8d90f9b --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc @@ -0,0 +1,69 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-extract-metatypes.html +\ingroup cmake-commands-qtcore + +\title qt_extract_metatypes +\keyword qt6_extract_metatypes + +\summary {Extracts metatypes from a Qt target and generates an associated metatypes.json file.} + +\cmakecommandsince 6.0 +\preliminarycmakecommand + +\section1 Synopsis + +\badcode +qt_extract_metatypes(target + [MANUAL_MOC_JSON_FILES json_files...] + [OUTPUT_FILES variable_name] +) +\endcode + +\versionlessCMakeCommandsNote qt6_extract_metatypes() + +\section1 Description + +Certain operations rely on metatype information being generated and collected +on targets. This is typically handled internally by Qt commands, but for +scenarios where this is not the case, \c{qt_extract_metatypes()} can be called +to force the collection of this information for a specific \c target. + +Metatype information is generated for a target's source files in one of the +following ways: + +\list +\li Automatically by AUTOMOC. The \c{qt_extract_metatypes()} command detects + when AUTOMOC is enabled on the \c target and will automatically extract the + information it needs. +\li Manually by invoking \c moc with the \c{--output-json} option. The project + is responsible for keeping track of all the JSON files generated using this + method and passing them to \c{qt_extract_metatypes()} with the + \c MANUAL_MOC_JSON_FILES option. +\endlist + +\c{qt_extract_metatypes()} produces a target-specific metatypes JSON file which +collects all the metatype details from the AUTOMOC and manual moc inputs. +It does this by calling \c moc with the \c{--collect-json} option. +If you need to know where to find the resultant metatypes JSON file (for +example, to pass it to another command or to install it), use the +\c OUTPUT_FILES option to provide the name of a variable in which to store its +absolute path. + +\section1 Automatic metatype extraction + +Since Qt 6.8, if you have not disabled \c{AUTOMOC} and either are using CMake +3.19 or later or are calling \l{qt6_finalize_target}{qt_finalize_target()} +manually, then \c{qt_extract_metatypes()} is automatically called as part of the +finalization step for \l{qt_add_library}. This has no effect if you have +manually called \c{qt_extract_metatypes()} before the finalization, possibly +with custom arguments. However, it does make sure that the metatypes are also +produced if you haven't. This is important if any of the types in the library +are used as part of any QML types any time in the future and has no downsides. + +Furthermore, \l{qt_add_qml_module} automatically invokes +\c{qt_extract_metatypes()} for its target. + +*/ diff --git a/src/corelib/doc/src/cmake/qt_finalize_project.qdoc b/src/corelib/doc/src/cmake/qt_finalize_project.qdoc new file mode 100644 index 0000000000..5506712691 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_finalize_project.qdoc @@ -0,0 +1,53 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-finalize-project.html +\ingroup cmake-commands-qtcore + +\title qt_finalize_project +\keyword qt6_finalize_project + +\summary {Handles various common platform-specific tasks associated with a Qt project.} +\preliminarycmakecommand + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.3 + +\section1 Synopsis + +\badcode +qt_finalize_project() +\endcode + +\versionlessCMakeCommandsNote qt6_finalize_project() + +\section1 Description + +Some targets that are created using Qt commands require additional actions +at the end of CMake configuring phase. +Depending on the platform, the function typically: +\list + \li Walks the build tree. + \li Resolves dependencies. + \li Applies any extra deployment steps. +\endlist + +With CMake version 3.19 or later, you don't need to call this command since +it consists of sub-commands that are ordinarily invoked at the end of +\c CMAKE_SOURCE_DIR directory scope processing. + +\include cmake-android-qt-finalize-project-warning.qdocinc warning + +\section2 Examples + +For projects that use a CMake version lower than 3.19, you need to call +\c qt_finalize_project manually. This example shows the typical use of the +function: + +\snippet cmake-macros/examples.cmake qt_finalize_project_manual + +\sa {cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS}{QT_NO_COLLECT_BUILD_TREE_APK_DEPS} +\sa {cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS}{QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS} +*/ diff --git a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc new file mode 100644 index 0000000000..b74dee64d2 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc @@ -0,0 +1,89 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-finalize-target.html +\ingroup cmake-commands-qtcore + +\title qt_finalize_target +\keyword qt6_finalize_target + +\summary {Handles various common platform-specific tasks associated with Qt targets.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_finalize_target(target) +\endcode + +\versionlessCMakeCommandsNote qt6_finalize_target() + +\section1 Description + +After a target is created, further processing or \e{finalization} steps are +sometimes needed. The steps to perform depend on the platform, the type of +target, and on various properties of the target. These steps are expected to be +performed within the same directory scope as the one in which the \c{target} +was created, so this command should also be called from that same directory +scope. + +This command is ordinarily invoked as part of a call to +\l{qt6_add_executable}{qt_add_executable()}, +\l{qt6_add_library}{qt_add_library()}, or \l{qt6_add_plugin}{qt_add_plugin()}. +The timing of when that call takes place and when a project might need to call +it explicitly, is discussed in the documentation of those commands. + +\sa {qt6_set_finalizer_mode}{qt_set_finalizer_mode()} + +\section1 Executable Targets + +For executable targets, \c{qt_finalize_target()} implements the logic described +in the subsections below, as appropriate for the platform and target provided. +Later Qt releases may expand finalization processing further. + +\section2 All Platforms + +Some internal processing is performed to facilitate automatic linking of Qt +plugins. This is especially important if using a statically built Qt or a +CMake version earlier than 3.21. + +\section2 Android + +\list +\li Generate a deployment settings file for the \c target. +\li Create a build target for generating an APK. +\endlist + +\section2 WASM + +Create \c{${target}.html} (a target-specific \c{wasm_shell.html} file), +\c{qtloader.js}, and \c{qtlogo.svg} files in the \c{CMAKE_CURRENT_BINARY_DIR}. + +\section2 iOS + +Finalization attempts to provide sensible values for the following target +properties if they are not already set, and their corresponding \c{CMAKE_...} +variable is also not set: + +\list +\li \c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM +\li \c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER +\li \c MACOSX_BUNDLE_GUI_IDENTIFIER +\endlist + +If required, the \l QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID variable can be used to +disable setting \c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM, and the +\l QT_NO_SET_XCODE_BUNDLE_IDENTIFIER variable can be used to disable setting +\c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER and \c MACOSX_BUNDLE_GUI_IDENTIFIER. + +\section1 Library Targets + +As of this Qt version, finalization for library targets does not perform any +processing. Future Qt versions may add finalization processing for libraries, +so you should ensure finalization is still invoked in the expected way. + +*/ 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..31d9e4384b --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc @@ -0,0 +1,110 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-deploy-app-script.html +\ingroup cmake-commands-qtcore + +\title qt_generate_deploy_app_script +\keyword qt6_generate_deploy_app_script + +\summary {Generate a deployment script for an application.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.3 +\note This command is currently only supported on Windows, macOS, and Linux. + +\section1 Synopsis + +\badcode +qt_generate_deploy_app_script( + TARGET target + OUTPUT_SCRIPT <var> + [NO_TRANSLATIONS] + [NO_COMPILER_RUNTIME] + [NO_UNSUPPORTED_PLATFORM_ERROR] + [DEPLOY_TOOL_OPTIONS ...] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_FILES files...] + [POST_EXCLUDE_FILES files...] +) +\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{OUTPUT_SCRIPT} 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{qt6_deploy_runtime_dependencies} +{qt_deploy_runtime_dependencies()} with a suitable set of options for the standard +install layout. Currently, this is only implemented for +\list + \li macOS app bundles built on a macOS host, + \li Linux executables built on a Linux host, + \li and Windows executables built on a Windows host. +\endlist +Cross-building a Windows executable on a Linux host, as well as similar +scenarios, are not currently supported. +Calling \c{qt_generate_deploy_app_script()} in such a case will result +in a fatal error, unless the \c{NO_UNSUPPORTED_PLATFORM_ERROR} option is given. + +On platforms other than macOS, Qt translations are automatically deployed. To +inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use +\l{qt6_deploy_translations}{qt_deploy_translations()} to deploy translations in a +customized way. + +For Windows desktop applications, the required runtime files for the compiler +are also installed by default. To prevent this, specify \c{NO_COMPILER_RUNTIME}. + +Since Qt 6.7, you can use \c{DEPLOY_TOOL_OPTIONS} to pass additional options to +the underlying deployment tool. This only has an effect if the underlying +deployment tool is either macdeployqt or windeployqt. + +For deploying a QML application, use +\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} +instead. + +For generating a custom deployment script, use +\l{qt6_generate_deploy_script}{qt_generate_deploy_script}. + +The options \c{PRE_INCLUDE_REGEXES}, \c{PRE_EXCLUDE_REGEXES}, +\c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES}, \c{POST_INCLUDE_FILES}, and +\c{POST_EXCLUDE_FILES} can be specified to control the deployment of runtime +dependencies. These options do not apply to all platforms and are forwarded +unmodified to \l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()}, + {qt6_generate_deploy_script}{qt_generate_deploy_script()}, + {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} + +\section1 Example + +The following example shows how to deploy an application \c{MyApp}. + +\include cmake-generate-deploy-app-script.qdocinc + +The following example shows how to use the \c{DEPLOY_TOOL_OPTIONS} parameter to +pass different options to macdeployqt and windeployqt. + +\include cmake-generate-deploy-app-script-deploy-tool-options.qdocinc + +*/ diff --git a/src/corelib/doc/src/cmake/qt_generate_deploy_script.qdoc b/src/corelib/doc/src/cmake/qt_generate_deploy_script.qdoc new file mode 100644 index 0000000000..eb8ed402a9 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_generate_deploy_script.qdoc @@ -0,0 +1,65 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-deploy-script.html +\ingroup cmake-commands-qtcore + +\title qt_generate_deploy_script +\keyword qt6_generate_deploy_script + +\summary {Generate a custom deployment script.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.5 + +\section1 Synopsis + +\badcode +qt_generate_deploy_script( + OUTPUT_SCRIPT <var> + [TARGET target] + [NAME script_name] + [CONTENT content] +) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_deploy_script() + +\section1 Description + +The command generates a script whose full file path will be stored in the +variable named by the \c{OUTPUT_SCRIPT} 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 command takes care of generating a file named suitably for multi-config +generators. Necessary includes are added such that Qt's CMake deployment +functions and variables are accessible. + +The \c TARGET argument specifies the target that will be deployed by the script. +This affects the file name of the generated script, unless \c NAME is specified. + +The \c NAME argument controls an identifiable portion within the deployment +script's automatically generated name. The \c NAME argument defaults to \c +custom if neither \c NAME nor \c TARGET are given. + +The \c CONTENT argument specifies the code that is written to the deployment +script. The content may contain generator expressions. + +This command is intended for generating custom deployment scripts that +directly call functions of Qt's deployment API. For less complex +deployment purposes, it is more convenient to use +\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} or +\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}, + {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} + +\section1 Example + +\snippet cmake-macros/deployment.cmake qt_generate_deploy_script_example + +*/ diff --git a/src/corelib/doc/src/cmake/qt_generate_moc.qdoc b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc new file mode 100644 index 0000000000..9b123f9323 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc @@ -0,0 +1,45 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-moc.html +\ingroup cmake-commands-qtcore + +\title qt_generate_moc +\keyword qt6_generate_moc + +\summary {Calls moc on an input file.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.0 + +\section1 Synopsis + +\badcode +qt_generate_moc(src_file dest_file + [TARGET target]) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_moc() + +\section1 Description + +Creates a rule to call the \l{moc}{Meta-Object Compiler (moc)} on \c src_file +and store the output in \c dest_file. + +\note This is a low-level macro. See the \l{CMake AUTOMOC Documentation} for a +more convenient way to let source files be processed with \c{moc}. +\l qt_wrap_cpp is also similar, but automatically generates a temporary file +path for you. + +\section1 Arguments + +You can set an explicit \c{TARGET}. This will make sure that the target +properties \c{INCLUDE_DIRECTORIES} and \c{COMPILE_DEFINITIONS} are also used +when scanning the source files with \c{moc}. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_generate_moc +*/ diff --git a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc new file mode 100644 index 0000000000..1f81a21cd2 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc @@ -0,0 +1,97 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-import-plugins.html +\ingroup cmake-commands-qtcore + +\title qt_import_plugins +\keyword qt6_import_plugins + +\summary {Specifies a custom set of plugins to import or exclude.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.14 + +\section1 Synopsis + +\badcode +qt_import_plugins(target + [INCLUDE plugin ...] + [EXCLUDE plugin ...] + [INCLUDE_BY_TYPE plugin_type plugin ...] + [EXCLUDE_BY_TYPE plugin_type] + [NO_DEFAULT] +) +\endcode + +\versionlessCMakeCommandsNote qt6_import_plugins() + +\section1 Description + +Specifies a custom set of plugins to import. The optional arguments: +\c INCLUDE, \c EXCLUDE, \c INCLUDE_BY_TYPE, and \c EXCLUDE_BY_TYPE, +can be used more than once. + +\list +\li \c INCLUDE -- can be used to specify a list of plugins to import. +\li \c EXCLUDE -- can be used to specify a list of plugins to exclude. +\li \c INCLUDE_BY_TYPE -- can be used to override the list of plugins to + import for a certain plugin type. +\li \c EXCLUDE_BY_TYPE -- can be used to specify a plugin type to exclude; + then no plugins of that type are imported. +\li \c NO_DEFAULT -- prevent the default plugins from being included + automatically (for example, the default platform plugin). +\endlist + +Qt provides plugin types such as \c imageformats, \c platforms, +and \c sqldrivers. + +\section2 Dynamic plugins + +If plugins are dynamic libraries, the function controls the plugin deployment. +Using this function, you may exclude specific plugin types from +being packaged into an Android APK, for example: + +\badcode +qt_add_executable(MyApp ...) +... +qt_import_plugins(MyApp EXCLUDE_BY_TYPE imageformats) +\endcode + +In the snippet above, all plugins that have the \c imageformats type will +be excluded when deploying \c MyApp. The resulting Android APK will not +contain any of the \c imageformats plugins. + +If the command isn't used, the target automatically deploys all plugins that +belong to the Qt modules that the target is linked against. + +\section2 Static plugins + +If the command isn't used the target automatically links against +a sane set of default static plugins, for each Qt module that the target is +linked against. For more information, see +\l{CMake target_link_libraries Documentation}{target_link_libraries}. + +Each plugin comes with a C++ stub file that automatically +initializes the static plugin. Consequently, any target that links against +a plugin has this C++ file added to its \c SOURCES. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_import_plugins + +In the snippet above, the following occurs with the executable \c myapp: + +\list +\li The \c Qt6::QCocoaIntegrationPlugin is imported into myapp. +\li The \c Qt6::QMinimalIntegrationPlugin plugin is + excluded from being automatically imported into myapp. +\li The default list of plugins for \c imageformats is + overridden to only include Qt6::QGifPlugin and Qt6::QJpegPlugin. +\li All \c sqldrivers plugins are excluded from automatic importing. +\endlist + +\sa{qt6_import_qml_plugins}{qt_import_qml_plugins()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_policy.qdoc b/src/corelib/doc/src/cmake/qt_policy.qdoc new file mode 100644 index 0000000000..6deb7a729c --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_policy.qdoc @@ -0,0 +1,65 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-policy.html +\ingroup cmake-commands-qtcore + +\title qt_policy +\keyword qt6_policy + +\summary {Modify the default behavior of Qt's CMake API.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.5 + +\section1 Synopsis + +\badcode +qt_policy( + [SET <policy_name> behavior] + [GET <policy_name> <variable>] +) +\endcode + +\versionlessCMakeCommandsNote qt6_policy() + +\section1 Description + +This command has two modes: + +\list +\li When the \c{SET} keyword is used, this command can be used to opt in to + behavior changes in Qt's CMake API, or to explicitly opt out of them. +\li When the \c{GET} keyword is used, \c{<variable>} is set to the current + behavior for the policy, i.e. \c OLD or \c NEW. +\endlist + +\c{<policy_name>} must be the name of one of the \l{Qt CMake policies}. +Policy names have the form of \c{QTP<NNNN>} where <NNNN> is +an integer specifying the index of the policy. Using an invalid policy +name results in an error. + +Code supporting older Qt versions can check the existence of a policy by +checking the value of the \c{QT_KNOWN_POLICY_<policy_name>} variable before +getting the value of \c <policy_name> or setting its behavior. + +\badcode +if(QT_KNOWN_POLICY_<policy_name>) + qt_policy(SET <policy_name> NEW) +endif() +\endcode + +You can set \c behavior to one of the following options: + +\list +\li \c{NEW} to opt into the new behavior +\li \c{OLD} to explicitly opt-out of it +\endlist + +\qtpolicydeprecatedbehavior + +\sa qt_standard_project_setup + +*/ diff --git a/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc new file mode 100644 index 0000000000..28622c11e8 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc @@ -0,0 +1,90 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-set-finalizer-mode.html +\ingroup cmake-commands-qtcore + +\title qt_set_finalizer_mode +\keyword qt6_set_finalizer_mode + +\summary {Customizes aspects of a target's finalization.} + +\cmakecommandsince 6.2 +\preliminarycmakecommand + +\section1 Synopsis + +\badcode +qt_set_finalizer_mode(target + ENABLE | DISABLE + MODES modes... +) +\endcode + +\versionlessCMakeCommandsNote qt6_set_finalizer_mode() + +\section1 Description + +This command is used to customize some aspects of the finalization of a +specific \c target. It only has an effect if called before \c target is +finalized, which occurs in one of the following scenarios: + +\list +\li The project explicitly calls \l{qt6_finalize_target}{qt_finalize_target()} + for the \c target. This usually means the \c MANUAL_FINALIZATION keyword was + passed to \l{qt6_add_executable}{qt_add_executable()} when the \c target + was defined. +\li CMake 3.17 or earlier is being used, in which case finalization always + occurs immediately as part of the call to + \l{qt6_add_executable}{qt_add_executable()}. +\li CMake 3.18 or later is being used, the \c MANUAL_FINALIZATION keyword was + not passed to \l{qt6_add_executable}{qt_add_executable()} when the \c target + was defined, and deferred finalization has been completed at the end of the + \c target's directory scope. +\endlist + +\c{qt_set_finalizer_mode()} is used to enable or disable a list of \e modes, +where a mode corresponds to a specific aspect of finalization. The currently +supported finalization modes are: + +\table +\header + \li Mode + \li Default + \li Finalization behavior +\row + \li \c static_plugins + \li Enabled + \li When Qt is built statically, it creates initializer object libraries + for its static plugins. If \c target is an executable and this + finalization mode is enabled, any plugin initializer object libraries + needed by the \c target will be directly linked to it. This + prevents cycles between Qt-provided static libraries and may reduce + link time. When this finalizer mode is disabled, each plugin + initializer is instead propagated via usage requirements of its + associated Qt library, which may cause cycles. If Qt is not built + statically, this finalizer mode is not relevant and isn't used. +\endtable + +\sa {qt6_finalize_target}{qt_finalize_target()} + +\section1 Example + +The following example assumes you are using CMake 3.19 or later (required for +deferred finalization): + +\badcode +qt_add_executable(my_app main.cpp) +qt_set_finalizer_mode(my_app ENABLE MODES static_plugins) +\endcode + +The same example using manual finalization might look like this: + +\badcode +qt_add_executable(my_app MANUAL_FINALIZATION main.cpp) +qt_set_finalizer_mode(my_app ENABLE MODES static_plugins) +qt_finalize_target(my_app) +\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..59b33f599c --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc @@ -0,0 +1,101 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-standard-project-setup.html +\ingroup cmake-commands-qtcore + +\title qt_standard_project_setup +\keyword qt6_standard_project_setup + +\summary {Setup project-wide defaults to a standard arrangement.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.3 + +\section1 Synopsis + +\badcode +qt_standard_project_setup( + [REQUIRES <version>] + [SUPPORTS_UP_TO <version>] + [I18N_TRANSLATED_LANGUAGES <language...>] + [I18N_SOURCE_LANGUAGE <language>] +) +\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} and \c{CMAKE_AUTOUIC} + 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. +\li CMake's \l USE_FOLDERS property is set to \c{ON}, and \l QT_TARGETS_FOLDER is + set to \c{QtInternalTargets}. IDEs that support folders will display + Qt-internal targets in this folder. +\endlist + +Since Qt 6.5, it is possible to change the default behavior of Qt's CMake +API by opting in to changes from newer Qt versions. If \c{REQUIRES} is +specified, all suggested changes introduced in Qt up to \c{REQUIRES} are enabled, +and using an older Qt version will result in an error. +If additionally \c{SUPPORTS_UP_TO} has been specified, any new changes introduced +in versions up to \c{SUPPORTS_UP_TO} are also enabled (but using an older Qt +version is not an error). This is similar to CMake's policy concept +(compare \l{cmake_policy}). + +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. + +To disable folder support for IDEs, set \l USE_FOLDERS to \c OFF before or after +the call to \c{qt_standard_project_setup}. + +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()} +\sa qt_policy + +\section1 Internationalization + +Since Qt 6.7, it is possible to specify the languages that are used for project +internationalization with the \c I18N_TRANSLATED_LANGUAGES argument. See \l +QT_I18N_TRANSLATED_LANGUAGES for details. + +Use I18N_SOURCE_LANGUAGE to specify the language that translatable strings are +written in. By default, \c en is used. See \l QT_I18N_SOURCE_LANGUAGE for +details. + +\section1 Example + +\include cmake-generate-deploy-app-script.qdocinc + +\sa {Automatic Determination of .ts File Paths}{qt_add_translations()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc new file mode 100644 index 0000000000..3b298a9d7e --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc @@ -0,0 +1,90 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-wrap-cpp.html +\ingroup cmake-commands-qtcore + +\title qt_wrap_cpp +\keyword qt6_wrap_cpp + +\summary {Creates .moc files from sources.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.0 + +\section1 Synopsis + +\badcode +qt_wrap_cpp(<VAR> src_file1 [src_file2 ...] + [TARGET target] + [OPTIONS ...] + [DEPENDS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_wrap_cpp() + +\section1 Description + +Creates rules for calling the \l{moc}{Meta-Object Compiler (moc)} on the given +source files. For each input file, an output file is generated in the build +directory. The paths of the generated files are added to \c{<VAR>}. + +\note This is a low-level macro. See the \l{CMake AUTOMOC Documentation} for a +more convenient way to let source files be processed with \c{moc}. + +\section1 Arguments + +You can set an explicit \c{TARGET}. This will make sure that the target +properties \c{INCLUDE_DIRECTORIES} and \c{COMPILE_DEFINITIONS} are also used +when scanning the source files with \c{moc}. + +Since Qt 6.8, when a source file is passed to \c{qt_wrap_cpp} instead of a +header file to generate a \c{.moc} file for a target, the \c{TARGET} parameter +is needed to set the correct include path for the generated \c{.moc} file in +the source file. As generated \c{.moc} files are added to the target's +sources by \c{qt_wrap_cpp}, they are not added to \c{<VAR>}. + +You can set additional \c{OPTIONS} that should be added to the \c{moc} calls. +You can find possible options in the \l{moc}{moc documentation}. + +The \c{OPTIONS} can evaluate generator expressions when \c{TARGET} is set. +\note If the \c{OPTIONS} include both generator expressions and special +characters, use variables to implement them. For example, use \c{$<ANGLE-R>}, +\c{$<COMMA>} and \c{$<SEMICOLON>} instead of \c{>}, \c{,} and \c{:}. Otherwise, +the generator expression will not be evaluated correctly. \c {OPTIONS} are +wrapped in generator expressions, so you must escape special characters in +them. + +\c{DEPENDS} allows you to add additional dependencies for recreation of the +generated files. This is useful when the sources have implicit dependencies, +like code for a Qt plugin that includes a \c{.json} file using the +Q_PLUGIN_METADATA() macro. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_wrap_cpp_1 + +In the following example, the generator expressions passed to \c{OPTIONS} +will be evaluated since \c{TARGET} is set. The argument is specified this way to +avoid syntax errors in the generator expressions. + +\snippet cmake-macros/examples.cmake qt_wrap_cpp_2 + +The following example uses \l{https://cmake.org/cmake/help/latest/command/target_compile_definitions.html}{target_compile_definitions} +to set \l{https://cmake.org/cmake/help/latest/prop_tgt/COMPILE_DEFINITIONS.html}{COMPILE_DEFINITIONS} which will be added to +\c{OPTIONS}. + +\snippet cmake-macros/examples.cmake qt_wrap_cpp_4 + +\snippet cmake-macros/examples.cpp qt_wrap_cpp_4 + +In the above file, \c{myapp.moc} is included in \c{myapp.cpp}. +To generate the \c{myapp.moc} file, the \c{qt_wrap_cpp} macro is used with the +\c{TARGET} parameter. The first parameter is empty because the \c{.moc} file +and its path will be added to the target's sources and include directories by +the \c{qt_wrap_cpp} macro. + +\snippet cmake-macros/examples.cmake qt_wrap_cpp_4 +*/ |