1AUTOMOC 2------- 3 4Should the target be processed with auto-moc (for Qt projects). 5 6:prop_tgt:`AUTOMOC` is a boolean specifying whether CMake will handle the Qt 7``moc`` preprocessor automatically, i.e. without having to use commands like 8:module:`QT4_WRAP_CPP() <FindQt4>`, ``QT5_WRAP_CPP()``, etc. 9Currently, Qt versions 4 to 6 are supported. 10 11This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` 12variable if it is set when a target is created. 13 14When this property is set ``ON``, CMake will scan the header and 15source files at build time and invoke ``moc`` accordingly. 16 17 18Header file processing 19^^^^^^^^^^^^^^^^^^^^^^ 20 21At configuration time, a list of header files that should be scanned by 22:prop_tgt:`AUTOMOC` is computed from the target's sources. 23 24- All header files in the target's sources are added to the scan list. 25- For all C++ source files ``<source_base>.<source_extension>`` in the 26 target's sources, CMake searches for 27 28 - a regular header with the same base name 29 (``<source_base>.<header_extention>``) and 30 - a private header with the same base name and a ``_p`` suffix 31 (``<source_base>_p.<header_extention>``) 32 33 and adds these to the scan list. 34 35At build time, CMake scans each unknown or modified header file from the 36list and searches for 37 38- a Qt macro from :prop_tgt:`AUTOMOC_MACRO_NAMES`, 39- additional file dependencies from the ``FILE`` argument of a 40 ``Q_PLUGIN_METADATA`` macro and 41- additional file dependencies detected by filters defined in 42 :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. 43 44If a Qt macro is found, then the header will be compiled by the ``moc`` to the 45output file ``moc_<base_name>.cpp``. The complete output file path is 46described in the section `Output file location`_. 47 48The header will be ``moc`` compiled again if a file from the additional file 49dependencies changes. 50 51Header ``moc`` output files ``moc_<base_name>.cpp`` can be included in source 52files. In the section `Including header moc files in sources`_ there is more 53information on that topic. 54 55 56Source file processing 57^^^^^^^^^^^^^^^^^^^^^^ 58 59At build time, CMake scans each unknown or modified C++ source file from the 60target's sources for 61 62- a Qt macro from :prop_tgt:`AUTOMOC_MACRO_NAMES`, 63- includes of header ``moc`` files 64 (see `Including header moc files in sources`_), 65- additional file dependencies from the ``FILE`` argument of a 66 ``Q_PLUGIN_METADATA`` macro and 67- additional file dependencies detected by filters defined in 68 :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. 69 70If a Qt macro is found, then the C++ source file 71``<base>.<source_extension>`` is expected to as well contain an include 72statement 73 74.. code-block:: c++ 75 76 #include <<base>.moc> // or 77 #include "<base>.moc" 78 79The source file then will be compiled by the ``moc`` to the output file 80``<base>.moc``. A description of the complete output file path is in section 81`Output file location`_. 82 83The source will be ``moc`` compiled again if a file from the additional file 84dependencies changes. 85 86Including header moc files in sources 87""""""""""""""""""""""""""""""""""""" 88 89A source file can include the ``moc`` output file of a header 90``<header_base>.<header_extension>`` by using an include statement of 91the form 92 93.. code-block:: c++ 94 95 #include <moc_<header_base>.cpp> // or 96 #include "moc_<header_base>.cpp" 97 98If the ``moc`` output file of a header is included by a source, it will 99be generated in a different location than if it was not included. This is 100described in the section `Output file location`_. 101 102 103Output file location 104^^^^^^^^^^^^^^^^^^^^ 105 106Included moc output files 107""""""""""""""""""""""""" 108 109``moc`` output files that are included by a source file will be generated in 110 111- ``<AUTOGEN_BUILD_DIR>/include`` 112 for single configuration generators or in 113- ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` 114 for :prop_gbl:`multi configuration <GENERATOR_IS_MULTI_CONFIG>` generators. 115 116Where ``<AUTOGEN_BUILD_DIR>`` is the value of the target property 117:prop_tgt:`AUTOGEN_BUILD_DIR`. 118 119The include directory is automatically added to the target's 120:prop_tgt:`INCLUDE_DIRECTORIES`. 121 122Not included moc output files 123""""""""""""""""""""""""""""" 124 125``moc`` output files that are not included in a source file will be generated 126in 127 128- ``<AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM>`` 129 for single configuration generators or in, 130- ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM>`` 131 for :prop_gbl:`multi configuration <GENERATOR_IS_MULTI_CONFIG>` generators. 132 133Where ``<SOURCE_DIR_CHECKSUM>`` is a checksum computed from the relative 134parent directory path of the ``moc`` input file. This scheme allows to have 135``moc`` input files with the same name in different directories. 136 137All not included ``moc`` output files will be included automatically by the 138CMake generated file 139 140- ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp``, or 141- ``<AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp``, 142 143which is added to the target's sources. 144 145 146Qt version detection 147^^^^^^^^^^^^^^^^^^^^ 148 149:prop_tgt:`AUTOMOC` enabled targets need to know the Qt major and minor 150version they're working with. The major version usually is provided by the 151``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[456]Core`` library, 152that the target links to. To find the minor version, CMake builds a list of 153available Qt versions from 154 155- ``Qt6Core_VERSION_MAJOR`` and ``Qt6Core_VERSION_MINOR`` variables 156 (usually set by ``find_package(Qt6...)``) 157- ``Qt6Core_VERSION_MAJOR`` and ``Qt6Core_VERSION_MINOR`` directory properties 158- ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` variables 159 (usually set by ``find_package(Qt5...)``) 160- ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` directory properties 161- ``QT_VERSION_MAJOR`` and ``QT_VERSION_MINOR`` variables 162 (usually set by ``find_package(Qt4...)``) 163- ``QT_VERSION_MAJOR`` and ``QT_VERSION_MINOR`` directory properties 164 165in the context of the :command:`add_executable` or :command:`add_library` call. 166 167Assumed ``INTERFACE_QT_MAJOR_VERSION`` is a valid number, the first 168entry in the list with a matching major version is taken. If no matching major 169version was found, an error is generated. 170If ``INTERFACE_QT_MAJOR_VERSION`` is not a valid number, the first 171entry in the list is taken. 172 173A ``find_package(Qt[456]...)`` call sets the ``QT/Qt[56]Core_VERSION_MAJOR/MINOR`` 174variables. If the call is in a different context than the 175:command:`add_executable` or :command:`add_library` call, e.g. in a function, 176then the version variables might not be available to the :prop_tgt:`AUTOMOC` 177enabled target. 178In that case the version variables can be forwarded from the 179``find_package(Qt[456]...)`` calling context to the :command:`add_executable` 180or :command:`add_library` calling context as directory properties. 181The following Qt5 example demonstrates the procedure. 182 183.. code-block:: cmake 184 185 function (add_qt5_client) 186 find_package(Qt5 REQUIRED QUIET COMPONENTS Core Widgets) 187 ... 188 set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" 189 PROPERTY Qt5Core_VERSION_MAJOR "${Qt5Core_VERSION_MAJOR}") 190 set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" 191 PROPERTY Qt5Core_VERSION_MINOR "${Qt5Core_VERSION_MAJOR}") 192 ... 193 endfunction () 194 ... 195 add_qt5_client() 196 add_executable(myTarget main.cpp) 197 target_link_libraries(myTarget Qt5::QtWidgets) 198 set_property(TARGET myTarget PROPERTY AUTOMOC ON) 199 200 201Modifiers 202^^^^^^^^^ 203 204:prop_tgt:`AUTOMOC_EXECUTABLE`: 205The ``moc`` executable will be detected automatically, but can be forced to 206a certain binary using this target property. 207 208:prop_tgt:`AUTOMOC_MOC_OPTIONS`: 209Additional command line options for ``moc`` can be set in this target property. 210 211:prop_tgt:`AUTOMOC_MACRO_NAMES`: 212This list of Qt macro names can be extended to search for additional macros in 213headers and sources. 214 215:prop_tgt:`AUTOMOC_DEPEND_FILTERS`: 216``moc`` dependency file names can be extracted from headers or sources by 217defining file name filters in this target property. 218 219:prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`: 220Compiler pre definitions for ``moc`` are written to the ``moc_predefs.h`` file. 221The generation of this file can be enabled or disabled in this target property. 222 223:prop_sf:`SKIP_AUTOMOC`: 224Sources and headers can be excluded from :prop_tgt:`AUTOMOC` processing by 225setting this source file property. 226 227:prop_sf:`SKIP_AUTOGEN`: 228Source files can be excluded from :prop_tgt:`AUTOMOC`, 229:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by 230setting this source file property. 231 232:prop_gbl:`AUTOGEN_SOURCE_GROUP`: 233This global property can be used to group files generated by 234:prop_tgt:`AUTOMOC` or :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. 235 236:prop_gbl:`AUTOGEN_TARGETS_FOLDER`: 237This global property can be used to group :prop_tgt:`AUTOMOC`, 238:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE, 239e.g. in MSVS. 240 241:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: 242A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or 243:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project, 244will be generated when this variable is ``ON``. 245 246:prop_tgt:`AUTOGEN_PARALLEL`: 247This target property controls the number of ``moc`` or ``uic`` processes to 248start in parallel during builds. 249 250See the :manual:`cmake-qt(7)` manual for more information on using CMake 251with Qt. 252