diff options
Diffstat (limited to 'Help')
122 files changed, 1467 insertions, 85 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index aba3742..576ed5b 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -112,9 +112,11 @@ The options are: build time. ``DEPENDS`` - Specify files on which the command depends. If any dependency is - an ``OUTPUT`` of another custom command in the same directory - (``CMakeLists.txt`` file) CMake automatically brings the other + Specify files on which the command depends. Entries in the ``DEPENDS`` + argument list which may also be target names are assumed to be target names, + so only entries which contain a path separator are detected as file paths. + If any dependency is an ``OUTPUT`` of another custom command in the same + directory (``CMakeLists.txt`` file) CMake automatically brings the other custom command into the target in which this command is built. A target-level dependency is added if any dependency is listed as ``BYPRODUCTS`` of a target or any of its build events in the same diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 7a3393b..5c67b2c 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -23,6 +23,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [STOP_TIME <time-of-day>] [RETURN_VALUE <result-var>] [CAPTURE_CMAKE_ERROR <result-var>] + [REPEAT <mode>:<n>] [QUIET] ) @@ -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/foreach.rst b/Help/command/foreach.rst index ae2afb2..a01a104 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -47,7 +47,7 @@ of undocumented behavior that may change in future releases. .. code-block:: cmake - foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]]) + foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]]) In this variant, ``<lists>`` is a whitespace or semicolon separated list of list-valued variables. The ``foreach`` @@ -82,3 +82,46 @@ yields -- X=6 -- X=7 -- X=8 + + +.. code-block:: cmake + + foreach(<loop_var>... IN ZIP_LISTS <lists>) + +In this variant, ``<lists>`` is a whitespace or semicolon +separated list of list-valued variables. The ``foreach`` +command iterates over each list simultaneously setting the +iteration variables as follows: + +- if the only ``loop_var`` given, then it sets a series of + ``loop_var_N`` variables to the current item from the + corresponding list; +- if multiple variable names passed, their count should match + the lists variables count; +- if any of the lists are shorter, the corresponding iteration + variable is not defined for the current iteration. + +.. code-block:: cmake + + list(APPEND English one two three four) + list(APPEND Bahasa satu dua tiga) + + foreach(num IN ZIP_LISTS English Bahasa) + message(STATUS "num_0=${num_0}, num_1=${num_1}") + endforeach() + + foreach(en ba IN ZIP_LISTS English Bahasa) + message(STATUS "en=${en}, ba=${ba}") + endforeach() + +yields +:: + + -- num_0=one, num_1=satu + -- num_0=two, num_1=dua + -- num_0=three, num_1=tiga + -- num_0=four, num_1= + -- en=one, ba=satu + -- en=two, ba=dua + -- en=three, ba=tiga + -- en=four, ba= diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 05e5d79..3f6f2f9 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -91,6 +91,12 @@ just terminate execution of the macro; rather, control is returned from the scope of the macro call. To avoid confusion, it is recommended to avoid :command:`return()` in macros altogether. +Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not +set for macro. + .. _`Argument Caveats`: Argument Caveats diff --git a/Help/command/message.rst b/Help/command/message.rst index c614286..6bc0e4c 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -1,13 +1,33 @@ message ------- -Display a message to the user. +Log a message. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `General messages`_ + message([<mode>] "message text" ...) + + `Reporting checks`_ + message(<checkState> "message text" ...) + + +General messages +^^^^^^^^^^^^^^^^ .. code-block:: cmake - message([<mode>] "message to display" ...) + message([<mode>] "message text" ...) + +Record the specified message text in the log. If more than one message +string is given, they are concatenated into a single message with no +separator between the strings. -The optional ``<mode>`` keyword determines the type of message: +The optional ``<mode>`` keyword determines the type of message, which +influences the way the message is handled: ``FATAL_ERROR`` CMake Error, stop processing and generation. @@ -59,12 +79,104 @@ The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE`` messages one at a time on a status line and other messages in an interactive pop-up box. The ``--log-level`` command-line option to each of these tools can be used to control which messages will be shown. +To make a log level persist between CMake runs, the +:variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead. +Note that the command line option takes precedence over the cache variable. -Messages of log levels ``NOTICE`` and below will also have each line preceded +Messages of log levels ``NOTICE`` and below will have each line preceded by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to a single string by concatenating its list items). For ``STATUS`` to ``TRACE`` messages, this indenting content will be inserted after the hyphens. +Messages of log levels ``NOTICE`` and below can also have each line preceded +with context of the form ``[some.context.example]``. The content between the +square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT` +list variable to a dot-separated string. The message context will always +appear before any indenting content but after any automatically added leading +hyphens. By default, message context is not shown, it has to be explicitly +enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context`` +command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` +variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for +usage examples. + CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs delimited by newlines. Indented text is considered pre-formatted. + + +Reporting checks +^^^^^^^^^^^^^^^^ + +A common pattern in CMake output is a message indicating the start of some +sort of check, followed by another message reporting the result of that check. +For example: + +.. code-block:: cmake + + message(STATUS "Looking for someheader.h") + #... do the checks, set checkSuccess with the result + if(checkSuccess) + message(STATUS "Looking for someheader.h - found") + else() + message(STATUS "Looking for someheader.h - not found") + endif() + +This can be more robustly and conveniently expressed using the ``CHECK_...`` +keyword form of the ``message()`` command: + +.. code-block:: cmake + + message(<checkState> "message" ...) + +where ``<checkState>`` must be one of the following: + + ``CHECK_START`` + Record a concise message about the check about to be performed. + + ``CHECK_PASS`` + Record a successful result for a check. + + ``CHECK_FAIL`` + Record an unsuccessful result for a check. + +When recording a check result, the command repeats the message from the most +recently started check for which no result has yet been reported, then some +separator characters and then the message text provided after the +``CHECK_PASS`` or ``CHECK_FAIL`` keyword. Check messages are always reported +at ``STATUS`` log level. + +Checks may be nested and every ``CHECK_START`` should have exactly one +matching ``CHECK_PASS`` or ``CHECK_FAIL``. +The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add +indenting to nested checks if desired. For example: + +.. code-block:: cmake + + message(CHECK_START "Finding my things") + list(APPEND CMAKE_MESSAGE_INDENT " ") + unset(missingComponents) + + message(CHECK_START "Finding partA") + # ... do check, assume we find A + message(CHECK_PASS "found") + + message(CHECK_START "Finding partB") + # ... do check, assume we don't find B + list(APPEND missingComponents B) + message(CHECK_FAIL "not found") + + list(POP_BACK CMAKE_MESSAGE_INDENT) + if(missingComponents) + message(CHECK_FAIL "missing components: ${missingComponents}") + else() + message(CHECK_PASS "all components found") + endif() + +Output from the above would appear something like the following:: + + -- Finding my things + -- Finding partA + -- Finding partA - found + -- Finding partB + -- Finding partB - not found + -- Finding my things - missing components: B diff --git a/Help/command/project.rst b/Help/command/project.rst index 3951456..b6093d3 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -102,9 +102,12 @@ options are intended for use as default values in package metadata and documenta Code Injection ^^^^^^^^^^^^^^ -If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file -pointed to by that variable will be included as the first step of the +If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set, +the files they point to will be included as the first step of the ``project()`` command. +If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be +included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`. If the :variable:`CMAKE_PROJECT_INCLUDE` or :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index 9271cd5..c5401e6 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -8,9 +8,9 @@ Add expected compiler features to a target. target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) Specifies compiler features required when compiling a given target. If the -feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable -or :variable:`CMAKE_CXX_COMPILE_FEATURES` variable, -then an error will be reported by CMake. If the use of the feature requires +feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`, +:variable:`CMAKE_CUDA_COMPILE_FEATURES`, or :variable:`CMAKE_CXX_COMPILE_FEATURES` +variables, then an error will be reported by CMake. If the use of the feature requires an additional compiler flag, such as ``-std=gnu++11``, the flag will be added automatically. diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index cd2aea6..a310e9f 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -128,3 +128,28 @@ on Windows Nullsoft Scriptable Install System. set(CPACK_NSIS_MENU_LINKS "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html" "CMake Help" "https://cmake.org" "CMake Web Site") + +.. variable:: CPACK_NSIS_UNINSTALL_NAME + + Specify the name of the program to uninstall the version. + Default is ``Uninstall``. + +.. variable:: CPACK_NSIS_WELCOME_TITLE + + The title to display on the top of the page for the welcome page. + +.. variable:: CPACK_NSIS_WELCOME_TITLE_3LINES + + Display the title in the welcome page on 3 lines instead of 2. + +.. variable:: CPACK_NSIS_FINISH_TITLE + + The title to display on the top of the page for the finish page. + +.. variable:: CPACK_NSIS_FINISH_TITLE_3LINES + + Display the title in the finish page on 3 lines instead of 2. + +.. variable:: CPACK_NSIS_MUI_HEADERIMAGE + + The image to display on the header of installers pages. 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_EXPORT_COMPILE_COMMANDS.rst b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 0000000..e9e0810 --- /dev/null +++ b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,9 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +.. include:: ENV_VAR.txt + +The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there +is no explicit configuration given on the first run while creating a new +build tree. On later runs in an existing build tree the value persists in +the cache as :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`. 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/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst new file mode 100644 index 0000000..92ca760 --- /dev/null +++ b/Help/generator/Ninja Multi-Config.rst @@ -0,0 +1,81 @@ +Ninja Multi-Config +------------------ + +Generates multiple ``build-<Config>.ninja`` files. + +This generator is very much like the :generator:`Ninja` generator, but with +some key differences. Only these differences will be discussed in this +document. + +Unlike the :generator:`Ninja` generator, ``Ninja Multi-Config`` generates +multiple configurations at once with :variable:`CMAKE_CONFIGURATION_TYPES` +instead of only one configuration with :variable:`CMAKE_BUILD_TYPE`. One +``build-<Config>.ninja`` file will be generated for each of these +configurations (with ``<Config>`` being the configuration name.) No +``build.ninja`` file is generated, unless +:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` is specified. You must specify +the desired ``build-<Config>.ninja`` file with ``ninja -f``. Running +``cmake --build . --config <Config> --target <target>`` will run Ninja with +``build-<Config>.ninja`` as the ``-f`` file and ``<target>`` as the build +target. + +If :variable:`CMAKE_NINJA_CROSS_CONFIG_ENABLE` is turned on, executables and +libraries of any configuration can be built regardless of which +``build-<Config>.ninja`` file is used, simply by specifying +``<target>:<OtherConfig>`` as the Ninja target. You can also specify +``<target>:all`` to build a target in all configurations. Each +``build-<Config>.ninja`` file will additionally have ``<target>`` targets which +are aliases for ``<target>:<Config>``. However, custom commands and custom +targets will always use the configuration specified in +``build-<Config>.ninja``. This is due to the fact that it is impossible in +Ninja for the same file to be output with different commands in the same build +graph. + +If :variable:`CMAKE_NINJA_CROSS_CONFIG_ENABLE` is not enabled, you can still +build any target in ``build-<Config>.ninja`` by specifying +``<target>:<Config>`` or ``<target>``, but not ``<target>:<OtherConfig>`` or +``<target>:all``. + +Consider the following example: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.16) + project(MultiConfigNinja C) + + add_executable(generator generator.c) + add_custom_command(OUTPUT generated.c COMMAND generator generated.c) + add_library(generated ${CMAKE_BINARY_DIR}/generated.c) + +Now assume you configure the project with ``Ninja Multi-Config`` and run one of +the following commands: + +.. code-block:: shell + + ninja -f build-Debug.ninja generated + # OR + cmake --build . --config Debug --target generated + +This would build the ``Debug`` configuration of ``generator``, which would be +used to generate ``generated.c``, which would be used to build the ``Debug`` +configuration of ``generated``. + +But if :variable:`CMAKE_NINJA_CROSS_CONFIG_ENABLE` is enabled, and you run the +following instead: + +.. code-block:: shell + + ninja -f build-Release.ninja generated:Debug + # OR + cmake --build . --config Release --target generated:Debug + +This would build the ``Release`` configuration of ``generator``, which would be +used to generate ``generated.c``, which would be used to build the ``Debug`` +configuration of ``generated``. This is useful for running a release-optimized +version of a generator utility while still building the debug version of the +targets built with the generated code. + +As a convenience, ``Ninja Multi-Config`` offers a +:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` setting. If this variable is +specified, a ``build.ninja`` file will be generated which points to the +specified ``build-<Config>.ninja`` file. diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index c75d2c4..275055d 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -1,7 +1,7 @@ Ninja ----- -Generates build.ninja files. +Generates ``build.ninja`` files. A ``build.ninja`` file is generated into the build tree. Use the ninja program to build the project through the ``all`` target and install the @@ -38,3 +38,9 @@ features have not been integrated into upstream Ninja. Kitware maintains a branch of Ninja with the required features on `github.com/Kitware/ninja`_. .. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme + +See Also +^^^^^^^^ + +The :generator:`Ninja Multi-Config` generator is similar to the ``Ninja`` +generator, but generates multiple configurations at once. diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index a14e322..05dc038 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -19,11 +19,11 @@ While features are typically specified in programming language standards, CMake provides a primary user interface based on granular handling of the features, not the language standard that introduced the feature. -The :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and -:prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global properties contain all the +The :prop_gbl:`CMAKE_C_KNOWN_FEATURES`, :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`, +and :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global properties contain all the features known to CMake, regardless of compiler support for the feature. -The :variable:`CMAKE_C_COMPILE_FEATURES` and -:variable:`CMAKE_CXX_COMPILE_FEATURES` variables contain all features +The :variable:`CMAKE_C_COMPILE_FEATURES`, :variable:`CMAKE_CUDA_COMPILE_FEATURES` +, and :variable:`CMAKE_CXX_COMPILE_FEATURES` variables contain all features CMake knows are known to the compiler, regardless of language standard or compile flags needed to use them. @@ -368,8 +368,9 @@ versions specified for each: * all compilers and versions listed above with only meta-features for C++. * ``TI``: Texas Instruments compiler. -CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` -from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` and +their associated meta-features (e.g. ``cuda_std_11``) available from the +following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * ``NVIDIA``: NVIDIA nvcc compiler 7.5+. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 96ceb94..adfc39e 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -23,10 +23,12 @@ Environment Variables that Control the Build /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /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-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 75f4bd4..691481b 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -596,7 +596,8 @@ Target-Dependent Queries requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via - :command:`install(EXPORT)` and empty otherwise. + :command:`install(EXPORT)`, or when evaluated in + :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. Output-Related Expressions -------------------------- diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 41f7652..6f88c0a 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -52,13 +52,14 @@ Makefile Generators /generator/Unix Makefiles /generator/Watcom WMake -Ninja Generator -^^^^^^^^^^^^^^^ +Ninja Generators +^^^^^^^^^^^^^^^^ .. toctree:: :maxdepth: 1 /generator/Ninja + /generator/Ninja Multi-Config .. _`IDE Build Tool Generators`: diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index c60dc40..be64112 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -122,6 +122,7 @@ They are normally called through the :command:`find_package` command. /module/FindCABLE /module/FindCoin3D /module/FindCups + /module/FindCUDAToolkit /module/FindCURL /module/FindCurses /module/FindCVS diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 44ea1a8..53cf264 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,17 @@ 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 + + CMP0101: target_compile_options honors BEFORE keyword in all scopes. </policy/CMP0101> + CMP0100: Let AUTOMOC and AUTOUIC process .hh header files. </policy/CMP0100> + CMP0099: Link properties are transitive over private dependency on static libraries. </policy/CMP0099> + 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 e704371..b3802d1 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -22,10 +22,13 @@ Properties of Global Scope /prop_gbl/AUTOMOC_TARGETS_FOLDER /prop_gbl/AUTORCC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES + /prop_gbl/CMAKE_CUDA_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES /prop_gbl/CMAKE_ROLE /prop_gbl/DEBUG_CONFIGURATIONS /prop_gbl/DISABLED_FEATURES + /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS + /prop_gbl/ECLIPSE_EXTRA_NATURES /prop_gbl/ENABLED_FEATURES /prop_gbl/ENABLED_LANGUAGES /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS @@ -36,12 +39,10 @@ Properties of Global Scope /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE /prop_gbl/GLOBAL_DEPENDS_NO_CYCLES /prop_gbl/IN_TRY_COMPILE + /prop_gbl/JOB_POOLS /prop_gbl/PACKAGES_FOUND /prop_gbl/PACKAGES_NOT_FOUND - /prop_gbl/JOB_POOLS /prop_gbl/PREDEFINED_TARGETS_FOLDER - /prop_gbl/ECLIPSE_EXTRA_NATURES - /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS /prop_gbl/REPORT_UNDEFINED_PROPERTIES /prop_gbl/RULE_LAUNCH_COMPILE /prop_gbl/RULE_LAUNCH_CUSTOM @@ -129,20 +130,20 @@ Properties on Targets /prop_tgt/AUTOGEN_ORIGIN_DEPENDS /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS /prop_tgt/AUTOMOC_EXECUTABLE /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC_PATH_PREFIX - /prop_tgt/AUTOMOC + /prop_tgt/AUTORCC + /prop_tgt/AUTORCC_EXECUTABLE + /prop_tgt/AUTORCC_OPTIONS /prop_tgt/AUTOUIC /prop_tgt/AUTOUIC_EXECUTABLE /prop_tgt/AUTOUIC_OPTIONS /prop_tgt/AUTOUIC_SEARCH_PATHS - /prop_tgt/AUTORCC - /prop_tgt/AUTORCC_EXECUTABLE - /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH /prop_tgt/BUILD_RPATH_USE_ORIGIN @@ -182,6 +183,7 @@ Properties on Targets /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DEPRECATION /prop_tgt/DISABLE_PRECOMPILE_HEADERS /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString @@ -348,6 +350,7 @@ Properties on Targets /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/VS_DOTNET_DOCUMENTATION_FILE /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES @@ -380,6 +383,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 @@ -442,8 +446,8 @@ Properties on Source Files :maxdepth: 1 /prop_sf/ABSTRACT - /prop_sf/AUTOUIC_OPTIONS /prop_sf/AUTORCC_OPTIONS + /prop_sf/AUTOUIC_OPTIONS /prop_sf/COMPILE_DEFINITIONS /prop_sf/COMPILE_FLAGS /prop_sf/COMPILE_OPTIONS diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 53b7f8d..26f1d80 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -37,10 +37,15 @@ Variables that Provide Information /variable/CMAKE_CROSSCOMPILING_EMULATOR /variable/CMAKE_CTEST_COMMAND /variable/CMAKE_CURRENT_BINARY_DIR + /variable/CMAKE_CURRENT_FUNCTION + /variable/CMAKE_CURRENT_FUNCTION_LIST_DIR + /variable/CMAKE_CURRENT_FUNCTION_LIST_FILE + /variable/CMAKE_CURRENT_FUNCTION_LIST_LINE /variable/CMAKE_CURRENT_LIST_DIR /variable/CMAKE_CURRENT_LIST_FILE /variable/CMAKE_CURRENT_LIST_LINE /variable/CMAKE_CURRENT_SOURCE_DIR + /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION @@ -48,6 +53,7 @@ Variables that Provide Information /variable/CMAKE_EXECUTABLE_SUFFIX /variable/CMAKE_EXTRA_GENERATOR /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES + /variable/CMAKE_FIND_DEBUG_MODE /variable/CMAKE_FIND_PACKAGE_NAME /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER @@ -70,7 +76,6 @@ Variables that Provide Information /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MATCH_n - /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION /variable/CMAKE_NETRC @@ -155,7 +160,6 @@ Variables that Change Behavior /variable/CMAKE_CODELITE_USE_TARGETS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES - /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName /variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES @@ -206,7 +210,12 @@ Variables that Change Behavior /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH + /variable/CMAKE_MESSAGE_CONTEXT + /variable/CMAKE_MESSAGE_CONTEXT_SHOW + /variable/CMAKE_MESSAGE_INDENT + /variable/CMAKE_MESSAGE_LOG_LEVEL /variable/CMAKE_MODULE_PATH + /variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN /variable/CMAKE_PREFIX_PATH @@ -214,6 +223,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE + /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -235,10 +245,12 @@ 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 /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_ENVIRONMENT /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES @@ -411,6 +423,7 @@ Variables that Control the Build /variable/CMAKE_MODULE_LINKER_FLAGS_INIT /variable/CMAKE_MSVCIDE_RUN_PATH /variable/CMAKE_MSVC_RUNTIME_LIBRARY + /variable/CMAKE_NINJA_CROSS_CONFIG_ENABLE /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -466,6 +479,7 @@ Variables for Languages /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 + /variable/CMAKE_CUDA_COMPILE_FEATURES /variable/CMAKE_CUDA_HOST_COMPILER /variable/CMAKE_CUDA_EXTENSIONS /variable/CMAKE_CUDA_STANDARD diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 4ab55a0..4315f0a 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -206,9 +206,24 @@ Options The :command:`message` command will only output messages of the specified log level or higher. The default log level is ``STATUS``. + To make a log level persist between CMake runs, set + :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead. + If both the command line option and the variable are given, the command line + option takes precedence. + For backward compatibility reasons, ``--loglevel`` is also accepted as a synonym for this option. +``--log-context`` + Enable the :command:`message` command outputting context attached to each + message. + + This option turns on showing context for the current CMake run only. + To make showing the context persistent for all subsequent CMake runs, set + :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead. + When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` + is ignored. + ``--debug-trycompile`` Do not delete the :command:`try_compile` build tree. Only useful on one :command:`try_compile` at a time. @@ -226,6 +241,12 @@ Options Print extra information during the cmake run like stack traces with :command:`message(SEND_ERROR)` calls. +``--debug-find`` + Put cmake find in a debug mode. + + Print extra find call information during the cmake run to standard + error. Output is designed for human consumption and not for parsing. + ``--trace`` Put cmake in trace mode. @@ -236,6 +257,66 @@ Options Like ``--trace``, but with variables expanded. +``--trace-format=<format>`` + Put cmake in trace mode and sets the trace output format. + + ``<format>`` can be one of the following values. + + ``human`` + Prints each trace line in a human-readable format. This is the + default format. + + ``json`` + Prints each line as a separate JSON document. Each document is + separated by a newline ( ``\n`` ). It is guaranteed that no + newline characters will be present inside a JSON document. + + JSON trace format: + + .. code-block:: json + + { + "file": "/full/path/to/the/CMake/file.txt", + "line": 0, + "cmd": "add_executable", + "args": ["foo", "bar"] + } + + The members are: + + ``file`` + The full path to the CMake source file where the function + was called. + + ``line`` + The line in `file` of the function call. + + ``cmd`` + The name of the function that was called. + + ``args`` + A string list of all function parameters. + + Additionally, the first JSON document outputted contains the + ``version`` key for the current major and minor version of the + + JSON trace format: + + .. code-block:: json + + { + "version": { + "major": 1, + "minor": 0 + } + } + + The members are: + + ``version`` + Indicates the version of the JSON format. The version has a + major and minor components following semantic version conventions. + ``--trace-source=<file>`` Put cmake in trace mode, but output only lines of a specified file. @@ -539,22 +620,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/ctest.1.rst b/Help/manual/ctest.1.rst index e29ebca..25cb639 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -261,10 +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. +``--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. - This is useful in finding 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. + +``--repeat-until-fail <n>`` + Equivalent to ``--repeat until-fail:<n>``. ``--max-width <width>`` Set the max width for a test name to output. @@ -1096,6 +1113,20 @@ Additional configuration settings include: * `CTest Script`_ variable: none * :module:`CTest` module variable: ``VALGRIND_COMMAND_OPTIONS`` +``DrMemoryCommand`` + Specify a ``MemoryCheckCommand`` that is known to be a command-line + compatible with DrMemory. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``DRMEMORY_COMMAND`` + +``DrMemoryCommandOptions`` + Specify command-line options to the ``DrMemoryCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``DRMEMORY_COMMAND_OPTIONS`` + .. _`CTest Submit Step`: CTest Submit Step diff --git a/Help/module/FindCUDAToolkit.rst b/Help/module/FindCUDAToolkit.rst new file mode 100644 index 0000000..5f01d68 --- /dev/null +++ b/Help/module/FindCUDAToolkit.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCUDAToolkit.cmake 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/policy/CMP0099.rst b/Help/policy/CMP0099.rst new file mode 100644 index 0000000..c897e7b --- /dev/null +++ b/Help/policy/CMP0099.rst @@ -0,0 +1,24 @@ +CMP0099 +------- + +Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`, +:prop_tgt:`INTERFACE_LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DEPENDS` +are now transitive over private dependencies of static libraries. + +In CMake 3.16 and below the interface link properties attached to libraries +are not propagated for private dependencies of static libraries. +Only the libraries themselves are propagated to link the dependent binary. +CMake 3.17 and later prefer to propagate all interface link properties. +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is to not propagate interface link +properties. The ``NEW`` behavior of this policy is to propagate interface link +properties. + +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/policy/CMP0100.rst b/Help/policy/CMP0100.rst new file mode 100644 index 0000000..b24d013 --- /dev/null +++ b/Help/policy/CMP0100.rst @@ -0,0 +1,40 @@ +CMP0100 +------- + +Let :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process +header files that end with a ``.hh`` extension. + +Since version 3.17, CMake processes header files that end with a +``.hh`` extension in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. +In earlier CMake versions, these header files were ignored by +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +This policy affects how header files that end with a ``.hh`` extension +get treated in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``OLD`` behavior for this policy is to ignore ``.hh`` header files +in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``NEW`` behavior for this policy is to process ``.hh`` header files +in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` just like other header files. + +.. note:: + + To silence the ``CMP0100`` warning source files can be excluded from + :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the + source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or + :prop_sf:`SKIP_AUTOGEN`. + + .. code-block:: cmake + + # Source skip example: + set_property(SOURCE /path/to/file1.hh PROPERTY SKIP_AUTOMOC ON) + set_property(SOURCE /path/to/file2.hh PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE /path/to/file3.hh PROPERTY SKIP_AUTOGEN ON) + +This policy was introduced in CMake version 3.17.0. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0101.rst b/Help/policy/CMP0101.rst new file mode 100644 index 0000000..9941acf --- /dev/null +++ b/Help/policy/CMP0101.rst @@ -0,0 +1,20 @@ +CMP0101 +------- + +:command:`target_compile_options` now honors ``BEFORE`` keyword in all scopes. + +In CMake 3.16 and below the :command:`target_compile_options` ignores the +``BEFORE`` keyword in private scope. CMake 3.17 and later honors +``BEFORE`` keyword in all scopes. This policy provides compatibility for +projects that have not been updated to expect the new behavior. + +The ``OLD`` behavior for this policy is to not honor ``BEFORE`` keyword in +private scope. The ``NEW`` behavior of this policy is to honor +``BEFORE`` keyword in all scopes. + +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_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst new file mode 100644 index 0000000..44e37fe --- /dev/null +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -0,0 +1,30 @@ +CMAKE_CUDA_KNOWN_FEATURES +------------------------- + +List of CUDA features known to this version of CMake. + +The features listed in this global property may be known to be available to the +CUDA compiler. If the feature is available with the C++ compiler, it will +be listed in the :variable:`CMAKE_CUDA_COMPILE_FEATURES` variable. + +The features listed here may be used with the :command:`target_compile_features` +command. See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + + +The features known to this version of CMake are: + +``cuda_std_03`` + Compiler mode is at least CUDA/C++ 03. + +``cuda_std_11`` + Compiler mode is at least CUDA/C++ 11. + +``cuda_std_14`` + Compiler mode is at least CUDA/C++ 14. + +``cuda_std_17`` + Compiler mode is at least CUDA/C++ 17. + +``cuda_std_20`` + Compiler mode is at least CUDA/C++ 20. diff --git a/Help/prop_tgt/AUTOGEN_PARALLEL.rst b/Help/prop_tgt/AUTOGEN_PARALLEL.rst index 07fbc5a..968b619 100644 --- a/Help/prop_tgt/AUTOGEN_PARALLEL.rst +++ b/Help/prop_tgt/AUTOGEN_PARALLEL.rst @@ -4,9 +4,9 @@ AUTOGEN_PARALLEL Number of parallel ``moc`` or ``uic`` processes to start when using :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. -The custom `<origin>_autogen` target starts a number of threads of which +The custom ``<origin>_autogen`` target starts a number of threads of which each one parses a source file and on demand starts a ``moc`` or ``uic`` -process. :prop_tgt:`AUTOGEN_PARALLEL` controls how many parallel threads +process. ``AUTOGEN_PARALLEL`` controls how many parallel threads (and therefore ``moc`` or ``uic`` processes) are started. - An empty (or unset) value or the string ``AUTO`` sets the number of @@ -14,7 +14,7 @@ process. :prop_tgt:`AUTOGEN_PARALLEL` controls how many parallel threads - A positive non zero integer value sets the exact thread/process count. - Otherwise a single thread/process is started. -By default :prop_tgt:`AUTOGEN_PARALLEL` is initialized from +By default ``AUTOGEN_PARALLEL`` is initialized from :variable:`CMAKE_AUTOGEN_PARALLEL`. See the :manual:`cmake-qt(7)` manual for more information on using CMake diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index f6dfabd..c18859b 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -172,7 +172,7 @@ variables. If the call is in a different context than the then the version variables might not be available to the :prop_tgt:`AUTOMOC` enabled target. In that case the version variables can be forwarded from the -`find_package(Qt[45]...)` calling context to the :command:`add_executable` +``find_package(Qt[45]...)`` calling context to the :command:`add_executable` or :command:`add_library` calling context as directory properties. The following Qt5 example demonstrates the procedure. diff --git a/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst index ebd5c49..330849b 100644 --- a/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst @@ -1,7 +1,7 @@ AUTOMOC_MOC_OPTIONS ------------------- -Additional options for moc when using :prop_tgt:`AUTOMOC` +Additional options for ``moc`` when using :prop_tgt:`AUTOMOC` This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` for this target. In this case, it holds additional command line @@ -9,7 +9,9 @@ options which will be used when ``moc`` is executed during the build, i.e. it is equivalent to the optional ``OPTIONS`` argument of the :module:`qt4_wrap_cpp() <FindQt4>` macro. -By default it is empty. +This property is initialized by the value of the +:variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable if it is set when a target +is created, or an empty string otherwise. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst index e2ebb3f..3e3059d 100644 --- a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst +++ b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst @@ -21,11 +21,11 @@ with Qt. Reproducible builds ^^^^^^^^^^^^^^^^^^^ -For reproducible builds is is recommended to keep headers that are ``moc`` +For reproducible builds it is recommended to keep headers that are ``moc`` compiled in one of the target :command:`include directories <target_include_directories>` and set :prop_tgt:`AUTOMOC_PATH_PREFIX` to ``ON`` (which is the default). This ensures -that +that: - ``moc`` output files are identical on different build setups, - ``moc`` output files will compile correctly when the source and/or diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index cca3e58..9a98f44 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -31,9 +31,10 @@ Modifiers The ``rcc`` executable will be detected automatically, but can be forced to a certain binary by setting this target property. -:prop_sf:`AUTORCC_OPTIONS`: -Additional command line options for ``rcc`` can be set via this ``.qrc`` -source file property. +:prop_tgt:`AUTORCC_OPTIONS`: +Additional command line options for ``rcc`` can be set via this target +property. The corresponding :prop_sf:`AUTORCC_OPTIONS` source file property +can be used to specify options to be applied only to a specific ``.qrc`` file. :prop_sf:`SKIP_AUTORCC`: ``.qrc`` files can be excluded from :prop_tgt:`AUTORCC` processing by diff --git a/Help/prop_tgt/AUTORCC_OPTIONS.rst b/Help/prop_tgt/AUTORCC_OPTIONS.rst index d6ade5a..5261aff 100644 --- a/Help/prop_tgt/AUTORCC_OPTIONS.rst +++ b/Help/prop_tgt/AUTORCC_OPTIONS.rst @@ -8,11 +8,9 @@ when ``rcc`` is executed during the build via :prop_tgt:`AUTORCC`, i.e. it is equivalent to the optional ``OPTIONS`` argument of the :module:`qt4_add_resources() <FindQt4>` macro. -By default it is empty. - This property is initialized by the value of the :variable:`CMAKE_AUTORCC_OPTIONS` variable if it is set when a target is -created. +created, or an empty string otherwise. The options set on the target may be overridden by :prop_sf:`AUTORCC_OPTIONS` set on the ``.qrc`` source file. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 5cf8755..cd24f5e 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -52,8 +52,11 @@ Modifiers The ``uic`` executable will be detected automatically, but can be forced to a certain binary using this target property. -:prop_sf:`AUTOUIC_OPTIONS`: Additional command line options for ``uic`` can -be set via this source file property on a ``<base_name>.ui`` file. +:prop_tgt:`AUTOUIC_OPTIONS`: +Additional command line options for ``uic`` can be set via this target +property. The corresponding :prop_sf:`AUTOUIC_OPTIONS` source file property +can be used to specify options to be applied only to a specific +``<base_name>.ui`` file. :prop_sf:`SKIP_AUTOUIC`: Source files can be excluded from :prop_tgt:`AUTOUIC` processing by setting diff --git a/Help/prop_tgt/AUTOUIC_OPTIONS.rst b/Help/prop_tgt/AUTOUIC_OPTIONS.rst index 3f613b9..425ea1c 100644 --- a/Help/prop_tgt/AUTOUIC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -8,11 +8,9 @@ This property holds additional command line options which will be used when equivalent to the optional ``OPTIONS`` argument of the :module:`qt4_wrap_ui() <FindQt4>` macro. -By default it is empty. - This property is initialized by the value of the :variable:`CMAKE_AUTOUIC_OPTIONS` variable if it is set when a target is -created. +created, or an empty string otherwise. The options set on the target may be overridden by :prop_sf:`AUTOUIC_OPTIONS` set on the ``.ui`` source file. diff --git a/Help/prop_tgt/COMPILE_FEATURES.rst b/Help/prop_tgt/COMPILE_FEATURES.rst index 195215e..46aec4f 100644 --- a/Help/prop_tgt/COMPILE_FEATURES.rst +++ b/Help/prop_tgt/COMPILE_FEATURES.rst @@ -4,7 +4,8 @@ COMPILE_FEATURES Compiler features enabled for this target. The list of features in this property are a subset of the features listed -in the :variable:`CMAKE_CXX_COMPILE_FEATURES` variable. +in the :variable:`CMAKE_C_COMPILE_FEATURES`, :variable:`CMAKE_CUDA_COMPILE_FEATURES`, and +:variable:`CMAKE_CXX_COMPILE_FEATURES` variables. Contents of ``COMPILE_FEATURES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for diff --git a/Help/prop_tgt/DEPRECATION.rst b/Help/prop_tgt/DEPRECATION.rst new file mode 100644 index 0000000..fef2e2e --- /dev/null +++ b/Help/prop_tgt/DEPRECATION.rst @@ -0,0 +1,7 @@ +DEPRECATION +----------- + +Deprecation message from imported target's developer. + +``DEPRECATION`` is the message regarding a deprecation status to be displayed +to downstream users of a target. diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index 2216072..747615a 100644 --- a/Help/prop_tgt/INSTALL_NAME_DIR.rst +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -10,3 +10,7 @@ installed targets. This property is initialized by the value of the variable :variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is created. + +This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`. +In particular, the ``$<INSTALL_PREFIX>`` generator expression can be used to set the +directory relative to the install-time prefix. 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/LINK_LIBRARIES_INDIRECTION.txt b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt index 1fdb6ad..fab4418 100644 --- a/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt +++ b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt @@ -2,8 +2,8 @@ A call to :command:`target_link_libraries(<target> ...)` may update this property on ``<target>``. If ``<target>`` was not created in the same directory as the call then :command:`target_link_libraries` will add a - suffix of the form ``::@<directory-id>`` to each entry, where the - ``::@`` is a separator and the ``<directory-id>`` is unspecified. + suffix of the form ``::@(directory-id)`` to each entry, where the + ``::@`` is a separator and the ``(directory-id)`` is unspecified. This tells the generators that the named libraries must be looked up in the scope of the caller rather than in the scope in which the ``<target>`` was created. Valid directory ids are stripped on export diff --git a/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst new file mode 100644 index 0000000..1bc361c --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst @@ -0,0 +1,6 @@ +VS_DOTNET_DOCUMENTATION_FILE +---------------------------- + +Visual Studio managed project .NET documentation output + +Sets the target XML documentation file output. 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/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/CMAKE_CURRENT_FUNCTION.rst b/Help/release/dev/CMAKE_CURRENT_FUNCTION.rst new file mode 100644 index 0000000..a15e63d --- /dev/null +++ b/Help/release/dev/CMAKE_CURRENT_FUNCTION.rst @@ -0,0 +1,9 @@ +CMAKE_CURRENT_FUNCTION +---------------------- + +* Define the following variables inside a function: + + - :variable:`CMAKE_CURRENT_FUNCTION` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` diff --git a/Help/release/dev/ExternalProject-git-no-recurse.rst b/Help/release/dev/ExternalProject-git-no-recurse.rst new file mode 100644 index 0000000..b9e09d3 --- /dev/null +++ b/Help/release/dev/ExternalProject-git-no-recurse.rst @@ -0,0 +1,7 @@ +ExternalProject-git-no-recurse +------------------------------ + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command gained a ``GIT_SUBMODULES_RECURSE`` option to specify whether + Git submodules should be updated recursively. The default is on to + preserve existing behavior. diff --git a/Help/release/dev/FindCUDAToolkit-module.rst b/Help/release/dev/FindCUDAToolkit-module.rst new file mode 100644 index 0000000..53a69c6 --- /dev/null +++ b/Help/release/dev/FindCUDAToolkit-module.rst @@ -0,0 +1,4 @@ +FindCUDAToolkit-module +---------------------- + +* The :module:`FindCUDAToolkit` module was added to find the CUDA Toolkit without enabling CUDA as a language. diff --git a/Help/release/dev/FindCURL-cmake-package.rst b/Help/release/dev/FindCURL-cmake-package.rst new file mode 100644 index 0000000..67c5bbc --- /dev/null +++ b/Help/release/dev/FindCURL-cmake-package.rst @@ -0,0 +1,7 @@ +FindCURL-cmake-package +---------------------- + +* The :module:`FindCURL` module learned to find CURL using + the ``CURLConfig.cmake`` package configuration file generated by + CURL's cmake buildsystem. It also gained a new ``CURL_NO_CURL_CMAKE`` + option to disable this behavior. 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/FindPython-SOABI.rst b/Help/release/dev/FindPython-SOABI.rst new file mode 100644 index 0000000..29f7292 --- /dev/null +++ b/Help/release/dev/FindPython-SOABI.rst @@ -0,0 +1,6 @@ +FindPython-SOABI +---------------- + +* The :module:`FindPython3` and :module:`FindPython` modules gained, + respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving + the standard extension suffix for modules. diff --git a/Help/release/dev/FindPythonConda-module.rst b/Help/release/dev/FindPythonConda-module.rst new file mode 100644 index 0000000..d762fbf --- /dev/null +++ b/Help/release/dev/FindPythonConda-module.rst @@ -0,0 +1,5 @@ +FindPythonConda-module +---------------------- + +* The :module:`FindPython` module has learned to find Python components in active + virtual environments managed by ``conda``. diff --git a/Help/release/dev/Link-properties-transitive.rst b/Help/release/dev/Link-properties-transitive.rst new file mode 100644 index 0000000..535b40c --- /dev/null +++ b/Help/release/dev/Link-properties-transitive.rst @@ -0,0 +1,8 @@ +Link-properties-transitive +-------------------------- + +* Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`, + :prop_tgt:`INTERFACE_LINK_DIRECTORIES` and + :prop_tgt:`INTERFACE_LINK_DEPENDS` are now transitive over private + dependency on static libraries. + See policy :policy:`CMP0099`. diff --git a/Help/release/dev/add_custom_command-depends-path.rst b/Help/release/dev/add_custom_command-depends-path.rst new file mode 100644 index 0000000..69a805b --- /dev/null +++ b/Help/release/dev/add_custom_command-depends-path.rst @@ -0,0 +1,8 @@ +add_custom_command-depends-path +------------------------------- + +* The :command:`add_custom_command` command learned to detect paths in + ``DEPENDS`` arguments and convert them to paths relative to the current + binary directory. This only applies to paths which contain a ``/`` or ``\\`` + in them because names like ``filename.txt`` could also be target names and + cannot be coverted into absolute paths blindly. diff --git a/Help/release/dev/add_target_deprecation.rst b/Help/release/dev/add_target_deprecation.rst new file mode 100644 index 0000000..b91eca9 --- /dev/null +++ b/Help/release/dev/add_target_deprecation.rst @@ -0,0 +1,7 @@ +add_target_deprecation +---------------------- + +* A :prop_tgt:`DEPRECATION` target property was added to mark + a target as deprecated. If a linked target is marked as + deprecated, a warning with the deprecation message is issued + at generate time. diff --git a/Help/release/dev/autogen_hh_headers.rst b/Help/release/dev/autogen_hh_headers.rst new file mode 100644 index 0000000..35ccd61 --- /dev/null +++ b/Help/release/dev/autogen_hh_headers.rst @@ -0,0 +1,6 @@ +autogen_hh_headers +------------------ + +* :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers with + a ``.hh`` extension. The new behavior is enabled by policy + :policy:`CMP0100`. diff --git a/Help/release/dev/ccmake-colored-values.rst b/Help/release/dev/ccmake-colored-values.rst new file mode 100644 index 0000000..b00885d --- /dev/null +++ b/Help/release/dev/ccmake-colored-values.rst @@ -0,0 +1,5 @@ +ccmake-colored-values +--------------------- + +* :manual:`ccmake(1)` now displays cache values using colors + based on the entry type if the terminal supports color. diff --git a/Help/release/dev/ccmake_progress_bar_and_log_display.rst b/Help/release/dev/ccmake_progress_bar_and_log_display.rst new file mode 100644 index 0000000..5c67c7d --- /dev/null +++ b/Help/release/dev/ccmake_progress_bar_and_log_display.rst @@ -0,0 +1,6 @@ +ccmake_progress_bar_and_log_display +----------------------------------- + +* :manual:`ccmake(1)` now displays messages and a progress bar during + configure and generate. It will keep the output displayed if any + errors or warnings occurred. diff --git a/Help/release/dev/command_debug_find.rst b/Help/release/dev/command_debug_find.rst new file mode 100644 index 0000000..673852c --- /dev/null +++ b/Help/release/dev/command_debug_find.rst @@ -0,0 +1,10 @@ +cmake-debug-find +---------------- + +* :manual:`cmake(1)` gained a ``--debug-find`` command line + option that can be used to provide information on where find + commands searched. + +* Variable :variable:`CMAKE_FIND_DEBUG_MODE` was introduced to + print extra find call information during the cmake run to standard + error. Output is designed for human consumption and not for parsing. 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-nsis-headerimage_var.rst b/Help/release/dev/cpack-nsis-headerimage_var.rst new file mode 100644 index 0000000..d44686b --- /dev/null +++ b/Help/release/dev/cpack-nsis-headerimage_var.rst @@ -0,0 +1,7 @@ +cpack-nsis-headerimage_var +-------------------------- + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_MUI_HEADERIMAGE` to set the header image. + To not break existing setups, it still defaults to + :variable:`CPACK_PACKAGE_ICON` if the new variable is not set. diff --git a/Help/release/dev/cpack-nsis-uninstaller-name.rst b/Help/release/dev/cpack-nsis-uninstaller-name.rst new file mode 100644 index 0000000..b7ceb4c --- /dev/null +++ b/Help/release/dev/cpack-nsis-uninstaller-name.rst @@ -0,0 +1,6 @@ +cpack-nsis-uninstaller-name +--------------------------- + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_UNINSTALL_NAME`. + This can be used to specify the name of the Uninstall program. diff --git a/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst b/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst new file mode 100644 index 0000000..8091d31 --- /dev/null +++ b/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst @@ -0,0 +1,10 @@ +cpack-nsis-welcome-finish-page-title +------------------------------------ + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_WELCOME_TITLE` and :variable:`CPACK_NSIS_WELCOME_TITLE_3LINES`. + These can be used to specify the welcome page title and display it in 3 lines. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_FINISH_TITLE` and :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`. + These can be used to specify the finish page title and display it in 3 lines. 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-configuration-type.rst b/Help/release/dev/ctest-configuration-type.rst new file mode 100644 index 0000000..89e36c4 --- /dev/null +++ b/Help/release/dev/ctest-configuration-type.rst @@ -0,0 +1,5 @@ +ctest-configuration-type +------------------------ + +* The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the command + line when :manual:`ctest(1)` is invoked with ``-C <cfg>``. diff --git a/Help/release/dev/ctest-drmemory-support.rst b/Help/release/dev/ctest-drmemory-support.rst new file mode 100644 index 0000000..b329995 --- /dev/null +++ b/Help/release/dev/ctest-drmemory-support.rst @@ -0,0 +1,5 @@ +ctest-drmemory-support +---------------------- + +* The :manual:`ctest(1)` gained support for Dr. Memory to run + memcheck runs. 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/cuda-gains-meta-features.rst b/Help/release/dev/cuda-gains-meta-features.rst new file mode 100644 index 0000000..e5e1022 --- /dev/null +++ b/Help/release/dev/cuda-gains-meta-features.rst @@ -0,0 +1,7 @@ +cuda-gains-meta-features +------------------------ + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + now offers meta-features for the CUDA language standard levels + (e.g. ``cuda_std_03``, ``cuda_std_14``). See + :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..401f4b2 --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,8 @@ +deprecate-policy-old +-------------------- + +* An explicit deprecation diagnostic was added for policy ``CMP0068`` + and policy ``CMP0069`` (``CMP0067`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. diff --git a/Help/release/dev/export-compile-commands-environment-variable.rst b/Help/release/dev/export-compile-commands-environment-variable.rst new file mode 100644 index 0000000..da9d66b --- /dev/null +++ b/Help/release/dev/export-compile-commands-environment-variable.rst @@ -0,0 +1,6 @@ +export-compile-commands-environment-variable +-------------------------------------------- + +* The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its + initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment + variable if no explicit configuration is given. diff --git a/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000..a6a5c71 --- /dev/null +++ b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst @@ -0,0 +1,11 @@ +feature-CMAKE_MESSAGE_CONTEXT +----------------------------- + +* The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used + to persist a log level between CMake runs, unlike the ``--log-level`` + command line option which only applies to that particular run. + +* The :command:`message` command learned to output context provided in + the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels + ``NOTICE`` and below. Enable this output with the new ``--log-context`` + command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable. 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/foreach-ZIP_LISTS.rst b/Help/release/dev/foreach-ZIP_LISTS.rst new file mode 100644 index 0000000..d45d9b9 --- /dev/null +++ b/Help/release/dev/foreach-ZIP_LISTS.rst @@ -0,0 +1,5 @@ +foreach-ZIP_LISTS +----------------- + +* The :command:`foreach` learned a new option ``ZIP_LISTS`` to iterate + over multiple lists simultaneously. diff --git a/Help/release/dev/install-name-dir-genex.rst b/Help/release/dev/install-name-dir-genex.rst new file mode 100644 index 0000000..0cb41f0 --- /dev/null +++ b/Help/release/dev/install-name-dir-genex.rst @@ -0,0 +1,7 @@ +install-name-dir-genex +---------------------- + +* The :prop_tgt:`INSTALL_NAME_DIR` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + In particular, the ``$<INSTALL_PREFIX>`` generator expression can + be used to set the directory relative to the install-time prefix. diff --git a/Help/release/dev/json_trace.rst b/Help/release/dev/json_trace.rst new file mode 100644 index 0000000..69a1fb7 --- /dev/null +++ b/Help/release/dev/json_trace.rst @@ -0,0 +1,7 @@ +json-trace +---------- + +* :manual:`cmake(1)` gained a ``--trace-format`` command line option that + can be used to set the ``--trace`` output format. Currently, the old + human readable and the new JSON format are supported. The new JSON format + is easier to parse automatically, than the existing format. 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/mingw_no_sh.rst b/Help/release/dev/mingw_no_sh.rst new file mode 100644 index 0000000..7008865 --- /dev/null +++ b/Help/release/dev/mingw_no_sh.rst @@ -0,0 +1,5 @@ +mingw-no-sh +----------- + +* The :generator:`MinGW Makefiles` generator no longer issues an error if + ``sh.exe`` is present in the environment's ``PATH``. diff --git a/Help/release/dev/multi-configuration-ninja.rst b/Help/release/dev/multi-configuration-ninja.rst new file mode 100644 index 0000000..d9f72cb --- /dev/null +++ b/Help/release/dev/multi-configuration-ninja.rst @@ -0,0 +1,6 @@ +multi-configuration-ninja +------------------------- + +* :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator, + which is similar to the :generator:`Ninja` generator but can be used to build + multiple configurations at once. diff --git a/Help/release/dev/new-message-types.rst b/Help/release/dev/new-message-types.rst new file mode 100644 index 0000000..8f164b9 --- /dev/null +++ b/Help/release/dev/new-message-types.rst @@ -0,0 +1,5 @@ +new-message-types +----------------- + +* The :command:`message` command gained new keywords ``CHECK_START``, + ``CHECK_PASS`` and ``CHECK_FAIL``. diff --git a/Help/release/dev/ninja-postgen-commands.rst b/Help/release/dev/ninja-postgen-commands.rst new file mode 100644 index 0000000..85b60dc --- /dev/null +++ b/Help/release/dev/ninja-postgen-commands.rst @@ -0,0 +1,5 @@ +ninja-postgen-commands +---------------------- + +* The :generator:`Ninja` generator learned to perform some post-processing on + the generated files for more consistent builds. 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/target_compile_options-BEFORE-keyword.rst b/Help/release/dev/target_compile_options-BEFORE-keyword.rst new file mode 100644 index 0000000..8dafddd --- /dev/null +++ b/Help/release/dev/target_compile_options-BEFORE-keyword.rst @@ -0,0 +1,5 @@ +target_compile_options-BEFORE-keyword +------------------------------------- + +* :command:`target_compile_options` command learns to honor ``BEFORE`` keyword + in all scopes. See policy :policy:`CMP0101`. diff --git a/Help/release/dev/vs-per-config-sources.rst b/Help/release/dev/vs-per-config-sources.rst new file mode 100644 index 0000000..bf7572b --- /dev/null +++ b/Help/release/dev/vs-per-config-sources.rst @@ -0,0 +1,5 @@ +vs-per-config-sources +--------------------- + +* :ref:`Visual Studio Generators` learned to support per-config sources. + Previously only :ref:`Command-Line Build Tool Generators` supported them. diff --git a/Help/release/dev/vs-vctargetspath.rst b/Help/release/dev/vs-vctargetspath.rst new file mode 100644 index 0000000..d40af34 --- /dev/null +++ b/Help/release/dev/vs-vctargetspath.rst @@ -0,0 +1,10 @@ +vs-vctargetspath +---------------- + +* With :ref:`Visual Studio Generators` for VS 2010 and above, + the :variable:`CMAKE_GENERATOR_TOOLSET` setting gained an option + to specify the ``VCTargetsPath`` value for project files. + +* The :variable:`CMAKE_VS_GLOBALS` variable value now applies during + compiler identification and in targets created by the + :command:`add_custom_target` command. diff --git a/Help/release/dev/vs_dotnet_documentation_file.rst b/Help/release/dev/vs_dotnet_documentation_file.rst new file mode 100644 index 0000000..fdffb1c --- /dev/null +++ b/Help/release/dev/vs_dotnet_documentation_file.rst @@ -0,0 +1,6 @@ +vs_dotnet_documentation_file +---------------------------- + +* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added + to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile`` + reference in ``.csproj`` files. diff --git a/Help/release/dev/xcode-scheme-env.rst b/Help/release/dev/xcode-scheme-env.rst new file mode 100644 index 0000000..238cb61 --- /dev/null +++ b/Help/release/dev/xcode-scheme-env.rst @@ -0,0 +1,5 @@ +xcode-scheme-env +---------------- + +* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added + to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property. 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/release/dev/xmllint-target.rst b/Help/release/dev/xmllint-target.rst new file mode 100644 index 0000000..19c69bf --- /dev/null +++ b/Help/release/dev/xmllint-target.rst @@ -0,0 +1,4 @@ +xmllint-target +-------------- + +* The :module:`FindLibXml2` module now provides an imported target for the xmllint executable diff --git a/Help/release/index.rst b/Help/release/index.rst index 0cc3f97..a4585a5 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst new file mode 100644 index 0000000..2cd2650 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst @@ -0,0 +1,11 @@ +CMAKE_CUDA_COMPILE_FEATURES +--------------------------- + +List of features known to the CUDA compiler + +These features are known to be available for use with the CUDA compiler. This +list is a subset of the features listed in the +:prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES` global property. + +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_CURRENT_FUNCTION.rst b/Help/variable/CMAKE_CURRENT_FUNCTION.rst new file mode 100644 index 0000000..aa2936c --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION.rst @@ -0,0 +1,6 @@ +CMAKE_CURRENT_FUNCTION +---------------------- + +When executing code inside a :command:`function`, this variable +contains the name of the current function. It can be used for +diagnostic or debug messages. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst new file mode 100644 index 0000000..0119381 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst @@ -0,0 +1,33 @@ +CMAKE_CURRENT_FUNCTION_LIST_DIR +------------------------------- + +When executing code inside a :command:`function`, this variable +contains the full directory of the listfile defining the current function. + +It is quite common practice in CMake that modules use some additional files +(e.g., templates to render). And the code typically did the following: + +.. code-block:: cmake + :caption: Bad + + set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}") + + function(foo) + configure_file( + "${_THIS_MODULE_BASE_DIR}/some.template.in" + some.output + ) + endfunction() + +Using this variable inside a function eliminates the neccessity of the +additional one with "global" scope: + +.. code-block:: cmake + :caption: Good + + function(foo) + configure_file( + "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in" + some.output + ) + endfunction() diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst new file mode 100644 index 0000000..d2c846a --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst @@ -0,0 +1,5 @@ +CMAKE_CURRENT_FUNCTION_LIST_FILE +-------------------------------- + +When executing code inside a :command:`function`, this variable +contains the full path to the listfile declaring a current function. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst new file mode 100644 index 0000000..5a7cd13 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst @@ -0,0 +1,5 @@ +CMAKE_CURRENT_FUNCTION_LIST_LINE +-------------------------------- + +When executing code inside a :command:`function`, this variable +contains the line number in the listfile where a current function has defined. diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 4548abc..6d2450b 100644 --- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -25,6 +25,9 @@ form. The format of the JSON file looks like: } ] +This is initialized by the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment +variable. + .. note:: This option is implemented only by :ref:`Makefile Generators` and the :generator:`Ninja`. It is ignored on other generators. diff --git a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst new file mode 100644 index 0000000..33ffdd6 --- /dev/null +++ b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_DEBUG_MODE +--------------------- + +Print extra find call information for the following commands to standard +error: +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +Output is designed for human consumption and not for parsing. +Enabling this variable is equivalent to using :manual:`cmake <cmake(1)>` ``--debug-find`` +with the added ability to enable debugging for a subset of find calls. + +.. code-block:: cmake + + set(CMAKE_FIND_DEBUG_MODE TRUE) + find_program(...) + set(CMAKE_FIND_DEBUG_MODE FALSE) + +Default is unset. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 222824f..53ad2f3 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -58,3 +58,8 @@ Supported pairs are: Specify the toolset version to use. Supported by VS 2017 and above with the specified toolset installed. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. + +``VCTargetsPath=<path>`` + Specify an alternative ``VCTargetsPath`` value for Visual Studio + project files. This allows use of VS platform extension configuration + files (``.props`` and ``.targets``) that are not installed with VS. 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 6b7e35a..c76e2d0 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``, ``OBJC``, ``OBJCXX``, 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_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000..6b4ca40 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst @@ -0,0 +1,62 @@ +CMAKE_MESSAGE_CONTEXT +--------------------- + +When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line +option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the +:command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a +dot-separated string surrounded by square brackets and prepends it to each line +for messages of log levels ``NOTICE`` and below. + +For logging contexts to work effectively, projects should generally +``APPEND`` and ``POP_BACK`` an item to the current value of +``CMAKE_MESSAGE_CONTEXT`` rather than replace it. +Projects should not assume the message context at the top of the source tree +is empty, as there are scenarios where the context might have already been set +(e.g. hierarchical projects). + +.. warning:: + + Valid context names are restricted to anything that could be used + as a CMake variable name. All names that begin with an underscore + or the string ``cmake_`` are also reserved for use by CMake and + should not be used by projects. + +Example: + +.. code-block:: cmake + + function(bar) + list(APPEND CMAKE_MESSAGE_CONTEXT "bar") + message(VERBOSE "bar VERBOSE message") + endfunction() + + function(baz) + list(APPEND CMAKE_MESSAGE_CONTEXT "baz") + message(DEBUG "baz DEBUG message") + endfunction() + + function(foo) + list(APPEND CMAKE_MESSAGE_CONTEXT "foo") + bar() + message(TRACE "foo TRACE message") + baz() + endfunction() + + list(APPEND CMAKE_MESSAGE_CONTEXT "top") + + message(VERBOSE "Before `foo`") + foo() + message(VERBOSE "After `foo`") + + list(POP_BACK CMAKE_MESSAGE_CONTEXT) + + +Which results in the following output: + +.. code-block:: none + + -- [top] Before `foo` + -- [top.foo.bar] bar VERBOSE message + -- [top.foo] foo TRACE message + -- [top.foo.baz] baz DEBUG message + -- [top] After `foo` diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst new file mode 100644 index 0000000..7ec218e --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst @@ -0,0 +1,15 @@ +CMAKE_MESSAGE_CONTEXT_SHOW +-------------------------- + +Setting this variable to true enables showing a context with each line +logged by the :command:`message` command (see :variable:`CMAKE_MESSAGE_CONTEXT` +for how the context itself is specified). + +This variable is an alternative to providing the ``--log-context`` option +on the :manual:`cmake <cmake(1)>` command line. Whereas the command line +option will apply only to that one CMake run, setting +``CMAKE_MESSAGE_CONTEXT_SHOW`` to true as a cache variable will ensure that +subsequent CMake runs will continue to show the message context. + +Projects should not set ``CMAKE_MESSAGE_CONTEXT_SHOW``. It is intended for +users so that they may control whether or not to include context with messages. diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst new file mode 100644 index 0000000..1d4cfe6 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst @@ -0,0 +1,15 @@ +CMAKE_MESSAGE_LOG_LEVEL +----------------------- + +When set, this variable specifies the logging level used by the +:command:`message` command. Valid values are the same as those for the +``--log-level`` command line option of the :manual:`cmake(1)` program. +If this variable is set and the ``--log-level`` command line option is +given, the command line option takes precedence. + +The main advantage to using this variable is to make a log level persist +between CMake runs. Setting it as a cache variable will ensure that +subsequent CMake runs will continue to use the chosen log level. + +Projects should not set this variable, it is intended for users so that +they may control the log level according to their own needs. diff --git a/Help/variable/CMAKE_NINJA_CROSS_CONFIG_ENABLE.rst b/Help/variable/CMAKE_NINJA_CROSS_CONFIG_ENABLE.rst new file mode 100644 index 0000000..5c9c1aa --- /dev/null +++ b/Help/variable/CMAKE_NINJA_CROSS_CONFIG_ENABLE.rst @@ -0,0 +1,6 @@ +CMAKE_NINJA_CROSS_CONFIG_ENABLE +------------------------------- + +If this variable is enabled, cross-configuration building is enabled in the +:generator:`Ninja Multi-Config` generator. See the generator's description for +more details. diff --git a/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst b/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst new file mode 100644 index 0000000..2b950e1 --- /dev/null +++ b/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst @@ -0,0 +1,7 @@ +CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE +------------------------------------ + +Specifies a configuration type to use as the default in ``build.ninja`` for the +:generator:`Ninja Multi-Config` generator. + +If this variable is not specified, no ``build.ninja`` file is generated. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst index 965c94e..5835264 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -5,5 +5,6 @@ A CMake language file or module to be included as the last step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst index 70b15e6..280c14a 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -5,5 +5,6 @@ A CMake language file or module to be included as the first step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and :variable:`CMAKE_PROJECT_INCLUDE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index 3485c38..74247f1 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -6,5 +6,6 @@ A CMake language file or module to be included as the last step of any name. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE` and :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst new file mode 100644 index 0000000..db1432d --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE +------------------------------------------- + +A CMake language file or module to be included as the first step of any +:command:`project` command calls that specify ``<PROJECT-NAME>`` as the project +name. This is intended for injecting custom code into project builds without +modifying their source. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_INCLUDE` and +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst index 2ba8fe2..2eea424 100644 --- a/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst +++ b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst @@ -1,8 +1,18 @@ CMAKE_VS_WINRT_BY_DEFAULT ------------------------- -Tell :ref:`Visual Studio Generators` for VS 2010 and above that the -target platform compiles as WinRT by default (compiles with ``/ZW``). +Inform :ref:`Visual Studio Generators` for VS 2010 and above that the +target platform enables WinRT compilation by default and it needs to +be explicitly disabled if ``/ZW`` or :prop_tgt:`VS_WINRT_COMPONENT` is +omitted (as opposed to enabling it when either of those options is +present) + +This makes cmake configuration consistent in terms of WinRT among +platforms - if you did not enable the WinRT compilation explicitly, it +will be disabled (by either not enabling it or explicitly disabling it) + +Note: WinRT compilation is always explicitly disabled for C language +source files, even if it is expliclty enabled for a project This variable is meant to be set by a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` for such platforms. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 0000000..4832659 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_ENVIRONMENT +------------------------------ + +Specify environment variables that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of environment variables and values of the form +``MYVAR=value`` those environment variables will be added to the +scheme. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. 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. diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst index c905480..9e277fa 100644 --- a/Help/variable/CTEST_CONFIGURATION_TYPE.rst +++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst @@ -3,3 +3,6 @@ CTEST_CONFIGURATION_TYPE Specify the CTest ``DefaultCTestConfigurationType`` setting in a :manual:`ctest(1)` dashboard client script. + +If the configuration type is set via ``-C <cfg>`` from the command line +then this variable is populated accordingly. diff --git a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst index b8b4c30..4e7d5c0 100644 --- a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst +++ b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst @@ -3,6 +3,6 @@ CTEST_MEMORYCHECK_TYPE Specify the CTest ``MemoryCheckType`` setting in a :manual:`ctest(1)` dashboard client script. -Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, and +Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, ``DrMemory`` and ``ThreadSanitizer``, ``AddressSanitizer``, ``LeakSanitizer``, ``MemorySanitizer``, and ``UndefinedBehaviorSanitizer``. |