diff options
Diffstat (limited to 'Help')
31 files changed, 304 insertions, 96 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index bd55e24..21236fa 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -140,21 +140,40 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. .. versionadded:: 3.12 - If called from within a find module or any other script loaded by a call to - :command:`find_package(<PackageName>)`, search prefixes unique to the - current package being found. Specifically, look in the - :variable:`<PackageName>_ROOT` CMake variable and the - :envvar:`<PackageName>_ROOT` environment variable. - The package root variables are maintained as a stack, so if called from - nested find modules or config packages, root paths from the parent's find - module or config package will be searched after paths from the current - module or package. In other words, the search order would be - ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, - ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting - the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. - See policy :policy:`CMP0074`. +1. If called from within a find module or any other script loaded by a call to + :command:`find_package(<PackageName>)`, search prefixes unique to the + current package being found. See policy :policy:`CMP0074`. + + .. versionadded:: 3.12 + + Specifically, search paths specified by the following variables, in order: + + a. :variable:`<PackageName>_ROOT` CMake variable, + where ``<PackageName>`` is the case-preserved package name. + + b. :variable:`<PACKAGENAME>_ROOT` CMake variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + c. :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the case-preserved package name. + + d. :envvar:`<PACKAGENAME>_ROOT` environment variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + The package root variables are maintained as a stack, so if called from + nested find modules or config packages, root paths from the parent's find + module or config package will be searched after paths from the current + module or package. In other words, the search order would be + ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 293d3f0..1ccd434 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -25,7 +25,8 @@ The first signature is for adding a custom command to produce an output: [DEPFILE depfile] [JOB_POOL job_pool] [VERBATIM] [APPEND] [USES_TERMINAL] - [COMMAND_EXPAND_LISTS]) + [COMMAND_EXPAND_LISTS] + [DEPENDS_EXPLICIT_ONLY]) This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) @@ -357,6 +358,24 @@ The options are: :ref:`Makefile Generators`, :ref:`Visual Studio Generators`, and the :generator:`Xcode` generator. +``DEPENDS_EXPLICIT_ONLY`` + + .. versionadded:: 3.27 + + Indicate that the command's ``DEPENDS`` argument represents all files + required by the command and implicit dependencies are not required. + + Without this option, if any target uses the output of the custom command, + CMake will consider that target's dependencies as implicit dependencies for + the custom command in case this custom command requires files implicitly + created by those targets. + + This option can be enabled on all custom commands by setting + :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``. + + Only the :ref:`Ninja Generators` actually use this information to remove + unnecessary implicit dependencies. + Examples: Generating Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 53555a4..02dd3986 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -12,13 +12,24 @@ Add a test to the project to be run by :manual:`ctest(1)`. Adds a test called ``<name>``. The test name may contain arbitrary characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument` -if necessary. See policy :policy:`CMP0110`. The options are: +if necessary. See policy :policy:`CMP0110`. + +CMake only generates tests if the :command:`enable_testing` command has been +invoked. The :module:`CTest` module invokes ``enable_testing`` automatically +unless ``BUILD_TESTING`` is set to ``OFF``. + +Tests added with the ``add_test(NAME)`` signature support using +:manual:`generator expressions <cmake-generator-expressions(7)>` +in test properties set by :command:`set_property(TEST)` or +:command:`set_tests_properties`. Test properties may only be set in the +directory the test is created in. + +``add_test`` options are: ``COMMAND`` - Specify the test command-line. If ``<command>`` specifies an - executable target (created by :command:`add_executable`) it will - automatically be replaced by the location of the executable created - at build time. + Specify the test command-line. If ``<command>`` specifies an executable + target created by :command:`add_executable`, it will automatically be + replaced by the location of the executable created at build time. The command may be specified using :manual:`generator expressions <cmake-generator-expressions(7)>`. @@ -27,38 +38,29 @@ if necessary. See policy :policy:`CMP0110`. The options are: Restrict execution of the test only to the named configurations. ``WORKING_DIRECTORY`` - Set the :prop_test:`WORKING_DIRECTORY` test property to - specify the working directory in which to execute the test. - If not specified the test will be run with the current working - directory set to the build directory corresponding to the - current source directory. - - The working directory may be specified using - :manual:`generator expressions <cmake-generator-expressions(7)>`. + Set the test property :prop_test:`WORKING_DIRECTORY` in which to execute the + test. If not specified, the test will be run in + :variable:`CMAKE_CURRENT_BINARY_DIR`. The working directory may be specified + using :manual:`generator expressions <cmake-generator-expressions(7)>`. ``COMMAND_EXPAND_LISTS`` .. versionadded:: 3.16 - Lists in ``COMMAND`` arguments will be expanded, including those - created with + Lists in ``COMMAND`` arguments will be expanded, including those created with :manual:`generator expressions <cmake-generator-expressions(7)>`. -The given test command is expected to exit with code ``0`` to pass and -non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test -property is set. Any output written to stdout or stderr will be -captured by :manual:`ctest(1)` but does not affect the pass/fail status -unless the :prop_test:`PASS_REGULAR_EXPRESSION`, -:prop_test:`FAIL_REGULAR_EXPRESSION` or -:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. +If the test command exits with code ``0`` the test passes. Non-zero exit code +is a "failed" test. The test property :prop_test:`WILL_FAIL` inverts this +logic. Note that system-level test failures such as segmentation faults or +heap errors will still fail the test even if ``WILL_FALL`` is true. Output +written to stdout or stderr is captured by :manual:`ctest(1)` and only +affects the pass/fail status via the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION`, or :prop_test:`SKIP_REGULAR_EXPRESSION` +test properties. .. versionadded:: 3.16 Added :prop_test:`SKIP_REGULAR_EXPRESSION` property. -Tests added with the ``add_test(NAME)`` signature support using -:manual:`generator expressions <cmake-generator-expressions(7)>` -in test properties set by :command:`set_property(TEST)` or -:command:`set_tests_properties`. - Example usage: .. code-block:: cmake @@ -71,16 +73,9 @@ This creates a test ``mytest`` whose command runs a ``testDriver`` tool passing the configuration name and the full path to the executable file produced by target ``myexe``. -.. note:: - - CMake will generate tests only if the :command:`enable_testing` - command has been invoked. The :module:`CTest` module invokes the - command automatically unless the ``BUILD_TESTING`` option is turned - ``OFF``. - --------------------------------------------------------------------- -This command also supports a simpler, but less flexible, signature: +The command syntax above is recommended over the older, less flexible form: .. code-block:: cmake diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index de4cb88..b82088e 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -367,17 +367,37 @@ The set of installation prefixes is constructed using the following steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are enabled. -1. .. versionadded:: 3.12 - Search paths specified in the :variable:`<PackageName>_ROOT` CMake - variable and the :envvar:`<PackageName>_ROOT` environment variable, - where ``<PackageName>`` is the package to be found - (the case-preserved first argument to ``find_package``). - The package root variables are maintained as a stack so if - called from within a find module, root paths from the parent's find - module will also be searched after paths for the current package. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting - the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. - See policy :policy:`CMP0074`. +1. Search prefixes unique to the current ``<PackageName>`` being found. + See policy :policy:`CMP0074`. + + .. versionadded:: 3.12 + + Specifically, search prefixes specified by the following variables, + in order: + + a. :variable:`<PackageName>_ROOT` CMake variable, + where ``<PackageName>`` is the case-preserved package name. + + b. :variable:`<PACKAGENAME>_ROOT` CMake variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + c. :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the case-preserved package name. + + d. :envvar:`<PACKAGENAME>_ROOT` environment variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + The package root variables are maintained as a stack so if + called from within a find module, root paths from the parent's find + module will also be searched after paths for the current package. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`. diff --git a/Help/command/math.rst b/Help/command/math.rst index 8386aab..6989ebc 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -9,7 +9,8 @@ Evaluate a mathematical expression. Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the resulting value. The result of the expression must be representable as a -64-bit signed integer. +64-bit signed integer. Floating point inputs are invalid e.g. ``1.1 * 10``. +Non-integer results e.g. ``3 / 2`` are truncated. The mathematical expression must be given as a string (i.e. enclosed in double quotation marks). An example is ``"5 * (10 + 13)"``. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst index f66af35..4f0b25e 100644 --- a/Help/command/separate_arguments.rst +++ b/Help/command/separate_arguments.rst @@ -69,7 +69,7 @@ be one of the following keywords: The contents of ``out`` will be: ``/path/to/cc;-c;main.c`` -.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx +.. _`Parsing C Command-Line Arguments`: https://learn.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments .. code-block:: cmake diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index ca19e0c..8dd4b94 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -82,8 +82,8 @@ It must be one of the following: to the installation prefix. ``TEST`` - Scope may name zero or more existing tests. - See also the :command:`set_tests_properties` command. + Scope is limited to the directory the command is called in. It may name zero + or more existing tests. See also command :command:`set_tests_properties`. Test property values may be specified using :manual:`generator expressions <cmake-generator-expressions(7)>` diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index c880049..af01252 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -111,7 +111,7 @@ Windows using WiX. simply provide the name of the culture. If you specify more than one culture identifier in a comma or semicolon delimited list, the first one that is found will be used. You can find a list of supported languages at: - https://wixtoolset.org//documentation/manual/v3/wixui/wixui_localization.html + https://wixtoolset.org/docs/v3/wixui/wixui_localization/ .. variable:: CPACK_WIX_TEMPLATE @@ -319,7 +319,7 @@ Windows using WiX. for using WiX extensions. Each declaration should be in the form name=url, where name is the plain namespace without the usual xmlns: prefix and url is an unquoted namespace url. A list of commonly known WiX schemata can be found here: - https://wixtoolset.org/documentation/manual/v3/xsd/ + https://wixtoolset.org/docs/v3/xsd/ .. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst index fa8c385..6e9c744 100644 --- a/Help/envvar/PackageName_ROOT.rst +++ b/Help/envvar/PackageName_ROOT.rst @@ -17,3 +17,17 @@ by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment variable convention on those platforms). See also the :variable:`<PackageName>_ROOT` CMake variable. + +.. envvar:: <PACKAGENAME>_ROOT + + .. versionadded:: 3.27 + + Calls to :command:`find_package(<PackageName>)` will also search in + prefixes specified by the upper-case ``<PACKAGENAME>_ROOT`` environment + variable. See policy :policy:`CMP0144`. + +.. note:: + + Note that the ``<PackageName>_ROOT`` and ``<PACKAGENAME>_ROOT`` + environment variables are distinct only on platforms that have + case-sensitive environments. diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst index 85da715..5c48bc9 100644 --- a/Help/generator/CodeBlocks.rst +++ b/Help/generator/CodeBlocks.rst @@ -1,6 +1,12 @@ CodeBlocks ---------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates CodeBlocks project files. Project files for CodeBlocks will be created in the top directory and diff --git a/Help/generator/CodeLite.rst b/Help/generator/CodeLite.rst index 4f276df..faec9b9 100644 --- a/Help/generator/CodeLite.rst +++ b/Help/generator/CodeLite.rst @@ -1,6 +1,12 @@ CodeLite ---------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates CodeLite project files. Project files for CodeLite will be created in the top directory and diff --git a/Help/generator/Eclipse CDT4.rst b/Help/generator/Eclipse CDT4.rst index 634e2b6..9c1610d 100644 --- a/Help/generator/Eclipse CDT4.rst +++ b/Help/generator/Eclipse CDT4.rst @@ -1,6 +1,12 @@ Eclipse CDT4 ------------ +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Eclipse CDT 4.0 project files. Project files for Eclipse will be created in the top directory. In diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst index 129bf63..11354f2 100644 --- a/Help/generator/Kate.rst +++ b/Help/generator/Kate.rst @@ -1,6 +1,12 @@ Kate ---- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Kate project files. A project file for Kate will be created in the top directory in the top level @@ -22,5 +28,8 @@ This "extra" generator may be specified as: ``Kate - Ninja`` Generate with :generator:`Ninja`. +``Kate - Ninja Multi-Config`` + Generate with :generator:`Ninja Multi-Config`. + ``Kate - Unix Makefiles`` Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst index 0a07ea9..a45ab08 100644 --- a/Help/generator/Sublime Text 2.rst +++ b/Help/generator/Sublime Text 2.rst @@ -1,6 +1,12 @@ Sublime Text 2 -------------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Sublime Text 2 project files. Project files for Sublime Text 2 will be created in the top directory diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index a09857b..5b118d1 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,6 +8,7 @@ Synopsis .. parsed-literal:: + ccmake [<options>] -B <path-to-build> [-S <path-to-source>] ccmake [<options>] <path-to-source | path-to-existing-build> Description diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index ed5bbbf..9647f0d 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -107,6 +107,12 @@ Other Generators Extra Generators ================ +.. deprecated:: 3.27 + + Support for "Extra Generators" is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Some of the `CMake Generators`_ listed in the :manual:`cmake(1)` command-line tool :option:`--help <cmake --help>` output may have variants that specify an extra generator for an auxiliary IDE tool. diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 367b0a7..26083ca 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,8 +9,8 @@ Synopsis .. parsed-literal:: cmake-gui [<options>] + cmake-gui [<options>] -B <path-to-build> [-S <path-to-source>] cmake-gui [<options>] <path-to-source | path-to-existing-build> - cmake-gui [<options>] -S <path-to-source> -B <path-to-build> cmake-gui [<options>] --browse-manual [<filename>] Description diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 22e9eb2..e4c286d 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.27 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0144: find_package uses upper-case PACKAGENAME_ROOT variables. </policy/CMP0144> + Policies Introduced by CMake 3.26 ================================= diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 8564e7c..0ba8363 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -166,6 +166,7 @@ Variables that Change Behavior /variable/BUILD_SHARED_LIBS /variable/CMAKE_ABSOLUTE_DESTINATION_FILES + /variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY /variable/CMAKE_APPBUNDLE_PATH /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index e48ecd9..1ea7626 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,8 +9,8 @@ Synopsis .. parsed-literal:: `Generate a Project Buildsystem`_ + cmake [<options>] -B <path-to-build> [-S <path-to-source>] cmake [<options>] <path-to-source | path-to-existing-build> - cmake [<options>] -S <path-to-source> -B <path-to-build> `Build a Project`_ cmake --build <dir> [<options>] [-- <build-tool-options>] @@ -116,6 +116,20 @@ Generate a Project Buildsystem Run CMake with one of the following command signatures to specify the source and build trees and generate a buildsystem: +``cmake [<options>] -B <path-to-build> [-S <path-to-source>]`` + + .. versionadded:: 3.13 + + Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` + as the source tree. The specified paths may be absolute or relative + to the current working directory. The source tree must contain a + ``CMakeLists.txt`` file. The build tree will be created automatically + if it does not already exist. For example: + + .. code-block:: console + + $ cmake -S src -B build + ``cmake [<options>] <path-to-source>`` Uses the current working directory as the build tree, and ``<path-to-source>`` as the source tree. The specified path may @@ -141,20 +155,6 @@ source and build trees and generate a buildsystem: $ cd build $ cmake . -``cmake [<options>] -S <path-to-source> -B <path-to-build>`` - - .. versionadded:: 3.13 - - Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` - as the source tree. The specified paths may be absolute or relative - to the current working directory. The source tree must contain a - ``CMakeLists.txt`` file. The build tree will be created automatically - if it does not already exist. For example: - - .. code-block:: console - - $ cmake -S src -B build - In all cases the ``<options>`` may be zero or more of the `Options`_ below. The above styles for specifying the source and build trees may be mixed. @@ -167,14 +167,14 @@ the current working directory (cwd) is used for the other. For example: ============================== ============ =========== Command Line Source Dir Build Dir ============================== ============ =========== + ``cmake -B build`` `cwd` ``build`` + ``cmake -B build src`` ``src`` ``build`` + ``cmake -B build -S src`` ``src`` ``build`` ``cmake src`` ``src`` `cwd` ``cmake build`` (existing) `loaded` ``build`` ``cmake -S src`` ``src`` `cwd` ``cmake -S src build`` ``src`` ``build`` ``cmake -S src -B build`` ``src`` ``build`` - ``cmake -B build`` `cwd` ``build`` - ``cmake -B build src`` ``src`` ``build`` - ``cmake -B build -S src`` ``src`` ``build`` ============================== ============ =========== .. versionchanged:: 3.23 @@ -781,7 +781,7 @@ Available commands are: (:option:`-A ... <cmake -A>`). The value is a list of platforms known to be supported. ``extraGenerators`` - A list of strings with all the extra generators compatible with + A list of strings with all the :ref:`Extra Generators` compatible with the generator. ``fileApi`` @@ -1080,11 +1080,18 @@ Available commands are: situations instead. Use ``--`` to stop interpreting options and treat all remaining arguments as paths, even if they start with ``-``. -.. option:: sleep <number>... +.. option:: sleep <number> .. versionadded:: 3.0 - Sleep for given number of seconds. + Sleep for ``<number>`` seconds. ``<number>`` may be a floating point number. + A practical minimum is about 0.1 seconds due to overhead in starting/stopping + CMake executable. This can be useful in a CMake script to insert a delay: + + .. code-block:: cmake + + # Sleep for about 0.5 seconds + execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5) .. option:: tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...] @@ -1189,7 +1196,7 @@ Available commands are: .. option:: time <command> [<args>...] - Run command and display elapsed time. + Run ``<command>`` and display elapsed time (including overhead of CMake frontend). .. versionadded:: 3.5 The command now properly passes arguments with spaces or special characters diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 5e82faa..994ae47 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -11,7 +11,7 @@ Synopsis .. parsed-literal:: `Run Tests`_ - ctest [<options>] + ctest [<options>] [--test-dir <path-to-build>] `Build and Test Mode`_ ctest --build-and-test <path-to-source> <path-to-build> @@ -354,7 +354,8 @@ Run Tests .. option:: --test-dir <dir> - Specify the directory in which to look for tests. + Specify the directory in which to look for tests, typically a CMake project + build directory. If not specified, the current directory is used. .. option:: --test-output-size-passed <size> diff --git a/Help/policy/CMP0144.rst b/Help/policy/CMP0144.rst new file mode 100644 index 0000000..3959d96 --- /dev/null +++ b/Help/policy/CMP0144.rst @@ -0,0 +1,26 @@ +CMP0144 +------- + +.. versionadded:: 3.27 + +:command:`find_package` uses upper-case ``<PACKAGENAME>_ROOT`` variables. + +In CMake 3.27 and above the :command:`find_package(<PackageName>)` command now +searches prefixes specified by the upper-case :variable:`<PACKAGENAME>_ROOT` +CMake variable and the :envvar:`<PACKAGENAME>_ROOT` environment variable +in addition to the case-preserved :variable:`<PackageName>_ROOT` and +:envvar:`<PackageName>_ROOT` variables used since policy :policy:`CMP0074`. +This policy provides compatibility with projects that have not been +updated to avoid using ``<PACKAGENAME>_ROOT`` variables for other purposes. + +The ``OLD`` behavior for this policy is to ignore ``<PACKAGENAME>_ROOT`` +variables if the original ``<PackageName>`` has lower-case characters. +The ``NEW`` behavior for this policy is to use ``<PACKAGENAME>_ROOT`` +variables. + +This policy was introduced in CMake version 3.27. 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/prop_test/WILL_FAIL.rst b/Help/prop_test/WILL_FAIL.rst index f1f94a4..4926f40 100644 --- a/Help/prop_test/WILL_FAIL.rst +++ b/Help/prop_test/WILL_FAIL.rst @@ -3,5 +3,6 @@ WILL_FAIL If set to true, this will invert the pass/fail flag of the test. -This property can be used for tests that are expected to fail and -return a non zero return code. +This property can be used for tests that are expected to fail and return a +non-zero return code. Note that system-level test failures such as segmentation +faults or heap errors will still fail the test even if ``WILL_FALL`` is true. diff --git a/Help/release/dev/deprecate-extra-generators.rst b/Help/release/dev/deprecate-extra-generators.rst new file mode 100644 index 0000000..ceb2f4e --- /dev/null +++ b/Help/release/dev/deprecate-extra-generators.rst @@ -0,0 +1,5 @@ +deprecate-extra-generators +-------------------------- + +* The :ref:`Extra Generators` have been deprecated. IDEs may use the + :manual:`cmake-file-api(7)` to view CMake-generated project build trees. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..9c38866 --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,7 @@ +deprecate-policy-old +-------------------- + +* Compatibility with versions of CMake older than 3.5 is now deprecated + and will be removed from a future version. Calls to + :command:`cmake_minimum_required` or :command:`cmake_policy` that set + the policy version to an older value now issue a deprecation diagnostic. diff --git a/Help/release/dev/find_package-PACKAGENAME_ROOT.rst b/Help/release/dev/find_package-PACKAGENAME_ROOT.rst new file mode 100644 index 0000000..0388271 --- /dev/null +++ b/Help/release/dev/find_package-PACKAGENAME_ROOT.rst @@ -0,0 +1,7 @@ +find_package-PACKAGENAME_ROOT +----------------------------- + +* The :command:`find_package` command now searches prefixes specified by + upper-case :variable:`<PACKAGENAME>_ROOT` CMake variables and upper-case + :envvar:`<PACKAGENAME>_ROOT` environment variables. + See policy :policy:`CMP0144`. diff --git a/Help/release/dev/ninja-custom-command-depends.rst b/Help/release/dev/ninja-custom-command-depends.rst new file mode 100644 index 0000000..0b7840c --- /dev/null +++ b/Help/release/dev/ninja-custom-command-depends.rst @@ -0,0 +1,11 @@ +ninja-custom-command-depends +---------------------------- + +* The :command:`add_custom_command` command gained a new + ``DEPENDS_EXPLICIT_ONLY`` option to tell the :ref:`Ninja Generators` + not to add any dependencies implied by the target to which it is + attached. + +* The :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` variable can + be set to enable ``DEPENDS_EXPLICIT_ONLY`` in all uses of + :command:`add_custom_command` command. diff --git a/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst b/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst new file mode 100644 index 0000000..9c9bd2c --- /dev/null +++ b/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst @@ -0,0 +1,11 @@ +CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY +---------------------------------------------- + +.. versionadded:: 3.27 + +Whether to enable DEPENDS_EXPLICIT_ONLY option by default in +:command:`add_custom_command`. + +This variable affects the default behavior of the :command:`add_custom_command` +command. Setting this variable to ``ON`` is equivalent to using the ``DEPENDS_EXPLICIT_ONLY`` +option in all uses of that command. diff --git a/Help/variable/CMAKE_EDIT_COMMAND.rst b/Help/variable/CMAKE_EDIT_COMMAND.rst index 2f4ab1f..b21434f 100644 --- a/Help/variable/CMAKE_EDIT_COMMAND.rst +++ b/Help/variable/CMAKE_EDIT_COMMAND.rst @@ -2,7 +2,8 @@ CMAKE_EDIT_COMMAND ------------------ Full path to :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. Defined only for -:ref:`Makefile Generators` when not using an "extra" generator for an IDE. +:ref:`Makefile Generators` and :ref:`Ninja Generators` when not using any +:ref:`Extra Generators`. This is the full path to the CMake executable that can graphically edit the cache. For example, :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. diff --git a/Help/variable/CMAKE_EXTRA_GENERATOR.rst b/Help/variable/CMAKE_EXTRA_GENERATOR.rst index 2c92323..0a113a5 100644 --- a/Help/variable/CMAKE_EXTRA_GENERATOR.rst +++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst @@ -1,6 +1,12 @@ CMAKE_EXTRA_GENERATOR --------------------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + The extra generator used to build the project. See :manual:`cmake-generators(7)`. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst index 6b17be3..8b728ba 100644 --- a/Help/variable/PackageName_ROOT.rst +++ b/Help/variable/PackageName_ROOT.rst @@ -14,3 +14,11 @@ This variable may hold a single prefix or a :ref:`semicolon-separated list <CMake Language Lists>` of multiple prefixes. See also the :envvar:`<PackageName>_ROOT` environment variable. + +.. variable:: <PACKAGENAME>_ROOT + + .. versionadded:: 3.27 + + Calls to :command:`find_package(<PackageName>)` will also search in + prefixes specified by the upper-case ``<PACKAGENAME>_ROOT`` CMake + variable. See policy :policy:`CMP0144`. |