summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSebastian Holtermann <sebholt@xwmw.org>2019-06-15 16:37:07 (GMT)
committerBrad King <brad.king@kitware.com>2019-06-19 14:40:42 (GMT)
commitb55e5d6641b6233eeb85926bb3abf39336051d90 (patch)
tree1c1e3cacd56e595f6d3c0b9e842814da1db65092
parentfdab21f30b48021a6ecad2307b092b4d55561ae9 (diff)
downloadCMake-b55e5d6641b6233eeb85926bb3abf39336051d90.zip
CMake-b55e5d6641b6233eeb85926bb3abf39336051d90.tar.gz
CMake-b55e5d6641b6233eeb85926bb3abf39336051d90.tar.bz2
Help: Autogen: Overhaul AUTOMOC target property documentation
- Rewrites and restructures the AUTOMOC target property documentation - Remove the reference to the deprecated CMAKE_AUTOMOC_RELAXED_MODE Fixes: #19167
-rw-r--r--Help/prop_tgt/AUTOMOC.rst274
1 files changed, 212 insertions, 62 deletions
diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst
index 3e6d560..f6dfabd 100644
--- a/Help/prop_tgt/AUTOMOC.rst
+++ b/Help/prop_tgt/AUTOMOC.rst
@@ -1,97 +1,247 @@
AUTOMOC
-------
-Should the target be processed with automoc (for Qt projects).
+Should the target be processed with auto-moc (for Qt projects).
:prop_tgt:`AUTOMOC` is a boolean specifying whether CMake will handle the Qt
``moc`` preprocessor automatically, i.e. without having to use the
-:module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro.
+:module:`QT4_WRAP_CPP() <FindQt4>` or ``QT5_WRAP_CPP()`` macro.
Currently Qt4 and Qt5 are supported.
+This property is initialized by the value of the :variable:`CMAKE_AUTOMOC`
+variable if it is set when a target is created.
+
When this property is set ``ON``, CMake will scan the header and
-source files at build time and invoke moc accordingly.
+source files at build time and invoke ``moc`` accordingly.
-* If an ``#include`` statement like ``#include "moc_<basename>.cpp"`` is found,
- a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is expected to appear in the
- ``<basename>.h(xx)`` header file. ``moc`` is run on the header
- file to generate ``moc_<basename>.cpp`` in the
- ``<AUTOGEN_BUILD_DIR>/include`` directory which is automatically added
- to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
- This allows the compiler to find the included ``moc_<basename>.cpp`` file
- regardless of the location the original source.
- * For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`,
- the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``.
+Header file processing
+^^^^^^^^^^^^^^^^^^^^^^
- * See :prop_tgt:`AUTOGEN_BUILD_DIR`.
+At configuration time, a list of header files that should be scanned by
+:prop_tgt:`AUTOMOC` is computed from the target's sources.
-* If an ``#include`` statement like ``#include "<basename>.moc"`` is found,
- a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is expected to appear in the
- source file and ``moc`` is run on the source file itself.
+- All header files in the target's sources are added to the scan list.
+- For all C++ source files ``<source_base>.<source_extension>`` in the
+ target's sources, CMake searches for
-* Header files that are not included by an ``#include "moc_<basename>.cpp"``
- statement are nonetheless scanned for a macro out of
- :prop_tgt:`AUTOMOC_MACRO_NAMES`.
- The resulting ``moc_<basename>.cpp`` files are generated in custom
- directories and automatically included in a generated
- ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file,
- which is compiled as part of the target.
+ - a regular header with the same base name
+ (``<source_base>.<header_extention>``) and
+ - a private header with the same base name and a ``_p`` suffix
+ (``<source_base>_p.<header_extention>``)
- * The custom directories with checksum
- based names help to avoid name collisions for ``moc`` files with the same
- ``<basename>``.
+ and adds these to the scan list.
- * See :prop_tgt:`AUTOGEN_BUILD_DIR`.
+At build time, CMake scans each unknown or modified header file from the
+list and searches for
-* Additionally, header files with the same base name as a source file,
- (like ``<basename>.h``) or ``_p`` appended to the base name (like
- ``<basename>_p.h``), are scanned for a macro out of
- :prop_tgt:`AUTOMOC_MACRO_NAMES`, and if found, ``moc``
- is also executed on those files.
+- a Qt macro from :prop_tgt:`AUTOMOC_MACRO_NAMES`,
+- additional file dependencies from the ``FILE`` argument of a
+ ``Q_PLUGIN_METADATA`` macro and
+- additional file dependencies detected by filters defined in
+ :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
-* ``AUTOMOC`` always checks multiple header alternative extensions,
- such as ``hpp``, ``hxx``, etc. when searching for headers.
+If a Qt macro is found, then the header will be compiled by the ``moc`` to the
+output file ``moc_<base_name>.cpp``. The complete output file path is
+described in the section `Output file location`_.
-* ``AUTOMOC`` looks for the ``Q_PLUGIN_METADATA`` macro and reruns the
- ``moc`` when the file addressed by the ``FILE`` argument of the macro changes.
+The header will be ``moc`` compiled again if a file from the additional file
+dependencies changes.
-This property is initialized by the value of the :variable:`CMAKE_AUTOMOC`
-variable if it is set when a target is created.
+Header ``moc`` output files ``moc_<base_name>.cpp`` can be included in source
+files. In the section `Including header moc files in sources`_ there is more
+information on that topic.
+
+
+Source file processing
+^^^^^^^^^^^^^^^^^^^^^^
+
+At build time, CMake scans each unknown or modified C++ source file from the
+target's sources for
+
+- a Qt macro from :prop_tgt:`AUTOMOC_MACRO_NAMES`,
+- includes of header ``moc`` files
+ (see `Including header moc files in sources`_),
+- additional file dependencies from the ``FILE`` argument of a
+ ``Q_PLUGIN_METADATA`` macro and
+- additional file dependencies detected by filters defined in
+ :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
+
+If a Qt macro is found, then the C++ source file
+``<base>.<source_extension>`` is expected to as well contain an include
+statement
+
+.. code-block:: c++
+
+ #include <<base>.moc> // or
+ #include "<base>.moc"
+
+The source file then will be compiled by the ``moc`` to the output file
+``<base>.moc``. A description of the complete output file path is in section
+`Output file location`_.
+
+The source will be ``moc`` compiled again if a file from the additional file
+dependencies changes.
+
+Including header moc files in sources
+"""""""""""""""""""""""""""""""""""""
+
+A source file can include the ``moc`` output file of a header
+``<header_base>.<header_extension>`` by using an include statement of
+the form
+
+.. code-block:: c++
+
+ #include <moc_<header_base>.cpp> // or
+ #include "moc_<header_base>.cpp"
+
+If the ``moc`` output file of a header is included by a source, it will
+be generated in a different location than if it was not included. This is
+described in the section `Output file location`_.
+
+
+Output file location
+^^^^^^^^^^^^^^^^^^^^
+
+Included moc output files
+"""""""""""""""""""""""""
+
+``moc`` output files that are included by a source file will be generated in
+
+- ``<AUTOGEN_BUILD_DIR>/include``
+ for single configuration generators or in
+- ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``
+ for :prop_gbl:`multi configuration <GENERATOR_IS_MULTI_CONFIG>` generators.
+
+Where ``<AUTOGEN_BUILD_DIR>`` is the value of the target property
+:prop_tgt:`AUTOGEN_BUILD_DIR`.
+
+The include directory is automatically added to the target's
+:prop_tgt:`INCLUDE_DIRECTORIES`.
+
+Not included moc output files
+"""""""""""""""""""""""""""""
+
+``moc`` output files that are not included in a source file will be generated
+in
+
+- ``<AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM>``
+ for single configuration generators or in,
+- ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM>``
+ for :prop_gbl:`multi configuration <GENERATOR_IS_MULTI_CONFIG>` generators.
+
+Where ``<SOURCE_DIR_CHECKSUM>`` is a checksum computed from the relative
+parent directory path of the ``moc`` input file. This scheme allows to have
+``moc`` input files with the same name in different directories.
+
+All not included ``moc`` output files will be included automatically by the
+CMake generated file
+
+- ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp``,
+
+which is added to the target's sources.
+
+
+Qt version detection
+^^^^^^^^^^^^^^^^^^^^
+
+:prop_tgt:`AUTOMOC` enabled targets need to know the Qt major and minor
+version they're working with. The major version usually is provided by the
+``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[45]Core`` library,
+that the target links to. To find the minor version, CMake builds a list of
+available Qt versions from
+
+- ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` variables
+ (usually set by ``find_package(Qt5...)``)
+- ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` directory properties
+- ``QT_VERSION_MAJOR`` and ``QT_VERSION_MINOR`` variables
+ (usually set by ``find_package(Qt4...)``)
+- ``QT_VERSION_MAJOR`` and ``QT_VERSION_MINOR`` directory properties
+
+in the context of the :command:`add_executable` or :command:`add_library` call.
+
+Assumed ``INTERFACE_QT_MAJOR_VERSION`` is a valid number, the first
+entry in the list with a matching major version is taken. If no matching major
+version was found, an error is generated.
+If ``INTERFACE_QT_MAJOR_VERSION`` is not a valid number, the first
+entry in the list is taken.
+
+A ``find_package(Qt[45]...)`` call sets the ``QT/Qt5Core_VERSION_MAJOR/MINOR``
+variables. If the call is in a different context than the
+:command:`add_executable` or :command:`add_library` call, e.g. in a function,
+then the version variables might not be available to the :prop_tgt:`AUTOMOC`
+enabled target.
+In that case the version variables can be forwarded from the
+`find_package(Qt[45]...)` calling context to the :command:`add_executable`
+or :command:`add_library` calling context as directory properties.
+The following Qt5 example demonstrates the procedure.
+
+.. code-block:: cmake
+
+ function (add_qt5_client)
+ find_package(Qt5 REQUIRED QUIET COMPONENTS Core Widgets)
+ ...
+ set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+ PROPERTY Qt5Core_VERSION_MAJOR "${Qt5Core_VERSION_MAJOR}")
+ set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+ PROPERTY Qt5Core_VERSION_MINOR "${Qt5Core_VERSION_MAJOR}")
+ ...
+ endfunction ()
+ ...
+ add_qt5_client()
+ add_executable(myTarget main.cpp)
+ target_link_libraries(myTarget Qt5::QtWidgets)
+ set_property(TARGET myTarget PROPERTY AUTOMOC ON)
+
+
+Modifiers
+^^^^^^^^^
+:prop_tgt:`AUTOMOC_EXECUTABLE`:
The ``moc`` executable will be detected automatically, but can be forced to
-a certain binary using the :prop_tgt:`AUTOMOC_EXECUTABLE` property.
+a certain binary using this target property.
-Additional command line options for ``moc`` can be set via the
-:prop_tgt:`AUTOMOC_MOC_OPTIONS` property.
+:prop_tgt:`AUTOMOC_MOC_OPTIONS`:
+Additional command line options for ``moc`` can be set in this target property.
-By enabling the :variable:`CMAKE_AUTOMOC_RELAXED_MODE` variable the
-rules for searching the files which will be processed by ``moc`` can be relaxed.
-See the documentation for this variable for more details.
+:prop_tgt:`AUTOMOC_MACRO_NAMES`:
+This list of Qt macro names can be extended to search for additional macros in
+headers and sources.
-The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the
-automoc targets together in an IDE, e.g. in MSVS.
+:prop_tgt:`AUTOMOC_DEPEND_FILTERS`:
+``moc`` dependency file names can be extracted from headers or sources by
+defining file name filters in this target property.
-The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group
-files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g. in MSVS.
+:prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`:
+Compiler pre definitions for ``moc`` are written to the ``moc_predefs.h`` file.
+The generation of this file can be enabled or disabled in this target property.
-Additional macro names to search for can be added to
-:prop_tgt:`AUTOMOC_MACRO_NAMES`.
+:prop_sf:`SKIP_AUTOMOC`:
+Sources and headers can be excluded from :prop_tgt:`AUTOMOC` processing by
+setting this source file property.
-Additional ``moc`` dependency file names can be extracted from source code
-by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
+:prop_sf:`SKIP_AUTOGEN`:
+Source files can be excluded from :prop_tgt:`AUTOMOC`,
+:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by
+setting this source file property.
-Compiler pre definitions for ``moc`` are written to a ``moc_predefs.h`` file
-which is controlled by :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`.
+:prop_gbl:`AUTOGEN_SOURCE_GROUP`:
+This global property can be used to group files generated by
+:prop_tgt:`AUTOMOC` or :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS.
-Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by
-enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`.
+:prop_gbl:`AUTOGEN_TARGETS_FOLDER`:
+This global property can be used to group :prop_tgt:`AUTOMOC`,
+:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE,
+e.g. in MSVS.
-The number of parallel ``moc`` processes to start can be modified by
-setting :prop_tgt:`AUTOGEN_PARALLEL`.
+:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`:
+A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or
+:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project,
+will be generated when this variable is ``ON``.
-A global ``autogen`` target that depends on all :prop_tgt:`AUTOMOC` generated
-``<ORIGIN>_autogen`` targets in the project can be generated by enabling
-:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`.
+:prop_tgt:`AUTOGEN_PARALLEL`:
+This target property controls the number of ``moc`` or ``uic`` processes to
+start in parallel during builds.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.