From 8aac65a3614646073904b41baa4a57e5db28fcec Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Oct 2019 07:54:59 -0400 Subject: Help: Document CMAKE_UNITY_BUILD in 3.16 release notes --- Help/release/3.16.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index a14effe..7992f2d 100644 --- a/Help/release/3.16.rst +++ b/Help/release/3.16.rst @@ -115,6 +115,10 @@ Variables specify the resource encoding for the the :generator:`Eclipse CDT4` extra generator. +* The :variable:`CMAKE_UNITY_BUILD` variable was added to initialize the + :prop_tgt:`UNITY_BUILD` target property to tell generators to batch + include source files for faster compilation times. + Properties ---------- -- cgit v0.12 From 1d9155eb9351120eadfa7d6386d0625b076d4be2 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Oct 2019 08:01:35 -0400 Subject: Help: Improve UNITY_BUILD documentation formatting --- Help/prop_tgt/UNITY_BUILD.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst index beac5d4..1e68dcd 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -5,26 +5,26 @@ Should the target source files be processed into batches for faster compilation. This feature is known as "Unity build", or "Jumbo build". -The `C` and `CXX` source files are grouped separately. +The ``C`` and ``CXX`` source files are grouped separately. This property is initialized by the value of the :variable:`CMAKE_UNITY_BUILD` variable if it is set when a target is created. -.. note :: +.. note:: - It's not recommended to directly set :prop_tgt:`UNITY_BUILD` - to `ON`, but to instead set :variable:`CMAKE_UNITY_BUILD` from - the command line. However, it IS recommended to set - :prop_tgt:`UNITY_BUILD` to `OFF` if you need to ensure that a - target doesn't get a unity build. + It's not recommended to directly set :prop_tgt:`UNITY_BUILD` + to ``ON``, but to instead set :variable:`CMAKE_UNITY_BUILD` from + the command line. However, it IS recommended to set + :prop_tgt:`UNITY_BUILD` to ``OFF`` if you need to ensure that a + target doesn't get a unity build. The batch size can be specified by setting :prop_tgt:`UNITY_BUILD_BATCH_SIZE`. The batching of source files is done by adding new sources files -wich will `#include` the source files, and exclude them from -building by setting :prop_sf:`HEADER_FILE_ONLY` to `ON`. +which will ``#include`` the source files, and exclude them from +building by setting :prop_sf:`HEADER_FILE_ONLY` to ``ON``. ODR (One definition rule) errors @@ -45,11 +45,11 @@ The source files that have :prop_sf:`COMPILE_OPTIONS`, With the :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` one can specify code to be injected in the unity source file before and after every -`#include` statement. +``#include`` statement. -.. note :: +.. note:: - The order of source files defined in the `CMakeLists.txt` will - be preserved into the generated unity source files. This can - be used to manually enforce a specific grouping based on the - :prop_tgt:`UNITY_BUILD_BATCH_SIZE`. + The order of source files defined in the ``CMakeLists.txt`` will + be preserved into the generated unity source files. This can + be used to manually enforce a specific grouping based on the + :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property. -- cgit v0.12 From ed06d27c7f0503a7d0d32d352d2e31bd4b82070e Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Oct 2019 08:05:29 -0400 Subject: Help: Extend documentation of CMAKE_UNITY_BUILD variable --- Help/variable/CMAKE_UNITY_BUILD.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst index 3096954..b653881 100644 --- a/Help/variable/CMAKE_UNITY_BUILD.rst +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -1,6 +1,8 @@ CMAKE_UNITY_BUILD ----------------- -Default value for :prop_tgt:`UNITY_BUILD` of targets. - -By default ``CMAKE_UNITY_BUILD`` is ``OFF``. +Initializes the :prop_tgt:`UNITY_BUILD` target property on targets +as they are created. Set to ``ON`` to batch compilation of multiple +sources within each target. This feature is known as "Unity build", +or "Jumbo build". By default this variable is not set and so does +not enable unity builds on targets. -- cgit v0.12 From 13c8dbd5a6bede4f3455203958238165437396e9 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Oct 2019 08:05:59 -0400 Subject: Help: Document CMAKE_UNITY_BUILD/CMAKE_EXPORT_COMPILE_COMMANDS limitation These two options currently do not work well together. Mention this limitation in the documentation. Issue: #19826 --- Help/prop_tgt/UNITY_BUILD.rst | 6 ++++++ Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst | 4 ++++ Help/variable/CMAKE_UNITY_BUILD.rst | 4 ++++ 3 files changed, 14 insertions(+) diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst index 1e68dcd..2faad92 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -26,6 +26,12 @@ The batching of source files is done by adding new sources files which will ``#include`` the source files, and exclude them from building by setting :prop_sf:`HEADER_FILE_ONLY` to ``ON``. +.. note:: + + Marking the original sources with :prop_sf:`HEADER_FILE_ONLY` + is considered an implementation detail that may change in the + future because it does not work well in combination with + the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable. ODR (One definition rule) errors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 8776279..4548abc 100644 --- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -28,3 +28,7 @@ form. The format of the JSON file looks like: .. note:: This option is implemented only by :ref:`Makefile Generators` and the :generator:`Ninja`. It is ignored on other generators. + + This option currently does not work well in combination with + the :prop_tgt:`UNITY_BUILD` target property or the + :variable:`CMAKE_UNITY_BUILD` variable. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst index b653881..bbcfd68 100644 --- a/Help/variable/CMAKE_UNITY_BUILD.rst +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -6,3 +6,7 @@ as they are created. Set to ``ON`` to batch compilation of multiple sources within each target. This feature is known as "Unity build", or "Jumbo build". By default this variable is not set and so does not enable unity builds on targets. + +.. note:: + This option currently does not work well in combination with + the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable. -- cgit v0.12