diff options
Diffstat (limited to 'Help')
22 files changed, 185 insertions, 11 deletions
diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index b288aad..d455f4b 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -9,6 +9,7 @@ different formats: - TGZ (.tar.gz) - TXZ (.tar.xz) - TZ (.tar.Z) + - TZST (.tar.zst) - ZIP (.zip) Variables specific to CPack Archive generator diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 25d6b24..19afb7d 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 0ae1ebe..2d473d8 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -112,6 +112,7 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT /variable/CMAKE_VS_PLATFORM_TOOLSET /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA + /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION @@ -431,6 +432,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/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 26ef904..2576cde 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -462,7 +462,7 @@ Available commands are: but the files or directories it point to. ``copy_directory <dir>... <destination>`` - Copy directories to ``<destination>`` directory. + Copy content of ``<dir>...`` directories to ``<destination>`` directory. If ``<destination>`` directory does not exist it will be created. ``copy_directory`` does follow symlinks. @@ -536,7 +536,8 @@ Available commands are: ``remove_directory <dir>...`` Remove ``<dir>`` directories and their contents. If a directory does - not exist it will be silently ignored. + not exist it will be silently ignored. If ``<dir>`` is a symlink to + a directory, just the symlink will be removed. ``rename <oldname> <newname>`` Rename a file or directory (on one volume). If file with the ``<newname>`` name diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 10f617e..f82c466 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -48,9 +48,11 @@ Options the :variable:`CPACK_GENERATOR` variable determines the default set of generators that will be used. -``-C <Configuration>`` - Specify the project configuration to be packaged (e.g. ``Debug``, - ``Release``, etc.). When the CMake project uses a multi-configuration +``-C <configs>`` + Specify the project configuration(s) to be packaged (e.g. ``Debug``, + ``Release``, etc.), where ``<configs>`` is a + :ref:`semicolon-separated list <CMake Language Lists>`. + When the CMake project uses a multi-configuration generator such as Xcode or Visual Studio, this option is needed to tell ``cpack`` which built executables to include in the package. 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 0000000..53f3970 --- /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 0000000..d326ee2 --- /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 0000000..2426689 --- /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 0000000..7795289 --- /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 0000000..f335463 --- /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/FindPkgConfig-module-name.rst b/Help/release/dev/FindPkgConfig-module-name.rst new file mode 100644 index 0000000..9f1cd36 --- /dev/null +++ b/Help/release/dev/FindPkgConfig-module-name.rst @@ -0,0 +1,6 @@ +FindPkgConfig-module-name +------------------------- + +* The :module:`FindPkgConfig` module :command:`pkg_search_module` macro + now defines a ``<prefix>_MODULE_NAME`` result variable containing the + first matching module name. diff --git a/Help/release/dev/FindPython-specify_artifacts.rst b/Help/release/dev/FindPython-specify_artifacts.rst new file mode 100644 index 0000000..7032f8b --- /dev/null +++ b/Help/release/dev/FindPython-specify_artifacts.rst @@ -0,0 +1,5 @@ +FindPython-specify_artifacts +---------------------------- + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + gain the capability to specify directly artifacts. diff --git a/Help/release/dev/cpack-install-multiple-configurations.rst b/Help/release/dev/cpack-install-multiple-configurations.rst new file mode 100644 index 0000000..d1692dc --- /dev/null +++ b/Help/release/dev/cpack-install-multiple-configurations.rst @@ -0,0 +1,5 @@ +cpack-install-multiple-configurations +------------------------------------- + +* CPack learned :variable:`CPACK_INSTALL_CMAKE_CONFIGURATIONS` to control + what configurations going to be packaged for multi-configuration generators. diff --git a/Help/release/dev/cpack-zstd.rst b/Help/release/dev/cpack-zstd.rst new file mode 100644 index 0000000..e1e64a2 --- /dev/null +++ b/Help/release/dev/cpack-zstd.rst @@ -0,0 +1,5 @@ +cpack-zstd +---------- + +* The :cpack_gen:`CPack Archive Generator` learned to generate `.tar.zst` + packages with Zstandard compression. diff --git a/Help/release/dev/gtest-1.8.1.rst b/Help/release/dev/gtest-1.8.1.rst new file mode 100644 index 0000000..2e48da4 --- /dev/null +++ b/Help/release/dev/gtest-1.8.1.rst @@ -0,0 +1,5 @@ +gtest-1.8.1 +----------- + +* The :module:`FindGTest` module has been updated to recognize + MSVC build trees generated by GTest 1.8.1. diff --git a/Help/release/dev/remove_directory-symlink.rst b/Help/release/dev/remove_directory-symlink.rst new file mode 100644 index 0000000..0896388 --- /dev/null +++ b/Help/release/dev/remove_directory-symlink.rst @@ -0,0 +1,6 @@ +remove_directory-symlink +------------------------ + +* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool, + when given the path to a symlink to a directory, now removes just + the symlink. It no longer removes content of the linked directory. diff --git a/Help/release/dev/unity-build.rst b/Help/release/dev/unity-build.rst new file mode 100644 index 0000000..293a375 --- /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_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index a01a8b7..222824f 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -40,10 +40,13 @@ The ``key=value`` pairs form a comma-separated list of options to specify generator-specific details of the toolset selection. Supported pairs are: -``cuda=<version>`` - Specify the CUDA toolkit version to use. Supported by VS 2010 - and above with the CUDA toolkit VS integration installed. - See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` variable. +``cuda=<version>|<path>`` + Specify the CUDA toolkit version to use or the path to a + standalone CUDA toolkit directory. Supported by VS 2010 + and above. The version can only be used with the CUDA + toolkit VS integration globally installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` and + :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR` variables. ``host=<arch>`` Specify the host tools architecture as ``x64`` or ``x86``. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst new file mode 100644 index 0000000..3096954 --- /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 0000000..3ab2344 --- /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``. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst index 1604a76..67b7f74 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst @@ -6,7 +6,9 @@ NVIDIA CUDA Toolkit version whose Visual Studio toolset to use. The :ref:`Visual Studio Generators` for VS 2010 and above support using a CUDA toolset provided by a CUDA Toolkit. The toolset version number may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of -the form ``cuda=8.0``. If none is specified CMake will choose a default -version. CMake provides the selected CUDA toolset version in this variable. +the form ``cuda=8.0``. Or it is automatically detected if a path to +a standalone CUDA directory is specified in the form ``cuda=C:\path\to\cuda``. +If none is specified CMake will choose a default version. +CMake provides the selected CUDA toolset version in this variable. The value may be empty if no CUDA Toolkit with Visual Studio integration is installed. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst new file mode 100644 index 0000000..060648a --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst @@ -0,0 +1,16 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR +----------------------------------------- + +Path to standalone NVIDIA CUDA Toolkit (eg. extracted from installer). + +The :ref:`Visual Studio Generators` for VS 2010 and above support using +a standalone (non-installed) NVIDIA CUDA toolkit. The path +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``cuda=C:\path\to\cuda``. The given directory must at least +contain a folder ``.\nvcc`` and must provide Visual Studio integration +files in path ``.\CUDAVisualStudioIntegration\extras\ +visual_studio_integration\MSBuildExtensions\``. One can create a standalone +CUDA toolkit directory by either opening a installer with 7zip or +copying the files that are extracted by the running installer. +The value may be empty if no path to a standalone CUDA Toolkit was +specified. |