Help: Add documentation for AUTOMOC_PATH_PREFIX

Help/manual/cmake-properties.7.rst

@@ -134,6 +134,7 @@ Properties on Targets
    /prop_tgt/AUTOMOC_EXECUTABLE
    /prop_tgt/AUTOMOC_MACRO_NAMES
    /prop_tgt/AUTOMOC_MOC_OPTIONS
+   /prop_tgt/AUTOMOC_PATH_PREFIX
    /prop_tgt/AUTOMOC
    /prop_tgt/AUTOUIC
    /prop_tgt/AUTOUIC_EXECUTABLE

Help/manual/cmake-variables.7.rst

@@ -342,6 +342,7 @@ Variables that Control the Build
    /variable/CMAKE_AUTOMOC_DEPEND_FILTERS
    /variable/CMAKE_AUTOMOC_MACRO_NAMES
    /variable/CMAKE_AUTOMOC_MOC_OPTIONS
+   /variable/CMAKE_AUTOMOC_PATH_PREFIX
    /variable/CMAKE_AUTORCC
    /variable/CMAKE_AUTORCC_OPTIONS
    /variable/CMAKE_AUTOUIC

Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst

@@ -0,0 +1,32 @@
+AUTOMOC_PATH_PREFIX
+-------------------
+
+When this property is ``ON``, CMake will generate the ``-p`` path prefix
+option for ``moc`` on :prop_tgt:`AUTOMOC` enabled Qt targets.
+
+To generate the path prefix, CMake tests if the header compiled by ``moc``
+is in any of the target
+:command:`include directories <target_include_directories>`.  If so, CMake will
+compute the relative path accordingly.  If the header is not in the
+:command:`include directories <target_include_directories>`, CMake will omit
+the ``-p`` path prefix option.  ``moc`` usually generates a
+relative include path in that case.
+
+:prop_tgt:`AUTOMOC_PATH_PREFIX` is initialized from the variable
+:variable:`CMAKE_AUTOMOC_PATH_PREFIX`, which is ``ON`` by default.
+
+See the :manual:`cmake-qt(7)` manual for more information on using CMake
+with Qt.
+
+Reproducible builds
+^^^^^^^^^^^^^^^^^^^
+
+For reproducible builds is is recommended to keep headers that are ``moc``
+compiled in one of the target
+:command:`include directories <target_include_directories>` and set
+:prop_tgt:`AUTOMOC_PATH_PREFIX` to ``ON`` (which is the default).  This ensures
+that
+
+- ``moc`` output files are identical on different build setups,
+- ``moc`` output files will compile correctly when the source and/or
+  build directory is a symbolic link.

Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst

@@ -0,0 +1,11 @@
+CMAKE_AUTOMOC_PATH_PREFIX
+-------------------------
+
+Whether to generate the ``-p`` path prefix option for ``moc`` on
+:prop_tgt:`AUTOMOC` enabled Qt targets.
+
+This variable is used to initialize the :prop_tgt:`AUTOMOC_PATH_PREFIX`
+property on all the targets.  See that target property for additional
+information.
+
+The default value is ``ON``.