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 the QT4_WRAP_CPP() or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are supported.

This property is initialized by the value of the 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.

Header file processing

At configuration time, a list of header files that should be scanned by AUTOMOC is computed from the target's sources.

  • 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

    • 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>)

    and adds these to the scan list.

At build time, CMake scans each unknown or modified header file from the list and searches for

  • a Qt macro from 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 AUTOMOC_DEPEND_FILTERS.

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.

The header will be moc compiled again if a file from the additional file dependencies changes.

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

If a Qt macro is found, then the C++ source file <base>.<source_extension> is expected to as well contain an include statement

#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

#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 multi configuration generators.

Where <AUTOGEN_BUILD_DIR> is the value of the target property AUTOGEN_BUILD_DIR.

The include directory is automatically added to the target's 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 multi configuration 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, or

  • <AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp,

which is added to the target's sources.

Qt version detection

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 add_executable() or 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 add_executable() or add_library() call, e.g. in a function, then the version variables might not be available to the AUTOMOC enabled target. In that case the version variables can be forwarded from the find_package(Qt[45]...) calling context to the add_executable() or add_library() calling context as directory properties. The following Qt5 example demonstrates the procedure.

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

AUTOMOC_EXECUTABLE: The moc executable will be detected automatically, but can be forced to a certain binary using this target property.

AUTOMOC_MOC_OPTIONS: Additional command line options for moc can be set in this target property.

AUTOMOC_MACRO_NAMES: This list of Qt macro names can be extended to search for additional macros in headers and sources.

AUTOMOC_DEPEND_FILTERS: moc dependency file names can be extracted from headers or sources by defining file name filters in this target property.

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.

SKIP_AUTOMOC: Sources and headers can be excluded from AUTOMOC processing by setting this source file property.

SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and AUTORCC processing by setting this source file property.

AUTOGEN_SOURCE_GROUP: This global property can be used to group files generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.

AUTOGEN_TARGETS_FOLDER: This global property can be used to group AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.

CMAKE_GLOBAL_AUTOGEN_TARGET: A global autogen target, that depends on all AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the project, will be generated when this variable is ON.

AUTOGEN_PARALLEL: This target property controls the number of moc or uic processes to start in parallel during builds.

See the cmake-qt(7) manual for more information on using CMake with Qt.