# 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 `qt4_wrap_cpp()`, qt5_wrap_cpp(), etc. Currently, Qt versions 4 to 6 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_extension>`) and

  - a private header with the same base name and a `_p` suffix (`<source_base>_p.<header_extension>`)

  and adds these to the scan list.

- The `AUTOMOC_INCLUDE_DIRECTORIES` target property may be set to explicitly tell `moc` what include directories to search. If not set, the default is to use the include directories from the target and its transitive closure of dependencies.

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

- a Qt macro from `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 `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

    #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[456]Core` library, that the target links to. To find the minor version, CMake builds a list of available Qt versions from

- `Qt6Core_VERSION_MAJOR` and `Qt6Core_VERSION_MINOR` variables (usually set by `find_package(Qt6...)`)

- `Qt6Core_VERSION_MAJOR` and `Qt6Core_VERSION_MINOR` directory properties

- `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[456]...)` call sets the `QT/Qt[56]Core_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[456]...)` 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.

`AUTOMOC_INCLUDE_DIRECTORIES`: Specifies one or more include directories for `AUTOMOC` to pass explicitly to `moc` instead of automatically discovering a target's include directories.

`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.

`AUTOGEN_COMMAND_LINE_LENGTH_MAX`: This target property controls the limit when to use response files for `moc` or `uic` processes on Windows.

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