diff options
Diffstat (limited to 'Help')
32 files changed, 525 insertions, 85 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index df7cc4e..aba3742 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -227,7 +227,8 @@ target is already built, the command will not execute. [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] [COMMENT comment] - [VERBATIM] [USES_TERMINAL]) + [VERBATIM] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS]) This defines a new command that will be associated with building the specified ``<target>``. The ``<target>`` must be defined in the current diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index d283948..5ab3766 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -79,6 +79,17 @@ must be available for the compiler to find them. Other header file names source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be included by absolute path. +When specifying angle brackets inside a :manual:`generator expression +<cmake-generator-expressions(7)>`, be sure to encode the closing ``>`` +as ``$<ANGLE-R>``. For example: + +.. code-block:: cmake + + target_precompile_headers(mylib PRIVATE + "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>" + "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>" + ) + See Also ^^^^^^^^ diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 0bc2ca3..edbf92c 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -103,15 +103,18 @@ The options are: ``<LANG>_STANDARD <std>`` Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, + :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`, or :prop_tgt:`CUDA_STANDARD` target property of the generated project. ``<LANG>_STANDARD_REQUIRED <bool>`` Specify the :prop_tgt:`C_STANDARD_REQUIRED`, - :prop_tgt:`CXX_STANDARD_REQUIRED`, or :prop_tgt:`CUDA_STANDARD_REQUIRED` + :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`, + :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED` target property of the generated project. ``<LANG>_EXTENSIONS <bool>`` Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`, + :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`, or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project. In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be @@ -171,6 +174,12 @@ then the language standard variables are honored: * :variable:`CMAKE_CXX_STANDARD` * :variable:`CMAKE_CXX_STANDARD_REQUIRED` * :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_OBJC_STANDARD` +* :variable:`CMAKE_OBJC_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJC_EXTENSIONS` +* :variable:`CMAKE_OBJCXX_STANDARD` +* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJCXX_EXTENSIONS` * :variable:`CMAKE_CUDA_STANDARD` * :variable:`CMAKE_CUDA_STANDARD_REQUIRED` * :variable:`CMAKE_CUDA_EXTENSIONS` diff --git a/Help/cpack_gen/packagemaker.rst b/Help/cpack_gen/packagemaker.rst index e9464b7..81acb9d 100644 --- a/Help/cpack_gen/packagemaker.rst +++ b/Help/cpack_gen/packagemaker.rst @@ -15,9 +15,60 @@ macOS using PackageMaker: compatible with. Different versions of macOS support different features. For example, CPack can only build component-based installers for macOS 10.4 or newer, and can only build installers that download - component son-the-fly for macOS 10.5 or newer. If left blank, this value + components on-the-fly for macOS 10.5 or newer. If left blank, this value will be set to the minimum version of macOS that supports the requested features. Set this variable to some value (e.g., 10.4) only if you want to guarantee that your installer will work on that version of macOS, and don't mind missing extra features available in the installer shipping with later versions of macOS. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND + + Adds a background to Distribtion XML if specified. The value contains the + path to image in ``Resources`` directory. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT + + Adds an ``alignment`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING + + Adds a ``scaling`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE + + Adds a ``mime-type`` attribute to the background in Distribution XML. + The option contains MIME type of an image. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI + + Adds an ``uti`` attribute to the background in Distribution XML. + The option contains UTI type of an image. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA + + Adds a background for the Dark Aqua theme to Distribution XML if + specified. The value contains the path to image in ``Resources`` + directory. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option, + but for the dark theme. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst index d22fcd4..82b79ae 100644 --- a/Help/cpack_gen/productbuild.rst +++ b/Help/cpack_gen/productbuild.rst @@ -58,7 +58,6 @@ macOS using ProductBuild: component name. No ``postinstall`` script is added if this variable is not defined for a given component. - .. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR If specified the productbuild generator copies files from this directory @@ -66,3 +65,54 @@ macOS using ProductBuild: before the :variable:`CPACK_RESOURCE_FILE_WELCOME`, :variable:`CPACK_RESOURCE_FILE_README`, and :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND + + Adds a background to Distribtion XML if specified. The value contains the + path to image in ``Resources`` directory. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT + + Adds an ``alignment`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_SCALING + + Adds a ``scaling`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE + + Adds a ``mime-type`` attribute to the background in Distribution XML. + The option contains MIME type of an image. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_UTI + + Adds an ``uti`` attribute to the background in Distribution XML. + The option contains UTI type of an image. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA + + Adds a background for the Dark Aqua theme to Distribution XML if + specified. The value contains the path to image in ``Resources`` + directory. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_SCALING` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option, + but for the dark theme. diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 44e2273..a1c1a6f 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -14,6 +14,11 @@ Review a Merge Request The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge`` command to integrate a merge request. Please check at least the following: +* If the MR source branch (or part of it) should be backported + to the ``release`` branch (and is already based on a commit + contained in the ``release`` branch), add a ``Backport: release`` or + ``Backport: release:<commit-ish>`` trailing line to the MR description. + * If the MR source branch is not named well for the change it makes (e.g. it is just ``master`` or the patch changed during review), add a ``Topic-rename: <topic>`` trailing line to the MR description @@ -38,9 +43,10 @@ command to integrate a merge request. Please check at least the following: of various nightly builders.) * Ensure that the MR targets the ``master`` branch. A MR intended for - the ``release`` branch should be based on ``release`` but still merged - to ``master`` first (via ``Do: merge``). A maintainer may then merge - the MR topic to ``release`` manually. + the ``release`` branch should be based on ``release`` but still target + ``master``. Use the above-mentioned ``Backport: release`` line to tell + ``Do: merge`` to merge to both. If a MR is merged without the backport + line, a maintainer may still merge the MR topic to ``release`` manually. Maintain Current Release ======================== @@ -51,6 +57,12 @@ using a local branch named ``release-$ver``, where ``$ver`` is the version number of the current release in the form ``$major.$minor``. It is always merged into ``master`` before publishing. +To merge an open MR to the ``release`` branch, edit its description to +use the ``Backport: release`` line mentioned above and then ``Do: merge`` +normally. To update the ``release`` branch manually (e.g. to merge a +``$topic`` branch that was merged without the backport line), use the +following procedure. + Before merging a ``$topic`` branch into ``release``, verify that the ``$topic`` branch has already been merged to ``master`` via the usual ``Do: merge`` process. Then, to merge the ``$topic`` branch into diff --git a/Help/dev/review.rst b/Help/dev/review.rst index cbde6fe..8ec41d2 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -53,6 +53,10 @@ in GitLab to track the state of a MR: to a period of inactivity. See the `Expire`_ step. Use this label after closing a MR for this reason. +* ``workflow:external-discussion`` indicates that the MR has been closed + pending discussion elsewhere. See the `External Discussion`_ step. + Use this label after closing a MR for this reason. + The workflow status labels are intended to be mutually exclusive, so please remove any existing workflow label when adding one. @@ -429,6 +433,21 @@ Additionally, ``Do: merge`` extracts configuration from trailing lines in the MR description (the following have no effect if used in a MR comment instead): +* ``Backport: release[:<commit-ish>]``: merge the topic branch into + the ``release`` branch to backport the change. This is allowed + only if the topic branch is based on a commit in ``release`` already. + If only part of the topic branch should be backported, specify it as + ``:<commit-ish>``. The ``<commit-ish>`` may use `git rev-parse`_ + syntax to reference commits relative to the topic ``HEAD``. + See additional `backport instructions`_ for details. + For example: + + ``Backport: release`` + Merge the topic branch head into both ``release`` and ``master``. + ``Backport: release:HEAD~1^2`` + Merge the topic branch head's parent's second parent commit into + the ``release`` branch. Merge the topic branch head to ``master``. + * ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of the MR topic branch in the constructed merge commit message. It is also used in merge commits constructed by ``Do: stage``. @@ -436,6 +455,8 @@ comment instead): rename set in the MR description. .. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members +.. _`backport instructions`: https://gitlab.kitware.com/utils/git-workflow/wikis/Backport-topics +.. _`git rev-parse`: https://git-scm.com/docs/git-rev-parse Close ----- diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 675b65c..94d08c6 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -289,6 +289,12 @@ Properties on Targets /prop_tgt/NAME /prop_tgt/NO_SONAME /prop_tgt/NO_SYSTEM_FROM_IMPORTED + /prop_tgt/OBJC_EXTENSIONS + /prop_tgt/OBJC_STANDARD + /prop_tgt/OBJC_STANDARD_REQUIRED + /prop_tgt/OBJCXX_EXTENSIONS + /prop_tgt/OBJCXX_STANDARD + /prop_tgt/OBJCXX_STANDARD_REQUIRED /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OSX_ARCHITECTURES /prop_tgt/OUTPUT_NAME_CONFIG diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 84018b7..01dd5fd 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -534,6 +534,12 @@ Variables for Languages /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_OBJC_EXTENSIONS + /variable/CMAKE_OBJC_STANDARD + /variable/CMAKE_OBJC_STANDARD_REQUIRED + /variable/CMAKE_OBJCXX_EXTENSIONS + /variable/CMAKE_OBJCXX_STANDARD + /variable/CMAKE_OBJCXX_STANDARD_REQUIRED /variable/CMAKE_Swift_LANGUAGE_VERSION /variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index f82c466..395cd41 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -55,6 +55,8 @@ Options 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. + The user is responsible for ensuring that the configuration(s) listed + have already been built before invoking ``cpack``. ``-D <var>=<value>`` Set a CPack variable. This will override any value set for ``<var>`` in the diff --git a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst index 53f3970..6d1e60d 100644 --- a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst +++ b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst @@ -1,7 +1,11 @@ SKIP_UNITY_BUILD_INCLUSION -------------------------- -Is this source file skipped by :prop_tgt:`UNITY_BUILD` feature. +Setting this property to true ensures the source file will be skipped by +unity builds when its associated target has its :prop_tgt:`UNITY_BUILD` +property set to true. The source file will instead be compiled on its own +in the same way as it would with unity builds disabled. -This property helps with "ODR (One definition rule)" problems -that one would run into when using an :prop_tgt:`UNITY_BUILD`. +This property helps with "ODR (One definition rule)" problems where combining +a particular source file with others might lead to build errors or other +unintended side effects. diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst index a9123cd..f0a1646 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -26,3 +26,6 @@ selected and its :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` value used. To get the location of an imported target read one of the :prop_tgt:`LOCATION` or ``LOCATION_<CONFIG>`` properties. + +For platforms with import libraries (e.g. Windows) see also +:prop_tgt:`IMPORTED_IMPLIB`. diff --git a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst new file mode 100644 index 0000000..9f9d804 --- /dev/null +++ b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst @@ -0,0 +1,20 @@ +OBJCXX_EXTENSIONS +----------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic ObjC++ standard level is +controlled by the :prop_tgt:`OBJCXX_STANDARD` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +If the property is not set, and the project has set the :prop_tgt:`CXX_EXTENSIONS`, +the value of :prop_tgt:`CXX_EXTENSIONS` is set for :prop_tgt:`OBJCXX_EXTENSIONS`. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJCXX_STANDARD.rst b/Help/prop_tgt/OBJCXX_STANDARD.rst new file mode 100644 index 0000000..3c925dc --- /dev/null +++ b/Help/prop_tgt/OBJCXX_STANDARD.rst @@ -0,0 +1,35 @@ +OBJCXX_STANDARD +--------------- + +The ObjC++ standard whose features are requested to build this target. + +This property specifies the ObjC++ standard whose features are requested +to build this target. For some compilers, this results in adding a +flag such as ``-std=gnu++11`` to the compile line. + +Supported values are ``98``, ``11``, ``14``, ``17``, and ``20``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11) + +with a compiler which does not support ``-std=gnu++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`OBJCXX_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +If the property is not set, and the project has set the :prop_tgt:`CXX_STANDARD`, +the value of :prop_tgt:`CXX_STANDARD` is set for :prop_tgt:`OBJCXX_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..c330abf --- /dev/null +++ b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +OBJCXX_STANDARD_REQUIRED +------------------------ + +Boolean describing whether the value of :prop_tgt:`OBJCXX_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`OBJCXX_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`OBJCXX_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +If the property is not set, and the project has set the :prop_tgt:`CXX_STANDARD_REQUIRED`, +the value of :prop_tgt:`CXX_STANDARD_REQUIRED` is set for :prop_tgt:`OBJCXX_STANDARD_REQUIRED`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/OBJC_EXTENSIONS.rst b/Help/prop_tgt/OBJC_EXTENSIONS.rst new file mode 100644 index 0000000..2de9e48 --- /dev/null +++ b/Help/prop_tgt/OBJC_EXTENSIONS.rst @@ -0,0 +1,20 @@ +OBJC_EXTENSIONS +--------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu11`` instead of ``-std=c11`` to the compile line. This +property is ``ON`` by default. The basic OBJC standard level is +controlled by the :prop_tgt:`OBJC_STANDARD` target property. + +If the property is not set, and the project has set the :prop_tgt:`C_EXTENSIONS`, +the value of :prop_tgt:`C_EXTENSIONS` is set for :prop_tgt:`OBJC_EXTENSIONS`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJC_STANDARD.rst b/Help/prop_tgt/OBJC_STANDARD.rst new file mode 100644 index 0000000..d1e1b24 --- /dev/null +++ b/Help/prop_tgt/OBJC_STANDARD.rst @@ -0,0 +1,35 @@ +OBJC_STANDARD +------------- + +The OBJC standard whose features are requested to build this target. + +This property specifies the OBJC standard whose features are requested +to build this target. For some compilers, this results in adding a +flag such as ``-std=gnu11`` to the compile line. + +Supported values are ``90``, ``99`` and ``11``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY OBJC_STANDARD 11) + +with a compiler which does not support ``-std=gnu11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu99`` or ``-std=gnu90`` flag if supported. This "decay" behavior may +be controlled with the :prop_tgt:`OBJC_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`OBJC_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +If the property is not set, and the project has set the :prop_tgt:`C_STANDARD`, +the value of :prop_tgt:`C_STANDARD` is set for :prop_tgt:`OBJC_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..8cf377c --- /dev/null +++ b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +OBJC_STANDARD_REQUIRED +---------------------- + +Boolean describing whether the value of :prop_tgt:`OBJC_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`OBJC_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`OBJC_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +If the property is not set, and the project has set the :prop_tgt:`C_STANDARD_REQUIRED`, +the value of :prop_tgt:`C_STANDARD_REQUIRED` is set for :prop_tgt:`OBJC_STANDARD_REQUIRED`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst index fab4f15..479802e 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -1,60 +1,60 @@ 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 -which will ``#include`` the source files, and exclude them from -building by setting :prop_sf:`HEADER_FILE_ONLY` to ``ON``. +When this property is set to true, the target source files will be combined +into batches for faster compilation. This is done by creating a (set of) +unity sources which ``#include`` the original sources, then compiling these +unity sources instead of the originals. This is known as a *Unity* or *Jumbo* +build. The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper +limit on how many sources can be combined per unity source file. + +Unity builds are not currently supported for all languages. CMake version +|release| supports combining ``C`` and ``CXX`` source files. For targets that +mix source files from more than one language, CMake will separate the languages +such that each generated unity source file only contains sources for a single +language. + +This property is initialized by the value of the :variable:`CMAKE_UNITY_BUILD` +variable when a target is created. .. 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. + Projects should not directly set the ``UNITY_BUILD`` property or its + associated :variable:`CMAKE_UNITY_BUILD` variable to true. Depending + on the capabilities of the build machine and compiler used, it might or + might not be appropriate to enable unity builds. Therefore, this feature + should be under developer control, which would normally be through the + developer choosing whether or not to set the :variable:`CMAKE_UNITY_BUILD` + variable on the :manual:`cmake(1)` command line or some other equivalent + method. However, it IS recommended to set the ``UNITY_BUILD`` target + property to false if it is known that enabling unity builds for the + target can lead to problems. ODR (One definition rule) errors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Since multiple source files are included into one source file, -it can lead to ODR errors. This section contains properties -which help fixing these errors. - -The source files marked by :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` -will be skipped from unity build. - -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` target property. +When multiple source files are included into one source file, as is done +for unity builds, it can potentially lead to ODR errors. CMake provides +a number of measures to help address such problems: + +* Any source file that has a non-empty :prop_sf:`COMPILE_OPTIONS`, + :prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or + :prop_sf:`INCLUDE_DIRECTORIES` source property will not be combined + into a unity source. + +* Projects can prevent an individual source file from being combined into + a unity source by setting its :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` + source property to true. This can be a more effective way to prevent + problems with specific files than disabling unity builds for an entire + target. + +* The :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and + :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` target properties can be used + to inject code into the unity source files before and after every + ``#include`` statement. + +* The order of source files added to the target via commands like + :command:`add_library`, :command:`add_executable` or + :command:`target_sources` will be preserved in 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/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst index 84047f2..44ffe27 100644 --- a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst +++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst @@ -1,13 +1,23 @@ UNITY_BUILD_BATCH_SIZE ---------------------- -Specifies how many source code files will be included into a -:prop_tgt:`UNITY_BUILD` source file. +Specifies the maximum number of source files that can be combined into any one +unity source file when unity builds are enabled by the :prop_tgt:`UNITY_BUILD` +target property. The original source files will be distributed across as many +unity source files as necessary to honor this limit. -If the property is not set, CMake will use the value provided -by :variable:`CMAKE_UNITY_BUILD_BATCH_SIZE`. +The initial value for this property is taken from the +:variable:`CMAKE_UNITY_BUILD_BATCH_SIZE` variable when the target is created. +If that variable has not been set, the initial value will be 8. -By setting it to value `0` the generated unity source file will -contain all the source files that would otherwise be split -into multiple batches. It is not recommended to do so, since it -would affect performance. +The batch size needs to be selected carefully. If set too high, the size of +the combined source files could result in the compiler using excessive memory +or hitting other similar limits. In extreme cases, this can even result in +build failure. On the other hand, if the batch size is too low, there will be +little gain in build performance. + +Although strongly discouraged, the batch size may be set to a value of 0 to +combine all the sources for the target into a single unity file, regardless of +how many sources are involved. This runs the risk of creating an excessively +large unity source file and negatively impacting the build performance, so +a value of 0 is not generally recommended. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst index 7795289..7231b61 100644 --- a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst +++ b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst @@ -2,7 +2,18 @@ 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. +feature just after every ``#include`` statement in the generated unity +source files. For example: -This could be something like `#undef NOMINMAX`. +.. code-block:: cmake + + set(after [[ + #if defined(NOMINMAX) + #undef NOMINMAX + #endif + ]]) + set_target_properties(myTarget PROPERTIES + UNITY_BUILD_CODE_AFTER_INCLUDE "${after}" + ) + +See also :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE`. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst index f335463..7ed6fa1 100644 --- a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst +++ b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst @@ -2,7 +2,18 @@ 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. +feature just before every ``#include`` statement in the generated unity +source files. For example: -This could be something like `#define NOMINMAX`. +.. code-block:: cmake + + set(before [[ + #if !defined(NOMINMAX) + #define NOMINMAX + #endif + ]]) + set_target_properties(myTarget PROPERTIES + UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}" + ) + +See also :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE`. diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index 1b875fa..0d1cc1e 100644 --- a/Help/release/3.16.rst +++ b/Help/release/3.16.rst @@ -207,9 +207,8 @@ CTest CPack ----- -* CPack variable :variable:`CPACK_INSTALL_CMAKE_CONFIGURATIONS` was added to - control what configurations are to be packaged for multi-configuration - CMake generators. +* :manual:`cpack(1)` learned support for multiple configurations for ``-C`` + option. * The :cpack_gen:`CPack DEB Generator` is now able to format generic text (usually used as the description for multiple CPack generators) according diff --git a/Help/release/dev/cpack-pkg-background.rst b/Help/release/dev/cpack-pkg-background.rst new file mode 100644 index 0000000..796f5d6 --- /dev/null +++ b/Help/release/dev/cpack-pkg-background.rst @@ -0,0 +1,8 @@ +cpack-pkg-background +-------------------- + +* The :cpack_gen:`CPack productbuild Generator` and + :cpack_gen:`CPack PackageMaker Generator` gained options + :variable:`CPACK_PRODUCTBUILD_BACKGROUND` and + :variable:`CPACK_PACKAGEMAKER_BACKGROUND`, respectively, + to specify a background image for the macOS installer. diff --git a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst new file mode 100644 index 0000000..8afa6f2 --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_EXTENSIONS +----------------------- + +Default value for :prop_tgt:`OBJCXX_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD.rst b/Help/variable/CMAKE_OBJCXX_STANDARD.rst new file mode 100644 index 0000000..4e5016a --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_STANDARD +--------------------- + +Default value for :prop_tgt:`OBJCXX_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..3a0602a --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_STANDARD_REQUIRED +------------------------------ + +Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst new file mode 100644 index 0000000..d9619d8 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_EXTENSIONS +--------------------- + +Default value for :prop_tgt:`OBJC_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD.rst b/Help/variable/CMAKE_OBJC_STANDARD.rst new file mode 100644 index 0000000..976c441 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_STANDARD +------------------- + +Default value for :prop_tgt:`OBJC_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..5c02096 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_STANDARD_REQUIRED +---------------------------- + +Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst index bbcfd68..a86cd67 100644 --- a/Help/variable/CMAKE_UNITY_BUILD.rst +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -1,11 +1,19 @@ CMAKE_UNITY_BUILD ----------------- -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. +This variable is used to initialize the :prop_tgt:`UNITY_BUILD` +property of targets when they are created. Setting it to true +enables batch compilation of multiple sources within each target. +This feature is known as a *Unity* or *Jumbo* build. + +Projects should not set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable unity builds according to the capabilities of their own machine +and compiler. + +By default, this variable is not set, which will result in unity builds +being disabled. .. note:: This option currently does not work well in combination with diff --git a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst index 3ab2344..7988d4b 100644 --- a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst +++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst @@ -1,6 +1,7 @@ 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``. +This variable is used to initialize the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` +property of targets when they are created. It specifies the default upper +limit on the number of source files that may be combined in any one unity +source file when unity builds are enabled for a target. |