diff options
Diffstat (limited to 'Help')
59 files changed, 765 insertions, 24 deletions
diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 7a3393b4d4..5c67b2c706 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 ae2afb2905..ecbfed3d9d 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`` diff --git a/Help/command/message.rst b/Help/command/message.rst index c614286c11..6bc0e4cfc6 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 395145619f..b6093d3b71 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/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index cd2aea682f..dc6524938c 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -128,3 +128,24 @@ 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. diff --git a/Help/cpack_gen/packagemaker.rst b/Help/cpack_gen/packagemaker.rst index e9464b749a..81acb9d57e 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 d22fcd48a5..82b79aeacf 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 44e2273477..a1c1a6fada 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 cbde6feead..8ec41d29c6 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 0000000000..e9e0810650 --- /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/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 96ceb945a8..c98f18f681 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -23,6 +23,7 @@ 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 diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 04b6ed2598..12eecd9932 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 75f4bd48a2..691481b992 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-policies.7.rst b/Help/manual/cmake-policies.7.rst index 44ea1a8fd0..eceeac7200 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.17 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0098> + Policies Introduced by CMake 3.16 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index e7043714c7..c5ef09abef 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -348,6 +348,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 +381,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 53b7f8ddd5..0c1d510995 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -70,7 +70,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 @@ -206,6 +205,10 @@ 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_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN @@ -214,6 +217,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 +239,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 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 4ab55a0d0f..6f338662fc 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. @@ -539,22 +554,38 @@ Available commands are: 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt ``remove [-f] <file>...`` - Remove the file(s). If any of the listed files already do not - exist, the command returns a non-zero exit code, but no message - is logged. The ``-f`` option changes the behavior to return a + .. deprecated:: 3.17 + + Remove the file(s). The planned behaviour was that if any of the + listed files already do not exist, the command returns a non-zero exit code, + but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such situations instead. ``remove`` does not follow symlinks. That means it remove only symlinks and not files it point to. + The implementation was buggy and always returned 0. It cannot be fixed without + breaking backwards compatibility. Use ``rm`` instead. + ``remove_directory <dir>...`` - Remove ``<dir>`` directories and their contents. If a directory does + .. deprecated:: 3.17 + + Remove ``<dir>`` directories and their contents. If a directory does not exist it will be silently ignored. If ``<dir>`` is a symlink to a directory, just the symlink will be removed. + Use ``rm`` instead. ``rename <oldname> <newname>`` Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. +``rm [-rRf] <file> <dir>...`` + Remove the files ``<file>`` or directories ``dir``. + Use ``-r`` or ``-R`` to remove directories and their contents recursively. + If any of the listed files/directories do not exist, the command returns a + non-zero exit code, but no message is logged. The ``-f`` option changes + the behavior to return a zero exit code (i.e. success) in such + situations instead. + ``server`` Launch :manual:`cmake-server(7)` mode. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index e29ebcaf6a..17bddb6789 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. diff --git a/Help/policy/CMP0098.rst b/Help/policy/CMP0098.rst new file mode 100644 index 0000000000..6d1443b764 --- /dev/null +++ b/Help/policy/CMP0098.rst @@ -0,0 +1,30 @@ +CMP0098 +------- + +:module:`FindFLEX` runs ``flex`` in directory +:variable:`CMAKE_CURRENT_BINARY_DIR` when executing. + +The module provides a ``FLEX_TARGET`` macro which generates FLEX output. +In CMake 3.16 and below the macro would generate a custom command that runs +``flex`` in the current source directory. CMake 3.17 and later prefer to +run it in the build directory and use :variable:`CMAKE_CURRENT_BINARY_DIR` +as the ``WORKING_DIRECTORY`` of its :command:`add_custom_command` invocation. +This ensures that any implicitly generated file is written relative to the +build tree rather than the source tree, unless the generated file is +provided as absolute path. + +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is for ``FLEX_TARGET`` to use +the current source directory for the ``WORKING_DIRECTORY`` and where +to generate implicit files. The ``NEW`` behavior of this policy is to +use the current binary directory for the ``WORKING_DIRECTORY`` relative to +which implicit files are generated unless provided as absolute path. + +This policy was introduced in CMake version 3.17. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index 2216072acb..747615ac8e 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/VS_DOTNET_DOCUMENTATION_FILE.rst b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst new file mode 100644 index 0000000000..1bc361c3da --- /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 0000000000..7ffa74bb43 --- /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 0000000000..e4cc01e23f --- /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/ExternalProject-git-no-recurse.rst b/Help/release/dev/ExternalProject-git-no-recurse.rst new file mode 100644 index 0000000000..b9e09d3564 --- /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/FindCURL-cmake-package.rst b/Help/release/dev/FindCURL-cmake-package.rst new file mode 100644 index 0000000000..67c5bbcb85 --- /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 0000000000..3569185e28 --- /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/ccmake-colored-values.rst b/Help/release/dev/ccmake-colored-values.rst new file mode 100644 index 0000000000..b00885dfc0 --- /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 0000000000..5c67c7ddc1 --- /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_rm.rst b/Help/release/dev/command_rm.rst new file mode 100644 index 0000000000..a58362e8df --- /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/cpack-nsis-uninstaller-name.rst b/Help/release/dev/cpack-nsis-uninstaller-name.rst new file mode 100644 index 0000000000..b7ceb4c12a --- /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 0000000000..8091d31e6e --- /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 0000000000..796f5d62ba --- /dev/null +++ b/Help/release/dev/cpack-pkg-background.rst @@ -0,0 +1,8 @@ +cpack-pkg-background +-------------------- + +* The :cpack_gen:`CPack productbuild Generator` and + :cpack_gen:`CPack PackageMaker Generator` gained options + :variable:`CPACK_PRODUCTBUILD_BACKGROUND` and + :variable:`CPACK_PACKAGEMAKER_BACKGROUND`, respectively, + to specify a background image for the macOS installer. diff --git a/Help/release/dev/ctest-repeat.rst b/Help/release/dev/ctest-repeat.rst new file mode 100644 index 0000000000..b1ff59bfdc --- /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/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000000..401f4b235f --- /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 0000000000..da9d66b721 --- /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 0000000000..a6a5c71a71 --- /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 0000000000..e0e2e16a52 --- /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/install-name-dir-genex.rst b/Help/release/dev/install-name-dir-genex.rst new file mode 100644 index 0000000000..0cb41f08d9 --- /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/load_cache-script-mode.rst b/Help/release/dev/load_cache-script-mode.rst new file mode 100644 index 0000000000..d84b08afe8 --- /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 0000000000..700886585b --- /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/new-message-types.rst b/Help/release/dev/new-message-types.rst new file mode 100644 index 0000000000..8f164b9e79 --- /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/sdcc-new-librarian.rst b/Help/release/dev/sdcc-new-librarian.rst new file mode 100644 index 0000000000..93961ce6b5 --- /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/vs-per-config-sources.rst b/Help/release/dev/vs-per-config-sources.rst new file mode 100644 index 0000000000..bf7572b6ed --- /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 0000000000..d40af349e4 --- /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 0000000000..fdffb1cfcc --- /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 0000000000..238cb618fa --- /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 0000000000..8eb5ed88f8 --- /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/index.rst b/Help/release/index.rst index 0cc3f97262..a4585a5ddf 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_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 4548abcc73..6d2450bc70 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_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 222824f6a9..53ad2f3e76 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_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000000..6b4ca40329 --- /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 0000000000..7ec218e04e --- /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 0000000000..1d4cfe6c60 --- /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_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst index 965c94ee7c..5835264497 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 70b15e662f..280c14a0ea 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 3485c38e44..74247f12b7 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 0000000000..db1432de65 --- /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_XCODE_SCHEME_ENVIRONMENT.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 0000000000..4832659ce7 --- /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 0000000000..cc690f7b1a --- /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. |