diff options
Diffstat (limited to 'src/corelib/doc/src/cmake/cmake-properties.qdoc')
| -rw-r--r-- | src/corelib/doc/src/cmake/cmake-properties.qdoc | 393 |
1 files changed, 354 insertions, 39 deletions
diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc index d379eed9c1..8fe2b0e88f 100644 --- a/src/corelib/doc/src/cmake/cmake-properties.qdoc +++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc @@ -1,33 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \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: @@ -36,15 +13,17 @@ target properties: */ /*! -\page cmake-target-property-QT_ANDROID_DEPLOYMENT_DEPENDENCIES.html +\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 @@ -66,15 +45,17 @@ is listed before its dependencies, it will fail to load on some devices. */ /*! -\page cmake-target-property-QT_ANDROID_EXTRA_LIBS.html +\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 @@ -83,19 +64,71 @@ A list of external libraries that will be copied into your application's 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 +\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 @@ -117,15 +150,17 @@ mangling is applied to the plugin library. */ /*! -\page cmake-target-property-QT_ANDROID_MIN_SDK_VERSION.html +\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 @@ -135,15 +170,17 @@ Specifies the minimum Android API level for the target. */ /*! -\page cmake-target-property-QT_ANDROID_PACKAGE_SOURCE_DIR.html +\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 @@ -167,15 +204,17 @@ then place this directly into the directory specified by this variable. */ /*! -\page cmake-target-property-QT_ANDROID_TARGET_SDK_VERSION.html +\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 @@ -185,15 +224,38 @@ Specifies the target Android API level for the target. */ /*! -\page cmake-target-property-QT_ANDROID_VERSION_CODE.html +\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 @@ -206,15 +268,17 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. */ /*! -\page cmake-target-property-QT_ANDROID_VERSION_NAME.html +\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 @@ -227,7 +291,31 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. */ /*! -\page cmake-target-property-QT_QML_ROOT_PATH.html +\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 @@ -236,6 +324,7 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. \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 @@ -247,7 +336,7 @@ will be used instead. */ /*! -\page cmake-target-property-QT_QML_IMPORT_PATH.html +\page cmake-target-property-qt-qml-import-path.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -256,6 +345,7 @@ will be used instead. \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 @@ -268,15 +358,17 @@ For application-specific QML imports, use */ /*! -\page cmake-target-property-QT_ANDROID_DEPLOYMENT_SETTINGS_FILE.html +\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 @@ -287,7 +379,48 @@ and overwritten by that command. */ /*! -\page cmake-target-property-qt_no_entrypoint.html +\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 @@ -296,6 +429,7 @@ and overwritten by that command. \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. @@ -305,7 +439,7 @@ On targets that must provide their own entry point, set the property \c qt_no_en */ /*! -\page cmake-target-property-qt_resource_prefix.html +\page cmake-target-property-qt-resource-prefix.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -314,9 +448,190 @@ On targets that must provide their own entry point, set the property \c qt_no_en \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} +*/ |