diff options
Diffstat (limited to 'src/corelib/doc/src')
63 files changed, 2781 insertions, 829 deletions
diff --git a/src/corelib/doc/src/animation.qdoc b/src/corelib/doc/src/animation.qdoc index e09300010a..3d6c1eefa2 100644 --- a/src/corelib/doc/src/animation.qdoc +++ b/src/corelib/doc/src/animation.qdoc @@ -22,153 +22,134 @@ \keyword Animation - The animation framework aims to provide an easy way for creating animated - and smooth GUIs. By animating Qt properties, the framework provides great - freedom for animating widgets and other \l{QObject}s. The framework can - also be used with the Graphics View framework. Many of the concepts - available in the animation framework are also available in \l{Qt Quick}, - where it offers a declarative way of defining animations. Much of the - knowledge acquired about the animation framework can be applied to - \l{Qt Quick}. - - In this overview, we explain the basics of its architecture. We - also show examples of the most common techniques that the - framework allows for animating \l{QObject}s and graphics items. + The animation framework provides an easy way to animate your GUI elements. + It enables you to animate a Qt property value of a widget or QObject. + Most of the features offered by the framework are also available in + \l{Qt Quick}, where it's possible to define animations in a declarative way. + + This overview explains the framework's architecture, with examples that + demonstrate the common techniques used for animating QObject and + GUI elements. \tableofcontents - \section1 The Animation Architecture + \section1 The Animation architecture - We will in this section take a high-level look at the animation - framework's architecture and how it is used to animate Qt - properties. The following diagram shows the most important classes - in the animation framework. + The following diagram shows the most important classes provided by the + framework: \image animations-architecture.png - The animation framework foundation consists of the base class - QAbstractAnimation, and its two subclasses QVariantAnimation and - QAnimationGroup. QAbstractAnimation is the ancestor of all - animations. It represents basic properties that are common for all - animations in the framework; notably, the ability to start, stop, - and pause an animation. It is also receives the time change - notifications. - - The animation framework further provides the QPropertyAnimation - class, which inherits QVariantAnimation and performs animation of - a Qt property, which is part of Qt's \l{Meta-Object - System}{meta-object system}. The class performs an interpolation - over the property using an easing curve. So when you want to - animate a value, you can declare it as a property and make your - class a QObject. Note that this gives us great freedom in - animating already existing widgets and other \l{QObject}s. + It includes the QAbstractAnimation class, which provides the + necessary foundation for animations. This class defines the + generic properties for all animations supported by the framework. + For example, the ability to start, stop, and pause an animation. The + class also receives the time change notifications. + + The framework further provides the QVariantAnimation and + QAnimationGroup classes, which build on their base case, QAbstractAnimation. + Next in the hierarchy is QPropertyAnimation, which is derived from + QVariantAnmiation, and it lets you animate a Qt property of a widget or + QObject. The class performs interpolation on the property value using an + easing curve. With these in place, you just need a QObject class with a + Qt property value that you can animate. + + \note It is required that the target object you are animating is a QObject + or its subclass. This is necessary as the animation framework depends on the + \l{Meta-Object System}{meta-object system} for all the information about the + object it is animating. Complex animations can be constructed by building a tree structure - of \l{QAbstractAnimation}s. The tree is built by using - \l{QAnimationGroup}s, which function as containers for other - animations. Note also that the groups are subclasses of - QAbstractAnimation, so groups can themselves contain other groups. + of \l{QAbstractAnimation}s, where the tree is a QAnimationGroup that + contains other animations. These animation groups can also contain + subgroups representing different groups or animations, such as + QParallelAnimationGroup and QSequentialAnimationGroup. - Behind the scenes, the animations are controlled by a global - timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} to - all animations that are playing. + Behind the scenes, all animations are controlled by a global + timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} about + all animations that are running. - For detailed descriptions of the classes' function and roles in - the framework, please look up their class descriptions. + For detailed information of these individual classes' and their roles in + the framework, refer to their documentation. - \section1 Classes in the Animation Framework + \section1 Classes offered by the framework - These classes provide a framework for creating both simple and complex - animations. + These classes provide the necessary infrastructure to create both simple and + complex animations. \annotatedlist animation - \section1 Animating Qt Properties + \section1 Animating Qt properties - As mentioned in the previous section, the QPropertyAnimation class can - interpolate over Qt properties. It is often this class that should be used - for animation of values; in fact, its superclass, QVariantAnimation, has an - empty implementation of \l{QVariantAnimation::}{updateCurrentValue()}, and - does not change any value unless we change it ourselves on the + As the QPropertyAnimation class can interpolate on Qt properties, it is + used often. In fact, its superclass---QVariantAnimation---provides an + abstract implementation of \l{QVariantAnimation::}{updateCurrentValue()}, + which does not change any value unless you change it on the \l{QVariantAnimation::valueChanged()}{valueChanged signal}. - A major reason we chose to animate Qt properties is that it - presents us with freedom to animate already existing classes in - the Qt API. Notably, the QWidget class (which we can also embed in - a QGraphicsView) has properties for its bounds, colors, etc. - Let's look at a small example: - - \code - QPushButton button("Animated Button"); - button.show(); + The framework lets you animate the Qt properties of the existing + classes in Qt. For example, the QWidget class---can be embedded in + a QGraphicsView---has properties for its bounds, colors, and so on. + The following example demonstrates how you can animate a QPushButton + widget: - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(10000); - animation.setStartValue(QRect(0, 0, 100, 30)); - animation.setEndValue(QRect(250, 250, 100, 30)); + \snippet code/src_corelib_animation_qpropertyanimation.cpp 0 - animation.start(); - \endcode + The example animates the \c pos Qt property of a QPushButton, to move + it from the top--left corner of the screen to the end position (250, 250), + in 10 seconds (10000 milliseconds). - This code will move \c button from the top left corner of the - screen to the position (250, 250) in 10 seconds (10000 milliseconds). - - The example above will do a linear interpolation between the - start and end value. It is also possible to set values - situated between the start and end value. The interpolation - will then go by these points. + It uses the linear interpolation method to control the speed of + animation between the start and end values. Try adding another value + in--between the start and end value to see how they are interpolated. + This time use the QPropertyAnimation::setKeyValueAt function to add + these values: \code - QPushButton button("Animated Button"); - button.show(); - - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(10000); - - animation.setKeyValueAt(0, QRect(0, 0, 100, 30)); - animation.setKeyValueAt(0.8, QRect(250, 250, 100, 30)); - animation.setKeyValueAt(1, QRect(0, 0, 100, 30)); - - animation.start(); + ... + anim->setDuration(10000); + anim->setKeyValueAt(0, QPoint(0, 0)); + anim->setKeyValueAt(0.8, QPoint(250, 250)); + anim->setKeyValueAt(1, QPoint(0, 0)); + ... \endcode - In this example, the animation will take the button to (250, 250) - in 8 seconds, and then move it back to its original position in - the remaining 2 seconds. The movement will be linearly - interpolated between these points. + In this example, the animation moves the button to + (250, 250) in 8 seconds, and moves it back to its original position in + the remaining 2 seconds. The button's movement is linear-interpolated + between these points. + + You can also animate a QObject's value that is not declared as a Qt + property, if the value has a setter method. In such cases, derive + a new class from the class that contains the value, and add a Qt property + for that value with the setter. - You also have the possibility to animate values of a QObject - that is not declared as a Qt property. The only requirement is - that this value has a setter. You can then subclass the class - containing the value and declare a property that uses this setter. - Note that each Qt property requires a getter, so you will need to - provide a getter yourself if this is not defined. + \note Each Qt property requires a getter also, so you should provide a + getter if that is not defined. \code class MyGraphicsRectItem : public QObject, public QGraphicsRectItem { Q_OBJECT - Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry) + Q_PROPERTY(QPointF pos READ pos WRITE setPos) }; \endcode - In the above code example, we subclass QGraphicsRectItem and - define a geometry property. We can now animate the widgets - geometry even if QGraphicsRectItem does not provide the geometry - property. + In this example, the \c MyGraphicsRectItem derives from + QGraphicsRectItem and QObject, and defines the \c pos property. You can + animate the item's \c pos even if QGraphicsRectItem does not provide + the \c pos property. - For a general introduction to the Qt property system, see its - \l{Qt's Property System}{overview}. + For a general introduction to the Qt property system, refer to + \l{Qt's Property System}. \section1 Animations and the Graphics View Framework - When you want to animate \l{QGraphicsItem}s, you also use - QPropertyAnimation. However, QGraphicsItem does not inherit QObject. - A good solution is to subclass the graphics item you wish to animate. - This class will then also inherit QObject. - This way, QPropertyAnimation can be used for \l{QGraphicsItem}s. - The example below shows how this is done. Another possibility is - to inherit QGraphicsWidget, which already is a QObject. + QPropertyAnimation can also be used to animate a QGraphicsItem, which does + not inherit QObject. In such cases, you derive a class from the graphics + item that you want to animate. This derived class should also inherit form + QObject to enable using QPropertyAnimation on a QGraphicsItem. The + following example shows how this is done: \code class Pixmap : public QObject, public QGraphicsPixmapItem @@ -176,121 +157,78 @@ Q_OBJECT Q_PROPERTY(QPointF pos READ pos WRITE setPos) ... + } \endcode - As described in the previous section, we need to define - properties that we wish to animate. + \note You can also derive from QGraphicsWidget, which already is a + QObject. - Note that QObject must be the first class inherited as the - meta-object system demands this. + As described in the previous section, you need to define + properties that you want to animate. The derived class must inherit + from QObject first as the meta-object system requires it. - \section1 Easing Curves + \section1 Easing curves - As mentioned, QPropertyAnimation performs an interpolation between - the start and end property value. In addition to adding more key - values to the animation, you can also use an easing curve. Easing - curves describe a function that controls how the speed of the - interpolation between 0 and 1 should be, and are useful if you - want to control the speed of an animation without changing the - path of the interpolation. + A QPropertyAnimation performs linear interpolation + between the start and end property values. In addition to adding more key + values to the animation, you can also choose an easing curve to control the + speed of interpolation between 0 and 1, without changing the + path. - \code - QPushButton button("Animated Button"); - button.show(); - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(3000); - animation.setStartValue(QRect(0, 0, 100, 30)); - animation.setEndValue(QRect(250, 250, 100, 30)); - - animation.setEasingCurve(QEasingCurve::OutBounce); - - animation.start(); - \endcode + \snippet code/src_corelib_animation_qpropertyanimation.cpp easing-curve - Here the animation will follow a curve that makes it bounce like a - ball as if it was dropped from the start to the end position. - QEasingCurve has a large collection of curves for you to choose - from. These are defined by the QEasingCurve::Type enum. If you are - in need of another curve, you can also implement one yourself, and + In this example, the animation follows a curve that makes the + \c button bounce like a ball. QEasingCurve offers a large collection of curves + to choose from the QEasingCurve::Type enum. If you want + to use another curve that is not available, implement one yourself and register it with QEasingCurve. - \omit Drop this for the first Lab release - (Example of custom easing curve (without the actual impl of - the function I expect) - \endomit + \section1 Grouping animations - \section1 Putting Animations Together - - An application will often contain more than one animation. For - instance, you might want to move more than one graphics item + An application often contains more than one animation. For + example, it wants to move more than one graphics item simultaneously or move them in sequence after each other. - The subclasses of QAnimationGroup (QSequentialAnimationGroup and - QParallelAnimationGroup) are containers for other animations so + The subclasses of QAnimationGroup---QSequentialAnimationGroup and + QParallelAnimationGroup---are containers for other animations so that these animations can be animated either in sequence or - parallel. The QAnimationGroup is an example of an animation that - does not animate properties, but it gets notified of time changes - periodically. This enables it to forward those time changes to its - contained animations, and thereby controlling when its animations - are played. - - Let's look at code examples that use both - QSequentialAnimationGroup and QParallelAnimationGroup, starting - off with the latter. - - \code - QPushButton *bonnie = new QPushButton("Bonnie"); - bonnie->show(); + parallel. The QAnimationGroup does not animate properties, but it + gets notified of time changes periodically. This enables it to + forward those time changes to the animation groups, which control when + their animations are played. - QPushButton *clyde = new QPushButton("Clyde"); - clyde->show(); + The two following examples demonstrate the use of both + QSequentialAnimationGroup and QParallelAnimationGroup: - QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "geometry"); - // Set up anim1 - - QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "geometry"); - // Set up anim2 - - QParallelAnimationGroup *group = new QParallelAnimationGroup; - group->addAnimation(anim1); - group->addAnimation(anim2); - - group->start(); - \endcode + \snippet code/src_corelib_animation_qpropertyanimation.cpp animation-group1 A parallel group plays more than one animation at the same time. - Calling its \l{QAbstractAnimation::}{start()} function will start - all animations it governs. - - \code - QPushButton button("Animated Button"); - button.show(); + Its \l{QAbstractAnimation::}{start()} function starts all + animations that are part of the group. - QPropertyAnimation anim1(&button, "geometry"); - anim1.setDuration(3000); - anim1.setStartValue(QRect(0, 0, 100, 30)); - anim1.setEndValue(QRect(500, 500, 100, 30)); + \snippet code/src_corelib_animation_qpropertyanimation.cpp animation-group2 - QPropertyAnimation anim2(&button, "geometry"); - anim2.setDuration(3000); - anim2.setStartValue(QRect(500, 500, 100, 30)); - anim2.setEndValue(QRect(1000, 500, 100, 30)); + As the name suggests, a QSequentialAnimationGroup plays + its animations in sequence. It starts the next animation in + the list after the previous finishes. - QSequentialAnimationGroup group; + A group is an animation itself, so you can add + it to another group. This way, building an animation tree, which define + when the animations are played in relation to each other. - group.addAnimation(&anim1); - group.addAnimation(&anim2); + \section1 Object ownership - group.start(); - \endcode + A QPropertyAnimation should always have a parent that controls + its lifespan. A typical application may include several animations that + are grouped, where the animation group takes ownership of those animations. + An independent QPropertyAnimation must be explicitly assigned a parent to + control its lifespan. In the following example, you can see that an + independent QPropertyAnimation has the QApplication instance as its + parent: - As you no doubt have guessed, QSequentialAnimationGroup plays - its animations in sequence. It starts the next animation in - the list after the previous is finished. + \snippet code/src_corelib_animation_qpropertyanimation.cpp 0 - Since an animation group is an animation itself, you can add - it to another group. This way, you can build a tree structure - of animations which specifies when the animations are played - in relation to each other. + \note You can also control the animation's lifespan by choosing a + \l{QAbstractAnimation::DeletionPolicy}{delete policy} while starting it. */ diff --git a/src/corelib/doc/src/cbor.qdoc b/src/corelib/doc/src/cbor.qdoc new file mode 100644 index 0000000000..30d7ddaf60 --- /dev/null +++ b/src/corelib/doc/src/cbor.qdoc @@ -0,0 +1,79 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \group cbor + \title CBOR Support in Qt + \ingroup qt-basic-concepts + \brief An overview of CBOR support in Qt. + \ingroup explanations-dataprocessingandio + + \ingroup frameworks-technologies + + \keyword CBOR + + Qt provides support for dealing with CBOR data. CBOR is a binary format to + store data that has a superset of the types available in JSON, but is more + compact. + + The CBOR support in Qt provides an easy to use C++ API to parse, + modify and save CBOR data. + + More details about the CBOR data format can be found in \l {RFC 7049}. + + \tableofcontents + + \section1 Overview + + CBOR is a format to store structured data. It has three groups of built-in types: + + \list + \li Basic types: integers, floating point, boolean, null, etc. + \li String-like types: strings and byte arrays + \li Containers: arrays and maps + \endlist + + In addition, CBOR can add a "tag" to extend the meaning of the type. The + container types can contain basic types, string-like types and containers. + + \sa {Parsing and displaying CBOR data}, {Serialization Converter}, {Saving and Loading a Game} + + \section1 The CBOR Classes + + \section2 The QCborValue Class + + The QCborValue class represents any CBOR type. It also has a simple API for + reading and writing to QCborStreamReader and QCborStreamWriter objects, as + well as manipulating such objects in memory, with the help of QCborArray + and QCborMap. The CborValue API is simplified from the full CBOR data type + and always represents all integers as \l qint64 and all floating-point as + \c double. This means QCborValue is unable to represent CBOR integer values + outside of the range of \l qint64 (-2^63 to 2^63-1). When creating a CBOR + stream, QCborValue::toCbor() can be configured to attempt to write the + shorter single- and half-precision floating-point representations. + + \section2 The QCborArray Class + + The QCborArray class is used to hold an array of QCborValue objects. A + QCborValue object can contain a QCborArray object. It has functions for + converting to and from QVariantList, QStringList, QJsonArray. + + \section2 The QCborMap Class + + The QCborMap class is used to hold an map of QCborValue objects. A + QCborValue object can contain a QCborMap object. It has functions for + converting to and from QVariantMap, QVariantMap, and QJsonObject, but it + can have keys of any type, not just QString. + + \section2 The QCborStreamReader Class + + The QCborStreamReader class is a low level API for reading CBOR data from a + QIODevice, a QByteArray, or a pointer to memory. It has an API similar to + the QXmlStreamReader class. + + \section2 The QCborStreamWriter Class + + The QCborStreamWriter class is a low level API for writing CBOR data to a + QIODevice or a QByteArray. It has an API similar to the QXmlStreamWriter + class. +*/ diff --git a/src/corelib/doc/src/cmake/cmake-commands.qdoc b/src/corelib/doc/src/cmake/cmake-commands.qdoc index 7e98c16e41..e185bab624 100644 --- a/src/corelib/doc/src/cmake/cmake-commands.qdoc +++ b/src/corelib/doc/src/cmake/cmake-commands.qdoc @@ -4,6 +4,7 @@ /*! \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 diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc index 25d69c36c3..b710ba7275 100644 --- a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// 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 @@ -10,6 +10,7 @@ /*! \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 @@ -21,8 +22,8 @@ find_package(Qt6 REQUIRED COMPONENTS Core) \sa{CMake Variable Reference} */ -*/*! -\page cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME.html +/*! +\page cmake-variable-android-ndk-host-system-name.html \ingroup cmake-variables-qtcore \title ANDROID_NDK_HOST_SYSTEM_NAME @@ -34,14 +35,14 @@ find_package(Qt6 REQUIRED COMPONENTS Core) \preliminarycmakevariable \cmakevariableandroidonly -This is normally set by the Android NDK toolchain file. It is written out as +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 +\page cmake-variable-android-sdk-root.html \ingroup cmake-variables-qtcore \title ANDROID_SDK_ROOT @@ -53,15 +54,16 @@ part of the deployment settings for a target. \preliminarycmakevariable \cmakevariableandroidonly -This specifies the location of the Android SDK when building for the Android platform. -It is written out as part of the deployment settings for a target. +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 +\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 @@ -72,15 +74,122 @@ It is written out as part of the deployment settings for a target. \preliminarycmakevariable \cmakevariableandroidonly -This contains a list of arguments to be passed to Android applications. It is written -out as part of the deployment settings for a target. +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_BUILD_ALL_ABIS.html +\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 @@ -91,29 +200,30 @@ out as part of the deployment settings for a target. \preliminarycmakevariable \cmakevariableandroidonly -The option automatically detects available ABIs of Qt for Android and uses them to +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 -Â Â Â ... + 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 FALSE by default. +The variable is set to \c FALSE by default. \sa{QT_PATH_ANDROID_ABI_<ABI>} */ /*! -\page cmake-variable-QT_ANDROID_ABIS.html +\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 @@ -124,10 +234,10 @@ The variable is set to FALSE by default. \preliminarycmakevariable \cmakevariableandroidonly -This variable specifies a list of ABIs to be used to build the project packages. +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. It's possible to specify the path to the Qt for Android ABI using +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 @@ -137,7 +247,7 @@ QT_ANDROID_ABIS logic. */ /*! -\page cmake-variable-QT_PATH_ANDROID_ABI.html +\page cmake-variable-qt-path-android-abi.html \ingroup cmake-variables-qtcore \title QT_PATH_ANDROID_ABI_<ABI> @@ -156,7 +266,129 @@ Each variable can be used to specify the path to Qt for Android for the correspo */ /*! -\page cmake-variable-QT_HOST_PATH.html +\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 @@ -165,15 +397,17 @@ Each variable can be used to specify the path to Qt for Android for the correspo \summary {Location of the host Qt installation when cross-compiling.} \cmakevariablesince 6.0 -\preliminarycmakevariable -When cross-compiling, this must be set to the install location of Qt for the host +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). +\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 +\page cmake-variable-qt-no-set-xcode-development-team-id.html \ingroup cmake-variables-qtcore \title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID @@ -186,11 +420,11 @@ platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc}, 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. -Set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to true if you want to prevent this. +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 +\page cmake-variable-qt-no-set-xcode-bundle-identifier.html \ingroup cmake-variables-qtcore \title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER @@ -204,17 +438,17 @@ 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. -Set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to true if you want to prevent this. +To prevent this, set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to \c TRUE. */ /*! -\page cmake-variable-QT_ENABLE_VERBOSE_DEPLOYMENT.html +\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} +\summary {Enables verbose mode of deployment tools.} \cmakevariablesince 6.3 \preliminarycmakevariable @@ -223,12 +457,12 @@ Enables verbose mode of the \l androiddeployqt deployment tool when it is called internally at build time, usually during target finalization. This variable also changes the default verbosity of install-time deployment -scripts for other platforms (see \l{qt_deploy_runtime_dependencies()}), but it +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 +\page cmake-variable-qt-deploy-support.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_SUPPORT @@ -243,19 +477,20 @@ must be set before the first \c{find_package(Qt6)} call to have that effect. 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 +CMake's configure phase. They are executed during installation or as part of a post-build rule. The following example shows one way the variable would be used when installing an application, along with its runtime dependencies: -\include cmake-deploy-runtime-dependencies.qdocinc +\include cmake-deploy-modified-variable-values.qdocinc -\sa qt_deploy_runtime_dependencies(), qt_deploy_qml_imports() +\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 +\page cmake-variable-qt-no-standard-project-setup.html \ingroup cmake-variables-qtcore \title QT_NO_STANDARD_PROJECT_SETUP @@ -264,16 +499,89 @@ an application, along with its runtime dependencies: \summary {Prevents subsequent calls to qt_standard_project_setup() from making any changes.} \cmakevariablesince 6.3 -\preliminarycmakevariable The \l{qt6_standard_project_setup}{qt_standard_project_setup()} command is typically called in the top level \c{CMakeLists.txt} file of a project. In some -scenarios, such projects may be absorbed as a child project of a larger project +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 true before bringing in the child project -via \l{add_subdirectory()}, \l{FetchContent_MakeAvailable()} or other similar +\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 index b10de9dc3b..ac5094e7cb 100644 --- a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc @@ -8,7 +8,7 @@ **/ /*! -\page cmake-variable-QT_DEPLOY_PREFIX.html +\page cmake-variable-qt-deploy-prefix.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_PREFIX @@ -19,7 +19,6 @@ \include cmake-deploy-var-usage.qdocinc \cmakevariablesince 6.3 -\preliminarycmakevariable \c{QT_DEPLOY_PREFIX} provides the base deployment directory. The other \c{QT_DEPLOY_..._DIR} variables should be treated as relative to this location. @@ -48,12 +47,13 @@ scripts should assume that the working directory is already set to the base install location and just use the prefix-relative \c{QT_DEPLOY_..._DIR} variables. -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIBEXEC_DIR, + QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR */ /*! -\page cmake-variable-QT_DEPLOY_BIN_DIR.html +\page cmake-variable-qt-deploy-bin-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_BIN_DIR @@ -64,7 +64,6 @@ variables. \include cmake-deploy-var-usage.qdocinc \cmakevariablesince 6.3 -\preliminarycmakevariable 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 @@ -89,12 +88,51 @@ should not be used for that scenario. \include cmake-deploy-runtime-dependencies.qdocinc -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_LIBEXEC_DIR, + QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR */ /*! -\page cmake-variable-QT_DEPLOY_LIB_DIR.html +\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 @@ -105,7 +143,6 @@ should not be used for that scenario. \include cmake-deploy-var-usage.qdocinc \cmakevariablesince 6.3 -\preliminarycmakevariable 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 @@ -132,11 +169,11 @@ should not be used for that scenario. \include cmake-deploy-modified-variable-values.qdocinc \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, - QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR + QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR */ /*! -\page cmake-variable-QT_DEPLOY_PLUGINS_DIR.html +\page cmake-variable-qt-deploy-plugins-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_PLUGINS_DIR @@ -147,7 +184,6 @@ should not be used for that scenario. \include cmake-deploy-var-usage.qdocinc \cmakevariablesince 6.3 -\preliminarycmakevariable Projects should use \c QT_DEPLOY_PLUGINS_DIR in their deploy scripts to avoid hard-coding a particular directory under which to deploy plugins. @@ -167,12 +203,13 @@ bundle contents. \include cmake-deploy-modified-variable-values.qdocinc -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_QML_DIR +\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 +\page cmake-variable-qt-deploy-qml-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_QML_DIR @@ -183,7 +220,6 @@ bundle contents. \include cmake-deploy-var-usage.qdocinc \cmakevariablesince 6.3 -\preliminarycmakevariable 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. @@ -205,6 +241,67 @@ to be deployed to different locations within the app bundle. \include cmake-deploy-modified-variable-values.qdocinc +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, + QT_DEPLOY_LIBEXEC_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, + QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-translations-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_TRANSLATIONS_DIR +\target cmake-variable-QT_DEPLOY_TRANSLATIONS_DIR + +\summary {Prefix-relative subdirectory for deploying Qt translations on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.5 + +Projects should use \c QT_DEPLOY_TRANSLATIONS_DIR in their deploy scripts to +avoid hard-coding a particular directory under which to deploy translations. + +\c QT_DEPLOY_TRANSLATIONS_DIR defaults to the value \c{translations}. To change +the value of \c QT_DEPLOY_TRANSLATIONS_DIR, set it in the project deployment +script before \c QT_DEPLOY_SUPPORT is included. + +The \c QT_DEPLOY_TRANSLATIONS_DIR path is relative to \l{QT_DEPLOY_PREFIX}. + +This variable is not meaningful when deploying on macOS or Windows. + +\section1 Example + +\include cmake-deploy-modified-variable-values.qdocinc + \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_PLUGINS_DIR + QT_DEPLOY_LIBEXEC_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-ignored-lib-dirs.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_IGNORED_LIB_DIRS +\target cmake-variable-QT_DEPLOY_IGNORED_LIB_DIRS + +\summary {Directories that are excluded from runtime dependencies search} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.5 + +This variable contains a list of directories that are not taken into account +when searching for runtime dependencies with \l{qt_deploy_runtime_dependencies}. + +Projects may alter this variable before calling +\l{qt_deploy_runtime_dependencies} to control from which directory runtime +dependencies are deployed. + +This variable is ignored if the \c{POST_EXCLUDE_REGEXES} option is specified in +the \l{qt_deploy_runtime_dependencies} call. + +This variable is not meaningful when deploying on macOS or Windows. + +\sa qt_deploy_runtime_dependencies */ diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc index bbb948aec2..8fe2b0e88f 100644 --- a/src/corelib/doc/src/cmake/cmake-properties.qdoc +++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc @@ -4,6 +4,7 @@ /*! \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: @@ -12,9 +13,10 @@ 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 @@ -43,9 +45,10 @@ 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 @@ -61,13 +64,64 @@ 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 @@ -96,9 +150,10 @@ 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 @@ -115,9 +170,10 @@ 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 @@ -148,9 +204,10 @@ 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 @@ -167,12 +224,34 @@ 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.} @@ -189,12 +268,13 @@ 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.} @@ -211,9 +291,10 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. */ /*! -\page cmake-target-property-QT_ANDROID_ABIS.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 @@ -234,7 +315,7 @@ The property only affects targets created with */ /*! -\page cmake-target-property-QT_QML_ROOT_PATH.html +\page cmake-target-property-qt-qml-root-path.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -255,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 @@ -277,9 +358,10 @@ 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 @@ -297,9 +379,10 @@ and overwritten by that command. */ /*! -\page cmake-target-property-QT_ANDROID_SYSTEM_LIBS_PREFIX.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 @@ -314,9 +397,10 @@ when those libraries are installed outside app's native (JNI) library directory. */ /*! -\page cmake-target-property-QT_ANDROID_NO_DEPLOY_QT_LIBS.html +\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 @@ -336,7 +420,7 @@ instead. */ /*! -\page cmake-target-property-qt_no_entrypoint.html +\page cmake-target-property-qt-no-entrypoint.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -355,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 @@ -375,6 +459,7 @@ 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: @@ -383,7 +468,7 @@ source file properties: */ /*! -\page cmake-source-file-property-QT_RESOURCE_ALIAS.html +\page cmake-source-file-property-qt-resource-alias.html \ingroup cmake-source-file-properties-qtcore \title QT_RESOURCE_ALIAS @@ -392,7 +477,6 @@ source file properties: \summary {Specifies the Qt resource alias for a file in a resource.} \cmakepropertysince 6.0 -\preliminarycmakeproperty 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. @@ -401,7 +485,34 @@ the property value overrides the runtime path where the resource file is found. */ /*! -\page cmake-target-property-QT_WASM_PTHREAD_POOL_SIZE.html +\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 @@ -425,7 +536,44 @@ For more information, see \l{https://emscripten.org/docs/porting/pthreads.html}{ */ /*! -\page cmake-target-property-QT_WASM_INITIAL_MEMORY.html +\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 @@ -445,3 +593,45 @@ 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 index 07e75f6fc5..8215d4c717 100644 --- a/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_bigresources.html +\page qt-add-bigresources.html \ingroup cmake-commands-qtcore \title qt_add_big_resources -\target qt6_add_big_resources +\keyword qt6_add_big_resources \summary {Compiles big binary resources into object code.} @@ -34,6 +34,14 @@ 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. diff --git a/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc index a247b6d7c0..12ee5e1aff 100644 --- a/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_binary_resources.html +\page qt-add-binary-resources.html \ingroup cmake-commands-qtcore \title qt_add_binary_resources -\target qt6_add_binary_resources +\keyword qt6_add_binary_resources \summary {Creates an RCC file from a list of Qt resource files.} diff --git a/src/corelib/doc/src/cmake/qt_add_executable.qdoc b/src/corelib/doc/src/cmake/qt_add_executable.qdoc index a09ecc8dfd..cc8c924c79 100644 --- a/src/corelib/doc/src/cmake/qt_add_executable.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_executable.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_executable.html +\page qt-add-executable.html \ingroup cmake-commands-qtcore \title qt_add_executable -\target qt6_add_executable +\keyword qt6_add_executable \summary {Creates and finalizes an application target of a platform-specific type.} @@ -60,25 +60,34 @@ for you as a convenience. 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 the -\l{qt6_finalize_target}{qt_finalize_target()} command. You might need to also -call the \l{qt6_finalize_project}{qt_finalize_project()} command at the end -of top-level CMakeLists.txt to correctly resolve the dependencies between -project targets. - -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 +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, finalization is performed immediately before this command returns. +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()}, @@ -101,5 +110,5 @@ 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.cmake +\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 index 52b85d0476..851a2d6210 100644 --- a/src/corelib/doc/src/cmake/qt_add_library.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_library.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_library.html +\page qt-add-library.html \ingroup cmake-commands-qtcore \title qt_add_library -\target qt6_add_library +\keyword qt6_add_library \summary {Creates and finalizes a library.} @@ -45,12 +45,15 @@ 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. The \c{qt_add_library()} command does not consider -\c BUILD_SHARED_LIBS when deciding the library type. +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 @@ -72,6 +75,6 @@ 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()} + {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 index 89a68dbee2..d2322086e7 100644 --- a/src/corelib/doc/src/cmake/qt_add_plugin.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_plugin.html +\page qt-add-plugin.html \ingroup cmake-commands-qtcore \title qt_add_plugin -\target qt6_add_plugin +\keyword qt6_add_plugin \summary {Creates a Qt plugin target.} @@ -21,9 +21,14 @@ 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 @@ -37,6 +42,9 @@ 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 @@ -63,4 +71,17 @@ 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 index 7de9b94854..2e713b1b8e 100644 --- a/src/corelib/doc/src/cmake/qt_add_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_resources.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_resources.html +\page qt-add-resources.html \ingroup cmake-commands-qtcore \title qt_add_resources -\target qt6_add_resources +\keyword qt6_add_resources \summary {Compiles binary resources into source code.} @@ -28,6 +28,7 @@ qt_add_resources(<TARGET> <RESOURCE_NAME> [PREFIX <PATH>] [LANG <LANGUAGE>] [BASE <PATH>] + [BIG_RESOURCES] [OUTPUT_TARGETS <VARIABLE_NAME>] [FILES ...] [OPTIONS ...]) \endcode @@ -47,8 +48,6 @@ 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}. -For embedding bigger resources, see \l qt_add_big_resources. - See \l{The Qt Resource System} for a general description of Qt resources. \section1 Arguments of the target-based variant @@ -56,7 +55,9 @@ See \l{The Qt Resource System} for a general description of Qt resources. \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. +\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. @@ -69,6 +70,16 @@ example, if \c BASE is \c{"assets"} and \c FILES is 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 @@ -94,4 +105,6 @@ 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 index 8219380bd5..ad95401f4d 100644 --- a/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc +++ b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_allow_non_utf8_sources.html +\page qt-allow-non-utf8-sources.html \ingroup cmake-commands-qtcore \title qt_allow_non_utf8_sources -\target qt6_allow_non_utf8_sources +\keyword qt6_allow_non_utf8_sources \summary {Prevents forcing source files to be treated as UTF-8 for Windows.} 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 index 7818596c76..b2415730f5 100644 --- a/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc @@ -2,18 +2,18 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_android_add_apk_target.html +\page qt-android-add-apk-target.html \ingroup cmake-commands-qtcore \title qt_android_add_apk_target -\target qt6_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 -\preliminarycmakecommand +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable instead. \cmakecommandandroidonly \section1 Synopsis 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 index 5451a6727c..a29e1f6123 100644 --- a/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc @@ -2,18 +2,19 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_android_apply_arch_suffix.html +\page qt-android-apply-arch-suffix.html \ingroup cmake-commands-qtcore \title qt_android_apply_arch_suffix -\target qt6_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 -\preliminarycmakecommand +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable +or \l qt_add_library instead. \cmakecommandandroidonly \section1 Synopsis 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 index 4df3a32101..5a7bbdc33f 100644 --- a/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc @@ -2,18 +2,18 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_android_generate_deployment_settings.html +\page qt-android-generate-deployment-settings.html \ingroup cmake-commands-qtcore \title qt_android_generate_deployment_settings -\target qt6_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 -\preliminarycmakecommand +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable instead. \cmakecommandandroidonly \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc index 4f2b638835..45fd8f4c5f 100644 --- a/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc +++ b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_deploy_qt_conf.html +\page qt-deploy-qt-conf.html \ingroup cmake-commands-qtcore \title qt_deploy_qt_conf -\target qt_deploy_qt_conf +\keyword qt6_deploy_qt_conf \summary {Write a qt.conf file at deployment time.} @@ -17,7 +17,6 @@ only be called from a deployment script. It cannot be called directly by the project. \cmakecommandsince 6.3 -\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. @@ -58,16 +57,15 @@ variables can be used to dynamically specify a path relative to the deployment b 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()}, - qt_deploy_runtime_dependencies() + {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()} \section1 Example \badcode # The following script must only be executed at install time -set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_custom.cmake") - -file(GENERATE OUTPUT ${deploy_script} CONTENT " -include(\"${QT_DEPLOY_SUPPORT}\") +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\" diff --git a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc index 6f950b4020..f64960492a 100644 --- a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc +++ b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_deploy_runtime_dependencies.html +\page qt-deploy-runtime-dependencies.html \ingroup cmake-commands-qtcore \title qt_deploy_runtime_dependencies -\target qt_deploy_runtime_dependencies +\keyword qt6_deploy_runtime_dependencies \summary {Deploy Qt plugins, Qt and non-Qt libraries needed by an executable.} @@ -17,7 +17,6 @@ can only be called from a deployment script. It cannot be called directly by the project during the configure stage. \cmakecommandsince 6.3 -\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. @@ -32,12 +31,22 @@ qt_deploy_runtime_dependencies( [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 @@ -47,22 +56,25 @@ When installing an application, it may be desirable to also install the libraries and plugins it depends on. When the application is a macOS app bundle or a Windows executable, \c{qt_deploy_runtime_dependencies()} can be called from an install-time script to deploy those dependencies. It will install -non-system libraries (both Qt and those provided by the project), plus an -appropriate set of Qt plugins. +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{qt_deploy_qml_imports()} for that. +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 a path to the executable file, relative to -the base install location. For example, \c{bin/MyApp.exe}, or more dynamically -\c{\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>}. -Specifying raw target names not wrapped in a generator epxression like -\c{<TARGET_FILE_NAME:>} is not supported. +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. @@ -92,13 +104,41 @@ directory structure. If the \c{GENERATE_QT_CONF} option is given, an appropriate \c{qt.conf} file will be written to the same directory as the \c{executable}. The paths in that \c{qt.conf} file will be based on the \c{CMAKE_INSTALL_xxxDIR} variables, whose defaults are provided by CMake's \l{GNUInstallDirs} module. -You can override some of those defaults with the \c{BIN_DIR}, \c{LIB_DIR}, -\c{PLUGINS_DIR}, and \c{QML_DIR} options, all of which are expected to be -relative to the base install location. A \c{qt.conf} file is always written if -\c{executable} is a macOS app bundle, regardless of whether or not -\c{GENERATE_QT_CONF} is provided. The \c{..._DIR} options are also ignored in -that case, since the directory layout of an app bundle is dictated by Apple's -requirements. + +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} @@ -114,10 +154,45 @@ 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()}, - qt_deploy_qt_conf(), qt_deploy_qml_imports() + {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 index b056afea85..91de52544e 100644 --- a/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc +++ b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_disable_unicode_defines.html +\page qt-disable-unicode-defines.html \ingroup cmake-commands-qtcore \title qt_disable_unicode_defines -\target qt6_disable_unicode_defines +\keyword qt6_disable_unicode_defines \summary {Prevents some unicode-related compiler definitions being set automatically on a target.} diff --git a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc index a430989036..7ec8d90f9b 100644 --- a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc +++ b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_extract_metatypes.html +\page qt-extract-metatypes.html \ingroup cmake-commands-qtcore \title qt_extract_metatypes -\target qt6_extract_metatypes +\keyword qt6_extract_metatypes \summary {Extracts metatypes from a Qt target and generates an associated metatypes.json file.} @@ -52,4 +52,18 @@ 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 index dc63e66cd6..5506712691 100644 --- a/src/corelib/doc/src/cmake/qt_finalize_project.qdoc +++ b/src/corelib/doc/src/cmake/qt_finalize_project.qdoc @@ -2,13 +2,13 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_finalize_project.html +\page qt-finalize-project.html \ingroup cmake-commands-qtcore \title qt_finalize_project -\target qt6_finalize_project +\keyword qt6_finalize_project -\summary {Handles various common platform-specific tasks associated with Qt project.} +\summary {Handles various common platform-specific tasks associated with a Qt project.} \preliminarycmakecommand \include cmake-find-package-core.qdocinc @@ -26,15 +26,19 @@ qt_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 walks through the build tree, resolves dependencies between targets -created by the user, and applies extra deployment steps. - -With CMake versions 3.19 and higher, you don't need to call this command since +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 scope. +\c CMAKE_SOURCE_DIR directory scope processing. -\include cmake-android-qt-finalize-project-warning.cmake +\include cmake-android-qt-finalize-project-warning.qdocinc warning \section2 Examples @@ -44,4 +48,6 @@ 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 index 558e89991f..b74dee64d2 100644 --- a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc +++ b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_finalize_target.html +\page qt-finalize-target.html \ingroup cmake-commands-qtcore \title qt_finalize_target -\target qt6_finalize_target +\keyword qt6_finalize_target \summary {Handles various common platform-specific tasks associated with Qt targets.} @@ -32,10 +32,10 @@ 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()} or -\l{qt6_add_library}{qt_add_library()}. The timing of when that call takes -place and when it might need to be called explicitly by a project is discussed -in the documentation of those commands. +\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()} @@ -61,7 +61,7 @@ CMake version earlier than 3.21. \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}. +\c{qtloader.js}, and \c{qtlogo.svg} files in the \c{CMAKE_CURRENT_BINARY_DIR}. \section2 iOS 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 index b3a3328098..31d9e4384b 100644 --- a/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc +++ b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc @@ -2,27 +2,35 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_generate_deploy_app_script.html +\page qt-generate-deploy-app-script.html \ingroup cmake-commands-qtcore \title qt_generate_deploy_app_script -\target qt6_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 -\preliminarycmakecommand -\note This command is currently only supported on Windows and macOS. +\note This command is currently only supported on Windows, macOS, and Linux. \section1 Synopsis \badcode qt_generate_deploy_app_script( TARGET target - FILENAME_VARIABLE var_name + 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 @@ -41,48 +49,62 @@ determined by \l{GNUInstallDirs} (except for macOS app bundles, which follow Apple's requirements instead). The command generates a script whose name will be stored in the variable named -by the \c{FILENAME_VARIABLE} option. That script is only written at CMake +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{qt_deploy_runtime_dependencies()} with a -suitable set of options for the standard install layout. -Currently, this is only implemented for macOS app bundles built on a macOS -host and Windows executables built on a Windows host. +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 -\badcode -cmake_minimum_required(VERSION 3.16...3.22) -project(MyThings) +The following example shows how to deploy an application \c{MyApp}. -find_package(Qt6 REQUIRED COMPONENTS Core) -qt_standard_project_setup() +\include cmake-generate-deploy-app-script.qdocinc -qt_add_executable(MyApp main.cpp) +The following example shows how to use the \c{DEPLOY_TOOL_OPTIONS} parameter to +pass different options to macdeployqt and windeployqt. -install(TARGETS MyApp - BUNDLE DESTINATION . - RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} -) +\include cmake-generate-deploy-app-script-deploy-tool-options.qdocinc -qt_generate_deploy_app_script( - TARGET MyApp - FILENAME_VARIABLE deploy_script - NO_UNSUPPORTED_PLATFORM_ERROR -) -install(SCRIPT ${deploy_script}) -\endcode */ diff --git a/src/corelib/doc/src/cmake/qt_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 index 4f60ae1ae2..9b123f9323 100644 --- a/src/corelib/doc/src/cmake/qt_generate_moc.qdoc +++ b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_generate_moc.html +\page qt-generate-moc.html \ingroup cmake-commands-qtcore \title qt_generate_moc -\target qt6_generate_moc +\keyword qt6_generate_moc \summary {Calls moc on an input file.} diff --git a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc index cea6fc61f5..1f81a21cd2 100644 --- a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc +++ b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc @@ -2,13 +2,13 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_import_plugins.html +\page qt-import-plugins.html \ingroup cmake-commands-qtcore \title qt_import_plugins -\target qt6_import_plugins +\keyword qt6_import_plugins -\summary {Specifies a custom set of plugins to import for a static Qt build.} +\summary {Specifies a custom set of plugins to import or exclude.} \include cmake-find-package-core.qdocinc @@ -48,17 +48,35 @@ can be used more than once. 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 plugins, for each Qt module that the target is linked -against. For more information, see +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 plugin. Consequently, any target that links against a plugin -has this C++ file added to its \c SOURCES. - -\note This command imports plugins from static Qt builds only. -On shared builds, it does nothing. +initializes the static plugin. Consequently, any target that links against +a plugin has this C++ file added to its \c SOURCES. \section1 Examples 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 index 476c63ccc0..28622c11e8 100644 --- a/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc +++ b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_set_finalizer_mode.html +\page qt-set-finalizer-mode.html \ingroup cmake-commands-qtcore \title qt_set_finalizer_mode -\target qt6_set_finalizer_mode +\keyword qt6_set_finalizer_mode \summary {Customizes aspects of a target's finalization.} diff --git a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc index b94d688e49..59b33f599c 100644 --- a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc +++ b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_standard_project_setup.html +\page qt-standard-project-setup.html \ingroup cmake-commands-qtcore \title qt_standard_project_setup -\target qt6_standard_project_setup +\keyword qt6_standard_project_setup \summary {Setup project-wide defaults to a standard arrangement.} @@ -17,7 +17,12 @@ \section1 Synopsis \badcode -qt_standard_project_setup() +qt_standard_project_setup( + [REQUIRES <version>] + [SUPPORTS_UP_TO <version>] + [I18N_TRANSLATED_LANGUAGES <language...>] + [I18N_SOURCE_LANGUAGE <language>] +) \endcode \versionlessCMakeCommandsNote qt6_standard_project_setup() @@ -42,8 +47,20 @@ have been defined. It does the following things: \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 @@ -57,12 +74,28 @@ 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-deploy-runtime-dependencies.qdocinc +\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 index 8390b81cd3..3b298a9d7e 100644 --- a/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc +++ b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_wrap_cpp.html +\page qt-wrap-cpp.html \ingroup cmake-commands-qtcore \title qt_wrap_cpp -\target qt6_wrap_cpp +\keyword qt6_wrap_cpp \summary {Creates .moc files from sources.} @@ -40,9 +40,23 @@ 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 @@ -50,5 +64,27 @@ Q_PLUGIN_METADATA() macro. \section1 Examples -\snippet cmake-macros/examples.cmake qt_wrap_cpp +\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 */ diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc index bed184de15..847be1bff6 100644 --- a/src/corelib/doc/src/containers.qdoc +++ b/src/corelib/doc/src/containers.qdoc @@ -39,7 +39,8 @@ \note Since Qt 5.14, range constructors are available for most of the container classes. QMultiMap is a notable exception. Their use is - encouraged in place of the various from/to methods. For example: + encouraged to replace of the various deprecated from/to methods of Qt 5. + For example: \snippet code/doc_src_containers.cpp 25 @@ -191,7 +192,30 @@ the C++ language doesn't specify any initialization; in those cases, Qt's containers automatically initialize the value to 0. - \section1 The Iterator Classes + \section1 Iterating over Containers + + \section2 Range-based for + + Range-based \c for should preferably be used for containers: + + \snippet code/doc_src_containers.cpp range_for + + Note that when using a Qt container in a non-const context, + \l{implicit sharing} may perform an undesired detach of the container. + To prevent this, use \c std::as_const(): + + \snippet code/doc_src_containers.cpp range_for_as_const + + For associative containers, this will loop over the values. + + \section2 Index-based + + For sequential containers that store their items contiguously in memory + (for example, QList), index-based iteration can be used: + + \snippet code/doc_src_containers.cpp index + + \section2 The Iterator Classes Iterators provide a uniform means to access items in a container. Qt's container classes provide two types of iterators: STL-style @@ -200,7 +224,7 @@ from \l{Implicit Sharing}{implicitly shared copies} due to a call to a non-const member function. - \section2 STL-Style Iterators + \section3 STL-Style Iterators STL-style iterators have been available since the release of Qt 2.0. They are compatible with Qt's and STL's \l{generic @@ -262,12 +286,10 @@ In the code snippets so far, we used the unary \c * operator to retrieve the item (of type QString) stored at a certain iterator - position, and we then called QString::toLower() on it. Most C++ - compilers also allow us to write \c{i->toLower()}, but some - don't. + position, and we then called QString::toLower() on it. - For read-only access, you can use const_iterator, \l{QList::constBegin}{constBegin()}, - and \l{QList::constEnd()}{constEnd()}. For example: + For read-only access, you can use const_iterator, \l{QList::cbegin}{cbegin()}, + and \l{QList::cend()}{cend()}. For example: \snippet code/doc_src_containers.cpp 12 @@ -315,7 +337,7 @@ This problem doesn't occur with functions that return a const or non-const reference to a container. - \section3 Implicit sharing iterator problem + \section4 Implicit sharing iterator problem \l{Implicit sharing} has another consequence on STL-style iterators: you should avoid copying a container while @@ -328,32 +350,11 @@ The above example only shows a problem with QList, but the problem exists for all the implicitly shared Qt containers. - \section2 Java-Style Iterators - \l{java-style-iterators}{Java-Style iterators} were introduced in Qt 4. Their API is modelled + \section3 Java-Style Iterators + \l{java-style-iterators}{Java-Style iterators} + are modelled on Java's iterator classes. - New code should should prefer \l{STL-Style Iterators}. - - \section1 Container keywords - - \target foreach - \section2 The foreach Keyword - \l{foreach-keyword}{The foreach keyword} is discouraged, new code should - prefer C++11 range-based loops. - - \target forever - \section2 The forever keyword. - In addition to \c foreach, Qt also provides a \c forever - pseudo-keyword for infinite loops: - - \snippet code/doc_src_containers.cpp 21 - - If you're worried about namespace pollution, you can disable - these macros by adding the following line to your \c .pro file: - - \snippet code/doc_src_containers.cpp 22 - - \note The alternative macros Q_FOREACH and Q_FOREVER remain defined - regardless. + New code should prefer \l{STL-Style Iterators}. \section1 Qt containers compared with std containers @@ -383,26 +384,26 @@ \li Similar to std::queue<T>, inherits from \l{QList}. \row \li \l{QSet}<T> - \li Similar to std::set<T>. Internally, \l{QSet} is implemented with a + \li Similar to std::unordered_set<T>. Internally, \l{QSet} is implemented with a \l{QHash}. \row \li \l{QMap}<Key, T> - \li Similar to std::map<T>. + \li Similar to std::map<Key, T>. \row \li \l{QMultiMap}<Key, T> - \li Similar to std::multimap<T>. + \li Similar to std::multimap<Key, T>. \row \li \l{QHash}<Key, T> - \li Most similar to std::map<T>. + \li Most similar to std::unordered_map<Key, T>. \row \li \l{QMultiHash}<Key, T> - \li Most similar to std::multimap<T>. + \li Most similar to std::unordered_multimap<Key, T>. \endtable \section1 Qt containers and std algorithms - You can used Qt containers with functions from \c{#include <algorithm>}. + You can use Qt containers with functions from \c{#include <algorithm>}. \snippet code/doc_src_containers.cpp 26 @@ -410,7 +411,7 @@ Qt includes other template classes that resemble containers in some respects. These classes don't provide iterators and cannot - be used with the \c foreach keyword. + be used with the \l foreach keyword. \list \li QCache<Key, T> provides a cache to store objects of a certain diff --git a/src/corelib/doc/src/custom-types.qdoc b/src/corelib/doc/src/custom-types.qdoc index 352a43549d..7922fd9477 100644 --- a/src/corelib/doc/src/custom-types.qdoc +++ b/src/corelib/doc/src/custom-types.qdoc @@ -6,7 +6,7 @@ \title Creating Custom Qt Types \brief How to create and register new types with Qt. - \ingroup best-practices + \ingroup how-to \tableofcontents @@ -37,7 +37,7 @@ The following \c Message class definition includes these members: - \snippet tools/customtype/message.h custom type definition + \snippet customtype/customtypeexample.cpp custom type definition The class also provides a constructor for normal use and two public member functions that are used to obtain the private data. @@ -53,11 +53,14 @@ to this class, we invoke the Q_DECLARE_METATYPE() macro on the class in the header file where it is defined: - \snippet tools/customtype/message.h custom type meta-type declaration + \snippet customtype/customtypeexample.cpp custom type meta-type declaration This now makes it possible for \c Message values to be stored in QVariant objects - and retrieved later. See the \l{Custom Type Example} for code that demonstrates - this. + and retrieved later: + + \snippet customtype/customtypeexample.cpp storing a custom value + \dots + \snippet customtype/customtypeexample.cpp retrieving a custom value The Q_DECLARE_METATYPE() macro also makes it possible for these values to be used as arguments to signals, but \e{only in direct signal-slot connections}. @@ -77,7 +80,7 @@ available for queued signal-slot communication as long as you call it before you make the first connection that uses the type. - The \l{Queued Custom Type Example} declares a \c Block class which is registered + The \l{Queued Custom Type} example declares a \c Block class which is registered in the \c{main.cpp} file: \snippet threads/queuedcustomtype/main.cpp main start @@ -107,18 +110,17 @@ It is often quite useful to make a custom type printable for debugging purposes, as in the following code: - \snippet tools/customtype/main.cpp printing a custom type + \snippet customtype/customtypeexample.cpp printing a custom type This is achieved by creating a streaming operator for the type, which is often defined in the header file for that type: - \snippet tools/customtype/message.h custom type streaming operator + \snippet customtype/customtypeexample.cpp custom type streaming operator declaration - The implementation for the \c Message type in the \l{Custom Type Example} - goes to some effort to make the printable representation as readable as - possible: + The implementation for the \c Message type here goes to some effort to make the + printable representation as readable as possible: - \snippet tools/customtype/message.cpp custom type streaming operator + \snippet customtype/customtypeexample.cpp custom type streaming operator The output sent to the debug stream can, of course, be made as simple or as complicated as you like. Note that the value returned by this function is @@ -131,9 +133,8 @@ The Q_DECLARE_METATYPE() macro and qRegisterMetaType() function documentation contain more detailed information about their uses and limitations. - The \l{Custom Type Example}{Custom Type} and \l{Queued Custom Type Example} - {Queued Custom Type} examples show how to implement a custom type with the - features outlined in this document. + The \l{Queued Custom Type} example shows how to implement a custom type with + the features outlined in this document. The \l{Debugging Techniques} document provides an overview of the debugging mechanisms discussed above. diff --git a/src/corelib/doc/src/datastreamformat.qdoc b/src/corelib/doc/src/datastreamformat.qdoc index c3e57a9adf..65b7eb5a20 100644 --- a/src/corelib/doc/src/datastreamformat.qdoc +++ b/src/corelib/doc/src/datastreamformat.qdoc @@ -7,7 +7,7 @@ \brief List of data types that can be serialized by QDataStream. The \l QDataStream class allows you to serialize the Qt data types - listed in this section as of \l{QDataStream::setVersion()}{version 18}. + listed in this section. It is always best to cast integers to a Qt integer type, such as \l{qint16} or \l{quint32}, when reading and writing. This ensures that @@ -31,7 +31,11 @@ \li QBitArray \li QBrush \li QByteArray + \li QCborArray + \li QCborMap + \li QCborValue \li QColor + \li QColorSpace \li QCursor \li QDate \li QDateTime @@ -39,33 +43,73 @@ \li QFont \li QGenericMatrix \li QHash<Key, T> + \li QHostAddress \li QIcon \li QImage + \li QJsonArray + \li QJsonDocument + \li QJsonObject + \li QJsonValue \li QKeySequence + \li QLine + \li QLineF \li QList<T> + \li QListWidgetItem + \li QLocale \li QMap<Key, T> \li QMargins + \li QMarginsF \li QMatrix4x4 - \li QPair<T1, T2> + \li QModelIndex + \li QModelIndexList + \li QMultiHash<Key + \li QMultiMap<Key + \li QNetworkCacheMetaData + \li QNetworkCacheMetaData::AttributesMap + \li QPageRanges + \li QPainterPath + \li std::pair<T1, T2> \li QPalette \li QPen \li QPicture \li QPixmap \li QPoint + \li QPointF + \li QPolygon + \li QPolygonF \li QQuaternion \li QRect + \li QRectF \li QRegularExpression \li QRegion + \li QSet \li QSize + \li QSizeF + \li QSizePolicy + \li QStandardItem \li QString + \li QTableWidgetItem + \li QTextBlockFormat + \li QTextCharFormat + \li QTextFormat + \li QTextFrameFormat + \li QTextLength + \li QTextListFormat + \li QTextTableCellFormat + \li QTimeZone \li QTime \li QTransform + \li QTreeWidgetItem + \li QTypeRevision \li QUrl + \li QUuid \li QVariant \li QVector2D \li QVector3D \li QVector4D + \li QVersionNumber \endlist - \sa {JSON Support in Qt} + \sa {JSON Support in Qt}, {CBOR Support in Qt} + */ diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc index 7e8977dbd9..b787651aba 100644 --- a/src/corelib/doc/src/external-resources.qdoc +++ b/src/corelib/doc/src/external-resources.qdoc @@ -83,6 +83,36 @@ */ /*! + \externalpage https://developer.android.com/training/data-storage/shared/documents-files + \title Android: Access documents and other files from shared storage +*/ + +/*! + \externalpage https://developer.android.com/reference/androidx/documentfile/provider/DocumentFile#getParentFile() + \title Android: DocumentFile.getParentFile() +*/ + +/*! + \externalpage https://developer.android.com/guide/topics/providers/content-provider-basics#ContentURIs + \title Android: Content URIs +*/ + +/*! + \externalpage https://developer.android.com/training/data-storage#scoped-storage + \title Android: Scoped storage +*/ + +/*! + \externalpage https://developer.android.com/training/data-storage/use-cases + \title Android: storage best practices +*/ + +/*! + \externalpage https://developer.android.com/reference/android/provider/MediaStore + \title Android: MediaStore +*/ + +/*! \externalpage https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html \title GNUInstallDirs */ @@ -121,3 +151,23 @@ \externalpage https://cmake.org/cmake/help/latest/module/FetchContent.html#command:fetchcontent_makeavailable \title FetchContent_MakeAvailable() */ + +/*! + \externalpage https://cmake.org/cmake/help/latest/prop_gbl/USE_FOLDERS.html + \title USE_FOLDERS +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/prop_tgt/FOLDER.html + \title FOLDER +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/command/cmake_policy.html + \title cmake_policy +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/guide/importing-exporting/index.html#creating-packages + \title Creating CMake packages +*/ diff --git a/src/corelib/doc/src/foreach-keyword.qdoc b/src/corelib/doc/src/foreach-keyword.qdoc index 780be6e09c..b3a4482528 100644 --- a/src/corelib/doc/src/foreach-keyword.qdoc +++ b/src/corelib/doc/src/foreach-keyword.qdoc @@ -31,7 +31,7 @@ \snippet code/doc_src_containers.cpp 16 - Unless the data type contains a comma (e.g., \c{QPair<int, + Unless the data type contains a comma (e.g., \c{std::pair<int, int>}), the variable used for iteration can be defined within the \c foreach statement: @@ -73,4 +73,15 @@ \c foreach would not. But using \c foreach always copies the container, which is usually not cheap for STL containers. If in doubt, prefer \c foreach for Qt containers, and range based \c for for STL ones. + + You can remove the availability of the Qt's \c foreach loop by + defining the \c{QT_NO_FOREACH} macro. +*/ + +/*! + \macro QT_NO_FOREACH + \since 6.0 + + Defining this macro removes the availability of Qt's \c foreach + loop. */ diff --git a/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc b/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc new file mode 100644 index 0000000000..0521aff662 --- /dev/null +++ b/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc @@ -0,0 +1,13 @@ +On Android, some limitations apply when dealing with +\l {Android: Content URIs}{content URIs}: +\list + \li Access permissions might be needed by prompting the user through the + \l QFileDialog which implements + \l {Android: Access documents and other files from shared storage}{Android's native file picker}. + \li Aim to follow the \l {Android: Scoped storage}{Scoped storage} guidelines, + such as using app specific directories instead of other public external directories. + For more information, also see + \l {Android: storage best practices}{storage best practices}. + \li Due to the design of Qt APIs (e.g. QFile), it's not possible to fully + integrate the latter APIs with Android's \l {Android: MediaStore}{MediaStore} APIs. +\endlist diff --git a/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.cmake b/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.qdocinc index 12fc7a1e14..47133f6d10 100644 --- a/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.cmake +++ b/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.qdocinc @@ -1,3 +1,8 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [warning] \warning If your \e Android project is built using a CMake version lower than 3.19, make sure that you call \l{qt_finalize_project}{qt6_finalize_project()} at the end of a top-level CMakeLists.txt. +//! [warning] diff --git a/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc index 6c1f20adb2..632ddf756f 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc @@ -2,8 +2,11 @@ cmake_minimum_required(VERSION 3.16...3.22) project(MyThings) +# The following CMAKE_INSTALL_*DIR variables are used to initialize their +# QT_DEPLOY_*_DIR counterparts. set(CMAKE_INSTALL_BINDIR "mybindir") set(CMAKE_INSTALL_LIBDIR "mylibdir") +set(CMAKE_INSTALL_LIBEXECDIR "mylibexecdir") find_package(Qt6 REQUIRED COMPONENTS Core) qt_standard_project_setup() @@ -15,10 +18,13 @@ file(GENERATE OUTPUT ${deploy_script} CONTENT " set(QT_DEPLOY_PLUGINS_DIR \"mypluginsdir\") set(QT_DEPLOY_QML_DIR \"myqmldir\") +set(QT_DEPLOY_TRANSLATIONS_DIR \"i18n\") include(\"${QT_DEPLOY_SUPPORT}\") qt_deploy_runtime_dependencies( EXECUTABLE \"\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>\" )") + +install(SCRIPT ${deploy_script}) \endcode diff --git a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc new file mode 100644 index 0000000000..0f46379c45 --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc @@ -0,0 +1,20 @@ +\badcode +set(deploy_tool_options_arg "") +if(APPLE) + set(deploy_tool_options_arg --hardened-runtime) +elseif(WIN32) + set(deploy_tool_options_arg --no-compiler-runtime) +endif() + +# Generate a deployment script to be executed at install time +qt_generate_deploy_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + CONTENT " +qt_deploy_runtime_dependencies( + EXECUTABLE \"${executable_path}\" + DEPLOY_TOOL_OPTIONS "${deploy_tool_options_arg}" + GENERATE_QT_CONF + VERBOSE +)") +\endcode diff --git a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc index 3c7fb8d5ee..6d026d6301 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc @@ -23,13 +23,11 @@ endif() qt_add_executable(HelperApp helper.cpp) set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:HelperApp>") -# The following script must only be executed at install time -set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake") - -file(GENERATE OUTPUT ${deploy_script} CONTENT " -# Including the file pointed to by QT_DEPLOY_SUPPORT ensures the generated -# deployment script has access to qt_deploy_runtime_dependencies() -include(\"${QT_DEPLOY_SUPPORT}\") +# Generate a deployment script to be executed at install time +qt_generate_deploy_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + CONTENT " qt_deploy_runtime_dependencies( EXECUTABLE \"${executable_path}\" ADDITIONAL_EXECUTABLES \"${helper_app_path}\" diff --git a/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc index c5a1a40356..27e04b5b08 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc @@ -1,2 +1,6 @@ This variable is defined by the script named by \l QT_DEPLOY_SUPPORT. It should only be used as part of deployment during installation or a post-build rule. + +\note This is a low-level deployment API variable, and should only be used in +advanced use-cases that are not covered by the higher-level API commands, like +\l{qt_generate_deploy_app_script}. diff --git a/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc new file mode 100644 index 0000000000..64c6b3e49f --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc @@ -0,0 +1,16 @@ +\badcode +set(deploy_tool_options_arg "") +if(APPLE) + set(deploy_tool_options_arg --hardened-runtime) +elseif(WIN32) + set(deploy_tool_options_arg --no-compiler-runtime) +endif() + +qt_generate_deploy_app_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + NO_UNSUPPORTED_PLATFORM_ERROR + DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg} +) +install(SCRIPT ${deploy_script}) +\endcode diff --git a/src/corelib/doc/src/includes/cmake-generate-deploy-app-script.qdocinc b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script.qdocinc new file mode 100644 index 0000000000..d5c1d2cf4a --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script.qdocinc @@ -0,0 +1,21 @@ +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 REQUIRED COMPONENTS Core) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) + +install(TARGETS MyApp + BUNDLE DESTINATION . + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} +) + +qt_generate_deploy_app_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + NO_UNSUPPORTED_PLATFORM_ERROR +) +install(SCRIPT ${deploy_script}) +\endcode diff --git a/src/corelib/doc/src/includes/models.qdocinc b/src/corelib/doc/src/includes/models.qdocinc new file mode 100644 index 0000000000..cf840b1cae --- /dev/null +++ b/src/corelib/doc/src/includes/models.qdocinc @@ -0,0 +1,14 @@ +//! [thread-safety-section1] +\section1 Thread safety + +Being a \l {Accessing QObject Subclasses from Other Threads}{subclass of +QObject}, \1 is not \l {Reentrancy and Thread-Safety}{thread-safe}. Any \1 +model-related API should only be called from the thread the model object lives +in. If the \1 is connected with a view, that means the GUI thread, as that is +where the view lives, and it will call into the model from the GUI thread. +Using a background thread to populate or modify the contents of a model is +possible, but requires care, as the background thread cannot call any +model-related API directly. Instead, you should queue the updates and apply +them in the main thread. This can be done with \l {Signals and Slots Across +Threads}{queued connections}. +//! [thread-safety-section1] diff --git a/src/corelib/doc/src/includes/permissions.qdocinc b/src/corelib/doc/src/includes/permissions.qdocinc new file mode 100644 index 0000000000..00bf848d37 --- /dev/null +++ b/src/corelib/doc/src/includes/permissions.qdocinc @@ -0,0 +1,51 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [requestPermission-functor] + When the request is ready, \a functor will be called as + \c {functor(const QPermission &permission)}, with + \c permission describing the result of the request. +//! [requestPermission-functor] + +//! [requestPermission-postamble] + If the user explicitly grants the application the requested \a permission, + or the \a permission is known to not require user authorization on the given + platform, the status will be Qt::PermissionStatus::Granted. + + If the user explicitly denies the application the requested \a permission, + or the \a permission is known to not be accessible or applicable to applications + on the given platform, the status will be Qt::PermissionStatus::Denied. + + The result of a request will never be Qt::PermissionStatus::Undetermined. + + \note Permissions can only be requested from the main thread. +//! [requestPermission-postamble] + +//! [permission-metadata] + \inmodule QtCore + \inheaderfile QPermissions + \ingroup permissions + \since 6.5 + \sa QPermission, + QCoreApplication::requestPermission(), + QCoreApplication::checkPermission(), + {Application Permissions} +//! [permission-metadata] + +//! [begin-usage-declarations] + To request this permission at runtime, the following platform + specific usage declarations have to be made at build time: + + \table + \header + \li Platform + \li Type + \li +//! [begin-usage-declarations] + +//! [end-usage-declarations] + \endtable + + Please see the individual usage declaration types for how + to add them to your project. +//! [end-usage-declarations] diff --git a/src/corelib/doc/src/includes/qstring.qdocinc b/src/corelib/doc/src/includes/qstring.qdocinc new file mode 100644 index 0000000000..66ed12dff3 --- /dev/null +++ b/src/corelib/doc/src/includes/qstring.qdocinc @@ -0,0 +1,36 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +// \1 is either "search" or "comparison" +//! [search-comparison-case-sensitivity] +If \a cs is Qt::CaseSensitive (the default), the \1 is case-sensitive; +otherwise the \1 is case-insensitive. +//! [search-comparison-case-sensitivity] + +//! [negative-index-start-search-from-end] +If \a from is -1, the search starts at the last character; if it is +-2, at the next to last character and so on. +//! [negative-index-start-search-from-end] + +//! [qstring-first-index-of] +Returns the index position of the first occurrence of the \1 \a \2 +in this string, searching forward from index position \a from. +Returns -1 if \a \2 is not found. +//! [qstring-first-index-of] + +//! [qstring-last-index-of] +Returns the index position of the last occurrence of the \1 \a \2 +in this string, searching backward from index position \a from. +//! [qstring-last-index-of] + +//! [qstring-local-8-bit-equivalent] +On Unix systems this is equivalent to \1(). +Note that on Apple systems this function does not take +\l{https://developer.apple.com/documentation/foundation/nsstring/1410091-defaultcstringencoding?language=objc} +{NSString.defaultCStringEncoding} or +\l{https://developer.apple.com/documentation/corefoundation/1541720-cfstringgetsystemencoding?language=objc} +{CFStringGetSystemEncoding()} into account, as these functions +typically return the legacy "Western (Mac OS Roman)" encoding, +which should not be used on modern Apple operating systems. +On Windows the system's current code page is used. +//! [qstring-local-8-bit-equivalent] diff --git a/src/corelib/doc/src/io.qdoc b/src/corelib/doc/src/io.qdoc index 80caf9a769..443d324f75 100644 --- a/src/corelib/doc/src/io.qdoc +++ b/src/corelib/doc/src/io.qdoc @@ -10,7 +10,7 @@ network handling. These \l{Qt Core} classes are used to handle input and output to and from - external devices, processes, files etc. as well as manipulating files and + external devices, processes, files etc., as well as manipulating files and directories. */ diff --git a/src/corelib/doc/src/ipc.qdoc b/src/corelib/doc/src/ipc.qdoc new file mode 100644 index 0000000000..7ec6f5fa3b --- /dev/null +++ b/src/corelib/doc/src/ipc.qdoc @@ -0,0 +1,492 @@ +// Copyright (C) 2022 Intel Corporation. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page ipc.html + \title Inter-Process Communication + \ingroup groups + \ingroup frameworks-technologies + \keyword ipc + \ingroup explanations-networkingandconnectivity + + \brief An overview of Qt's inter-process communication functionality + + Qt supports many ways of communicating with other processes running in the + same system or in different systems. There are basically three types of + inter-process communication mechanisms: + + \list 1 + \li Synchronization primitives + \li Exchanging of arbitrary byte-level data + \li Passing structured messages + \endlist + + \section1 Synchronization primitives + + Qt only provides one class for explicit inter-process synchronization: + \l{QSystemSemaphore}. A QSystemSemaphore is like a \l{QSemaphore} that is + accessible by multiple processes in the same system. It is globally + identified by a "key", which in Qt is represented by the \l{QNativeIpcKey} + class. Additionally, depending on the OS, Qt may support multiple different + backends for sharing memory; see the \l{Native IPC Keys} documentation for + more information and limitations. + + It is possible to use regular thread-synchronization primitives such as + mutexes, wait conditions, and read-write locks, located in memory that is + shared between processes. Qt does not provide any class to support this, + but applications can use low-level operations on certain operating systems. + + Other Qt classes may be used to provide higher-level locking, like + \l{QLockFile}, or by acquiring a unique, system-wide resource. Such + techniques include \l{QTcpServer}{TCP} or \l{QUdpSocket}{UDP} ports or + well-known names in \l{QDBusConnection::registerService}{D-Bus}. + + \section1 Byte-level data sharing + + Using byte-level data, applications can implement any communication + protocol they may choose. Sharing of byte data can be stream-oriented + (serialized) or can allow random access (a similar condition to + QFileDevice::isSequential()). + + For serial communication, Qt provides a number of different classes and + even full modules: + \list + \li Pipes and FIFOs: \l QFile + \li Child processes: \l QProcess + \li Sockets: \l QTcpSocket, \l QUdpSocket (in \l{Qt Network}) + \li HTTP(S): \l QNetworkAccessManager (in \l{Qt Network}) and + \l QHttpServer (in \l{Qt HTTP Server}) + \li CoAP(S): \l QCoapClient (in \l{Qt CoAP}) + \endlist + + For random-access data sharing within the same system, Qt provides + \l{QSharedMemory}. See the \l{Shared Memory} documentation for detailed + information. + + \section1 Structured message passing + + Qt also provides a number of techniques to exchange structured messages + with other processes. Applications can build on top of the byte-level + solutions above, such as by using \l QJsonDocument or \l QXmlStreamReader / + \l QXmlStreamWriter over HTTP to perform JSONRPC or XMLRPC, respectively, + or \l QCborValue with QtCoAP. + + Dedicated Qt modules for structured messages and remote procedure-calling + include: + \list + \li \l{Qt D-Bus} + \li \l{Qt Remote Objects} + \li \l{Qt WebSockets} + \endlist +*/ + +/*! + \page shared-memory.html + \title Shared Memory + \keyword ipc + \keyword shared memory + + \brief Overview of the techniques for sharing memory between processes. + + Qt provides two techniques to share memory with other processes in the same + system: \l{QSharedMemory} and memory-mapped files using \l{QFile}. Memory + that is shared with other processes is often referred to as a "segment", + and although it may have been implemented as specific segments on + processors with segmented memory models in the past, this is not the case + in any modern operating system. Shared memory segments are simply regions + of memory that the operating system will ensure are available to all + processes participating. + + \note The address at which the segment is located in memory will almost + always be different for each process that is participating in the sharing. + Therefore, applications must take care to share only position-independent + data, such as primitive C++ types or arrays of such types. + + \section1 Sharing memory using QSharedMemory + + QSharedMemory provides a simple API to create a shared memory segment of a + given size or attach to one that was created by another process. + Additionally, it provides a pair of methods to \l{QSharedMemory::}{lock} + and \l{QSharedMemory::}{unlock} the whole segment, using an internal + \l{QSystemSemaphore}. + + Shared memory segments and system semaphores are globally identified in the + system through a "key", which in Qt is represented by the \l{QNativeIpcKey} + class. Additionally, depending on the OS, Qt may support multiple different + backends for sharing memory; see the \l{Native IPC Keys} documentation for + more information and limitations. + + QSharedMemory is designed to share memory only within the same privilege + level (that is, not with untrusted other processes, such as those started + by other users). For backends that support it, QSharedMemory will create + segments such that only processes with the same privilege level can attach. + + \section1 Sharing memory via memory-mapped files + + Most files can be mapped to memory using QFile::map() and, if the + \l{QFileDevice::MapPrivateOption}{MapPrivateOption} option is not specified, + any writes to the mapped segment will be observed by all other processes + that have mapped the same file. Exceptions to files that can be mapped to + memory include remote files found in network shares or those located in + certain filesystems. Even if the operating system does allow mapping remote + files to memory, I/O operations on the file will likely be cached and + delayed, thus making true memory sharing impossible. + + This solution has the major advantages of being independent of any backend + API and of being simpler to interoperate with from non-Qt applications. + Since \l{QTemporaryFile} is a \l{QFile}, applications can use that class to + achieve clean-up semantics and to create unique shared memory segments too. + + To achieve locking of the shared memory segment, applications will need to + deploy their own mechanisms. One way may be to use \l QLockFile. Another + and less costly solution is to use QBasicAtomicInteger or \c{std::atomic} in + a pre-determined offset in the segment itself. Higher-level locking + primitives may be available on some operating systems; for example, on + Linux, applications can set the "pshared" flag in the mutex attribute + passed to \c{pthread_mutex_create()} to indicate that the mutex resides in + a shared memory segment. + + Be aware that the operating system will likely attempt to commit to + permanent storage any writes made to the shared memory. This may be desired + or it may be a performance penalty if the file itself was meant to be + temporary. In that case, applications should locate a RAM-backed + filesystem, such as \c{tmpfs} on Linux (see + QStorageInfo::fileSystemType()), or pass a flag to the native file-opening + function to inform the OS to avoid committing the contents to storage. + + It is possible to use file-backed shared memory to communicate with + untrusted processes, in which case the application should exercise great + care. The files may be truncated/shrunk and cause applications accessing + memory beyond the file's size to crash. + + \section2 Linux hints on memory-mapped files + + On modern Linux systems, while the \c{/tmp} directory is often a \c{tmpfs} + mount point, that is not a requirement. However, the \c{/dev/shm} directory + is required to be a \c{tmpfs} and exists for the very purpose of sharing + memory. Do note that it is world-readable and writable (like \c{/tmp} and + \c{/var/tmp}), so applications must be careful of the contents revealed + there. Another alternative is to use the XDG Runtime Directory (see + QStandardPaths::writableLocation() and \l{QStandardPaths::RuntimeLocation}), + which on Linux systems using systemd is a user-specific \c{tmpfs}. + + An even more secure solution is to create a "memfd" using \c{memfd_create(2)} + and use interprocess communication to pass the file descriptor, like + \l{QDBusUnixFileDescriptor} or by letting the child process of a \l{QProcess} + inherit it. "memfds" can also be sealed against being shrunk, so they are + safe to be used when communicating with processes with a different privilege + level. + + \section2 FreeBSD hints on memory-mapped files + + FreeBSD also has \c{memfd_create(2)} and can pass file descriptors to other + processes using the same techniques as Linux. It does not have temporary + filesystems mounted by default. + + \section2 Windows hints on memory-mapped files + + On Windows, the application can request the operating system avoid saving + the file's contents on permanent storage. This request is performed by + passing the \c{FILE_ATTRIBUTE_TEMPORARY} flag in the + \c{dwFlagsAndAttributes} parameter to the \c{CreateFile} Win32 function, + the \c{_O_SHORT_LIVED} flag to \c{_open()} low-level function, or by + including the modifier "T" to the + \c{fopen()} C runtime function. + + There's also a flag to inform the operating system to delete the file when + the last handle to it is closed (\c{FILE_FLAG_DELETE_ON_CLOSE}, + \c{_O_TEMPORARY}, and the "D" modifier), but do note that all processes + attempting to open the file must agree on using this flag or not using it. A + mismatch will likely cause a sharing violation and failure to open the file. +*/ + +/*! + \page native-ipc-keys.html + \title Native IPC Keys + \keyword ipc + \keyword shared memory + \keyword system semaphore + + \brief An overview of keys for QSharedMemory and QSystemSemaphore + + The \l QSharedMemory and \l QSystemSemaphore classes identify their + resource using a system-wide identifier known as a "key". The low-level key + value as well as the key type are encapsulated in Qt using the \l + QNativeIpcKey class. That class also provides the proper means of + exchanging the key with other processes, by way of + QNativeIpcKey::toString() and QNativeIpcKey::fromString(). + + Qt currently supports three distinct backends for those two classes, which + match the values available in the \l{QNativeIpcKey::Type} enumeration. + \list + \li POSIX Realtime extensions (IEEE 1003.1b, POSIX.1b) + \li X/Open System Interfaces (XSI) or System V (SVr4), though also now part of POSIX + \li Windows primitives + \endlist + + As the name indicates, the Windows primitives are only available on the + Windows operating system, where they are the default backend. The other two + are usually both available on Unix operating systems. The following table + provides an overview of typical availability since Qt 6.6: + + \table + \header \li Operating system \li POSIX \li System V \li Windows + \row \li Android \li \li \li + \row \li INTEGRITY \li \li \li + \row \li QNX \li Yes \li \li + \row \li \macos \li Yes \li Usually (1) \li + \row \li Other Apple OSes \li Yes \li \li + \row \li Other Unix systems \li Yes \li Yes \li + \row \li Windows \li Rarely (2) \li \li Yes + \endtable + + \note 1 Sandboxed \macos applications, which include all applications + distributed via the Apple App Store, may not use System V objects. + + \note 2 Some GCC-compatible C runtimes on Windows provide POSIX-compatible + shared memory support, but this is rare. It is always absent with the + Microsoft compiler. + + To determine whether a given key type is supported, applications should + call QSharedMemory::isKeyTypeSupported() and + QSystemSemaphore::isKeyTypeSupported(). + + QNativeIpcKey also provides support for compatibility with Qt applications + prior to its introduction. The following sections detail the limitations of + the backends, the contents of the string keys themselves, and + compatibility. + + \section1 Cross-platform safe key format + + QNativeIpcKey::setNativeKey() and QNativeIpcKey::nativeKey() handle the + low-level native key, which may be used with the native APIs and shared + with other, non-Qt processes (see below for the API). This format is not + usually cross-platform, so both QSharedMemory and QSystemSemaphore provide + a function to translate a cross-platform identifier string to the native + key: QSharedMemory::platformSafeKey() and + QSystemSemaphore::platformSafeKey(). + + The length of the cross-platform key on most platforms is the same as that + of a file name, but is severely limited on Apple platforms to only 30 + usable bytes (be mindful of UTF-8 encoding if using characters outside the + US-ASCII range). The format of the key is also similar to that of a file + path component, meaning it should not contain any characters not allowed in + file names, in particular those that separate path components (slash and + backslash), with the exception of sandboxed applications on Apple operating + systems. The following are good examples of cross-platform keys: "myapp", + "org.example.myapp", "org.example.myapp-12345". Note that it is up to the + caller to prevent oversized keys, and to ensure that the key contains legal + characters on the respective platform. Qt will silently truncate keys that + are too long. + + \b{Apple sandbox limitations:} if the application is running inside of a + sandbox in an Apple operating system, the key must be in a very specific + format: \c {<application group identifier>/<custom identifier>}. Sandboxing + is implied for all applications distributed through the Apple App Store. + See Apple's documentation + \l{https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW24} + {here} and \l{https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_application-groups} + {here} for more information, including how to obtain the application's group identifier. + + \section1 Native key format + + This section details the format of the native keys of the supported + backends. + + \section3 POSIX Realtime + Native keys resemble file names and may contain any character that file + names do, except for a slash. POSIX requires the first character in the key + name to be a slash and leaves undetermined whether any additional slashes + are permitted. On most operating systems, the key length is the same as a + file name, but it is limited to 32 characters on Apple operating systems + (this includes the first slash and the terminating null, so only 30 usable + characters are possible). + + The following are good examples of native POSIX keys: "/myapp", + "/org.example.myapp", "/org.example.myapp-12345". + + QSharedMemory::platformSafeKey() and QSystemSemaphore::platformSafeKey() + simply prepend the slash. On Apple operating systems, they also truncate + the result to the available size. + + \section3 Windows + Windows key types are NT + \l{https://learn.microsoft.com/en-us/windows/win32/sync/object-namespaces}{kernel + object names} and may be up to \c{MAX_PATH} (260) characters in length. + They look like relative paths (that is, they don't start with a backslash + or a drive letter), but unlike file names on Windows, they are + case-sensitive. + + The following are good examples of native Windows keys: "myapp", + "org.example.myapp", "org.example.myapp-12345". + + QSharedMemory::platformSafeKey() and QSystemSemaphore::platformSafeKey() + insert a prefix to disambiguate shared memory and system semaphores, + respectively. + + \section3 X/Open System Interfaces (XSI) / System V + System V keys take the form of the name of a file in the system, and thus + have the exact same limitations as file paths do. Both QSharedMemory and + QSystemSemaphore will create this file if it does not exist when creating + the object. If auto-removal is disabled, it may also be shared between + QSharedMemory and QSystemSemaphore without conflict and can be any extant + file (for example, it can be the process executable itself, see + QCoreApplication::applicationFilePath()). The path should be an absolute + one to avoid mistakes due to different current directories. + + QSharedMemory::platformSafeKey() and QSystemSemaphore::platformSafeKey() + always return an absolute path. If the input was already absolute, they + will return their input unchanged. Otherwise, they will prepend a suitable + path where the application usually has permission to create files in. + + \section1 Ownership + + Shared memory and system semaphore objects need to be created before use, + which is accomplished with QSharedMemory::create() or by passing + QSystemSemaphore::Create to the constructor, respectively. + + On Unix systems, the Qt classes that created the object will be responsible + for cleaning up the object in question. Therefore, if the application with + that C++ object exits uncleanly (a crash, qFatal(), etc.), the object may + be left behind. If that happens, applications may fail to create the + object again and should instead attach to an existing one. For example, for + QSharedMemory: + + \code + if (!shm.create(4096) && shm.error() == QSharedMemory::AlreadyExists) + shm.attach(); + \endcode + + Re-attaching to a QSystemSemaphore is probably unwise, as the token counter + in it is probably in an unknown state and therefore may lead to deadlocks. + + \section3 POSIX Realtime + POSIX Realtime object ownership is patterned after files, in the sense that + they exist independent of any process using them or not. Qt is unable to + determine if the object is still in use, so auto-removal will remove it + even then, which will make attaching to the same object impossible but + otherwise not affecting existing attachments. + + Prior to Qt 6.6, Qt never cleaned up POSIX Realtime objects, except on QNX. + + \section3 X/Open System Interfaces (XSI) / System V + There are two resources managed by the Qt classes: the file the key refers + to and the object itself. QSharedMemory manages the object cooperatively: + the last attachment is responsible for removing the object itself and then + removing the key file. QSystemSemaphore will remove the object if and only + if it was passed QSystemSemaphore::Create; additionally, if it created the + key file, it will remove that too. + + Since Qt 6.6, it is possible to ask either class not to clean up. + + \section3 Windows + The operating system owns the object and will clean up after the last + handle to the object is closed. + + \section1 Interoperability with old Qt applications + + The QNativeIpcKey class was introduced in Qt 6.6. Prior to this version, + QSharedMemory and QSystemSemaphore backends were determined at the time of + Qt's own build. For Windows systems, it was always the Windows backend. For + Unix systems, it defaulted to the System V backend if the configuration + script determined it was available. If it was not available, it fell back + to the POSIX one. The POSIX backend could be explicitly + selected using the \c{-feature-ipc_posix} option to the Qt configure + script; if it was enabled, the \c{QT_POSIX_IPC} macro would be defined. + + Qt 6.6 retains the configure script option but it no longer controls the + availability of the backends. Instead, it changes what + QNativeIpcKey::legacyDefaultTypeForOs() will return. Applications that need + to retain compatibility must use this key type exclusively to guarantee + interoperability. + + The API in both QSharedMemory and QSystemSemaphore had the concept of a + cross-platform key, which is now deprecated in favor of using + QSharedMemory::legacyNativeKey() and QSystemSemaphore::legacyNativeKey(). + Those two functions produce the same native key as the deprecated functions + did in prior versions. If the old code was for example: + + \code + QSharedMemory shm("org.example.myapplication"); + QSystemSemaphore sem("org.example.myapplication"); + \endcode + + It can be updated to be: + \code + QSharedMemory shm(QSharedMemory::legacyNativeKey("org.example.myapplication")); + QSystemSemaphore sem(QSystemSemaphore::legacyNativeKey("org.example.myapplication")); + \endcode + + If the two applications exchanged native keys, there is no need to update + code such as: + + \code + QSharedMemory shm; + shm.setNativeKey(key); + \endcode + + Though if the older application did accept a native key, the new one may + opt to use \c{platformSafeKey()} with a second argument of + QNativeIpcKey::legacyDefaultTypeForOs(). + + \section3 X/Open System Interfaces (XSI) / System V + Never use existing files for QSharedMemory keys, as the old Qt application + may attempt to remove it. Instead, let QSharedMemory create it. + + \section1 Interoperability with non-Qt applications + + Interoperability with non-Qt applications is possible, with some limitations: + \list + \li Creation of shared memory segments must not race + \li QSharedMemory support for locking the segment is unavailable + \endlist + + Communication with non-Qt applications must always be through the native + key. + + QSharedMemory always maps the entire segment to memory. The non-Qt + application may choose to only map a subset of it to memory, with no ill + effects. + + \section3 POSIX Realtime + POSIX shared memory can be opened using + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/shm_open.html}{shm_open()} + and POSIX system semaphores can be opened using + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_open.html}{sem_open()}. + + Both of those functions take a \c name parameter that is the result of + QNativeIpcKey::nativeKey(), encoded for file names using + QFile::encodeName() / QFile::decodeName(). + + \section3 Windows + Windows shared memory objects can be opened using + \l{https://learn.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-createfilemappingw}{CreateFileMappingW} + and Windows system semaphore objects can be opened using + \l{https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-createsemaphorew}{CreateSemaphoreW}. + Despite the name of both functions starting with "Create", they are able + to attach to existing objects. + + The \c lpName parameter to those functions is the result of + QNativeIpcKey::nativeKey(), without transformation. + + If the foreign application uses the non-Unicode version of those functions + (ending in "A"), the name can be converted to and from 8-bit using QString. + + \section3 X/Open System Interfaces (XSI) / System V + System V shared memory can be obtained using + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/shmget.html}{shmget()} + and System V system semaphores can be obtained using + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/semget.html}{semget()}. + + The \c{key} parameter to either of those functions is the result of the + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/ftok.html}{ftok()} + function when passed the file name obtained from QNativeIpcKey::nativeKey() + with an \c id of 81 or 0x51 (the ASCII capital letter 'Q'). + + System V semaphore objects may contain multiple semaphores, but + QSystemSemaphore only uses the first one (number 0 for \c{sem_num}). + + Both QSharedMemory and QSystemSemaphore default to removing the object + using the \c{IPC_RMID} operation to \c{shmctl()} and \c{semctl()} + respectively if they are the last attachment. +*/ diff --git a/src/corelib/doc/src/json.qdoc b/src/corelib/doc/src/json.qdoc index 3097075eb9..98ae202cfa 100644 --- a/src/corelib/doc/src/json.qdoc +++ b/src/corelib/doc/src/json.qdoc @@ -6,7 +6,7 @@ \title JSON Support in Qt \ingroup qt-basic-concepts \brief An overview of JSON support in Qt. - + \ingroup explanations-dataprocessingandio \ingroup frameworks-technologies \keyword JSON @@ -73,8 +73,7 @@ A valid JSON document is either an array or an object, so a document always starts with a square or curly bracket. - \sa {JSON Save Game Example} - + \sa {Saving and Loading a Game} \section1 The JSON Classes @@ -82,5 +81,4 @@ \l{Implicit Sharing}{implicitly shared classes}. JSON support in Qt consists of these classes: - */ diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc index f9f129df97..9b3ea6ae66 100644 --- a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc +++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc @@ -32,7 +32,7 @@ different objects. The \l {Introductory Example} below demonstrates the usage of bindable - properties in C++ code. You can also check \l {Bindable Properties Example} + properties in C++ code. You can also check \l {Bindable Properties} example to see how the bindable properties can help to improve your code. \section1 Introductory Example @@ -247,4 +247,18 @@ be called for the current value of the property, register your callback using subscribe() instead. + \section1 Interaction with Q_PROPERTYs + + A \l {The Property System}{Q_PROPERTY} that defines \c BINDABLE can be bound and + used in binding expressions. You can implement such properties using \l {QProperty}, + \l {QObjectBindableProperty}, or \l {QObjectComputedProperty}. + + Q_PROPERTYs without \c BINDABLE can also be bound and be used in binding expressions, + as long as they define a \c NOTIFY signal. You must wrap the property in a \l QBindable + using the \c {QBindable(QObject* obj, const char* property)} constructor. Then, the + property can be bound using \l QBindable::setBinding() or used in a binding + expression via \l QBindable::value(). You must use \c QBindable::value() in binding + expressions instead of the normal property \c READ function (or \c MEMBER) to enable + dependency tracking if the property is not \c BINDABLE. + */ diff --git a/src/corelib/doc/src/objectmodel/metaobjects.qdoc b/src/corelib/doc/src/objectmodel/metaobjects.qdoc index 62226ca466..3d7685447f 100644 --- a/src/corelib/doc/src/objectmodel/metaobjects.qdoc +++ b/src/corelib/doc/src/objectmodel/metaobjects.qdoc @@ -5,7 +5,7 @@ \page metaobjects.html \title The Meta-Object System \brief An overview of Qt's meta-object system and introspection capabilities. - + \ingroup explanations-basics \ingroup qt-basic-concepts \keyword meta-object \keyword Meta-Object System diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index 94078b5b6c..99a3e60d88 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -5,7 +5,7 @@ \page properties.html \title The Property System \brief An overview of Qt's property system. - + \ingroup explanations-basics \ingroup qt-basic-concepts \keyword Qt's Property System @@ -44,14 +44,21 @@ specified. It is for reading the property value. Ideally, a const function is used for this purpose, and it must return either the property's type or a const reference to that type. e.g., QWidget::focus is a read-only - property with \c READ function, QWidget::hasFocus(). + property with \c READ function, QWidget::hasFocus(). If a \c BINDABLE is + specified, you can write \c{READ default} to have the \c READ accessor + generated from the \c BINDABLE. \li A \c WRITE accessor function is optional. It is for setting the property value. It must return void and must take exactly one argument, either of the property's type or a pointer or reference to that type. e.g., QWidget::enabled has the \c WRITE function QWidget::setEnabled(). Read-only properties do not need \c WRITE - functions. e.g., QWidget::focus has no \c WRITE function. + functions. e.g., QWidget::focus has no \c WRITE function. If you specify + both a \c BINDABLE and \c{WRITE default}, a \c WRITE accessor will be + generated from the \c BINDABLE. The generated \c WRITE accessor will \e not + explicitly emit any signal declared with \c NOTIFY. You should register + the signal as change handler to the \c BINDABLE, for example using + \l{Q_OBJECT_BINDABLE_PROPERTY}. \li A \c MEMBER variable association is required if no \c READ accessor function is specified. This makes the given member variable @@ -75,8 +82,9 @@ which must be of the same type as the property. The parameter will take the new value of the property. The \c NOTIFY signal should only be emitted when the property has really been changed, to avoid bindings being unnecessarily - re-evaluated in QML, for example. Qt emits automatically that signal when - needed for MEMBER properties that do not have an explicit setter. + re-evaluated in QML, for example. The signal is emitted automatically when + the property is changed via the Qt API (QObject::setProperty, + QMetaProperty, etc.), but not when the MEMBER is changed directly. \li A \c REVISION number or \c REVISION() macro is optional. If included, it defines the property and its notifier signal to be used in a particular @@ -85,7 +93,7 @@ \li The \c DESIGNABLE attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., - \l {Qt Designer Manual}{Qt Designer}). Most properties are \c DESIGNABLE + \l {Qt Widgets Designer Manual}{\QD}). Most properties are \c DESIGNABLE (default true). Valid values are true and false. \li The \c SCRIPTABLE attribute indicates whether this property @@ -200,7 +208,10 @@ The \c READ function is const and returns the property type. The \c WRITE function returns void and has exactly one parameter of the property type. The meta-object compiler enforces these - requirements. + requirements. The equality check in the \c WRITE function, while not + mandatory, is good practice as there is no point in notifying and + potentially forcing re-evaluation in other places if nothing has + changed. Given a pointer to an instance of MyClass or a pointer to a QObject that is an instance of MyClass, we have two ways to set @@ -266,7 +277,9 @@ Connected to the property system is an additional macro, Q_CLASSINFO(), that can be used to attach additional - \e{name}--\e{value} pairs to a class's meta-object, for example: + \e{name}--\e{value} pairs to a class's meta-object. This is + used for instance to mark a property as the \e default one + in the context of \l{QML Object Types}: \snippet code/doc_src_properties.cpp 7 @@ -288,5 +301,5 @@ and the general tips on implementing and using \l {Qt Bindable Properties}{bindable properties}. - \sa {Qt Bindable Properties} + \sa {Qt Bindable Properties}, {Defining QML Types from C++} */ diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc index 1b427f5775..f0eeb20048 100644 --- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc +++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc @@ -8,7 +8,7 @@ \ingroup qt-basic-concepts \brief An overview of Qt's signals and slots inter-object communication mechanism. - + \ingroup explanations-basics Signals and slots are used for communication between objects. The signals and slots mechanism is a central feature of Qt and probably the part that differs most from the features provided by @@ -109,8 +109,7 @@ when the signal is emitted. Signals are automatically generated by the \l moc and must not be - implemented in the \c .cpp file. They can never have return types - (i.e. use \c void). + implemented in the \c .cpp file. A note about arguments: Our experience shows that signals and slots are more reusable if they do not use special types. If @@ -297,8 +296,7 @@ callbacks, you'd have to find five different names and keep track of the types yourself. - \sa QLCDNumber, QObject::connect(), {Digital Clock Example}, - {Tetrix Example} + \sa QLCDNumber, QObject::connect() \section1 Signals And Slots With Default Arguments diff --git a/src/corelib/doc/src/qt6-changes.qdoc b/src/corelib/doc/src/qt6-changes.qdoc index 8bf8066964..011568ef75 100644 --- a/src/corelib/doc/src/qt6-changes.qdoc +++ b/src/corelib/doc/src/qt6-changes.qdoc @@ -5,7 +5,7 @@ \page qtcore-changes-qt6.html \title Changes to Qt Core \ingroup changes-qt-5-to-6 - \brief Migrate Qt Core to Qt 6. + \brief Changes to containers, strings, serialization and I/O classes. Qt 6 is a result of the conscious effort to make the framework more efficient and easy to use. @@ -528,252 +528,13 @@ \section2 The QRegularExpression class - In Qt6, all methods taking the \c QRegExp got removed from our code-base. - Therefore it is very likely that you will have to port your application or - library to \l QRegularExpression. + In Qt 6, the \c QRegExp type has been retired to the Qt5Compat module + and all Qt APIs using it have been removed from other modules. + Client code which used it can be ported to use \l QRegularExpression + in its place. As \l QRegularExpression is present already in Qt 5, + this can be done and tested before migration to Qt 6. - \l QRegularExpression implements Perl-compatible regular expressions. It - fully supports Unicode. For an overview of the regular expression syntax - supported by \l QRegularExpression, please refer to the aforementioned - pcrepattern(3) man page. A regular expression is made up of two things: a - pattern string and a set of pattern options that change the meaning of the - pattern string. - - There are some subtle differences between \l QRegularExpression and \c - QRegExp that will be explained by this document to ease the porting effort. - - \l QRegularExpression is more strict when it comes to the syntax of the - regular expression. Therefore it is always good to check the expression - for \l {QRegularExpression::isValid}{validity}. - - \l QRegularExpression can almost always be declared const (except when the - pattern changes), while \c QRegExp almost never could be. - - There is no replacement for the \l {QRegExp::CaretMode}{CaretMode} - enumeration. The \l {QRegularExpression::AnchoredMatchOption} match option - can be used to emulate the QRegExp::CaretAtOffset behavior. There is no - equivalent for the other QRegExp::CaretMode modes. - - \l QRegularExpression supports only Perl-compatible regular expressions. - Still, it does not support all the features available in Perl-compatible - regular expressions. The most notable one is the fact that duplicated names - for capturing groups are not supported, and using them can lead to - undefined behavior. This may change in a future version of Qt. - - \section3 Wildcard matching - - There is no direct way to do wildcard matching in \l QRegularExpression. - However, the \l {QRegularExpression::wildcardToRegularExpression} method - is provided to translate glob patterns into a Perl-compatible regular - expression that can be used for that purpose. - - For example, if you have code like - - \code - QRegExp wildcard("*.txt"); - wildcard.setPatternSyntax(QRegExp::Wildcard); - \endcode - - you can rewrite it as - - \code - auto wildcard = QRegularExpression(QRegularExpression::wildcardToRegularExpression("*.txt")); - \endcode - - Please note though that not all shell like wildcard pattern might be - translated in a way you would expect it. The following example code will - silently break if simply converted using the above mentioned function: - - \code * - const QString fp1("C:/Users/dummy/files/content.txt"); - const QString fp2("/home/dummy/files/content.txt"); - - QRegExp re1("\1/files/*"); - re1.setPatternSyntax(QRegExp::Wildcard); - ... = re1.exactMatch(fp1); // returns true - ... = re1.exactMatch(fp2); // returns true - - // but converted with QRegularExpression::wildcardToRegularExpression() - - QRegularExpression re2(QRegularExpression::wildcardToRegularExpression("\1/files/*")); - ... = re2.match(fp1).hasMatch(); // returns false - ... = re2.match(fp2).hasMatch(); // returns false - \endcode - - \section3 Searching forward - - Forward searching inside a string was usually implemented with a loop using - \c {QRegExp::indexIn} and a growing offset, but can now be easily implemented - with \l QRegularExpressionMatchIterator or \l {QString::indexOf}. - - For example, if you have code like - - \code - QString subject("the quick fox"); - - int offset = 0; - QRegExp re("(\\w+)"); - while ((offset = re.indexIn(subject, offset)) != -1) { - offset += re.matchedLength(); - // ... - } - \endcode - - you can rewrite it as - - \code - QRegularExpression re("(\\w+)"); - QString subject("the quick fox"); - - QRegularExpressionMatchIterator i = re.globalMatch(subject); - while (i.hasNext()) { - QRegularExpressionMatch match = i.next(); - // ... - } - - // or alternatively using QString::indexOf - - qsizetype from = 0; - QRegularExpressionMatch match; - while ((from = subject.indexOf(re, from, &match)) != -1) { - from += match.capturedLength(); - // ... - } - \endcode - - \section3 Searching backwards - - Backwards searching inside a string was usually often implemented as a loop - over \c {QRegExp::lastIndexIn}, but can now be easily implemented using - \l {QString::lastIndexOf} and \l {QRegularExpressionMatch}. - - \note \l QRegularExpressionMatchIterator is not capable of performing a - backwards search. - - For example, if you have code like - - \code - int offset = -1; - QString subject("Lorem ipsum dolor sit amet, consetetur sadipscing."); - - QRegExp re("\\s+([ids]\\w+)"); - while ((offset = re.lastIndexIn(subject, offset)) != -1) { - --offset; - // ... - } - \endcode - - you can rewrite it as - - \code - qsizetype from = -1; - QString subject("Lorem ipsum dolor sit amet, consetetur sadipscing."); - - QRegularExpressionMatch match; - QRegularExpression re("\\s+([ids]\\w+)"); - while ((from = subject.lastIndexOf(re, from, &match)) != -1) { - --from; - // ... - } - \endcode - - \section3 exactMatch vs. match.hasMatch - - \c {QRegExp::exactMatch} served two purposes: it exactly matched a regular - expression against a subject string, and it implemented partial matching. - Exact matching indicates whether the regular expression matches the entire - subject string. For example: - - \code - QString source("abc123"); - - QRegExp("\\d+").exactMatch(source); // returns false - QRegExp("[a-z]+\\d+").exactMatch(source); // returns true - - QRegularExpression("\\d+").match(source).hasMatch(); // returns true - QRegularExpression("[a-z]+\\d+").match(source).hasMatch(); // returns true - \endcode - - Exact matching is not reflected in \l QRegularExpression. If you want to be - sure that the subject string matches the regular expression exactly, you - can wrap the pattern using the \l {QRegularExpression::anchoredPattern} - function: - - \code - QString source("abc123"); - - QString pattern("\\d+"); - QRegularExpression(pattern).match(source).hasMatch(); // returns true - - pattern = QRegularExpression::anchoredPattern(pattern); - QRegularExpression(pattern).match(source).hasMatch(); // returns false - \endcode - - \section3 Minimal matching - - \c QRegExp::setMinimal() implemented minimal matching by simply reversing - the greediness of the quantifiers (\c QRegExp did not support lazy - quantifiers, like *?, +?, etc.). QRegularExpression instead does support - greedy, lazy and possessive quantifiers. The \l - {QRegularExpression::InvertedGreedinessOption} pattern option can be useful - to emulate the effects of \c QRegExp::setMinimal(): if enabled, it inverts - the greediness of quantifiers (greedy ones become lazy and vice versa). - - \section3 Different pattern syntax - - Porting a regular expression from \c QRegExp to \l QRegularExpression may - require changes to the pattern itself. Therefore it is recommended to check - the pattern used with the \l {QRegularExpression::isValid} method. This is - especially important for user provided pattern or pattern not controlled by - the developer. - - In other cases, a pattern ported from \c QRegExp to \l QRegularExpression may - silently change semantics. Therefore, it is necessary to review the patterns - used. The most notable cases of silent incompatibility are: - - \list - \li Curly braces are needed in order to use a hexadecimal escape like \c - {\xHHHH} with more than 2 digits. A pattern like \c {\x2022} needs - to be ported to \c {\x{2022}}, or it will match a space \c {(0x20)} - followed by the string \c {"22"}. In general, it is highly recommended - to always use curly braces with the \c {\x} escape, no matter the - amount of digits specified. - - \li A \c{0-to-n} quantification like \c {{,n}} needs to be ported to - \c {{0,n}} to preserve semantics. Otherwise, a pattern such as - \c {\d{,3}} would actually match a digit followed by the exact - string \c {"{,3}"}. - \endlist - - \section3 Partial Matching - - When using \c QRegExp::exactMatch(), if an exact match was not found, one - could still find out how much of the subject string was matched by the - regular expression by calling \c QRegExp::matchedLength(). If the returned - length was equal to the subject string's length, then one could conclude - that a partial match was found. - \l QRegularExpression supports partial matching explicitly by means of the - appropriate \l {QRegularExpression::MatchType}. - - \section3 Global matching - - Due to limitations of the \c QRegExp API it was impossible to implement - global matching correctly (that is, like Perl does). In particular, patterns - that can match zero characters (like "a*") are problematic. \l - {QRegularExpression::wildcardToRegularExpression} implements Perl global - match correctly, and the returned iterator can be used to examine each - result. - - \section3 Unicode properties support - - When using \c QRegExp, character classes such as \c{\w}, \c{\d}, etc. match - characters with the corresponding Unicode property: for instance, \c{\d} - matches any character with the Unicode Nd (decimal digit) property. Those - character classes only match ASCII characters by default. When using \l - QRegularExpression: for instance, \c{\d} matches exactly a character in the - 0-9 ASCII range. It is possible to change this behavior by using the \l - {QRegularExpression::UseUnicodePropertiesOption} - pattern option. + \include corelib/port-from-qregexp.qdocinc porting-to-qregularexpression \section2 The QRegExp class @@ -782,6 +543,8 @@ code-bases working. If you want to use \c QRegExp further, see \l {Using the Qt5Compat module}. + \section1 QEvent and subclasses + The QEvent class defined a copy constructor and an assignment operator, in spite of being a polymorphic class. Copying classes with virtual methods can result in slicing when assigning objects from different classes to each diff --git a/src/corelib/doc/src/qtcore-index.qdoc b/src/corelib/doc/src/qtcore-index.qdoc index 377e199784..38452e1b2b 100644 --- a/src/corelib/doc/src/qtcore-index.qdoc +++ b/src/corelib/doc/src/qtcore-index.qdoc @@ -75,8 +75,11 @@ \list \li \l{The Animation Framework} \li \l{JSON Support in Qt} + \li \l{CBOR Support in Qt} + \li \l{Inter-Process Communication} \li \l{How to Create Qt Plugins} \li \l{The Event System} + \li \l{Application Permissions} \endlist \section1 Reference diff --git a/src/corelib/doc/src/qtcore.qdoc b/src/corelib/doc/src/qtcore.qdoc index 4dd56e4227..a46add1342 100644 --- a/src/corelib/doc/src/qtcore.qdoc +++ b/src/corelib/doc/src/qtcore.qdoc @@ -14,3 +14,21 @@ The \l{Qt Core} page contains information about how to use the module. */ + +/*! + \module QtCorePrivate + \title Qt Core Private C++ Classes + \qtvariable core-private + \preliminary + \brief Provides private core functionality. + +//! [qtcoreprivate-usage] + When building with CMake, use the following commands to use + private Qt Core APIs: + + \badcode + find_package(Qt6 REQUIRED COMPONENTS Core) + target_link_libraries(mytarget PRIVATE Qt6::CorePrivate) + \endcode +//! [qtcoreprivate-usage] +*/ diff --git a/src/corelib/doc/src/qtserialization.qdoc b/src/corelib/doc/src/qtserialization.qdoc new file mode 100644 index 0000000000..14ee5e7a9c --- /dev/null +++ b/src/corelib/doc/src/qtserialization.qdoc @@ -0,0 +1,145 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtserialization.html + \title Qt Serialization + \brief Serializations provided by Qt API + + The purpose of serialization is to save the state of an object to be able to + recreate it when needed. It allows you to perform actions like: + + \list + \li Sending the object to a remote application by using a web service + \li Passing the object as a JSON or XML string + \li Saving and restoring user information or sharing it across applications + \endlist + + The Qt API provides support for serialization for several use cases: + + \list + \li \l JSON support in Qt provides an easy to use C++ API to parse, modify + and save JSON data. \l {CBOR} {CBOR Support in Qt} is a compact form + of binary data encoding that is a superset of JSON. + \li \l QDataStream provides serialization of binary data to a QIODevice + \li \l {Qt XML C++ Classes} provide C++ implementations of the \l {XML Streaming} + and DOM standards for XML + \li \l CBOR is Qt's implementation for the CBOR serialization format. + \li \l QSettings provides a way of serializing and storing platform independent + application settings. + \endlist + + \section1 Advantages of JSON and CBOR + + When you use \l JSON information is stored in a QJsonObject and a QJsonDocument + takes care to stream values into a QByteArray. + + For example + \code + QJsonObject jobject; + jobject["SensorID"] = m_id; + jobject["AmbientTemperature"] = m_ambientTemperature; + jobject["ObjectTemperature"] = m_objectTemperature; + jobject["AccelerometerX"] = m_accelerometerX; + jobject["AccelerometerY"] = m_accelerometerY; + jobject["AccelerometerZ"] = m_accelerometerZ; + jobject["Altitude"] = m_altitude; + jobject["Light"] = m_light; + jobject["Humidity"] = m_humidity; + QJsonDocument doc( jobject ); + + return doc.toJson(); + \endcode + + JSON has several advantages: + + \list + \li Textual JSON is declarative, which makes it readable to humans + \li The information is structured + \li Exchanging generic information is easy + \li JSON allows extending messages with additional values + \li Many solutions exist to receive and parse JSON in cloud-based solutions + \endlist + + \l CBOR is the Concise Binary Object Representation, a very compact form of + binary data encoding that is a superset of JSON. It was created by the IETF + Constrained RESTful Environments (CoRE) WG, which has been used in many new + RFCs. CBOR shares many of the advantages of JSON, but sacrifices human + readability for compactness. + + \section1 Advantages of QDataStream Classes + + \l QDataStream is a viable option when the whole flow of data is determined + and not about to change. In addition, both the reader and the writer of the + data must be written in Qt. + + Adding support for this to a class requires two additional operators. + For example, for a class named SensorInformation: + + \code + QDataStream &operator<<(QDataStream &, const SensorInformation &); + QDataStream &operator>>(QDataStream &, SensorInformation &); + \endcode + + The implementation for the serialization is shown below: + + \code + QDataStream &operator<<(QDataStream &out, const SensorInformation &item) + { + QDataStream::FloatingPointPrecision prev = out.floatingPointPrecision(); + out.setFloatingPointPrecision(QDataStream::DoublePrecision); + out << item.m_id + << item.m_ambientTemperature + << item.m_objectTemperature + << item.m_accelerometerX + << item.m_accelerometerY + << item.m_accelerometerZ + << item.m_altitude + << item.m_light + << item.m_humidity; + out.setFloatingPointPrecision(prev); + return out; + } + \endcode + + Deserialization works similarly, but using the \c {>>} operator. + For example, \c {out >> item.m_id}, and so on. + + Usually, using QDataStream is faster than using textual JSON. + + \section1 Advantages of Qt XML C++ Classes + + Qt provides both DOM classes and stream-based classes to read and write + XML content. + + Qt provides the QDomDocument class that represents the XML document and + two classes for reading and writing the XML through a simple streaming API: + QXmlStreamReader and QXmlStreamWriter. + + \section2 The DOM XML Classes + + QDomDocument class represents the entire XML document. It is the root of the + document tree and provides primary access to the document's data. + + \section2 The Stream-Based XML Classes + + A stream reader reports an XML document as a stream of tokens. This differs + from SAX as SAX applications provide handlers to receive XML events from the + parser, whereas the QXmlStreamReader drives the loop, pulling tokens from the + reader when they are needed. This pulling approach makes it possible to build + recursive descent parsers, allowing XML parsing code to be split into + different methods or classes. + + QXmlStreamReader a parser for well-formed XML 1.0, excluding external parsed + entities. Hence, data provided to the stream reader adheres to the + W3C's criteria for well-formed XML, or an error will be raised. Functions + such as \c atEnd(), \c error(), and \c hasError() can be used to test for + such errors and obtain a description of them. + + The QXmlStreamWriter is a streaming API that takes care of prefixing namespaces, + when the namespaceUri is specified when writing elements or attributes. + + \section1 Classes that Provide Serialization + + \annotatedlist qtserialization +*/ diff --git a/src/corelib/doc/src/resource-system.qdoc b/src/corelib/doc/src/resource-system.qdoc index 45934a29d0..7c7613c9b8 100644 --- a/src/corelib/doc/src/resource-system.qdoc +++ b/src/corelib/doc/src/resource-system.qdoc @@ -17,7 +17,7 @@ Most commonly, the resource files are embedded into your application executable, or in libraries and plugins that are loaded by the application executable. Alternatively, the resource files can also be stored in an - \l{External Resource Files}{exernal resource file}. + \l{External Resource Files}{external resource file}. The resource system is based on tight cooperation between Qt's \l rcc resource compiler, the build system, and the Qt runtime API. @@ -59,8 +59,8 @@ the \c .qrc file. The path is also used by default to identify the file's content at runtime. - That is, the file \c copy.png will be available in the resource system as - \c{:/images/copy.png} or \c{qrc:/images/copy.png}. + That is, the file \c titlebarLeft.png will be available in the resource system as + \c{:/res/titlebarLeft.png} or \c{qrc:/res/titlebarLeft.png}. To override this default run-time name, see \l{Prefixes} and \l{Aliases}. \e{Qt Creator}, \e{Qt Design Studio}, \QD, and \e{Qt Visual Studio Tools} @@ -102,13 +102,16 @@ variable. If you add a \c .qrc file path to the variable, the listed resource files will be embedded into the generated library or executable: - \snippet resource-system/application.pro 0 + \snippet resource-system/application.pro qrc - For simple applications, it is also possible to let qmake generate the - \c .qrc file for you, avoiding the need for an additional file to be - maintained: + This creates a resource of several \c{.png} files, that are addressable + like this: \c{":/res/titlebarLeft.png"}. - \snippet resource-system/application.pro 1 + If the directory layout of the files you want to embed into the resource + doesn't match the expectations of the application, you can specify + \c{resources.base}. \c base is a path prefix that denotes the root point of + the file's alias. In the example above, if \c{resources.base} is set to + \c{"res"}, then \c{titlebarLeft.png} is addressable as \c{":/titlebarLeft.png"}. \section1 Runtime API @@ -127,9 +130,6 @@ \snippet resource-system/main.cpp url - See the \l{mainwindows/application}{Application} example for an actual - application that uses Qt's resource system to store its icons. - \section1 Advanced Topics \section2 Prefixes @@ -157,6 +157,25 @@ The file is from the application then only accessible as \c :/cut-img.png or \c{qrc:/cut-img.png}. + \section2 Discarding the file contents + + Sometimes you want to add a file node to the resource file system but + don't actually want to add the file contents. \c .qrc files allow this + by setting the \c empty attribute to \c{true}. + + \snippet code/doc_src_resources.qdoc 4 + + The resulting file is then still accessible from the application, but + its contents are empty. + + This is useful to strip QML source code from an application 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. + \section2 Language Selectors Some resources need to change based on the user's locale, such as @@ -188,14 +207,7 @@ resource file's content and metadata is then done after the compilation and linking phase, through another rcc call. - For qmake, this is enabled by adding \c resources_big to the \c CONFIG - variable: - - \snippet resource-system/application.pro 2 - - For CMake, you need to use the \l{qt_add_big_resources} function: - - \snippet resource-system/CMakeLists.txt qt_add_big_resources + For CMake, you need to use the \l{qt_add_big_resources} function. \section2 External Resource Files @@ -223,13 +235,13 @@ resource compiler \l rcc: \code - rcc -g python application.qrc > application_rc.py + rcc -g python mainwindow.qrc > mainwindow_rc.py \endcode The module can then be imported in the application: \code - import application_rc.py + import mainwindow_rc.py \endcode \section2 Compression diff --git a/src/corelib/doc/src/timers.qdoc b/src/corelib/doc/src/timers.qdoc index c9ad054b17..dc205a47b9 100644 --- a/src/corelib/doc/src/timers.qdoc +++ b/src/corelib/doc/src/timers.qdoc @@ -6,17 +6,17 @@ \title Timers \brief How to use Qt timers in your application. - \ingroup best-practices + \ingroup how-to QObject, the base class of all Qt objects, provides the basic timer support in Qt. With QObject::startTimer(), you start a timer with an interval in milliseconds as argument. The function - returns a unique integer timer ID. The timer will now fire at + returns a unique integral timer ID. The timer will then fire at regular intervals until you explicitly call QObject::killTimer() - with the timer ID. + with that timer ID. For this mechanism to work, the application must run in an event - loop. You start an event loop with QApplication::exec(). When a + loop. You cat start an event loop with QApplication::exec(). When a timer fires, the application sends a QTimerEvent, and the flow of control leaves the event loop until the timer event is processed. This implies that a timer cannot fire while your application is @@ -31,69 +31,65 @@ stop all timers in the object's thread; it is not possible to start timers for objects in another thread. - The upper limit for the interval value is determined by the number - of milliseconds that can be specified in a signed integer - (in practice, this is a period of just over 24 days). The accuracy - depends on the underlying operating system. Windows 2000 has 15 - millisecond accuracy; other systems that we have tested can handle - 1 millisecond intervals. - - The main API for the timer functionality is QTimer. That class - provides regular timers that emit a signal when the timer fires, and - inherits QObject so that it fits well into the ownership structure - of most Qt programs. The normal way of using it is like this: - - \snippet timers/timers.cpp 0 - \snippet timers/timers.cpp 1 - \snippet timers/timers.cpp 2 - - The QTimer object is made into a child of \c this object so that, - when \c this object is deleted, the timer is deleted too. - Next, its \l{QTimer::}{timeout()} signal is connected to the slot - that will do the work, it is started with a value of 1000 - milliseconds, indicating that it will time out every second. - - QTimer also provides a static function for single-shot timers. + The main API for the timer functionality was \l QTimer. QTimer stores + the interval in a signed integer, which limits the maximum interval it + supports to the number of milliseconds that can fit in a signed integer + (in practice, this is a period of around 24 days). + + Qt 6.8 introduced the \l QChronoTimer class to replace QTimer. QChronoTimer + stores the interval as \c std::chrono::nanoseconds, which means that + the maximum interval it supports is around 292 years. This mitigates + the chances of integer overflow that QTimer had if the interval was more + than \c{std::numeric_limits<int>::max()}. + + The accuracy of the timers depends on the underlying operating system. + Windows 2000 has 15ms accuracy; other systems that we have tested can + handle 1ms intervals. + + QChronoTimer provides regular timers that emit a signal when the timer + fires, and inherits from QObject so that it fits well into the ownership + structure of most Qt programs. The normal way of using it is like this: + + \snippet timers/timers.cpp timer-interval-in-ctor + \snippet timers/timers.cpp timer-setinterval + + The QChronoTimer object is made into a child of the \c this object so + that, when \c this is destroyed, the timer is destroyed too. Next, the + \l{QChronoTimer::}{timeout()} signal is connected to the slot that will + do the work, the timer interval can be either passed to the constructor, + or set later on with setInterval(). + + QChronoTimer also provides static functions for single-shot timers. For example: - \snippet timers/timers.cpp 3 + \snippet timers/timers.cpp qchronotimer-singleshot - 200 milliseconds (0.2 seconds) after this line of code is - executed, the \c updateCaption() slot will be called. + 200ms after this line of code is executed, the \c updateCaption() slot + will be called. - For QTimer to work, you must have an event loop in your - application; that is, you must call QCoreApplication::exec() - somewhere. Timer events will be delivered only while the event - loop is running. + For QChronoTimer to work, you must have an event loop in your application; + that is, you must call QCoreApplication::exec() somewhere. Timer events + will be delivered only while the event loop is running. - In multithreaded applications, you can use QTimer in any thread - that has an event loop. To start an event loop from a non-GUI - thread, use QThread::exec(). Qt uses the timer's - \l{QObject::thread()}{thread affinity} to determine which thread - will emit the \l{QTimer::}{timeout()} signal. Because of this, you - must start and stop the timer in its thread; it is not possible to - start a timer from another thread. - - The \l{widgets/analogclock}{Analog Clock} example shows how to use - QTimer to redraw a widget at regular intervals. From \c{AnalogClock}'s - implementation: - - \snippet timers/analogclock.cpp 0 - \snippet timers/analogclock.cpp 2 - \snippet timers/analogclock.cpp 3 - \snippet timers/analogclock.cpp 4 - \snippet timers/analogclock.cpp 5 - \snippet timers/analogclock.cpp 6 - \dots - \snippet timers/analogclock.cpp 7 - - Every second, QTimer will call the QWidget::update() slot to + In multithreaded applications, you can use QChronoTimer in any thread + that has an event loop. To start an event loop from a non-GUI thread, use + QThread::exec(). Qt uses the timer's \l{QObject::thread()}{thread affinity} + to determine which thread will emit the \l{QChronoTimer::}{timeout()} + signal. Because of this, you must start and stop the timer in its thread; + it is not possible to start a timer from another thread. + + The \l{widgets/analogclock}{Analog Clock} example shows how to + use QChronoTimer to redraw a widget at regular intervals. From + \c{AnalogClock}'s implementation: + + \snippet timers/analogclock.cpp analogclock-qchronotimer + + Every second, QChronoTimer will call the QWidget::update() slot to refresh the clock's display. If you already have a QObject subclass and want an easy optimization, you can use QBasicTimer instead of QTimer. With QBasicTimer, you must reimplement \l{QObject::timerEvent()}{timerEvent()} in your QObject subclass - and handle the timeout there. The \l{widgets/wiggly}{Wiggly} - example shows how to use QBasicTimer. + and handle the timeout there. */ |