From c705279bae45c85b689febd66d5437d9ec05c9b9 Mon Sep 17 00:00:00 2001 From: Nikita Nemkin Date: Sun, 8 Nov 2020 01:30:30 +0500 Subject: Help: Add `.. versionadded` directives to commands documentation This change ony concerns directives that appear in the document body. The guidelines for inserting version directives: * Baseline version is CMake 3.0, i.e. directives start at 3.1. * Always use `.. versionadded::` directive, avoid ad-hoc version references. Exception: policy pages. * For new command signatures, put `versionadded` on a separate line after the signature. * For a group of new signatures in a new document section, a single version note at the beginning of the section is sufficient. * For new options, put `versionadded` on a separate line before option description. * If all the option descriptions in the list are short one-liners, it's fine to put `versionadded` on the same line as the description. * If multiple option descriptions in close proximity would have the same ..versionadded directive, consider adding a single directive after the list, mentioning all added options. * For compact value lists and sub-option lists, put a single `versionadded` directive after the list mentioning all additions. * When a change is described in a single paragraph, put `versionadded` into that paragraph. * When only part of the paragraph has changed, separate the changed part if it doesn't break the flow. Otherwise, write a follow-up clarification paragraph and apply version directive to that. * When multiple version directives are close by, order earlier additions before later additions. * Indent related lists and code blocks to include them in the scope of `versionadded` directive. Issue: #19715 --- Help/command/DEVICE_LINK_OPTIONS.txt | 21 ++-- Help/command/FIND_XXX.txt | 42 ++++---- Help/command/OPTIONS_SHELL.txt | 14 +-- Help/command/add_custom_command.rst | 37 +++++-- Help/command/add_custom_target.rst | 30 ++++-- Help/command/add_dependencies.rst | 3 + Help/command/add_executable.rst | 30 ++++-- Help/command/add_library.rst | 70 +++++++----- Help/command/add_test.rst | 5 + Help/command/cmake_host_system_information.rst | 8 ++ Help/command/cmake_minimum_required.rst | 3 + Help/command/cmake_parse_arguments.rst | 32 +++--- Help/command/cmake_policy.rst | 3 + Help/command/configure_file.rst | 28 +++-- Help/command/ctest_build.rst | 9 +- Help/command/ctest_configure.rst | 4 + Help/command/ctest_coverage.rst | 4 + Help/command/ctest_memcheck.rst | 2 + Help/command/ctest_start.rst | 9 +- Help/command/ctest_submit.rst | 32 +++++- Help/command/ctest_test.rst | 18 ++++ Help/command/ctest_update.rst | 4 + Help/command/ctest_upload.rst | 4 + Help/command/enable_language.rst | 9 ++ Help/command/execute_process.rst | 25 ++++- Help/command/export.rst | 17 ++- Help/command/file.rst | 143 ++++++++++++++++++------- Help/command/find_package.rst | 23 ++-- Help/command/foreach.rst | 2 + Help/command/function.rst | 5 +- Help/command/get_directory_property.rst | 6 +- Help/command/get_filename_component.rst | 16 +-- Help/command/get_property.rst | 36 ++++--- Help/command/get_source_file_property.rst | 28 ++--- Help/command/if.rst | 64 ++++++----- Help/command/include_external_msproject.rst | 7 +- Help/command/install.rst | 105 ++++++++++-------- Help/command/link_directories.rst | 30 +++--- Help/command/list.rst | 21 ++++ Help/command/macro.rst | 5 +- Help/command/mark_as_advanced.rst | 8 +- Help/command/math.rst | 23 ++-- Help/command/message.rst | 47 ++++---- Help/command/project.rst | 27 ++++- Help/command/separate_arguments.rst | 4 + Help/command/set_property.rst | 41 ++++--- Help/command/set_source_files_properties.rst | 7 +- Help/command/source_group.rst | 7 ++ Help/command/string.rst | 58 +++++++--- Help/command/target_compile_definitions.rst | 4 +- Help/command/target_compile_features.rst | 4 +- Help/command/target_compile_options.rst | 4 +- Help/command/target_include_directories.rst | 4 +- Help/command/target_link_libraries.rst | 20 +++- Help/command/target_link_options.rst | 4 +- Help/command/target_sources.rst | 24 +++-- Help/command/try_compile.rst | 120 ++++++++++++--------- Help/command/try_run.rst | 13 +++ 58 files changed, 939 insertions(+), 434 deletions(-) diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt index 3f0226f..1297cd0 100644 --- a/Help/command/DEVICE_LINK_OPTIONS.txt +++ b/Help/command/DEVICE_LINK_OPTIONS.txt @@ -1,11 +1,12 @@ -When a device link step is involved, which is controlled by -:prop_tgt:`CUDA_SEPARABLE_COMPILATION` and -:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`, -the raw options will be delivered to the host and device link steps (wrapped in -``-Xcompiler`` or equivalent for device link). Options wrapped with -``$`` -:manual:`generator expression ` will be used -only for the device link step. Options wrapped with ``$`` -:manual:`generator expression ` will be used -only for the host link step. +.. versionadded:: 3.18 + When a device link step is involved, which is controlled by + :prop_tgt:`CUDA_SEPARABLE_COMPILATION` and + :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`, + the raw options will be delivered to the host and device link steps (wrapped in + ``-Xcompiler`` or equivalent for device link). Options wrapped with + ``$`` + :manual:`generator expression ` will be used + only for the device link step. Options wrapped with ``$`` + :manual:`generator expression ` will be used + only for the host link step. diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 4a62c5b..97eecfc 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -33,9 +33,6 @@ of this command. If the |SEARCH_XXX| is found the result is stored in the variable and the search will not be repeated unless the variable is cleared. If nothing is found, the result will be ``-NOTFOUND``. -The ``REQUIRED`` option stops processing with an error message if nothing -is found, otherwise the search will be attempted again the -next time |FIND_XXX| is invoked with the same variable. Options include: @@ -60,7 +57,11 @@ Options include: Specify the documentation string for the ```` cache entry. ``REQUIRED`` - Stop processing with an error message if nothing is found. + .. versionadded:: 3.18 + + Stop processing with an error message if nothing is found, otherwise + the search will be attempted again the next time |FIND_XXX| is invoked + with the same variable. If ``NO_DEFAULT_PATH`` is specified, then no additional paths are added to the search. @@ -84,20 +85,21 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ```` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. If called from within a find module or any other script loaded by a call to - :command:`find_package()`, search prefixes unique to the - current package being found. Specifically, look in the - :variable:`_ROOT` CMake variable and the - :envvar:`_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 - ``_ROOT``, ``ENV{_ROOT}``, - ``_ROOT``, ``ENV{_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. .. versionadded:: 3.12 + If called from within a find module or any other script loaded by a call to + :command:`find_package()`, search prefixes unique to the + current package being found. Specifically, look in the + :variable:`_ROOT` CMake variable and the + :envvar:`_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 + ``_ROOT``, ``ENV{_ROOT}``, + ``_ROOT``, ``ENV{_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`. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| @@ -151,6 +153,10 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: or in the short-hand version of the command. These are typically hard-coded guesses. +.. versionadded:: 3.16 + Added ``CMAKE_FIND_USE__PATH`` variables to globally disable + various search locations. + .. |FIND_ARGS_XXX| replace:: NAMES name On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 0f8ec32..4051ffe 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,9 +1,11 @@ The final set of compile or link options used for a target is constructed by accumulating options from the current target and the usage requirements of its dependencies. The set of options is de-duplicated to avoid repetition. -While beneficial for individual options, the de-duplication step can break -up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may -specify a group of options using shell-like quoting along with a ``SHELL:`` -prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string -is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. -For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. + +.. versionadded:: 3.12 + While beneficial for individual options, the de-duplication step can break + up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may + specify a group of options using shell-like quoting along with a ``SHELL:`` + prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string + is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. + For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index a28b0b1..45e4e3e 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -51,6 +51,8 @@ The options are: used in the future. ``BYPRODUCTS`` + .. versionadded:: 3.2 + Specify the files the command is expected to produce but whose modification time may or may not be newer than the dependencies. If a byproduct name is a relative path it will be interpreted @@ -88,10 +90,11 @@ The options are: * The target is not being cross-compiled (i.e. the :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). - * The target is being cross-compiled and an emulator is provided (i.e. - its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). - In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be - prepended to the command before the location of the target executable. + * .. versionadded:: 3.6 + The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. If neither of the above conditions are met, it is assumed that the command name is a program to be found on the ``PATH`` at build time. @@ -153,18 +156,23 @@ The options are: 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 - directory to ensure the byproducts will be available. + + .. versionadded:: 3.16 + 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 + directory to ensure the byproducts will be available. If ``DEPENDS`` is not specified, the command will run whenever the ``OUTPUT`` is missing; if the command does not actually create the ``OUTPUT``, the rule will always run. - Arguments to ``DEPENDS`` may use - :manual:`generator expressions `. + .. versionadded:: 3.1 + Arguments to ``DEPENDS`` may use + :manual:`generator expressions `. ``COMMAND_EXPAND_LISTS`` + .. versionadded:: 3.8 + Lists in ``COMMAND`` arguments will be expanded, including those created with :manual:`generator expressions `, @@ -184,6 +192,8 @@ The options are: only for Makefile generators and will be ignored by other generators. ``JOB_POOL`` + .. versionadded:: 3.15 + Specify a :prop_gbl:`pool ` for the :generator:`Ninja` generator. Incompatible with ``USES_TERMINAL``, which implies the ``console`` pool. @@ -211,6 +221,8 @@ The options are: source file property. ``USES_TERMINAL`` + .. versionadded:: 3.2 + The command will be given direct access to the terminal if possible. With the :generator:`Ninja` generator, this places the command in the ``console`` :prop_gbl:`pool `. @@ -230,10 +242,13 @@ The options are: If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. - Arguments to ``WORKING_DIRECTORY`` may use - :manual:`generator expressions `. + .. versionadded:: 3.13 + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions `. ``DEPFILE`` + .. versionadded:: 3.7 + Specify a ``.d`` depfile for the :generator:`Ninja` generator. A ``.d`` file holds dependencies usually emitted by the custom command itself. diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 2eb0c88..e490b18 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -32,6 +32,8 @@ The options are: called ``ALL``). ``BYPRODUCTS`` + .. versionadded:: 3.2 + Specify the files the command is expected to produce but whose modification time may or may not be updated on subsequent builds. If a byproduct name is a relative path it will be interpreted @@ -67,10 +69,11 @@ The options are: * The target is not being cross-compiled (i.e. the :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). - * The target is being cross-compiled and an emulator is provided (i.e. - its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). - In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be - prepended to the command before the location of the target executable. + * .. versionadded:: 3.6 + The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. If neither of the above conditions are met, it is assumed that the command name is a program to be found on the ``PATH`` at build time. @@ -103,14 +106,18 @@ The options are: :command:`add_custom_command` command calls in the same directory (``CMakeLists.txt`` file). They will be brought up to date when the target is built. - A target-level dependency is added if any dependency is a byproduct - of a target or any of its build events in the same directory to ensure - the byproducts will be available before this target is built. + + .. versionadded:: 3.16 + A target-level dependency is added if any dependency is a byproduct + of a target or any of its build events in the same directory to ensure + the byproducts will be available before this target is built. Use the :command:`add_dependencies` command to add dependencies on other targets. ``COMMAND_EXPAND_LISTS`` + .. versionadded:: 3.8 + Lists in ``COMMAND`` arguments will be expanded, including those created with :manual:`generator expressions `, @@ -119,6 +126,8 @@ The options are: to be properly expanded. ``JOB_POOL`` + .. versionadded:: 3.15 + Specify a :prop_gbl:`pool ` for the :generator:`Ninja` generator. Incompatible with ``USES_TERMINAL``, which implies the ``console`` pool. @@ -141,6 +150,8 @@ The options are: tool-specific special characters. ``USES_TERMINAL`` + .. versionadded:: 3.2 + The command will be given direct access to the terminal if possible. With the :generator:`Ninja` generator, this places the command in the ``console`` :prop_gbl:`pool `. @@ -150,5 +161,6 @@ The options are: If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. - Arguments to ``WORKING_DIRECTORY`` may use - :manual:`generator expressions `. + .. versionadded:: 3.13 + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions `. diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst index de219a5..14c0183 100644 --- a/Help/command/add_dependencies.rst +++ b/Help/command/add_dependencies.rst @@ -17,6 +17,9 @@ Dependencies added to an :ref:`imported target ` or an :ref:`interface library ` are followed transitively in its place since the target itself does not build. +.. versionadded:: 3.3 + Allow adding dependencies to interface libraries. + See the ``DEPENDS`` option of :command:`add_custom_target` and :command:`add_custom_command` commands for adding file-level dependencies in custom rules. See the :prop_sf:`OBJECT_DEPENDS` diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index e073228..dde9429 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -17,13 +17,21 @@ Normal Executables [source1] [source2 ...]) Adds an executable target called ```` to be built from the source -files listed in the command invocation. (The source files can be omitted -here if they are added later using :command:`target_sources`.) The +files listed in the command invocation. The ```` corresponds to the logical target name and must be globally unique within a project. The actual file name of the executable built is constructed based on conventions of the native platform (such as ``.exe`` or just ````). +.. versionadded:: 3.1 + Source arguments to ``add_executable`` may use "generator expressions" with + the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` + manual for available expressions. + +.. versionadded:: 3.11 + The source files can be omitted if they are added later using + :command:`target_sources`. + By default the executable file will be created in the build tree directory corresponding to the source tree directory in which the command was invoked. See documentation of the @@ -43,10 +51,8 @@ If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` target property for details. -Source arguments to ``add_executable`` may use "generator expressions" with -the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` -manual for available expressions. See the :manual:`cmake-buildsystem(7)` -manual for more on defining buildsystem properties. +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are pre-processed, and you want to have the original sources reachable from @@ -85,10 +91,14 @@ be used to refer to ```` in subsequent commands. The ```` does not appear in the generated buildsystem as a make target. The ```` may not be an ``ALIAS``. -An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target ` -has scope in the directory in which the alias is created and below. -The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the -alias is global or not. +.. versionadded:: 3.11 + An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target ` + +.. versionadded:: 3.18 + An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is + scoped to the directory in which it is created and subdirectories. + The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the + alias is global or not. ``ALIAS`` targets can be used as targets to read properties from, executables for custom commands and custom targets. They can also be diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index b7dfabc..d3fbdcf 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -17,13 +17,21 @@ Normal Libraries [...]) Adds a library target called ```` to be built from the source files -listed in the command invocation. (The source files can be omitted here -if they are added later using :command:`target_sources`.) The ```` +listed in the command invocation. The ```` corresponds to the logical target name and must be globally unique within a project. The actual file name of the library built is constructed based on conventions of the native platform (such as ``lib.a`` or ``.lib``). +.. versionadded:: 3.1 + Source arguments to ``add_library`` may use "generator expressions" with + the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` + manual for available expressions. + +.. versionadded:: 3.11 + The source files can be omitted if they are added later using + :command:`target_sources`. + ``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of library to be created. ``STATIC`` libraries are archives of object files for use when linking other targets. ``SHARED`` libraries are linked @@ -34,9 +42,13 @@ type is ``STATIC`` or ``SHARED`` based on whether the current value of the variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and ``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property is set to ``ON`` automatically. -A ``SHARED`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK` +A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` target property to create an macOS Framework. +.. versionadded:: 3.8 + A ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK` + target property to create a static Framework. + If a library does not export any symbols, it must not be declared as a ``SHARED`` library. For example, a Windows resource DLL or a managed C++/CLI DLL that exports no unmanaged symbols would need to be a ``MODULE`` library. @@ -55,10 +67,8 @@ If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` target property for details. -Source arguments to ``add_library`` may use "generator expressions" with -the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` -manual for available expressions. See the :manual:`cmake-buildsystem(7)` -manual for more on defining buildsystem properties. +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are pre-processed, and you want to have the original sources reachable from @@ -93,6 +103,9 @@ systems (such as Xcode) may not like targets that have only object files, so consider adding at least one real source file to any target that references ``$``. +.. versionadded:: 3.12 + Object libraries can be linked to with :command:`target_link_libraries`. + Interface Libraries ^^^^^^^^^^^^^^^^^^^ @@ -121,23 +134,28 @@ like any other target. An interface library created with the above signature has no source files itself and is not included as a target in the generated buildsystem. -Since CMake 3.19, an interface library target may be created with -source files: +.. versionadded:: 3.15 + An interface library can have :prop_tgt:`PUBLIC_HEADER` and + :prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those + properties can be installed using the :command:`install(TARGETS)` command. -.. code-block:: cmake +.. versionadded:: 3.19 + An interface library target may be created with source files: + + .. code-block:: cmake - add_library( INTERFACE [...] [EXCLUDE_FROM_ALL]) + add_library( INTERFACE [...] [EXCLUDE_FROM_ALL]) -Source files may be listed directly in the ``add_library`` call or added -later by calls to :command:`target_sources` with the ``PRIVATE`` or -``PUBLIC`` keywords. + Source files may be listed directly in the ``add_library`` call or added + later by calls to :command:`target_sources` with the ``PRIVATE`` or + ``PUBLIC`` keywords. -If an interface library has source files (i.e. the :prop_tgt:`SOURCES` -target property is set), it will appear in the generated buildsystem -as a build target much like a target defined by the -:command:`add_custom_target` command. It does not compile any sources, -but does contain build rules for custom commands created by the -:command:`add_custom_command` command. + If an interface library has source files (i.e. the :prop_tgt:`SOURCES` + target property is set), it will appear in the generated buildsystem + as a build target much like a target defined by the + :command:`add_custom_target` command. It does not compile any sources, + but does contain build rules for custom commands created by the + :command:`add_custom_command` command. .. note:: In most command signatures where the ``INTERFACE`` keyword appears, @@ -211,10 +229,14 @@ used to refer to ```` in subsequent commands. The ```` does not appear in the generated buildsystem as a make target. The ```` may not be an ``ALIAS``. -An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target ` -has scope in the directory in which the alias is created and below. -The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the -alias is global or not. +.. versionadded:: 3.11 + An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target ` + +.. versionadded:: 3.18 + An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is + scoped to the directory in which it is created and below. + The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the + alias is global or not. ``ALIAS`` targets can be used as linkable targets and as targets to read properties from. They can also be tested for existence with the diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 2b4d082..832d8db 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -31,6 +31,8 @@ if necessary. See policy :policy:`CMP0110`. The options are: current source directory. ``COMMAND_EXPAND_LISTS`` + .. versionadded:: 3.16 + Lists in ``COMMAND`` arguments will be expanded, including those created with :manual:`generator expressions `. @@ -43,6 +45,9 @@ unless the :prop_test:`PASS_REGULAR_EXPRESSION`, :prop_test:`FAIL_REGULAR_EXPRESSION` or :prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. +.. versionadded:: 3.16 + Added :prop_test:`SKIP_REGULAR_EXPRESSION` property. + The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 2e9563a..2b902a9 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -24,6 +24,14 @@ Key Description ``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in MiB [#mebibytes]_ ``TOTAL_PHYSICAL_MEMORY`` Total physical memory in MiB [#mebibytes]_ ``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in MiB [#mebibytes]_ +============================= ================================================ + +.. versionadded:: 3.10 + Additional ```` values are available: + +============================= ================================================ +Key Description +============================= ================================================ ``IS_64BIT`` One if processor is 64Bit ``HAS_FPU`` One if processor has floating point unit ``HAS_MMX`` One if processor supports MMX instructions diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index e6ebcf0..fe0e424 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -7,6 +7,9 @@ Require a minimum version of cmake. cmake_minimum_required(VERSION [...] [FATAL_ERROR]) +.. versionadded:: 3.12 + The optional ```` version. + Sets the minimum required version of cmake for a project. Also updates the policy settings as explained below. diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index 8803ec8..824b7dd 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -21,11 +21,12 @@ respective options. The first signature reads processes arguments passed in the ``...``. This may be used in either a :command:`macro` or a :command:`function`. -The ``PARSE_ARGV`` signature is only for use in a :command:`function` -body. In this case the arguments that are parsed come from the -``ARGV#`` variables of the calling function. The parsing starts with -the ````-th argument, where ```` is an unsigned integer. This allows for -the values to have special characters like ``;`` in them. +.. versionadded:: 3.7 + The ``PARSE_ARGV`` signature is only for use in a :command:`function` + body. In this case the arguments that are parsed come from the + ``ARGV#`` variables of the calling function. The parsing starts with + the ````-th argument, where ```` is an unsigned integer. + This allows for the values to have special characters like ``;`` in them. The ```` argument contains all options for the respective macro, i.e. keywords which can be used when calling the macro without any value @@ -40,12 +41,11 @@ The ```` argument contains all keywords for this macro which can be followed by more than one value, like e.g. the ``TARGETS`` or ``FILES`` keywords of the :command:`install` command. -.. note:: - - All keywords shall be unique. I.e. every keyword shall only be specified - once in either ````, ```` or - ````. A warning will be emitted if uniqueness is - violated. +.. versionadded:: 3.5 + All keywords shall be unique. I.e. every keyword shall only be specified + once in either ````, ```` or + ````. A warning will be emitted if uniqueness is + violated. When done, ``cmake_parse_arguments`` will consider for each of the keywords listed in ````, ```` and @@ -61,10 +61,12 @@ All remaining arguments are collected in a variable were recognized. This can be checked afterwards to see whether your macro was called with unrecognized parameters. -```` and ```` that were given no -values at all are collected in a variable ``_KEYWORDS_MISSING_VALUES`` -that will be undefined if all keywords received values. This can be checked -to see if there were keywords without any values given. +.. versionadded:: 3.15 + ```` and ```` that were given no + values at all are collected in a variable + ``_KEYWORDS_MISSING_VALUES`` that will be undefined if all keywords + received values. This can be checked to see if there were keywords without + any values given. Consider the following example macro, ``my_install()``, which takes similar arguments to the real :command:`install` command: diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index 4bc7807..94060d9 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -28,6 +28,9 @@ encourage projects to set policies based on CMake versions: cmake_policy(VERSION [...]) +.. versionadded:: 3.12 + The optional ```` version. + ```` and the optional ```` are each CMake versions of the form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ```` version must be at least ``2.4`` and at most the running version of CMake. diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 8d66a9b..63ea84d 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -38,22 +38,24 @@ a false constant by the :command:`if` command. The "..." content on the line after the variable name, if any, is processed as above. Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with either ``#define VAR 1`` or ``#define VAR 0`` similarly. -The result lines (with the exception of the ``#undef`` comments) can be -indented using spaces and/or tabs between the ``#`` character -and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace -indentation will be preserved in the output lines: -.. code-block:: c +.. versionadded:: 3.10 + The result lines (with the exception of the ``#undef`` comments) can be + indented using spaces and/or tabs between the ``#`` character + and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace + indentation will be preserved in the output lines: - # cmakedefine VAR - # cmakedefine01 VAR + .. code-block:: c -will be replaced, if ``VAR`` is defined, with + # cmakedefine VAR + # cmakedefine01 VAR -.. code-block:: c + will be replaced, if ``VAR`` is defined, with + + .. code-block:: c - # define VAR - # define VAR 1 + # define VAR + # define VAR 1 If the input file is modified the build system will re-run CMake to re-configure the file and generate the build system again. @@ -88,11 +90,15 @@ The arguments are: This is useful for configuring scripts that use ``${VAR}`` syntax. ``NO_SOURCE_PERMISSIONS`` + .. versionadded:: 3.19 + Does not transfer the file permissions of the original file to the copy. The copied file permissions default to the standard 644 value (-rw-r--r--). ``USE_SOURCE_PERMISSIONS`` + .. versionadded:: 3.20 + Transfer the file permissions of the original file to the output file. ``NEWLINE_STYLE