Autogen: Doc: Add documentation for (CMAKE_)AUTOMOC_COMPILER_PREDEFINES

Also adds the documentation for CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND.

Closes #17275

6 files changed, 46 insertions, 0 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 0adfff6bf6..dd59a0054e 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -122,6 +122,7 @@ Properties on Targets
    /prop_tgt/ARCHIVE_OUTPUT_NAME
    /prop_tgt/AUTOGEN_BUILD_DIR
    /prop_tgt/AUTOGEN_TARGET_DEPENDS
+   /prop_tgt/AUTOMOC_COMPILER_PREDEFINES
    /prop_tgt/AUTOMOC_DEPEND_FILTERS
    /prop_tgt/AUTOMOC_MACRO_NAMES
    /prop_tgt/AUTOMOC_MOC_OPTIONS
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index cba81e5186..66d3049176 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -270,6 +270,7 @@ Variables that Control the Build
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_AUTOMOC
+   /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES
    /variable/CMAKE_AUTOMOC_DEPEND_FILTERS
    /variable/CMAKE_AUTOMOC_MACRO_NAMES
    /variable/CMAKE_AUTOMOC_MOC_OPTIONS
@@ -398,6 +399,7 @@ Variables for Languages
    /variable/CMAKE_LANG_COMPILER_LOADED
    /variable/CMAKE_LANG_COMPILER_TARGET
    /variable/CMAKE_LANG_COMPILER_VERSION
+   /variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND
    /variable/CMAKE_LANG_COMPILE_OBJECT
    /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY
    /variable/CMAKE_LANG_CREATE_SHARED_MODULE
diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst
index 641ac09aa8..9e5261fd3d 100644
--- a/Help/prop_tgt/AUTOMOC.rst
+++ b/Help/prop_tgt/AUTOMOC.rst
@@ -76,6 +76,9 @@ Additional macro names to search for can be added to :prop_tgt:`AUTOMOC_MACRO_NA
 Additional ``moc`` dependency file names can be extracted from source code
 by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
 
+Compiler pre definitions for ``moc`` are written to a ``moc_predefs.h`` file
+which is controlled by :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`.
+
 Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by
 enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 
diff --git a/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst
new file mode 100644
index 0000000000..57a647f3c4
--- /dev/null
+++ b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst
@@ -0,0 +1,24 @@
+AUTOMOC_COMPILER_PREDEFINES
+---------------------------
+
+Boolean value used by :prop_tgt:`AUTOMOC` to determine if the
+compiler pre definitions file ``moc_predefs.h`` should be generated.
+
+CMake generates a ``moc_predefs.h`` file with compiler pre definitions
+from the output of the command defined in
+:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>`
+when
+
+- :prop_tgt:`AUTOMOC` is enabled,
+- :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is enabled,
+- :variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` isn't empty and
+- the Qt version is greater or equal 5.8.
+
+The ``moc_predefs.h`` file, which is generated in :prop_tgt:`AUTOGEN_BUILD_DIR`,
+is passed to ``moc`` as the argument to the ``--include`` option.
+
+By default :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is initialized from
+:variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES`, which is ON by default.
+
+See the :manual:`cmake-qt(7)` manual for more information on using CMake
+with Qt.
diff --git a/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst
new file mode 100644
index 0000000000..7e1c53d06b
--- /dev/null
+++ b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst
@@ -0,0 +1,8 @@
+CMAKE_AUTOMOC_COMPILER_PREDEFINES
+---------------------------------
+
+This variable is used to initialize the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`
+property on all the targets. See that target property for additional
+information.
+
+By default it is ON.
diff --git a/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst
new file mode 100644
index 0000000000..e050f43e63
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst
@@ -0,0 +1,8 @@
+CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND
+----------------------------------------
+
+Command that outputs the compiler pre definitions.
+
+See :prop_tgt:`AUTOMOC` which uses
+:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>`
+to generate the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`.