echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Autogen: Update Documentation

Browse Source 
* Add Qt 6 to documentation
* Add explanation about `<ORIGIN>_autogen_timestamp_deps`

Fixes: #25201
This commit is contained in:
Orkun Tokdemir 2024-02-06 16:46:01 +01:00 committed by Brad King
parent 16cc011fa5
commit ccaf529c4e
12 changed files with 126 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Help/command/qt_wrap_cpp.rst
View File

@ -8,7 +8,7 @@ qt_wrap_cpp
:module:`FindQt4` module provides the ``qt4_wrap_cpp()`` macro, which
should be used instead for Qt 4 projects. For projects using Qt 5 or
later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
``qt5_wrap_cpp()``).
`qt5_wrap_cpp() <https://doc.qt.io/qt-5/qtcore-cmake-qt5-wrap-cpp.html>`_).
Manually create Qt Wrappers.

72
Help/manual/cmake-qt.7.rst
View File

@ -10,34 +10,39 @@ cmake-qt(7)
Introduction
============
CMake can find and use Qt 4 and Qt 5 libraries. The Qt 4 libraries are found
by the :module:`FindQt4` find-module shipped with CMake, whereas the
Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See
:manual:`cmake-packages(7)` for more information about CMake packages, and
see `the Qt cmake manual <https://doc.qt.io/qt-5/cmake-manual.html>`_
for your Qt version.
CMake can find and use Qt 4, Qt 5 and Qt 6 libraries. The Qt 4 libraries are
found by the :module:`FindQt4` find-module shipped with CMake, whereas the
Qt 5 and Qt 6 libraries are found using "Config-file Packages" shipped with
Qt 5 and Qt 6. See :manual:`cmake-packages(7)` for more information about CMake
packages, and see `the Qt cmake manual`_ for your Qt version.
Qt 4 and Qt 5 may be used together in the same
.. _`the Qt cmake manual`: https://doc.qt.io/qt-6/cmake-manual.html
Qt 4, Qt 5 and Qt 6 may be used together in the same
:manual:`CMake buildsystem <cmake-buildsystem(7)>`:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR)
cmake_minimum_required(VERSION 3.16 FATAL_ERROR)
project(Qt4And5)
project(Qt4_5_6)
set(CMAKE_AUTOMOC ON)
find_package(Qt5 COMPONENTS Widgets DBus REQUIRED)
find_package(Qt6 COMPONENTS Widgets DBus REQUIRED)
add_executable(publisher publisher.cpp)
target_link_libraries(publisher Qt5::Widgets Qt5::DBus)
target_link_libraries(publisher Qt6::Widgets Qt6::DBus)
find_package(Qt5 COMPONENTS Gui DBus REQUIRED)
add_executable(subscriber1 subscriber1.cpp)
target_link_libraries(subscriber1 Qt5::Gui Qt5::DBus)
find_package(Qt4 REQUIRED)
add_executable(subscriber subscriber.cpp)
target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus)
add_executable(subscriber2 subscriber2.cpp)
target_link_libraries(subscriber2 Qt4::QtGui Qt4::QtDBus)
A CMake target may not link to both Qt 4 and Qt 5. A diagnostic is issued if
this is attempted or results from transitive target dependency evaluation.
A CMake target may not link to more than one Qt version. A diagnostic is issued
if this is attempted or results from transitive target dependency evaluation.
Qt Build Tools
==============
@ -46,7 +51,7 @@ Qt relies on some bundled tools for code generation, such as ``moc`` for
meta-object code generation, ``uic`` for widget layout and population,
and ``rcc`` for virtual file system content generation. These tools may be
automatically invoked by :manual:`cmake(1)` if the appropriate conditions
are met. The automatic tool invocation may be used with both Qt 4 and Qt 5.
are met. The automatic tool invocation may be used with Qt version 4 to 6.
.. _`Qt AUTOMOC`:
@ -158,7 +163,7 @@ should be used when running ``uic``:
.. code-block:: cmake
add_library(KI18n klocalizedstring.cpp)
target_link_libraries(KI18n Qt5::Core)
target_link_libraries(KI18n Qt6::Core)
# KI18n uses the tr2i18n() function instead of tr(). That function is
# declared in the klocalizedstring.h header.
@ -213,25 +218,44 @@ overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property.
Source files can be excluded from :prop_tgt:`AUTORCC` processing by
enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`.
.. _`<ORIGIN>_autogen`:
The ``<ORIGIN>_autogen`` target
===============================
The ``moc`` and ``uic`` tools are executed as part of a synthesized
``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by
CMake. By default that ``<ORIGIN>_autogen`` target inherits the dependencies
:ref:`<ORIGIN>_autogen` :command:`custom target <add_custom_target>` generated by
CMake. By default that :ref:`<ORIGIN>_autogen` target inherits the dependencies
of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`).
Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding
Target dependencies may be added to the :ref:`<ORIGIN>_autogen` target by adding
them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
.. note::
If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or
:ref:`Makefile Generators`, see :ref:`<ORIGIN>_autogen_timestamp_deps`.
.. _`<ORIGIN>_autogen_timestamp_deps`:
The ``<ORIGIN>_autogen_timestamp_deps`` target
==============================================
If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or
:ref:`Makefile Generators`, the ``<ORIGIN>_autogen_timestamp_deps`` target is
also created in addition to the :ref:`<ORIGIN>_autogen` target. This target
does not have any sources or commands to execute, but it has dependencies that
were previously inherited by the pre-Qt 5.15 :ref:`<ORIGIN>_autogen` target.
These dependencies will serve as a list of order-only dependencies for the
custom command, without forcing the custom command to re-execute.
Visual Studio Generators
========================
When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake
generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>`
instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>`
(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`).
This isn't always possible though and
an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used,
instead of the :ref:`<ORIGIN>_autogen`
:command:`custom target <add_custom_target>` (for :prop_tgt:`AUTOMOC` and
:prop_tgt:`AUTOUIC`). This isn't always possible though and an
:ref:`<ORIGIN>_autogen` :command:`custom target <add_custom_target>` is used,
when either
- the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't

42
Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst
View File

@ -4,20 +4,29 @@ AUTOGEN_ORIGIN_DEPENDS
.. versionadded:: 3.14
Switch for forwarding origin target dependencies to the corresponding
``_autogen`` target.
:ref:`<ORIGIN>_autogen` target.
.. note::
If Qt 5.15 or later is used and the generator is either :generator:`Ninja`
or :ref:`Makefile Generators`, origin target dependencies are forwarded to
the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of
:ref:`<ORIGIN>_autogen`
Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property
``ON`` have a corresponding ``_autogen`` target which generates
``moc`` and ``uic`` files. As this ``_autogen`` target is created at
``ON`` have a corresponding :ref:`<ORIGIN>_autogen` target which generates
``moc`` and ``uic`` files. As this :ref:`<ORIGIN>_autogen` target is created at
generate-time, it is not possible to define dependencies of it using
e.g. :command:`add_dependencies`. Instead the
``AUTOGEN_ORIGIN_DEPENDS`` target property decides whether the origin
target dependencies should be forwarded to the ``_autogen`` target or not.
e.g. :command:`add_dependencies`. Instead the ``AUTOGEN_ORIGIN_DEPENDS``
target property decides whether the origin target dependencies should be
forwarded to the :ref:`<ORIGIN>_autogen` target or not.
By default ``AUTOGEN_ORIGIN_DEPENDS`` is initialized from
:variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` which is ``ON`` by default.
In total the dependencies of the ``_autogen`` target are composed from
In total the dependencies of the :ref:`<ORIGIN>_autogen` target are composed
from
- forwarded origin target dependencies
(enabled by default via ``AUTOGEN_ORIGIN_DEPENDS``)
@ -26,15 +35,14 @@ In total the dependencies of the ``_autogen`` target are composed from
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.
Note
^^^^
.. note::
Disabling ``AUTOGEN_ORIGIN_DEPENDS`` is useful to avoid building of
origin target dependencies when building the ``_autogen`` target only.
This is especially interesting when a
:variable:`global autogen target <CMAKE_GLOBAL_AUTOGEN_TARGET>` is enabled.
Disabling ``AUTOGEN_ORIGIN_DEPENDS`` is useful to avoid building of
origin target dependencies when building the :ref:`<ORIGIN>_autogen` target
only. This is especially interesting when a
:variable:`global autogen target <CMAKE_GLOBAL_AUTOGEN_TARGET>` is enabled.
When the ``_autogen`` target doesn't require all the origin target's
dependencies, and ``AUTOGEN_ORIGIN_DEPENDS`` is disabled, it might be
necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` to add missing
dependencies.
When the :ref:`<ORIGIN>_autogen` target doesn't require all the origin target's
dependencies, and ``AUTOGEN_ORIGIN_DEPENDS`` is disabled, it might be
necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` to add missing
dependencies.

4
Help/prop_tgt/AUTOGEN_PARALLEL.rst
View File

@ -6,9 +6,9 @@ AUTOGEN_PARALLEL
Number of parallel ``moc`` or ``uic`` processes to start when using
:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
The custom ``<origin>_autogen`` target starts a number of threads of which
The custom :ref:`<ORIGIN>_autogen` target starts a number of threads of which
each one parses a source file and on demand starts a ``moc`` or ``uic``
process. ``AUTOGEN_PARALLEL`` controls how many parallel threads
process. ``AUTOGEN_PARALLEL`` controls how many parallel threads
(and therefore ``moc`` or ``uic`` processes) are started.
- An empty (or unset) value or the string ``AUTO`` sets the number of

28
Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
View File

@ -1,18 +1,28 @@
AUTOGEN_TARGET_DEPENDS
----------------------
Additional target dependencies of the corresponding ``_autogen`` target.
Additional target dependencies of the corresponding :ref:`<ORIGIN>_autogen`
target.
.. note::
If Qt 5.15 or later is used and the generator is either :generator:`Ninja`
or :ref:`Makefile Generators`, additional target dependencies are added to
the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of the
:ref:`<ORIGIN>_autogen` target.
Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property
``ON`` have a corresponding ``_autogen`` target which generates
``moc`` and ``uic`` files. As this ``_autogen`` target is created at
generate-time, it is not possible to define dependencies of it using
e.g. :command:`add_dependencies`. Instead the
``AUTOGEN_TARGET_DEPENDS`` target property can be set to a
:ref:`;-list <CMake Language Lists>` of additional dependencies for the
``_autogen`` target. Dependencies can be target names or file names.
``ON`` have a corresponding :ref:`<ORIGIN>_autogen` target which generates
``moc`` and ``uic`` files. As this :ref:`<ORIGIN>_autogen` target is created
at generate-time, it is not possible to define dependencies of it using e.g.
:command:`add_dependencies`. Instead the ``AUTOGEN_TARGET_DEPENDS`` target
property can be set to a :ref:`;-list <CMake Language Lists>` of additional
dependencies for the :ref:`<ORIGIN>_autogen` target. Dependencies can be target
names or file names.
In total the dependencies of the ``_autogen`` target are composed from
In total the dependencies of the :ref:`<ORIGIN>_autogen` target are composed
from
- forwarded origin target dependencies
(enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`)

10
Help/prop_tgt/AUTOMOC.rst
View File

@ -3,11 +3,13 @@ AUTOMOC
Should the target be processed with auto-moc (for Qt projects).
``AUTOMOC`` is a boolean specifying whether CMake will handle the Qt
``moc`` preprocessor automatically, i.e. without having to use commands like
:module:`QT4_WRAP_CPP() <FindQt4>`, ``QT5_WRAP_CPP()``, etc.
``AUTOMOC`` is a boolean specifying whether CMake will handle the Qt ``moc``
preprocessor automatically, i.e. without having to use commands like
:module:`QT4_WRAP_CPP() <FindQt4>`, `qt5_wrap_cpp()`_, etc.
Currently, Qt versions 4 to 6 are supported.
.. _qt5_wrap_cpp(): https://doc.qt.io/qt-5/qtcore-cmake-qt5-wrap-cpp.html
This property is initialized by the value of the :variable:`CMAKE_AUTOMOC`
variable if it is set when a target is created.
@ -240,7 +242,7 @@ e.g. in MSVS.
:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`:
A global ``autogen`` target, that depends on all ``AUTOMOC`` or
:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project,
:prop_tgt:`AUTOUIC` generated :ref:`<ORIGIN>_autogen` targets in the project,
will be generated when this variable is ``ON``.
:prop_tgt:`AUTOGEN_PARALLEL`:

6
Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst
View File

@ -22,14 +22,14 @@ file gets rebuilt even when the source file itself doesn't change.
If any of the extracted files is :prop_sf:`GENERATED` or if it is not in the
target's sources, then it might be necessary to add it to the
``_autogen`` target dependencies.
:ref:`<ORIGIN>_autogen` target dependencies.
See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference.
By default ``AUTOMOC_DEPEND_FILTERS`` is initialized from
:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default.
From Qt 5.15.0 on this variable is ignored as moc is able to output the correct
dependencies.
From Qt 5.15.0 on this variable is ignored as ``moc`` is able to output the
correct dependencies.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

4
Help/prop_tgt/AUTORCC.rst
View File

@ -5,9 +5,11 @@ Should the target be processed with auto-rcc (for Qt projects).
``AUTORCC`` is a boolean specifying whether CMake will handle
the Qt ``rcc`` code generator automatically, i.e. without having to use
commands like :module:`QT4_ADD_RESOURCES() <FindQt4>`, ``QT5_ADD_RESOURCES()``,
commands like :module:`QT4_ADD_RESOURCES() <FindQt4>`, `qt5_add_resources()`_,
etc. Currently, Qt versions 4 to 6 are supported.
.. _`qt5_add_resources()`: https://doc.qt.io/qt-5/qtcore-cmake-qt5-add-resources.html
When this property is ``ON``, CMake will handle ``.qrc`` files added
as target sources at build time and invoke ``rcc`` accordingly.
This property is initialized by the value of the :variable:`CMAKE_AUTORCC`

6
Help/prop_tgt/AUTOUIC.rst
View File

@ -5,9 +5,11 @@ Should the target be processed with auto-uic (for Qt projects).
``AUTOUIC`` is a boolean specifying whether CMake will handle
the Qt ``uic`` code generator automatically, i.e. without having to use
commands like :module:`QT4_WRAP_UI() <FindQt4>`, ``QT5_WRAP_UI()``, etc.
commands like :module:`QT4_WRAP_UI() <FindQt4>`, `qt5_wrap_ui()`_, etc.
Currently, Qt versions 4 to 6 are supported.
.. _`qt5_wrap_ui()`: https://doc.qt.io/qt-5/qtwidgets-cmake-qt5-wrap-ui.html
This property is initialized by the value of the :variable:`CMAKE_AUTOUIC`
variable if it is set when a target is created.
@ -74,7 +76,7 @@ e.g. in MSVS.
:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`:
A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or
``AUTOUIC`` generated ``<ORIGIN>_autogen`` targets in the project,
``AUTOUIC`` generated :ref:`<ORIGIN>_autogen` targets in the project,
will be generated when this variable is ``ON``.
:prop_tgt:`AUTOGEN_PARALLEL`:

2
Help/release/3.14.rst
View File

@ -302,7 +302,7 @@ Autogen
* A new :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` variable and
:prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property may be set to enable or
disable forwarding of the origin target dependencies to the corresponding
``_autogen`` target.
:ref:`<ORIGIN>_autogen` target.
CTest
-----

9
Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst
View File

@ -4,7 +4,14 @@ CMAKE_AUTOGEN_ORIGIN_DEPENDS
.. versionadded:: 3.14
Switch for forwarding origin target dependencies to the corresponding
``_autogen`` targets.
:ref:`<ORIGIN>_autogen` targets.
.. note::
If Qt 5.15 or later is used and the generator is either :generator:`Ninja`
or :ref:`Makefile Generators`, additional target dependencies are added to
the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of the
:ref:`<ORIGIN>_autogen` target.
This variable is used to initialize the :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`
property on all the targets. See that target property for additional

13
Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst
View File

@ -7,7 +7,7 @@ Switch to enable generation of a global ``autogen`` target.
When ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is enabled, a custom target
``autogen`` is generated. This target depends on all :prop_tgt:`AUTOMOC` and
:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project.
:prop_tgt:`AUTOUIC` generated :ref:`<ORIGIN>_autogen` targets in the project.
By building the global ``autogen`` target, all :prop_tgt:`AUTOMOC` and
:prop_tgt:`AUTOUIC` files in the project will be generated.
@ -19,10 +19,9 @@ By default ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is unset.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.
Note
^^^^
.. note::
``<ORIGIN>_autogen`` targets by default inherit their origin target's
dependencies. This might result in unintended dependency target
builds when only ``<ORIGIN>_autogen`` targets are built. A solution is to
disable :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets.
:ref:`<ORIGIN>_autogen` targets by default inherit their origin target's
dependencies. This might result in unintended dependency target builds when
only :ref:`<ORIGIN>_autogen` targets are built. A solution is to disable
:prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets.