From 7114c141e27532df709fcae1266bb4ce9b6e850c Mon Sep 17 00:00:00 2001 From: Cristian Adam Date: Fri, 26 Jul 2019 16:08:32 +0200 Subject: Unity build: Add support for Ninja and Makefile generators --- Help/manual/cmake-properties.7.rst | 5 +++ Help/manual/cmake-variables.7.rst | 2 + Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst | 7 +++ Help/prop_tgt/UNITY_BUILD.rst | 55 +++++++++++++++++++++++ Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst | 13 ++++++ Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst | 8 ++++ Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst | 8 ++++ Help/release/dev/unity-build.rst | 6 +++ Help/variable/CMAKE_UNITY_BUILD.rst | 6 +++ Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst | 6 +++ 10 files changed, 116 insertions(+) create mode 100644 Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst create mode 100644 Help/prop_tgt/UNITY_BUILD.rst create mode 100644 Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst create mode 100644 Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst create mode 100644 Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst create mode 100644 Help/release/dev/unity-build.rst create mode 100644 Help/variable/CMAKE_UNITY_BUILD.rst create mode 100644 Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst (limited to 'Help') diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 25d6b247da..19afb7d57d 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -323,6 +323,10 @@ Properties on Targets /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME /prop_tgt/TYPE + /prop_tgt/UNITY_BUILD + /prop_tgt/UNITY_BUILD_BATCH_SIZE + /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE + /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE @@ -450,6 +454,7 @@ Properties on Source Files /prop_sf/SKIP_AUTORCC /prop_sf/SKIP_AUTOUIC /prop_sf/SKIP_PRECOMPILE_HEADERS + /prop_sf/SKIP_UNITY_BUILD_INCLUSION /prop_sf/Swift_DEPENDENCIES_FILE /prop_sf/Swift_DIAGNOSTICS_FILE /prop_sf/SYMBOLIC diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 0ae1ebe1de..739e4b5ffd 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -431,6 +431,8 @@ Variables that Control the Build /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE + /variable/CMAKE_UNITY_BUILD + /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_GLOBALS diff --git a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst new file mode 100644 index 0000000000..53f3970256 --- /dev/null +++ b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst @@ -0,0 +1,7 @@ +SKIP_UNITY_BUILD_INCLUSION +-------------------------- + +Is this source file skipped by :prop_tgt:`UNITY_BUILD` feature. + +This property helps with "ODR (One definition rule)" problems +that one would run into when using an :prop_tgt:`UNITY_BUILD`. diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst new file mode 100644 index 0000000000..d326ee2466 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -0,0 +1,55 @@ +UNITY_BUILD +----------- + +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. + +This property is initialized by the value of the +:variable:`CMAKE_UNITY_BUILD` variable if it is set when +a target is created. + +.. 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. + +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`. + + +ODR (One definition rule) errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since multiple source files are included into one source file, +it can lead to ODR errors. This section contains properites +which help fixing these errors. + +The source files marked by :prop_sf:`GENERATED` will be skipped +from unity build. This applies also for the source files marked +with :prop_sf:`SKIP_UNITY_BUILD_INCLUSION`. + +The source files that have :prop_sf:`COMPILE_OPTIONS`, +:prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or +:prop_sf:`INCLUDE_DIRECTORIES` will also be skipped. + +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. + +.. 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`. diff --git a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst new file mode 100644 index 0000000000..24266894b9 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,13 @@ +UNITY_BUILD_BATCH_SIZE +---------------------- + +Specifies how many source code files will be included into a +:prop_tgt:`UNITY_BUILD` source file. + +If the property is not set, CMake will use the value provided +by :variable:`CMAKE_UNITY_BUILD_BATCH_SIZE`. + +By setting it to value `0` the generated unity source file will +contain all the source files that would be otherwise be split +into multiple batches. It is not recommended to do so, since it +would affect performance. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst new file mode 100644 index 0000000000..779528902f --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst @@ -0,0 +1,8 @@ +UNITY_BUILD_CODE_AFTER_INCLUDE +------------------------------ + +Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` +feature just after the `#include` statement of the targeted source +files. + +This could be something like `#undef NOMINMAX`. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst new file mode 100644 index 0000000000..f33546328a --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst @@ -0,0 +1,8 @@ +UNITY_BUILD_CODE_BEFORE_INCLUDE +------------------------------- + +Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` +feature just before the `#include` statement of the targeted source +files. + +This could be something like `#define NOMINMAX`. diff --git a/Help/release/dev/unity-build.rst b/Help/release/dev/unity-build.rst new file mode 100644 index 0000000000..293a3754d2 --- /dev/null +++ b/Help/release/dev/unity-build.rst @@ -0,0 +1,6 @@ +Unity build +----------- + +* The :prop_tgt:`UNITY_BUILD` target property was added to tell + generators to batch include source files for faster compilation + times. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst new file mode 100644 index 0000000000..3096954c20 --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -0,0 +1,6 @@ +CMAKE_UNITY_BUILD +----------------- + +Default value for :prop_tgt:`UNITY_BUILD` of targets. + +By default ``CMAKE_UNITY_BUILD`` is ``OFF``. diff --git a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst new file mode 100644 index 0000000000..3ab2344caa --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,6 @@ +CMAKE_UNITY_BUILD_BATCH_SIZE +---------------------------- + +Default value for :prop_tgt:`UNITY_BUILD_BATCH_SIZE` of targets. + +By default ``CMAKE_UNITY_BUILD_BATCH_SIZE`` is set to ``8``. -- cgit v1.2.1