diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index 56d4ca7935..e9da396390 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -63,20 +63,24 @@ If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` will be run on the file. The result will be put into a file named according to ``moc_.cpp``. If the macro is found in a C++ implementation file, the moc output will be put into a file named according to -``.moc``, following the Qt conventions. The ``moc file`` may be -included by the user in the C++ implementation file with a preprocessor -``#include``. If it is not so included, it will be added to a separate file -which is compiled into the target. +``.moc``, following the Qt conventions. The ``.moc`` must +be included by the user in the C++ implementation file with a preprocessor +``#include``. + +Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the +``/_autogen/include`` directory which is +automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. +(This differs from CMake 3.7 and below; see their documentation for details.) + +Not included ``moc_.cpp`` files will be generated in custom +folders to avoid name collisions and included in a separate +``/_autogen/moc_compilation.cpp`` +file which is compiled into the target. The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being invoked for, and for the appropriate build configuration. -The generated ``moc_*.cpp`` and ``*.moc`` files are placed in the -``/_autogen/include`` directory which is -automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. -(This differs from CMake 3.7 and below; see their documentation for details.) - The :prop_tgt:`AUTOMOC` target property may be pre-set for all following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The :prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index b42643fef0..4ac9b6e083 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -8,31 +8,41 @@ preprocessor automatically, i.e. without having to use the :module:`QT4_WRAP_CPP() ` or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are supported. -When this property is set ``ON``, CMake will scan the +When this property is set ``ON``, CMake will scan the header and source files at build time and invoke moc accordingly. -* If an ``#include`` statement like ``#include "moc_foo.cpp"`` is found, - the ``Q_OBJECT`` class declaration is expected in the header, and - ``moc`` is run on the header file. A ``moc_foo.cpp`` file will be - generated from the source's header into the - ``/_autogen/include`` - directory which is automatically added to the target's +* If an ``#include`` statement like ``#include "moc_.cpp"`` is found, + the ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in an otherwise empty + line of the ``.h(xx)`` header file. ``moc`` is run on the header file to + generate ``moc_.cpp`` in the + ``/_autogen/include`` directory + which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. This allows the compiler to find the - included ``moc_foo.cpp`` file regardless of the location the original source. - However, if multiple source files in different directories do this then their - generated moc files would collide. In this case a diagnostic will be issued. + included ``moc_.cpp`` file regardless of the location the + original source. -* If an ``#include`` statement like ``#include "foo.moc"`` is found, - then a ``Q_OBJECT`` is expected in the current source file and ``moc`` - is run on the file itself. Additionally, header files with the same - base name (like ``foo.h``) or ``_p`` appended to the base name (like - ``foo_p.h``) are parsed for ``Q_OBJECT`` macros, and if found, ``moc`` - is also executed on those files. ``AUTOMOC`` checks multiple header - alternative extensions, such as ``hpp``, ``hxx`` etc when searching - for headers. The resulting moc files, which are not included as shown - above in any of the source files are included in a generated - ``moc_compilation.cpp`` file, which is compiled as part of the - target. +* If an ``#include`` statement like ``#include ".moc"`` is found, + then ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in the current source + file and ``moc`` is run on the source file itself. + +* Header files that are not included by an ``#include "moc_.cpp"`` + statement are nonetheless scanned for ``Q_OBJECT`` or ``Q_GADGET`` macros. + The resulting ``moc_.cpp`` files are generated in custom + directories and automatically included in the generated + ``/_autogen/moc_compilation.cpp`` file, + which is compiled as part of the target. The custom directories help to + avoid name collisions for moc files with the same ````. + +* Additionally, header files with the same base name as a source file, + (like ``.h``) or ``_p`` appended to the base name (like + ``_p.h``), are parsed for ``Q_OBJECT`` or ``Q_GADGET`` macros, + and if found, ``moc`` is also executed on those files. + +* ``AUTOMOC`` always checks multiple header alternative extensions, + such as ``hpp``, ``hxx``, etc. when searching for headers. + +* ``AUTOMOC`` looks for the ``Q_PLUGIN_METADATA`` macro and reruns the + ``moc`` when the file addressed by the ``FILE`` argument of the macro changes. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created.