diff options
| -rw-r--r-- | Help/prop_tgt/UNITY_BUILD.rst | 36 | ||||
| -rw-r--r-- | Help/release/3.16.rst | 4 | ||||
| -rw-r--r-- | Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst | 4 | ||||
| -rw-r--r-- | Help/variable/CMAKE_UNITY_BUILD.rst | 10 |
4 files changed, 37 insertions, 17 deletions
diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst index beac5d4..2faad92 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -5,27 +5,33 @@ 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``. +.. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -45,11 +51,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. 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 ---------- 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 3096954..bbcfd68 100644 --- a/Help/variable/CMAKE_UNITY_BUILD.rst +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -1,6 +1,12 @@ CMAKE_UNITY_BUILD ----------------- -Default value for :prop_tgt:`UNITY_BUILD` of targets. +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. -By default ``CMAKE_UNITY_BUILD`` is ``OFF``. +.. note:: + This option currently does not work well in combination with + the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable. |