diff options
Diffstat (limited to 'Help')
64 files changed, 1030 insertions, 310 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/ctest_test.rst b/Help/command/ctest_test.rst index 0a33da3..5c67b2c 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -17,12 +17,13 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [EXCLUDE_FIXTURE_SETUP <regex>] [EXCLUDE_FIXTURE_CLEANUP <regex>] [PARALLEL_LEVEL <level>] - [HARDWARE_SPEC_FILE <file>] + [RESOURCE_SPEC_FILE <file>] [TEST_LOAD <threshold>] [SCHEDULE_RANDOM <ON|OFF>] [STOP_TIME <time-of-day>] [RETURN_VALUE <result-var>] [CAPTURE_CMAKE_ERROR <result-var>] + [REPEAT <mode>:<n>] [QUIET] ) @@ -83,10 +84,10 @@ The options are: Specify a positive number representing the number of tests to be run in parallel. -``HARDWARE_SPEC_FILE <file>`` +``RESOURCE_SPEC_FILE <file>`` Specify a - :ref:`hardware specification file <ctest-hardware-specification-file>`. See - :ref:`ctest-hardware-allocation` for more information. + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. ``TEST_LOAD <threshold>`` While running tests in parallel, try not to start tests when they @@ -95,6 +96,25 @@ The options are: and then the ``--test-load`` command-line argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting in the :ref:`CTest Test Step`. +``REPEAT <mode>:<n>`` + Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times. + The modes are: + + ``UNTIL_FAIL`` + Require each test to run ``<n>`` times without failing in order to pass. + This is useful in finding sporadic failures in test cases. + + ``UNTIL_PASS`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests if they fail for any reason. + This is useful in tolerating sporadic failures in test cases. + + ``AFTER_TIMEOUT`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests only if they timeout. + This is useful in tolerating sporadic timeouts in test cases + on busy machines. + ``SCHEDULE_RANDOM <ON|OFF>`` Launch tests in a random order. This may be useful for detecting implicit test dependencies. diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index d283948..569c7eb 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -3,33 +3,21 @@ target_precompile_headers Add a list of header files to precompile. +Precompiling header files can speed up compilation by creating a partially +processed version of some header files, and then using that version during +compilations rather than repeatedly parsing the original headers. + +Main Form +^^^^^^^^^ + .. code-block:: cmake target_precompile_headers(<target> <INTERFACE|PUBLIC|PRIVATE> [header1...] [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) - target_precompile_headers(<target> REUSE_FROM <other_target>) - -Adds header files to :prop_tgt:`PRECOMPILE_HEADERS` or -:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties. - -The second signature will reuse an already precompiled header file artefact -from another target. This is done by setting the -:prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` to ``<other_target>`` value. -The ``<other_target>`` will become a dependency of ``<target>``. - -.. note:: - - The second signature will require the same set of compiler options, - compiler flags, compiler definitions for both ``<target>``, and - ``<other_target>``. Compilers (e.g. GCC) will issue a warning if the - precompiled header file cannot be used (``-Winvalid-pch``). - -Precompiling header files can speed up compilation by creating a partially -processed version of some header files, and then using that version during -compilations rather than repeatedly parsing the original headers. - +The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. @@ -38,25 +26,50 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``. -(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) -Repeated calls for the same ``<target>`` append items in the order called. +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>`` +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). +Repeated calls for the same ``<target>`` will append items in the order called. + +Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets +that will be :ref:`exported <install(EXPORT)>`, or they should at least use +the ``$<BUILD_INTERFACE:...>`` generator expression to prevent precompile +headers from appearing in an installed exported target. Consumers of a target +should typically be in control of what precompile headers they use, not have +precompile headers forced on them by the targets being consumed (since +precompile headers are not typically usage requirements). A notable exception +to this is where an :ref:`interface library <Interface Libraries>` is created +to define a commonly used set of precompile headers in one place and then other +targets link to that interface library privately. In this case, the interface +library exists specifically to propagate the precompile headers to its +consumers and the consumer is effectively still in control, since it decides +whether to link to the interface library or not. + +The list of header files is used to generate a header file named +``cmake_pch.h|xx`` which is used to generate the precompiled header file +(``.pch``, ``.gch``, ``.pchi``) artifact. The ``cmake_pch.h|xx`` header +file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to +all source files, so sources do not need to have ``#include "pch.h"``. + +Header file names specified with angle brackets (e.g. ``<unordered_map>``) or +explicit double quotes (escaped for the :manual:`cmake-language(7)`, +e.g. ``[["other_header.h"]]``) will be treated as is, and include directories +must be available for the compiler to find them. Other header file names +(e.g. ``project_header.h``) are interpreted as being relative to the current +source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be +included by absolute path. -Arguments to ``target_precompile_headers`` may use "generator expressions" +Arguments to ``target_precompile_headers()`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly useful for specifying a language-specific header to precompile for -only one language (e.g. ``CXX`` and not ``C``). - -Usage -^^^^^ +only one language (e.g. ``CXX`` and not ``C``). For example: .. code-block:: cmake - target_precompile_headers(<target> + target_precompile_headers(myTarget PUBLIC project_header.h "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>" @@ -65,25 +78,47 @@ Usage <unordered_map> ) -The list of header files is used to generate a header file named -``cmake_pch.h|xx`` which is used to generate the precompiled header file -(``.pch``, ``.gch``, ``.pchi``) artifact. The ``cmake_pch.h|xx`` header -file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to -all source files, so sources do not need to have ``#include "pch.h"``. +When specifying angle brackets inside a :manual:`generator expression +<cmake-generator-expressions(7)>`, be sure to encode the closing ``>`` +as ``$<ANGLE-R>``. For example: -Header file names specified with angle brackets (e.g. ``<unordered_map>``) or -explicit double quotes (escaped for the :manual:`cmake-language(7)`, -e.g. ``[["other_header.h"]]``) will be treated as is, and include directories -must be available for the compiler to find them. Other header file names -(e.g. ``project_header.h``) are interpreted as being relative to the current -source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be -included by absolute path. +.. code-block:: cmake + + target_precompile_headers(mylib PRIVATE + "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>" + "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>" + ) + + +Reusing Precompile Headers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The command also supports a second signature which can be used to specify that +one target re-uses a precompiled header file artefact from another target +instead of generating its own: + +.. code-block:: cmake + + target_precompile_headers(<target> REUSE_FROM <other_target>) + +This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to +``<other_target>`` and adds a dependency such that ``<target>`` will depend +on ``<other_target>``. CMake will halt with an error if the +:prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when +the ``REUSE_FROM`` form is used. + +.. note:: + + The ``REUSE_FROM`` form requires the same set of compiler options, + compiler flags and compiler definitions for both ``<target>`` and + ``<other_target>``. Some compilers (e.g. GCC) may issue a warning if the + precompiled header file cannot be used (``-Winvalid-pch``). See Also ^^^^^^^^ -For disabling precompile headers for specific targets there is the -property :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`. +To disable precompile headers for specific targets, see the +:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property. -For skipping certain source files there is the source file property -:prop_sf:`SKIP_PRECOMPILE_HEADERS`. +To prevent precompile headers from being used when compiling a specific +source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property. 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/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst new file mode 100644 index 0000000..4f91e9a --- /dev/null +++ b/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_COMPILER_LAUNCHER +------------------------------ + +.. include:: ENV_VAR.txt + +Default compiler launcher to use for the specified language. Will only be used +by CMake to initialize the variable on the first configuration. Afterwards, it +is available through the cache setting of the variable of the same name. For +any configuration run (including the first), the environment variable will be +ignored if the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable is defined. diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index 3f20aa2..d74d160 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -610,12 +610,12 @@ CTest will read in this file when it runs. To create a simple dashboard you can run **cmake** or **cmake-gui** to configure the project, but do not build it yet. Instead, change directory to the binary tree, and then run:: - ctest [-VV] –D Experimental + ctest [-VV] -D Experimental Remember, for multi-config generators (e.g. Visual Studio), the configuration type must be specified:: - ctest [-VV] -C Debug –D Experimental + ctest [-VV] -C Debug -D Experimental Or, from an IDE, build the ``Experimental`` target. diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index a821189..a14e322 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -28,10 +28,15 @@ CMake knows are known to the compiler, regardless of language standard or compile flags needed to use them. Features known to CMake are named mostly following the same convention -as the Clang feature test macros. The are some exceptions, such as +as the Clang feature test macros. There are some exceptions, such as CMake using ``cxx_final`` and ``cxx_override`` instead of the single ``cxx_override_control`` used by Clang. +Note that there are no separate compile features properties or variables for +the ``OBJC`` or ``OBJCXX`` languages. These are based off ``C`` or ``C++`` +respectively, so the properties and variables for their corresponding base +language should be used instead. + Compile Feature Requirements ============================ diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index c98f18f..adfc39e 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -28,6 +28,7 @@ Environment Variables that Control the Build /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_LANG_COMPILER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 04b6ed2..12eecd9 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -199,6 +199,7 @@ The reply index file contains a JSON object: "root": "/prefix/share/cmake-3.14" }, "generator": { + "multiConfig": false, "name": "Unix Makefiles" } }, @@ -267,6 +268,9 @@ The members are: A JSON object describing the CMake generator used for the build. It has members: + ``multiConfig`` + A boolean specifying whether the generator supports multiple output + configurations. ``name`` A string specifying the name of the generator. ``platform`` diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 44ea1a8..eceeac7 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.17 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0098> + Policies Introduced by CMake 3.16 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 02e07eb..c5ef09a 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 @@ -375,6 +381,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER @@ -415,10 +422,10 @@ Properties on Tests /prop_test/LABELS /prop_test/MEASUREMENT /prop_test/PASS_REGULAR_EXPRESSION - /prop_test/PROCESSES /prop_test/PROCESSOR_AFFINITY /prop_test/PROCESSORS /prop_test/REQUIRED_FILES + /prop_test/RESOURCE_GROUPS /prop_test/RESOURCE_LOCK /prop_test/RUN_SERIAL /prop_test/SKIP_REGULAR_EXPRESSION diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 84018b7..0c1d510 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -239,6 +239,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS @@ -534,6 +535,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/cmake.1.rst b/Help/manual/cmake.1.rst index 71110d1..6f33866 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -554,22 +554,38 @@ Available commands are: 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt ``remove [-f] <file>...`` - Remove the file(s). If any of the listed files already do not - exist, the command returns a non-zero exit code, but no message - is logged. The ``-f`` option changes the behavior to return a + .. deprecated:: 3.17 + + Remove the file(s). The planned behaviour was that if any of the + listed files already do not exist, the command returns a non-zero exit code, + but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such situations instead. ``remove`` does not follow symlinks. That means it remove only symlinks and not files it point to. + The implementation was buggy and always returned 0. It cannot be fixed without + breaking backwards compatibility. Use ``rm`` instead. + ``remove_directory <dir>...`` - Remove ``<dir>`` directories and their contents. If a directory does + .. deprecated:: 3.17 + + Remove ``<dir>`` directories and their contents. If a directory does not exist it will be silently ignored. If ``<dir>`` is a symlink to a directory, just the symlink will be removed. + Use ``rm`` instead. ``rename <oldname> <newname>`` Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. +``rm [-rRf] <file> <dir>...`` + Remove the files ``<file>`` or directories ``dir``. + Use ``-r`` or ``-R`` to remove directories and their contents recursively. + If any of the listed files/directories do not exist, the command returns a + non-zero exit code, but no message is logged. The ``-f`` option changes + the behavior to return a zero exit code (i.e. success) in such + situations instead. + ``server`` Launch :manual:`cmake-server(7)` mode. 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/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 0097cee..17bddb6 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -90,14 +90,14 @@ Options See `Label and Subproject Summary`_. -``--hardware-spec-file <file>`` - Run CTest with :ref:`hardware allocation <ctest-hardware-allocation>` enabled, +``--resource-spec-file <file>`` + Run CTest with :ref:`resource allocation <ctest-resource-allocation>` enabled, using the - :ref:`hardware specification file <ctest-hardware-specification-file>` + :ref:`resource specification file <ctest-resource-specification-file>` specified in ``<file>``. When ``ctest`` is run as a `Dashboard Client`_ this sets the - ``HardwareSpecFile`` option of the `CTest Test Step`_. + ``ResourceSpecFile`` option of the `CTest Test Step`_. ``--test-load <level>`` While running tests in parallel (e.g. with ``-j``), try not to start @@ -261,23 +261,27 @@ Options fail, subsequent calls to CTest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). -``--repeat-until-fail <n>`` - Require each test to run ``<n>`` times without failing in order to pass. - - This is useful in finding sporadic failures in test cases. +``--repeat <mode>:<n>`` + Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times. + The modes are: -``--repeat-until-pass <n>`` - Allow each test to run up to ``<n>`` times in order to pass. - Repeats tests if they fail for any reason. + ``until-fail`` + Require each test to run ``<n>`` times without failing in order to pass. + This is useful in finding sporadic failures in test cases. - This is useful in tolerating sporadic failures in test cases. + ``until-pass`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests if they fail for any reason. + This is useful in tolerating sporadic failures in test cases. -``--repeat-after-timeout <n>`` - Allow each test to run up to ``<n>`` times in order to pass. - Repeats tests only if they timeout. + ``after-timeout`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests only if they timeout. + This is useful in tolerating sporadic timeouts in test cases + on busy machines. - This is useful in tolerating sporadic timeouts in test cases - on busy machines. +``--repeat-until-fail <n>`` + Equivalent to ``--repeat until-fail:<n>``. ``--max-width <width>`` Set the max width for a test name to output. @@ -980,10 +984,10 @@ Arguments to the command may specify some of the step settings. Configuration settings include: -``HardwareSpecFile`` +``ResourceSpecFile`` Specify a - :ref:`hardware specification file <ctest-hardware-specification-file>`. See - :ref:`ctest-hardware-allocation` for more information. + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. ``LabelsForSubprojects`` Specify a semicolon-separated list of labels that will be treated as @@ -1294,22 +1298,22 @@ model is defined as follows: Test properties. Can contain keys for each of the supported test properties. -.. _`ctest-hardware-allocation`: +.. _`ctest-resource-allocation`: -Hardware Allocation +Resource Allocation =================== -CTest provides a mechanism for tests to specify the hardware that they need and -how much of it they need, and for users to specify the hardware availiable on +CTest provides a mechanism for tests to specify the resources that they need +in a fine-grained way, and for users to specify the resources availiable on the running machine. This allows CTest to internally keep track of which -hardware is in use and which is free, scheduling tests in a way that prevents -them from trying to claim hardware that is not available. +resources are in use and which are free, scheduling tests in a way that +prevents them from trying to claim resources that are not available. A common use case for this feature is for tests that require the use of a GPU. Multiple tests can simultaneously allocate memory from a GPU, but if too many tests try to do this at once, some of them will fail to allocate, resulting in a failed test, even though the test would have succeeded if it had the memory -it needed. By using the hardware allocation feature, each test can specify how +it needed. By using the resource allocation feature, each test can specify how much memory it requires from a GPU, allowing CTest to schedule tests in a way that running several of these tests at once does not exhaust the GPU's memory pool. @@ -1325,40 +1329,60 @@ When a test is executed, and slots from a resource are allocated to that test, tests may assume that they have exclusive use of those slots for the duration of the test's process. -The CTest hardware allocation feature consists of two inputs: +The CTest resource allocation feature consists of two inputs: -* The :ref:`hardware specification file <ctest-hardware-specification-file>`, - described below, which describes the hardware resources available on the - system, and -* The :prop_test:`PROCESSES` property of tests, which describes the resources - required by the test +* The :ref:`resource specification file <ctest-resource-specification-file>`, + described below, which describes the resources available on the system. +* The :prop_test:`RESOURCE_GROUPS` property of tests, which describes the + resources required by the test. -When CTest runs a test, the hardware allocated to that test is passed in the +When CTest runs a test, the resources allocated to that test are passed in the form of a set of -:ref:`environment variables <ctest-hardware-environment-variables>` as +:ref:`environment variables <ctest-resource-environment-variables>` as described below. Using this information to decide which resource to connect to is left to the test writer. -Please note that these processes are not spawned by CTest. The ``PROCESSES`` -property merely tells CTest what processes the test expects to launch. It is up -to the test itself to do this process spawning, and read the :ref:`environment -variables <ctest-hardware-environment-variables>` to determine which resources -each process has been allocated. - -.. _`ctest-hardware-specification-file`: - -Hardware Specification File +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. + +Note that even if a test specifies a ``RESOURCE_GROUPS`` property, it is still +possible for that to test to run without any resource allocation (and without +the corresponding +:ref:`environment variables <ctest-resource-environment-variables>`) +if the user does not pass a resource specification file. Passing this file, +either through the ``--resource-spec-file`` command-line argument or the +``RESOURCE_SPEC_FILE`` argument to :command:`ctest_test`, is what activates the +resource allocation feature. Tests should check the +``CTEST_RESOURCE_GROUP_COUNT`` environment variable to find out whether or not +resource allocation is activated. This variable will always (and only) be +defined if resource allocation is activated. If resource allocation is not +activated, then the ``CTEST_RESOURCE_GROUP_COUNT`` variable will not exist, +even if it exists for the parent ``ctest`` process. If a test absolutely must +have resource allocation, then it can return a failing exit code or use the +:prop_test:`SKIP_RETURN_CODE` or :prop_test:`SKIP_REGULAR_EXPRESSION` +properties to indicate a skipped test. + +.. _`ctest-resource-specification-file`: + +Resource Specification File --------------------------- -The hardware specification file is a JSON file which is passed to CTest, either -on the :manual:`ctest(1)` command line as ``--hardware-spec-file``, or as the -``HARDWARE_SPEC_FILE`` argument of :command:`ctest_test`. The hardware +The resource specification file is a JSON file which is passed to CTest, either +on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the +``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. The resource specification file must be a JSON object. All examples in this document assume -the following hardware specification file: +the following resource specification file: .. code-block:: json { + "version": { + "major": 1, + "minor": 0 + }, "local": [ { "gpus": [ @@ -1390,12 +1414,17 @@ the following hardware specification file: The members are: +``version`` + An object containing a ``major`` integer field and a ``minor`` integer field. + Currently, the only supported version is major ``1``, minor ``0``. Any other + value is an error. + ``local`` - A JSON array consisting of CPU sockets present on the system. Currently, only - one socket is supported. + A JSON array of resource sets present on the system. Currently, this array + is restricted to being of size 1. - Each socket is a JSON object with members whose names are equal to the - desired resource types, such as ``gpu``. These names must start with a + Each array element is a JSON object with members whose names are equal to the + desired resource types, such as ``gpus``. These names must start with a lowercase letter or an underscore, and subsequent characters can be a lowercase letter, a digit, or an underscore. Uppercase letters are not allowed, because certain platforms have case-insensitive environment @@ -1436,12 +1465,12 @@ In the example file above, there are four GPUs with ID's 0 through 3. GPU 0 has 2 slots, GPU 1 has 4, GPU 2 has 2, and GPU 3 has a default of 1 slot. There is also one cryptography chip with 4 slots. -``PROCESSES`` Property ----------------------- +``RESOURCE_GROUPS`` Property +---------------------------- -See :prop_test:`PROCESSES` for a description of this property. +See :prop_test:`RESOURCE_GROUPS` for a description of this property. -.. _`ctest-hardware-environment-variables`: +.. _`ctest-resource-environment-variables`: Environment Variables --------------------- @@ -1449,65 +1478,67 @@ Environment Variables Once CTest has decided which resources to allocate to a test, it passes this information to the test executable as a series of environment variables. For each example below, we will assume that the test in question has a -:prop_test:`PROCESSES` property of ``2,gpus:2;gpus:4,gpus:1,crypto_chips:2``. +:prop_test:`RESOURCE_GROUPS` property of +``2,gpus:2;gpus:4,gpus:1,crypto_chips:2``. The following variables are passed to the test process: -.. envvar:: CTEST_PROCESS_COUNT +.. envvar:: CTEST_RESOURCE_GROUP_COUNT - The total number of processes specified by the :prop_test:`PROCESSES` + The total number of groups specified by the :prop_test:`RESOURCE_GROUPS` property. For example: - * ``CTEST_PROCESS_COUNT=3`` + * ``CTEST_RESOURCE_GROUP_COUNT=3`` This variable will only be defined if :manual:`ctest(1)` has been given a - ``--hardware-spec-file``, or if :command:`ctest_test` has been given a - ``HARDWARE_SPEC_FILE``. If no hardware specification file has been given, + ``--resource-spec-file``, or if :command:`ctest_test` has been given a + ``RESOURCE_SPEC_FILE``. If no resource specification file has been given, this variable will not be defined. -.. envvar:: CTEST_PROCESS_<num> +.. envvar:: CTEST_RESOURCE_GROUP_<num> - The list of resource types allocated to each process, with each item + The list of resource types allocated to each group, with each item separated by a comma. ``<num>`` is a number from zero to - ``CTEST_PROCESS_COUNT`` minus one. ``CTEST_PROCESS_<num>`` is defined for - each ``<num>`` in this range. For example: + ``CTEST_RESOURCE_GROUP_COUNT`` minus one. ``CTEST_RESOURCE_GROUP_<num>`` + is defined for each ``<num>`` in this range. For example: - * ``CTEST_PROCESS_0=gpus`` - * ``CTEST_PROCESS_1=gpus`` - * ``CTEST_PROCESS_2=crypto_chips,gpus`` + * ``CTEST_RESOURCE_GROUP_0=gpus`` + * ``CTEST_RESOURCE_GROUP_1=gpus`` + * ``CTEST_RESOURCE_GROUP_2=crypto_chips,gpus`` -.. envvar:: CTEST_PROCESS_<num>_<resource-type> +.. envvar:: CTEST_RESOURCE_GROUP_<num>_<resource-type> The list of resource IDs and number of slots from each ID allocated to each - process for a given resource type. This variable consists of a series of + group for a given resource type. This variable consists of a series of pairs, each pair separated by a semicolon, and with the two items in the pair separated by a comma. The first item in each pair is ``id:`` followed by the ID of a resource of type ``<resource-type>``, and the second item is ``slots:`` followed by the number of slots from that resource allocated to - the given process. For example: + the given group. For example: - * ``CTEST_PROCESS_0_GPUS=id:0,slots:2`` - * ``CTEST_PROCESS_1_GPUS=id:2,slots:2`` - * ``CTEST_PROCESS_2_GPUS=id:1,slots:4;id:3,slots:1`` - * ``CTEST_PROCESS_2_CRYPTO_CHIPS=id:card0,slots:2`` + * ``CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2`` + * ``CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2`` + * ``CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1`` + * ``CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2`` - In this example, process 0 gets 2 slots from GPU ``0``, process 1 gets 2 slots - from GPU ``2``, and process 2 gets 4 slots from GPU ``1`` and 2 slots from - cryptography chip ``card0``. + In this example, group 0 gets 2 slots from GPU ``0``, group 1 gets 2 slots + from GPU ``2``, and group 2 gets 4 slots from GPU ``1``, 1 slot from GPU + ``3``, and 2 slots from cryptography chip ``card0``. - ``<num>`` is a number from zero to ``CTEST_PROCESS_COUNT`` minus one. + ``<num>`` is a number from zero to ``CTEST_RESOURCE_GROUP_COUNT`` minus one. ``<resource-type>`` is the name of a resource type, converted to uppercase. - ``CTEST_PROCESS_<num>_<resource-type>`` is defined for the product of each - ``<num>`` in the range listed above and each resource type listed in - ``CTEST_PROCESS_<num>``. + ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` is defined for the product + of each ``<num>`` in the range listed above and each resource type listed in + ``CTEST_RESOURCE_GROUP_<num>``. Because some platforms have case-insensitive names for environment variables, the names of resource types may not clash in a case-insensitive environment. Because of this, for the sake of simplicity, all resource types must be listed in all lowercase in the - :ref:`hardware specification file <ctest-hardware-specification-file>` and in - the :prop_test:`PROCESSES` property, and they are converted to all uppercase - in the ``CTEST_PROCESS_<num>_<resource-type>`` environment variable. + :ref:`resource specification file <ctest-resource-specification-file>` and + in the :prop_test:`RESOURCE_GROUPS` property, and they are converted to all + uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment + variable. See Also ======== diff --git a/Help/policy/CMP0098.rst b/Help/policy/CMP0098.rst new file mode 100644 index 0000000..6d1443b --- /dev/null +++ b/Help/policy/CMP0098.rst @@ -0,0 +1,30 @@ +CMP0098 +------- + +:module:`FindFLEX` runs ``flex`` in directory +:variable:`CMAKE_CURRENT_BINARY_DIR` when executing. + +The module provides a ``FLEX_TARGET`` macro which generates FLEX output. +In CMake 3.16 and below the macro would generate a custom command that runs +``flex`` in the current source directory. CMake 3.17 and later prefer to +run it in the build directory and use :variable:`CMAKE_CURRENT_BINARY_DIR` +as the ``WORKING_DIRECTORY`` of its :command:`add_custom_command` invocation. +This ensures that any implicitly generated file is written relative to the +build tree rather than the source tree, unless the generated file is +provided as absolute path. + +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is for ``FLEX_TARGET`` to use +the current source directory for the ``WORKING_DIRECTORY`` and where +to generate implicit files. The ``NEW`` behavior of this policy is to +use the current binary directory for the ``WORKING_DIRECTORY`` relative to +which implicit files are generated unless provided as absolute path. + +This policy was introduced in CMake version 3.17. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt 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_test/PROCESSES.rst b/Help/prop_test/PROCESSES.rst deleted file mode 100644 index d09c6d1..0000000 --- a/Help/prop_test/PROCESSES.rst +++ /dev/null @@ -1,54 +0,0 @@ -PROCESSES ----------- - -Set to specify the number of processes spawned by a test, and the resources -that they require. See :ref:`hardware allocation <ctest-hardware-allocation>` -for more information on how this property integrates into the CTest hardware -allocation feature. - -The ``PROCESSES`` property is a :ref:`semicolon-separated list <CMake Language -Lists>` of process descriptions. Each process description consists of an -optional number of processes for the description followed by a series of -resource requirements for those processes. These requirements (and the number -of processes) are separated by commas. The resource requirements consist of the -name of a resource type, followed by a colon, followed by an unsigned integer -specifying the number of slots required on one resource of the given type. - -Please note that these processes are not spawned by CTest. The ``PROCESSES`` -property merely tells CTest what processes the test expects to launch. It is up -to the test itself to do this process spawning, and read the :ref:`environment -variables <ctest-hardware-environment-variables>` to determine which resources -each process has been allocated. - -Consider the following example: - -.. code-block:: cmake - - add_test(NAME MyTest COMMAND MyExe) - set_property(TEST MyTest PROPERTY PROCESSES - "2,gpus:2" - "gpus:4,crypto_chips:2") - -In this example, there are two process descriptions (implicitly separated by a -semicolon.) The content of the first description is ``2,gpus:2``. This -description spawns 2 processes, each of which requires 2 slots from a single -GPU. The content of the second description is ``gpus:4,crypto_chips:2``. This -description does not specify a process count, so a default of 1 is assumed. -This single process requires 4 slots from a single GPU and 2 slots from a -single cryptography chip. In total, 3 processes are spawned from this test, -each with their own unique requirements. - -When CTest sets the :ref:`environment variables -<ctest-hardware-environment-variables>` for a test, it assigns a process number -based on the process description, starting at 0 on the left and the number of -processes minus 1 on the right. For example, in the example above, the two -processes in the first description would have IDs of 0 and 1, and the single -process in the second description would have an ID of 2. - -Both the ``PROCESSES`` and :prop_test:`RESOURCE_LOCK` properties serve similar -purposes, but they are distinct and orthogonal. Resources specified by -``PROCESSES`` do not affect :prop_test:`RESOURCE_LOCK`, and vice versa. Whereas -:prop_test:`RESOURCE_LOCK` is a simpler property that is used for locking one -global resource, ``PROCESSES`` is a more advanced property that allows multiple -tests to simultaneously use multiple resources of the same type, specifying -their requirements in a fine-grained manner. diff --git a/Help/prop_test/RESOURCE_GROUPS.rst b/Help/prop_test/RESOURCE_GROUPS.rst new file mode 100644 index 0000000..63c56ce --- /dev/null +++ b/Help/prop_test/RESOURCE_GROUPS.rst @@ -0,0 +1,70 @@ +RESOURCE_GROUPS +--------------- + +Specify resources required by a test, grouped in a way that is meaningful to +the test. See :ref:`resource allocation <ctest-resource-allocation>` +for more information on how this property integrates into the CTest resource +allocation feature. + +The ``RESOURCE_GROUPS`` property is a :ref:`semicolon-separated list <CMake +Language Lists>` of group descriptions. Each entry consists of an optional +number of groups using the description followed by a series of resource +requirements for those groups. These requirements (and the number of groups) +are separated by commas. The resource requirements consist of the name of a +resource type, followed by a colon, followed by an unsigned integer +specifying the number of slots required on one resource of the given type. + +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. + +Consider the following example: + +.. code-block:: cmake + + add_test(NAME MyTest COMMAND MyExe) + set_property(TEST MyTest PROPERTY RESOURCE_GROUPS + "2,gpus:2" + "gpus:4,crypto_chips:2") + +In this example, there are two group descriptions (implicitly separated by a +semicolon.) The content of the first description is ``2,gpus:2``. This +description specifies 2 groups, each of which requires 2 slots from a single +GPU. The content of the second description is ``gpus:4,crypto_chips:2``. This +description does not specify a group count, so a default of 1 is assumed. +This single group requires 4 slots from a single GPU and 2 slots from a +single cryptography chip. In total, 3 resource groups are specified for this +test, each with its own unique requirements. + +Note that the number of slots following the resource type specifies slots from +a *single* instance of the resource. If the resource group can tolerate +receiving slots from different instances of the same resource, it can indicate +this by splitting the specification into multiple requirements of one slot. For +example: + +.. code-block:: cmake + + add_test(NAME MyTest COMMAND MyExe) + set_property(TEST MyTest PROPERTY RESOURCE_GROUPS + "gpus:1,gpus:1,gpus:1,gpus:1") + +In this case, the single resource group indicates that it needs four GPU slots, +all of which may come from separate GPUs (though they don't have to; CTest may +still assign slots from the same GPU.) + +When CTest sets the :ref:`environment variables +<ctest-resource-environment-variables>` for a test, it assigns a group number +based on the group description, starting at 0 on the left and the number of +groups minus 1 on the right. For example, in the example above, the two +groups in the first description would have IDs of 0 and 1, and the single +group in the second description would have an ID of 2. + +Both the ``RESOURCE_GROUPS`` and :prop_test:`RESOURCE_LOCK` properties serve +similar purposes, but they are distinct and orthogonal. Resources specified by +``RESOURCE_GROUPS`` do not affect :prop_test:`RESOURCE_LOCK`, and vice versa. +Whereas :prop_test:`RESOURCE_LOCK` is a simpler property that is used for +locking one global resource, ``RESOURCE_GROUPS`` is a more advanced property +that allows multiple tests to simultaneously use multiple resources of the +same type, specifying their requirements in a fine-grained manner. diff --git a/Help/prop_test/RESOURCE_LOCK.rst b/Help/prop_test/RESOURCE_LOCK.rst index 7d61f77..8b13a01 100644 --- a/Help/prop_test/RESOURCE_LOCK.rst +++ b/Help/prop_test/RESOURCE_LOCK.rst @@ -9,10 +9,10 @@ not to run concurrently. See also :prop_test:`FIXTURES_REQUIRED` if the resource requires any setup or cleanup steps. -Both the :prop_test:`PROCESSES` and ``RESOURCE_LOCK`` properties serve similar -purposes, but they are distinct and orthogonal. Resources specified by -:prop_test:`PROCESSES` do not affect ``RESOURCE_LOCK``, and vice versa. Whereas -``RESOURCE_LOCK`` is a simpler property that is used for locking one global -resource, :prop_test:`PROCESSES` is a more advanced property that allows -multiple tests to simultaneously use multiple resources of the same type, -specifying their requirements in a fine-grained manner. +Both the :prop_test:`RESOURCE_GROUPS` and ``RESOURCE_LOCK`` properties serve +similar purposes, but they are distinct and orthogonal. Resources specified by +:prop_test:`RESOURCE_GROUPS` do not affect ``RESOURCE_LOCK``, and vice versa. +Whereas ``RESOURCE_LOCK`` is a simpler property that is used for locking one +global resource, :prop_test:`RESOURCE_GROUPS` is a more advanced property +that allows multiple tests to simultaneously use multiple resources of the +same type, specifying their requirements in a fine-grained manner. 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/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst index d8be954..d16a7a1 100644 --- a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst @@ -3,8 +3,12 @@ INSTALL_RPATH_USE_LINK_PATH Add paths to linker search and installed rpath. -``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` will -append directories in the linker search path and outside the project -to the :prop_tgt:`INSTALL_RPATH`. This property is initialized by the value of -the variable ``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` if it is set when a -target is created. +``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` +will append to the runtime search path (rpath) of installed binaries +any directories outside the project that are in the linker search path or +contain linked library files. The directories are appended after the +value of the :prop_tgt:`INSTALL_RPATH` target property. + +This property is initialized by the value of the variable +:variable:`CMAKE_INSTALL_RPATH_USE_LINK_PATH` if it is set when a target is +created. diff --git a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst index 8ff7e8b..e285407 100644 --- a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst +++ b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst @@ -7,6 +7,8 @@ Targets may populate this property to publish the header files for consuming targets to precompile. The :command:`target_precompile_headers` command populates this property with values given to the ``PUBLIC`` and ``INTERFACE`` keywords. Projects may also get and set the property directly. +See the discussion in :command:`target_precompile_headers` for guidance on +appropriate use of this property for installed or exported targets. Contents of ``INTERFACE_PRECOMPILE_HEADERS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` 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/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst b/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst new file mode 100644 index 0000000..7ffa74b --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_WORKING_DIRECTORY +------------------------------ + +Specify the ``Working Directory`` a of the `Run` and `Profile` +action in the generated Xcode scheme. In case the value contains +generator expressions those are evaluated. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index 3f198ca..0d1cc1e 100644 --- a/Help/release/3.16.rst +++ b/Help/release/3.16.rst @@ -192,8 +192,8 @@ Autogen CTest ----- -* :manual:`ctest(1)` now has the ability to serialize tests based on hardware - requirements for each test. See :ref:`ctest-hardware-allocation` for +* :manual:`ctest(1)` now has the ability to schedule tests based on resource + requirements for each test. See :ref:`ctest-resource-allocation` for details. * A new test property, :prop_test:`SKIP_REGULAR_EXPRESSION`, has been added. @@ -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/FindFLEX-work-dir.rst b/Help/release/dev/FindFLEX-work-dir.rst new file mode 100644 index 0000000..3569185 --- /dev/null +++ b/Help/release/dev/FindFLEX-work-dir.rst @@ -0,0 +1,6 @@ +FindFLEX-work-dir +----------------- + +* The :module:`FindFLEX` module's ``FLEX_TARGET`` command now runs ``flex`` + with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory. + See policy :policy:`CMP0098`. diff --git a/Help/release/dev/FindLibArchive-target.rst b/Help/release/dev/FindLibArchive-target.rst new file mode 100644 index 0000000..8998dae --- /dev/null +++ b/Help/release/dev/FindLibArchive-target.rst @@ -0,0 +1,5 @@ +FindLibArchive-target +--------------------- + +* The :module:`FindLibArchive` module now returns an ``IMPORTED`` target + for libarchive. diff --git a/Help/release/dev/command_rm.rst b/Help/release/dev/command_rm.rst new file mode 100644 index 0000000..a58362e --- /dev/null +++ b/Help/release/dev/command_rm.rst @@ -0,0 +1,12 @@ +Command-Line +-------------------- + +* :manual:`cmake(1)` gained a ``rm`` command line + option that can be used to remove directories (with ``-r`` or ``-R`` flag) + and files. + If the ``-f`` flag is not specified, attempting to remove a file that + doesn't exist returns an non-zero error code. + This command deprecates ``remove`` and ``remove_directory``. + The ``remove`` implementation was buggy and always returned 0 when ``force`` + flag was not present and a file didn't exist. It cannot be fixed without + breaking backwards compatibility so we introduced ``rm``. diff --git a/Help/release/dev/compiler-launcher-env.rst b/Help/release/dev/compiler-launcher-env.rst new file mode 100644 index 0000000..58519d9 --- /dev/null +++ b/Help/release/dev/compiler-launcher-env.rst @@ -0,0 +1,5 @@ +compiler-launcher-env +--------------------- + +* The :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable may now be + used to initialize the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable. 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/release/dev/ctest-repeat-until-pass.rst b/Help/release/dev/ctest-repeat-until-pass.rst deleted file mode 100644 index d177247..0000000 --- a/Help/release/dev/ctest-repeat-until-pass.rst +++ /dev/null @@ -1,6 +0,0 @@ -ctest-repeat-until-pass ------------------------ - -* The :manual:`ctest(1)` tool learned new ``--repeat-until-pass <n>`` - and ``--repeat-after-timeout <n>`` options to help tolerate sporadic - test failures. diff --git a/Help/release/dev/ctest-repeat.rst b/Help/release/dev/ctest-repeat.rst new file mode 100644 index 0000000..b1ff59b --- /dev/null +++ b/Help/release/dev/ctest-repeat.rst @@ -0,0 +1,10 @@ +ctest-repeat +------------ + +* The :manual:`ctest(1)` tool gained a ``--repeat <mode>:<n>`` option + to specify conditions in which to repeat tests. This generalizes + the existing ``--repeat-until-fail <n>`` option to add modes for + ``until-pass`` and ``after-timeout``. + +* The :command:`ctest_test` command gained a ``REPEAT <mode>:<n>`` option + to specify conditions in which to repeat tests. diff --git a/Help/release/dev/fileapi-multi-config.rst b/Help/release/dev/fileapi-multi-config.rst new file mode 100644 index 0000000..e0e2e16 --- /dev/null +++ b/Help/release/dev/fileapi-multi-config.rst @@ -0,0 +1,6 @@ +fileapi-multi-config +-------------------- + +* The :manual:`file API <cmake-file-api(7)>` index file now emits a + ``multiConfig`` flag specifying whether or not the generator supports + multiple output configurations. diff --git a/Help/release/dev/load_cache-script-mode.rst b/Help/release/dev/load_cache-script-mode.rst new file mode 100644 index 0000000..d84b08a --- /dev/null +++ b/Help/release/dev/load_cache-script-mode.rst @@ -0,0 +1,5 @@ +load_cache-script-mode +---------------------- + +* The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed + when using ``cmake -P`` to :ref:`Run a Script <Script Processing Mode>`. diff --git a/Help/release/dev/ninja-tool.rst b/Help/release/dev/ninja-tool.rst new file mode 100644 index 0000000..aa0292e --- /dev/null +++ b/Help/release/dev/ninja-tool.rst @@ -0,0 +1,7 @@ +ninja-tool +---------- + +* The :generator:`Ninja` generator now prefers the first ninja build + tool to appear in the ``PATH`` no matter whether it is called + ``ninja-build``, ``ninja``, or ``samu``. Previously the first + of those names to appear anywhere in the ``PATH`` would be preferred. diff --git a/Help/release/dev/sdcc-new-librarian.rst b/Help/release/dev/sdcc-new-librarian.rst new file mode 100644 index 0000000..93961ce --- /dev/null +++ b/Help/release/dev/sdcc-new-librarian.rst @@ -0,0 +1,6 @@ +sdcc-new-librarian +------------------ + +* Since sdcc 3.2.0, sdcclib has been deprecated in favor of sdar as librarian. + Since sdcc 3.8.6, it has been removed from the distribution. + Use sdar if found, else use sdcclib to keep older compatibility. diff --git a/Help/release/dev/xcode-scheme-workdir.rst b/Help/release/dev/xcode-scheme-workdir.rst new file mode 100644 index 0000000..8eb5ed8 --- /dev/null +++ b/Help/release/dev/xcode-scheme-workdir.rst @@ -0,0 +1,7 @@ +xcode-scheme-workdir +-------------------- + +* The Xcode generator learnt to set the value of the + ``Custom Working Directory`` schema + option with the :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` + target property. diff --git a/Help/release/dev/xlf-ninja.rst b/Help/release/dev/xlf-ninja.rst new file mode 100644 index 0000000..916e713 --- /dev/null +++ b/Help/release/dev/xlf-ninja.rst @@ -0,0 +1,5 @@ +xlf-ninja +--------- + +* The IBM XL Fortran compiler is now supported by the :generator:`Ninja` + generator. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst index ba8a850..5f08728 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst @@ -3,6 +3,13 @@ CMAKE_HOST_SYSTEM_PROCESSOR The name of the CPU CMake is running on. -On systems that support ``uname``, this variable is set to the output of -``uname -p``. On Windows it is set to the value of the environment variable -``PROCESSOR_ARCHITECTURE``. +On Windows, this variable is set to the value of the environment variable +``PROCESSOR_ARCHITECTURE``. On systems that support ``uname``, this variable is +set to the output of: + +- ``uname -m`` on GNU, Linux, Cygwin, Darwin, Android, or +- ``arch`` on OpenBSD, or +- on other systems, + + * ``uname -p`` if its exit code is nonzero, or + * ``uname -m`` otherwise. diff --git a/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst index 78148d5..a99c108 100644 --- a/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst +++ b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst @@ -3,7 +3,11 @@ CMAKE_INSTALL_RPATH_USE_LINK_PATH Add paths to linker search and installed rpath. -``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``true`` -will append directories in the linker search path and outside the -project to the :prop_tgt:`INSTALL_RPATH`. This is used to initialize the -target property :prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` for all targets. +``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` +will append to the runtime search path (rpath) of installed binaries +any directories outside the project that are in the linker search path or +contain linked library files. The directories are appended after the +value of the :prop_tgt:`INSTALL_RPATH` target property. + +This varibale is used to initialize the target property +:prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` for all targets. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index e6c8bb5..e5dda60 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -5,3 +5,6 @@ Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. This variable is used to initialize the property on each target as it is created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, or ``CUDA``. + +This variable is initialized to the :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` +environment variable if it is set. 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. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst new file mode 100644 index 0000000..cc690f7 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_WORKING_DIRECTORY +------------------------------------ + +Specify the ``Working Directory`` a of the `Run` and `Profile` +action in the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. |