Merge topic 'autogen_path_prefix'

cc0900d9cd Help: Add release notes for AUTOMOC_PATH_PREFIX
692d8e3492 Help: Add documentation for AUTOMOC_PATH_PREFIX
1933ade9f1 Tests: At QtAutogen.MocIncludeSymlink test
706d9738a6 Tests: Merge QtAutogen.MocIncludeStrict and MocIncludeRelaxed
d018d27c10 Autogen: Add moc path prefix generation (AUTOMOC_PATH_PREFIX)
77983c8147 Autogen: Add IsHeader flag to SourceFileT class
f9e5441eb4 Autogen: Abbreviate file paths in messages
51676cf655 Autogen: Split JobEvalCacheT job into separate moc and uic jobs
...

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !3818

1 files changed, 32 insertions, 0 deletions

diff --git a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst
new file mode 100644
index 0000000..e2ebb3f
--- /dev/null
+++ b/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.