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 fora regular header with the same base name (
<source_base>.<header_extention>) anda private header with the same base name and a
_psuffix (<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
FILEargument of aQ_PLUGIN_METADATAmacro andadditional 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
mocfiles (see Including header moc files in sources),additional file dependencies from the
FILEargument of aQ_PLUGIN_METADATAmacro andadditional 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>/includefor single configuration generators or in<AUTOGEN_BUILD_DIR>/include_<CONFIG>formulti configurationgenerators.
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>formulti configurationgenerators.
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¶
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_MAJORandQt5Core_VERSION_MINORvariables (usually set byfind_package(Qt5...))Qt5Core_VERSION_MAJORandQt5Core_VERSION_MINORdirectory propertiesQT_VERSION_MAJORandQT_VERSION_MINORvariables (usually set byfind_package(Qt4...))QT_VERSION_MAJORandQT_VERSION_MINORdirectory 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.