diff options
Diffstat (limited to 'Help')
247 files changed, 2844 insertions, 1129 deletions
diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt index 3d50208163..878754ddfd 100644 --- a/Help/command/DEVICE_LINK_OPTIONS.txt +++ b/Help/command/DEVICE_LINK_OPTIONS.txt @@ -7,8 +7,6 @@ Host And Device Specific Link Options :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 - ``$<DEVICE_LINK:...>`` - :manual:`generator expression <cmake-generator-expressions(7)>` will be used - only for the device link step. Options wrapped with ``$<HOST_LINK:...>`` - :manual:`generator expression <cmake-generator-expressions(7)>` will be used - only for the host link step. + :genex:`$<DEVICE_LINK:...>` generator expression will be used + only for the device link step. Options wrapped with :genex:`$<HOST_LINK:...>` + generator expression will be used only for the host link step. diff --git a/Help/command/GENEX_NOTE.txt b/Help/command/GENEX_NOTE.txt new file mode 100644 index 0000000000..4a7906ce95 --- /dev/null +++ b/Help/command/GENEX_NOTE.txt @@ -0,0 +1,6 @@ +.. |more_see_also| replace:: See the :manual:`cmake-buildsystem(7)` manual + for more on defining buildsystem properties. + +Arguments to |command_name| may use generator expressions +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. |more_see_also| diff --git a/Help/command/SUPPORTED_LANGUAGES.txt b/Help/command/SUPPORTED_LANGUAGES.txt new file mode 100644 index 0000000000..a98c07a5d3 --- /dev/null +++ b/Help/command/SUPPORTED_LANGUAGES.txt @@ -0,0 +1,25 @@ + +Supported languages are ``C``, ``CXX`` (i.e. C++), ``CSharp`` (i.e. C#), ``CUDA``, +``OBJC`` (i.e. Objective-C), ``OBJCXX`` (i.e. Objective-C++), ``Fortran``, ``HIP``, +``ISPC``, ``Swift``, ``ASM``, ``ASM_NASM``, ``ASM_MARMASM``, ``ASM_MASM``, and ``ASM-ATT``. + + .. versionadded:: 3.8 + Added ``CSharp`` and ``CUDA`` support. + + .. versionadded:: 3.15 + Added ``Swift`` support. + + .. versionadded:: 3.16 + Added ``OBJC`` and ``OBJCXX`` support. + + .. versionadded:: 3.18 + Added ``ISPC`` support. + + .. versionadded:: 3.21 + Added ``HIP`` support. + + .. versionadded:: 3.26 + Added ``ASM_MARMASM`` support. + +If enabling ``ASM``, list it last so that CMake can check whether +compilers for other languages like ``C`` work for assembly too. diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst index 48e33be63f..b2eb2af3b7 100644 --- a/Help/command/add_compile_definitions.rst +++ b/Help/command/add_compile_definitions.rst @@ -21,7 +21,13 @@ Function-style definitions are not supported. CMake will automatically escape the value correctly for the native build system (note that CMake language syntax may require escapes to specify some values). -Arguments to ``add_compile_definitions`` 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. +.. versionadded:: 3.26 + Any leading ``-D`` on an item will be removed. + +.. |command_name| replace:: ``add_compile_definitions`` +.. include:: GENEX_NOTE.txt + +See Also +^^^^^^^^ + +* The command :command:`target_compile_definitions` adds target-specific definitions. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 36f403c8ae..0ccebc679b 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -14,10 +14,8 @@ directory and below. Arguments ^^^^^^^^^ -Arguments to ``add_compile_options`` 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. +.. |command_name| replace:: ``add_compile_options`` +.. include:: GENEX_NOTE.txt .. include:: OPTIONS_SHELL.txt @@ -30,22 +28,25 @@ this command is in a compiler-specific conditional clause: .. code-block:: cmake if (MSVC) - # warning level 4 and all warnings as errors - add_compile_options(/W4 /WX) + # warning level 4 + add_compile_options(/W4) else() - # lots of warnings and all warnings as errors - add_compile_options(-Wall -Wextra -pedantic -Werror) + # additional warnings + add_compile_options(-Wall -Wextra -Wpedantic) endif() +To set per-language options, use the :genex:`$<COMPILE_LANGUAGE>` +or :genex:`$<COMPILE_LANGUAGE:languages>` generator expressions. + See Also ^^^^^^^^ -This command can be used to add any options. However, for -adding preprocessor definitions and include directories it is recommended -to use the more specific commands :command:`add_compile_definitions` -and :command:`include_directories`. +* This command can be used to add any options. However, for + adding preprocessor definitions and include directories it is recommended + to use the more specific commands :command:`add_compile_definitions` + and :command:`include_directories`. -The command :command:`target_compile_options` adds target-specific options. +* The command :command:`target_compile_options` adds target-specific options. -The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one -source file. +* The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one + source file. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 99adc85c12..293d3f01bc 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -31,14 +31,12 @@ This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) that specifies any output of the custom command as a source file is given a rule to generate the file using the command at build time. -Do not list the output in more than one independent target that -may build in parallel or the two instances of the rule may conflict -(instead use the :command:`add_custom_target` command to drive the -command and make the other targets depend on that one). -In makefile terms this creates a new target in the following form:: - OUTPUT: MAIN_DEPENDENCY DEPENDS - COMMAND +Do not list the output in more than one independent target that +may build in parallel or the instances of the rule may conflict. +Instead, use the :command:`add_custom_target` command to drive the +command and make the other targets depend on that one. See the +`Example: Generating Files for Multiple Targets`_ below. The options are: @@ -140,6 +138,10 @@ The options are: Display the given message before the commands are executed at build time. + .. versionadded:: 3.26 + Arguments to ``COMMENT`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``DEPENDS`` Specify files on which the command depends. Each argument is converted to a dependency as follows: @@ -229,15 +231,24 @@ The options are: ``OUTPUT`` Specify the output files the command is expected to produce. - If an output name is a relative path it will be interpreted - relative to the build tree directory corresponding to the - current source directory. Each output file will be marked with the :prop_sf:`GENERATED` source file property automatically. If the output of the custom command is not actually created as a file on disk it should be marked with the :prop_sf:`SYMBOLIC` source file property. + If an output file name is a relative path, its absolute path is + determined by interpreting it relative to: + + 1. the build directory corresponding to the current source directory + (:variable:`CMAKE_CURRENT_BINARY_DIR`), or + + 2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`). + + The path in the build directory is preferred unless the path in the + source tree is mentioned as an absolute source file path elsewhere + in the current directory. + .. versionadded:: 3.20 Arguments to ``OUTPUT`` may use a restricted set of :manual:`generator expressions <cmake-generator-expressions(7)>`. @@ -385,6 +396,49 @@ will re-run whenever ``in.txt`` changes. where ``<config>`` is the build configuration, and then compile the generated source as part of a library. +Example: Generating Files for Multiple Targets +"""""""""""""""""""""""""""""""""""""""""""""" + +If multiple independent targets need the same custom command output, +it must be attached to a single custom target on which they all depend. +Consider the following example: + +.. code-block:: cmake + + add_custom_command( + OUTPUT table.csv + COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat + -o table.csv + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat + VERBATIM) + add_custom_target(generate_table_csv DEPENDS table.csv) + + add_custom_command( + OUTPUT foo.cxx + COMMAND genFromTable -i table.csv -case foo -o foo.cxx + DEPENDS table.csv # file-level dependency + generate_table_csv # target-level dependency + VERBATIM) + add_library(foo foo.cxx) + + add_custom_command( + OUTPUT bar.cxx + COMMAND genFromTable -i table.csv -case bar -o bar.cxx + DEPENDS table.csv # file-level dependency + generate_table_csv # target-level dependency + VERBATIM) + add_library(bar bar.cxx) + +Output ``foo.cxx`` is needed only by target ``foo`` and output ``bar.cxx`` +is needed only by target ``bar``, but *both* targets need ``table.csv``, +transitively. Since ``foo`` and ``bar`` are independent targets that may +build concurrently, we prevent them from racing to generate ``table.csv`` +by placing its custom command in a separate target, ``generate_table_csv``. +The custom commands generating ``foo.cxx`` and ``bar.cxx`` each specify a +target-level dependency on ``generate_table_csv``, so the targets using them, +``foo`` and ``bar``, will not build until after target ``generate_table_csv`` +is built. + .. _`add_custom_command(TARGET)`: Build Events @@ -490,3 +544,8 @@ Ninja Multi-Config ``add_custom_command`` supports the :generator:`Ninja Multi-Config` generator's cross-config capabilities. See the generator documentation for more information. + +See Also +^^^^^^^^ + +* :command:`add_custom_target` diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index d8882ca99b..545b9a5ae3 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -109,6 +109,10 @@ The options are: Display the given message before the commands are executed at build time. + .. versionadded:: 3.26 + Arguments to ``COMMENT`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``DEPENDS`` Reference files and outputs of custom commands created with :command:`add_custom_command` command calls in the same directory @@ -181,3 +185,8 @@ Ninja Multi-Config ``add_custom_target`` supports the :generator:`Ninja Multi-Config` generator's cross-config capabilities. See the generator documentation for more information. + +See Also +^^^^^^^^ + +* :command:`add_custom_command` diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index fe69188363..5c1f7b43bd 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -1,7 +1,7 @@ add_definitions --------------- -Add -D define flags to the compilation of source files. +Add ``-D`` define flags to the compilation of source files. .. code-block:: cmake @@ -31,5 +31,8 @@ backwards compatibility. See documentation of the properties for details on adding preprocessor definitions to specific scopes and configurations. -See the :manual:`cmake-buildsystem(7)` manual for more on defining -buildsystem properties. +See Also +^^^^^^^^ + +* The :manual:`cmake-buildsystem(7)` manual for more on defining + buildsystem properties. diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst index 14c0183031..23cb4058f9 100644 --- a/Help/command/add_dependencies.rst +++ b/Help/command/add_dependencies.rst @@ -20,7 +20,12 @@ 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` -source file property to add file-level dependencies to object files. +See Also +^^^^^^^^ + +* The ``DEPENDS`` option of :command:`add_custom_target` and + :command:`add_custom_command` commands for adding file-level + dependencies in custom rules. + +* The :prop_sf:`OBJECT_DEPENDS` source file property to add + file-level dependencies to object files. diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index dde94293e9..d9ea0da1a1 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -107,3 +107,8 @@ The ``<name>`` may not be used to modify properties of ``<target>``, that is, it may not be used as the operand of :command:`set_property`, :command:`set_target_properties`, :command:`target_link_libraries` etc. An ``ALIAS`` target may not be installed or exported. + +See Also +^^^^^^^^ + +* :command:`add_library` diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 7dc4365e6e..07c8babd29 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -83,10 +83,10 @@ Object Libraries Creates an :ref:`Object Library <Object Libraries>`. An object library compiles source files but does not archive or link their object files into a -library. Instead other targets created by :command:`add_library` or +library. Instead other targets created by ``add_library`` or :command:`add_executable` may reference the objects using an expression of the -form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the -object library name. For example: +form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where +``objlib`` is the object library name. For example: .. code-block:: cmake @@ -101,7 +101,7 @@ They may contain custom commands generating such sources, but not ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build 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 -``$<TARGET_OBJECTS:objlib>``. +:genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>`. .. versionadded:: 3.12 Object libraries can be linked to with :command:`target_link_libraries`. @@ -261,3 +261,8 @@ to modify properties of ``<target>``, that is, it may not be used as the operand of :command:`set_property`, :command:`set_target_properties`, :command:`target_link_libraries` etc. An ``ALIAS`` target may not be installed or exported. + +See Also +^^^^^^^^ + +* :command:`add_executable` diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index f03e7c0e4c..c09e106908 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst @@ -23,13 +23,18 @@ exist to add libraries (:command:`target_link_libraries` or since they do not use a linker. To add archiver or MSVC librarian flags, see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. -Arguments to ``add_link_options`` 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. +.. |command_name| replace:: ``add_link_options`` +.. include:: GENEX_NOTE.txt .. include:: DEVICE_LINK_OPTIONS.txt .. include:: OPTIONS_SHELL.txt .. include:: LINK_OPTIONS_LINKER.txt + +See Also +^^^^^^^^ + +* :command:`link_libraries` +* :command:`target_link_libraries` +* :command:`target_link_options` diff --git a/Help/command/block.rst b/Help/command/block.rst index dfd60d446d..a352e83651 100644 --- a/Help/command/block.rst +++ b/Help/command/block.rst @@ -71,6 +71,6 @@ inside the block. See Also ^^^^^^^^ - * :command:`endblock` - * :command:`return` - * :command:`cmake_policy` +* :command:`endblock` +* :command:`return` +* :command:`cmake_policy` diff --git a/Help/command/build_name.rst b/Help/command/build_name.rst index 2a1fbae627..5acf858300 100644 --- a/Help/command/build_name.rst +++ b/Help/command/build_name.rst @@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`. Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead. -:: +.. code-block:: cmake build_name(variable) diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index c84c5b57b7..76824ef1f0 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -17,7 +17,7 @@ Synopsis Query host system specific information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_host_system_information(RESULT <variable> QUERY <key> ...) diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index d159770492..031bd5690e 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -79,3 +79,8 @@ invokes cmake_policy(VERSION 2.4[...<max>]) which enables compatibility features for CMake 2.4 and lower. + +See Also +^^^^^^^^ + +* :command:`cmake_policy` diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index 7c85da6103..0bb1d91bb1 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -113,3 +113,9 @@ interpreted as the beginning of the new option. E.g. is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. + +See Also +^^^^^^^^ + +* :command:`function` +* :command:`macro` diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index eb7da07e38..4e6bedb650 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -237,7 +237,7 @@ The following forms of the ``GET`` subcommand each retrieve a different component or group of components from a path. See `Path Structure And Terminology`_ for the meaning of each path component. -:: +.. code-block:: cmake cmake_path(GET <path-var> ROOT_NAME <out-var>) cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>) @@ -408,7 +408,7 @@ meaning of each path component. .. _HAS_RELATIVE_PART: .. _HAS_PARENT_PATH: -:: +.. code-block:: cmake cmake_path(HAS_ROOT_NAME <path-var> <out-var>) cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>) @@ -432,7 +432,7 @@ Note the following special cases: .. _IS_ABSOLUTE: -:: +.. code-block:: cmake cmake_path(IS_ABSOLUTE <path-var> <out-var>) @@ -446,7 +446,7 @@ false while ``HAS_ROOT_DIRECTORY`` can be true. .. _IS_RELATIVE: -:: +.. code-block:: cmake cmake_path(IS_RELATIVE <path-var> <out-var>) @@ -454,7 +454,7 @@ This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``. .. _IS_PREFIX: -:: +.. code-block:: cmake cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>) @@ -476,7 +476,7 @@ are :ref:`normalized <Normalization>` before the check. .. _Path COMPARE: .. _COMPARE: -:: +.. code-block:: cmake cmake_path(COMPARE <input1> EQUAL <input2> <out-var>) cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>) @@ -510,7 +510,7 @@ Modification .. _cmake_path-SET: -:: +.. code-block:: cmake cmake_path(SET <path-var> [NORMALIZE] <input>) @@ -539,7 +539,7 @@ Output:: .. _APPEND: -:: +.. code-block:: cmake cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) @@ -570,7 +570,7 @@ the following algorithm (pseudo-code) applies: .. _APPEND_STRING: -:: +.. code-block:: cmake cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) @@ -579,7 +579,7 @@ Append all the ``<input>`` arguments to the ``<path-var>`` without adding any .. _REMOVE_FILENAME: -:: +.. code-block:: cmake cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>]) @@ -609,7 +609,7 @@ Output:: .. _REPLACE_FILENAME: -:: +.. code-block:: cmake cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>]) @@ -628,7 +628,7 @@ equivalent to the following: .. _REMOVE_EXTENSION: -:: +.. code-block:: cmake cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>]) @@ -637,7 +637,7 @@ Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``. .. _REPLACE_EXTENSION: -:: +.. code-block:: cmake cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>]) @@ -661,7 +661,7 @@ Generation .. _NORMAL_PATH: -:: +.. code-block:: cmake cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>]) @@ -670,7 +670,7 @@ Normalize ``<path-var>`` according the steps described in :ref:`Normalization`. .. _cmake_path-RELATIVE_PATH: .. _RELATIVE_PATH: -:: +.. code-block:: cmake cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>]) @@ -686,7 +686,7 @@ as that used by C++ .. _ABSOLUTE_PATH: -:: +.. code-block:: cmake cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>]) @@ -713,7 +713,7 @@ target platform when cross-compiling. .. _cmake_path-NATIVE_PATH: .. _NATIVE_PATH: -:: +.. code-block:: cmake cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>) @@ -727,7 +727,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized .. _cmake_path-TO_CMAKE_PATH_LIST: .. _TO_CMAKE_PATH_LIST: -:: +.. code-block:: cmake cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE]) @@ -749,7 +749,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized .. _cmake_path-TO_NATIVE_PATH_LIST: .. _TO_NATIVE_PATH_LIST: -:: +.. code-block:: cmake cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE]) @@ -788,7 +788,7 @@ Hashing .. _HASH: -:: +.. code-block:: cmake cmake_path(HASH <path-var> <out-var>) diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index 54fc548158..cde74a733c 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -150,3 +150,8 @@ use the pre-record policies when they are invoked. If the function or macro implementation sets policies, the changes automatically propagate up through callers until they reach the closest nested policy stack entry. + +See Also +^^^^^^^^ + +* :command:`cmake_minimum_required` diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 1d81423515..6f4cedfa67 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -58,7 +58,7 @@ or #define VAR 1 Input lines of the form ``#cmakedefine01 VAR ...`` will expand -as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``, +as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 1``, which may lead to undefined behavior. .. versionadded:: 3.10 @@ -174,11 +174,16 @@ Otherwise it will contain: /* #undef FOO_ENABLE */ /* #undef FOO_STRING */ -One may then use the :command:`include_directories` command to +One may then use the :command:`target_include_directories` command to specify the output directory as an include directory: .. code-block:: cmake - include_directories(${CMAKE_CURRENT_BINARY_DIR}) + target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}") so that sources may include the header as ``#include <foo.h>``. + +See Also +^^^^^^^^ + +* :command:`file(GENERATE)` diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 8c81f2d526..bce17396e0 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -3,7 +3,7 @@ ctest_build Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_build([BUILD <build-dir>] [APPEND] [CONFIGURATION <config>] diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst index 95712aac06..f23dd22244 100644 --- a/Help/command/ctest_configure.rst +++ b/Help/command/ctest_configure.rst @@ -3,7 +3,7 @@ ctest_configure Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND] [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET] diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index a6c643bbc5..319c97855c 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -3,7 +3,7 @@ ctest_coverage Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_coverage([BUILD <build-dir>] [APPEND] [LABELS <label>...] diff --git a/Help/command/ctest_empty_binary_directory.rst b/Help/command/ctest_empty_binary_directory.rst index 77536673ce..5d26de1219 100644 --- a/Help/command/ctest_empty_binary_directory.rst +++ b/Help/command/ctest_empty_binary_directory.rst @@ -3,9 +3,9 @@ ctest_empty_binary_directory empties the binary directory -:: +.. code-block:: cmake - ctest_empty_binary_directory( directory ) + ctest_empty_binary_directory(<directory>) Removes a binary directory. This command will perform some checks prior to deleting the directory in an attempt to avoid malicious or diff --git a/Help/command/ctest_memcheck.rst b/Help/command/ctest_memcheck.rst index 8b79077946..4ca7364f03 100644 --- a/Help/command/ctest_memcheck.rst +++ b/Help/command/ctest_memcheck.rst @@ -3,7 +3,7 @@ ctest_memcheck Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_memcheck([BUILD <build-dir>] [APPEND] [START <start-number>] diff --git a/Help/command/ctest_read_custom_files.rst b/Help/command/ctest_read_custom_files.rst index cf8e17a9cb..53c093e55f 100644 --- a/Help/command/ctest_read_custom_files.rst +++ b/Help/command/ctest_read_custom_files.rst @@ -3,9 +3,9 @@ ctest_read_custom_files read CTestCustom files. -:: +.. code-block:: cmake - ctest_read_custom_files( directory ... ) + ctest_read_custom_files(<directory>...) Read all the CTestCustom.ctest or CTestCustom.cmake files from the given directory. diff --git a/Help/command/ctest_run_script.rst b/Help/command/ctest_run_script.rst index a2b348f4ca..145bd90959 100644 --- a/Help/command/ctest_run_script.rst +++ b/Help/command/ctest_run_script.rst @@ -3,7 +3,7 @@ ctest_run_script runs a :option:`ctest -S` script -:: +.. code-block:: cmake ctest_run_script([NEW_PROCESS] script_file_name script_file_name1 script_file_name2 ... [RETURN_VALUE var]) diff --git a/Help/command/ctest_sleep.rst b/Help/command/ctest_sleep.rst index 16a914c0b4..42b9768f00 100644 --- a/Help/command/ctest_sleep.rst +++ b/Help/command/ctest_sleep.rst @@ -3,13 +3,13 @@ ctest_sleep sleeps for some amount of time -:: +.. code-block:: cmake ctest_sleep(<seconds>) Sleep for given number of seconds. -:: +.. code-block:: cmake ctest_sleep(<time1> <duration> <time2>) diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 921279a43c..2d68a37ac4 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -3,7 +3,7 @@ ctest_start Starts the testing for a given model -:: +.. code-block:: cmake ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET]) diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index d66182540a..3b6bf3a7f1 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -3,7 +3,7 @@ ctest_submit Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_submit([PARTS <part>...] [FILES <file>...] [SUBMIT_URL <url>] @@ -96,7 +96,7 @@ Submit to CDash Upload API .. versionadded:: 3.2 -:: +.. code-block:: cmake ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>] [SUBMIT_URL <url>] diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 4f9f89198b..cf20ade86e 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -3,7 +3,7 @@ ctest_test Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_test([BUILD <build-dir>] [APPEND] [START <start-number>] @@ -30,7 +30,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. ) .. - _note: If updating the argument list here, please also update the argument + NOTE If updating the argument list here, please also update the argument list documentation for :command:`ctest_memcheck` as well. Run tests in the project build tree and store results in diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst index 63f991b5e0..836cdf1ff9 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -3,7 +3,7 @@ ctest_update Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst index ffddd0a43a..344979a21e 100644 --- a/Help/command/ctest_upload.rst +++ b/Help/command/ctest_upload.rst @@ -3,7 +3,7 @@ ctest_upload Upload files to a dashboard server as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>]) diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 76b060b709..5278e30544 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -73,3 +73,9 @@ project via corresponding options to the :command:`get_property` command. with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one underscore. It is recommended that the property name have a prefix specific to the project. + +See Also +^^^^^^^^ + +* :command:`get_property` +* :command:`set_property` diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index d9103b8906..21b38bade0 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -9,24 +9,13 @@ Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc) Enables support for the named languages in CMake. This is the same as the :command:`project` command but does not create any of the extra -variables that are created by the project command. Example languages -are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, -``HIP``, ``ISPC``, and ``ASM``. +variables that are created by the project command. -.. versionadded:: 3.8 - Added ``CUDA`` support. +.. include:: SUPPORTED_LANGUAGES.txt -.. versionadded:: 3.16 - Added ``OBJC`` and ``OBJCXX`` support. - -.. versionadded:: 3.18 - Added ``ISPC`` support. - -.. versionadded:: 3.21 - Added ``HIP`` support. - -If enabling ``ASM``, enable it last so that CMake can check whether -compilers for other languages like ``C`` work for assembly too. +By default ``C`` and ``CXX`` are enabled if no language options are given. +Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, +to skip enabling any languages. This command must be called in file scope, not in a function call. Furthermore, it must be called in the highest directory common to all diff --git a/Help/command/exec_program.rst b/Help/command/exec_program.rst index bc9b069166..983a6df9e5 100644 --- a/Help/command/exec_program.rst +++ b/Help/command/exec_program.rst @@ -8,7 +8,7 @@ exec_program Run an executable program during the processing of the CMakeList.txt file. -:: +.. code-block:: cmake exec_program(Executable [directory in which to run] [ARGS <arguments to executable>] diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index d4ba4654db..98430c5c42 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -32,6 +32,11 @@ Commands are executed concurrently as a pipeline, with the standard output of each process piped to the standard input of the next. A single standard error pipe is used for all processes. +``execute_process`` runs commands while CMake is configuring the project, +prior to build system generation. Use the :command:`add_custom_target` and +:command:`add_custom_command` commands to create custom commands that run +at build time. + Options: ``COMMAND`` @@ -51,8 +56,8 @@ Options: (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to redirect stdin, stdout, and stderr.) - If a sequential execution of multiple commands is required, use multiple - :command:`execute_process` calls with a single ``COMMAND`` argument. + For **sequential execution** of multiple commands use multiple + ``execute_process`` calls each with a single ``COMMAND`` argument. ``WORKING_DIRECTORY`` The named directory will be set as the current working directory of @@ -76,22 +81,46 @@ Options: given ``COMMAND`` arguments. Each entry will be an integer return code from the corresponding child or a string describing an error condition. +``INPUT_FILE <file>`` + ``<file>`` is attached to the standard input pipe of the *first* ``COMMAND`` + process. + +``OUTPUT_FILE <file>`` + ``<file>`` is attached to the standard output pipe of the *last* ``COMMAND`` + process. + +``ERROR_FILE <file>`` + ``<file>`` is attached to the standard error pipe of *all* ``COMMAND`` + processes. + +.. versionadded:: 3.3 + If the same ``<file>`` is named for both ``OUTPUT_FILE`` and ``ERROR_FILE`` + then it will be used for both standard output and standard error pipes. + +``OUTPUT_QUIET``, ``ERROR_QUIET`` + The standard output on ``OUTPUT_VARIABLE`` or standard error on + ``ERROR_VARIABLE`` are not connected (no variable content). + The ``*_FILE`` and ``ECHO_*_VARIABLE`` options are not affected. + ``OUTPUT_VARIABLE``, ``ERROR_VARIABLE`` The variable named will be set with the contents of the standard output and standard error pipes, respectively. If the same variable is named for both pipes their output will be merged in the order produced. -``INPUT_FILE, OUTPUT_FILE``, ``ERROR_FILE`` - The file named will be attached to the standard input of the first - process, standard output of the last process, or standard error of - all processes, respectively. +``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE`` + .. versionadded:: 3.18 + + The standard output or standard error will not be exclusively redirected to + the specified variables. - .. versionadded:: 3.3 - If the same file is named for both output and error then it will be used - for both. + The output will be duplicated into the specified variables and also onto + standard output or standard error analogous to the ``tee`` Unix command. -``OUTPUT_QUIET``, ``ERROR_QUIET`` - The standard output or standard error results will be quietly ignored. +.. note:: + If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the + same pipe the precedence is *not specified*. + If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will + be shared with the corresponding pipes of the CMake process itself. ``COMMAND_ECHO <where>`` .. versionadded:: 3.15 @@ -126,17 +155,6 @@ Options: Accept ``UTF-8`` spelling for consistency with the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. -``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE`` - .. versionadded:: 3.18 - - The standard output or standard error will not be exclusively redirected to - the configured variables. - - The output will be duplicated, it will be sent into the configured variables - and also on standard output or standard error. - - This is analogous to the ``tee`` Unix command. - ``COMMAND_ERROR_IS_FATAL <ANY|LAST>`` .. versionadded:: 3.19 @@ -151,15 +169,3 @@ Options: If the last command in the list of commands fails, the ``execute_process()`` command halts with an error. Commands earlier in the list will not cause a fatal error. - -If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the -same pipe the precedence is not specified. -If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will -be shared with the corresponding pipes of the CMake process itself. - -The :command:`execute_process` command is a newer more powerful version of -:command:`exec_program`, but the old command has been kept for compatibility. -Both commands run while CMake is processing the project prior to build -system generation. Use :command:`add_custom_target` and -:command:`add_custom_command` to create custom commands that run at -build time. diff --git a/Help/command/export_library_dependencies.rst b/Help/command/export_library_dependencies.rst index 9753abf54d..6cb4643532 100644 --- a/Help/command/export_library_dependencies.rst +++ b/Help/command/export_library_dependencies.rst @@ -15,7 +15,7 @@ The old-style library dependencies file does not take into account per-configuration names of libraries or the :prop_tgt:`LINK_INTERFACE_LIBRARIES` target property. -:: +.. code-block:: cmake export_library_dependencies(<file> [APPEND]) diff --git a/Help/command/file.rst b/Help/command/file.rst index fbe2a81545..df895d080b 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -526,10 +526,10 @@ from the input content to produce the output content. The options are: ``OUTPUT <output-file>`` Specify the output file name to generate. Use generator expressions - such as ``$<CONFIG>`` to specify a configuration-specific output file - name. Multiple configurations may generate the same output file only - if the generated content is identical. Otherwise, the ``<output-file>`` - must evaluate to an unique name for each configuration. + such as :genex:`$<CONFIG>` to specify a configuration-specific + output file name. Multiple configurations may generate the same output + file only if the generated content is identical. Otherwise, the + ``<output-file>`` must evaluate to an unique name for each configuration. .. versionchanged:: 3.10 A relative path (after evaluating generator expressions) is treated @@ -540,8 +540,9 @@ from the input content to produce the output content. The options are: .. versionadded:: 3.19 Specify which target to use when evaluating generator expressions that - require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``, - ``$<TARGET_PROPERTY:prop>``). + require a target for evaluation (e.g. + :genex:`$<COMPILE_FEATURES:...>`, + :genex:`$<TARGET_PROPERTY:prop>`). ``NO_SOURCE_PERMISSIONS`` .. versionadded:: 3.20 @@ -749,7 +750,8 @@ The options are: file(COPY_FILE <oldname> <newname> [RESULT <result>] - [ONLY_IF_DIFFERENT]) + [ONLY_IF_DIFFERENT] + [INPUT_MAY_BE_RECENT]) .. versionadded:: 3.21 @@ -768,6 +770,14 @@ The options are: contents are already the same as ``<oldname>`` (this avoids updating ``<newname>``'s timestamp). +``INPUT_MAY_BE_RECENT`` + .. versionadded:: 3.26 + + Tell CMake that the input file may have been recently created. This is + meaningful only on Windows, where files may be inaccessible for a short + time after they are created. With this option, if permission is denied, + CMake will retry reading the input a few times. + This sub-command has some similarities to :command:`configure_file` with the ``COPYONLY`` option. An important difference is that :command:`configure_file` creates a dependency on the source file, so CMake will be re-run if it changes. @@ -1213,6 +1223,9 @@ directed to do so with the ``COMPRESSION`` option. Valid values for The ``<compression-level>`` should be between 0-9, with the default being 0. The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. +.. versionadded:: 3.26 + The ``<compression-level>`` of the ``Zstd`` algorithm can be set between 0-19. + .. note:: With ``FORMAT`` set to ``raw`` only one file will be compressed with the compression type specified by ``COMPRESSION``. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index c99c73dd35..de4cb88435 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -370,7 +370,8 @@ 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. + 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. diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index ddf8dfa84f..c3fdbf7abd 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -74,8 +74,7 @@ processed: message(STATUS "X=${X}") endforeach() -yields -:: +yields:: -- X=0 -- X=1 @@ -119,8 +118,7 @@ iteration variables as follows: message(STATUS "en=${en}, ba=${ba}") endforeach() -yields -:: +yields:: -- num_0=one, num_1=satu -- num_0=two, num_1=dua diff --git a/Help/command/function.rst b/Help/command/function.rst index fc55c034ff..069f9fa792 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -77,5 +77,6 @@ extra argument. See Also ^^^^^^^^ +* :command:`cmake_parse_arguments` * :command:`endfunction` * :command:`return` diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst index 96764a3b99..b1d18a0d8e 100644 --- a/Help/command/get_cmake_property.rst +++ b/Help/command/get_cmake_property.rst @@ -12,9 +12,12 @@ the ``<property>`` is stored in the variable ``<var>``. If the property is not found, ``<var>`` will be set to ``NOTFOUND``. See the :manual:`cmake-properties(7)` manual for available properties. -See also the :command:`get_property` command ``GLOBAL`` option. - In addition to global properties, this command (for historical reasons) also supports the :prop_dir:`VARIABLES` and :prop_dir:`MACROS` directory properties. It also supports a special ``COMPONENTS`` global property that lists the components given to the :command:`install` command. + +See Also +^^^^^^^^ + +* the :command:`get_property` command ``GLOBAL`` option diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst index 0ccbfb0272..209d2f8bdb 100644 --- a/Help/command/get_directory_property.rst +++ b/Help/command/get_directory_property.rst @@ -33,4 +33,9 @@ the search will chain to a parent scope as described for the Get a variable definition from a directory. This form is useful to get a variable definition from another directory. -See also the more general :command:`get_property` command. + +See Also +^^^^^^^^ + +* :command:`define_property` +* the more general :command:`get_property` command diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 4bfe087735..899ede60d5 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -69,3 +69,8 @@ left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then any command-line arguments present in the ``<FileName>`` string are split from the program name and stored in ``<arg_var>``. This is used to separate a program name from its arguments in a command line string. + +See Also +^^^^^^^^ + +* :command:`cmake_path` diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 46da2853b2..6b9931ef6d 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -99,3 +99,9 @@ documentation is requested for a property that has not been defined The :prop_sf:`GENERATED` source file property may be globally visible. See its documentation for details. + +See Also +^^^^^^^^ + +* :command:`define_property` +* :command:`set_property` diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst index ae41565985..e83e9c27be 100644 --- a/Help/command/get_source_file_property.rst +++ b/Help/command/get_source_file_property.rst @@ -39,9 +39,14 @@ Use :command:`set_source_files_properties` to set property values. Source file properties usually control how the file is built. One property that is always there is :prop_sf:`LOCATION`. -See also the more general :command:`get_property` command. - .. note:: The :prop_sf:`GENERATED` source file property may be globally visible. See its documentation for details. + +See Also +^^^^^^^^ + +* :command:`define_property` +* the more general :command:`get_property` command +* :command:`set_source_files_properties` diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index 985b1ff682..8c6dcb169b 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -22,6 +22,10 @@ query the target instead. This command can get properties for any target so far created. The targets do not need to be in the current ``CMakeLists.txt`` file. -See also the more general :command:`get_property` command. +See Also +^^^^^^^^ -See :ref:`Target Properties` for the list of properties known to CMake. +* :command:`define_property` +* the more general :command:`get_property` command +* :command:`set_target_properties` +* :ref:`Target Properties` for the list of properties known to CMake diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst index 6bcc1ef2ad..2b6f35457a 100644 --- a/Help/command/get_test_property.rst +++ b/Help/command/get_test_property.rst @@ -19,4 +19,8 @@ an empty string. For a list of standard properties you can type :option:`cmake --help-property-list`. -See also the more general :command:`get_property` command. +See Also +^^^^^^^^ + +* :command:`define_property` +* the more general :command:`get_property` command diff --git a/Help/command/if.rst b/Help/command/if.rst index b72769f6d1..684c1135b1 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -165,6 +165,8 @@ File Operations Resolves symbolic links, i.e. if the named file or directory is a symbolic link, returns true if the target of the symbolic link exists. + False if the given path is an empty string. + ``if(file1 IS_NEWER_THAN file2)`` True if ``file1`` is newer than ``file2`` or if one of the two files doesn't exist. Behavior is well-defined only for full paths. If the file @@ -173,10 +175,12 @@ File Operations of a tie. This includes the case of passing the same file name for both file1 and file2. -``if(IS_DIRECTORY path-to-directory)`` - True if the given name is a directory. Behavior is well-defined only +``if(IS_DIRECTORY path)`` + True if ``path`` is a directory. Behavior is well-defined only for full paths. + False if the given path is an empty string. + ``if(IS_SYMLINK file-name)`` True if the given name is a symbolic link. Behavior is well-defined only for full paths. @@ -428,6 +432,6 @@ condition syntax accepts ``<variable|string>``. See also ^^^^^^^^ - * :command:`else` - * :command:`elseif` - * :command:`endif` +* :command:`else` +* :command:`elseif` +* :command:`endif` diff --git a/Help/command/include_directories.rst b/Help/command/include_directories.rst index fe281c3c8f..d2948edcb3 100644 --- a/Help/command/include_directories.rst +++ b/Help/command/include_directories.rst @@ -29,13 +29,16 @@ Signalling this setting might achieve effects such as the compiler skipping warnings, or these fixed-install system files not being considered in dependency calculations - see compiler docs. -Arguments to ``include_directories`` 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. +.. |command_name| replace:: ``include_directories`` +.. include:: GENEX_NOTE.txt .. note:: Prefer the :command:`target_include_directories` command to add include directories to individual targets and optionally propagate/export them to dependents. + +See Also +^^^^^^^^ + +* :command:`target_include_directories` diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst index dca3b6f0e4..e8cafacf0c 100644 --- a/Help/command/include_guard.rst +++ b/Help/command/include_guard.rst @@ -13,7 +13,7 @@ Sets up an include guard for the current CMake file (see the :variable:`CMAKE_CURRENT_LIST_FILE` variable documentation). CMake will end its processing of the current file at the location of the -:command:`include_guard` command if the current file has already been +``include_guard`` command if the current file has already been processed for the applicable scope (see below). This provides functionality similar to the include guards commonly used in source headers or to the ``#pragma once`` directive. If the current file has been processed previously diff --git a/Help/command/install.rst b/Help/command/install.rst index feff4360c4..126888aa7a 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -32,7 +32,7 @@ are executed in order during installation. .. versionchanged:: 3.22 The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the - default copying behavior of :command:`install()`. + default copying behavior of ``install()``. There are multiple signatures for this command. Some of them define installation options for files and targets. Options common to @@ -379,7 +379,7 @@ top level: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the ``<targets>`` when exported by the `install(EXPORT)`_ command. If a relative path is specified, it is treated as relative to the - ``$<INSTALL_PREFIX>``. + :genex:`$<INSTALL_PREFIX>`. ``RUNTIME_DEPENDENCY_SET`` .. versionadded:: 3.21 diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst index 494f3d0ee5..9b191248b1 100644 --- a/Help/command/install_files.rst +++ b/Help/command/install_files.rst @@ -11,7 +11,7 @@ directly replaced by the ``FILES`` form of the :command:`install` command. The regexp form can be expressed more clearly using the ``GLOB`` form of the :command:`file` command. -:: +.. code-block:: cmake install_files(<dir> extension file file ...) @@ -23,14 +23,14 @@ removed first. This is useful for providing lists of source files such as foo.cxx when you want the corresponding foo.h to be installed. A typical extension is ``.h``. -:: +.. code-block:: cmake install_files(<dir> regexp) Any files in the current source directory that match the regular expression will be installed. -:: +.. code-block:: cmake install_files(<dir> FILES file file ...) diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst index eafae89966..5b42904150 100644 --- a/Help/command/install_programs.rst +++ b/Help/command/install_programs.rst @@ -11,7 +11,7 @@ directly replaced by the ``PROGRAMS`` form of the :command:`install` command. The regexp form can be expressed more clearly using the ``GLOB`` form of the :command:`file` command. -:: +.. code-block:: cmake install_programs(<dir> file1 file2 [file3 ...]) install_programs(<dir> FILES file1 [file2 ...]) @@ -20,7 +20,7 @@ Create rules to install the listed programs into the given directory. Use the ``FILES`` argument to guarantee that the file list version of the command will be used even when there is only one argument. -:: +.. code-block:: cmake install_programs(<dir> regexp) diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst index 9355f8d532..7653776646 100644 --- a/Help/command/install_targets.rst +++ b/Help/command/install_targets.rst @@ -8,7 +8,7 @@ install_targets This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. -:: +.. code-block:: cmake install_targets(<dir> [RUNTIME_DIRECTORY dir] target target) diff --git a/Help/command/link_directories.rst b/Help/command/link_directories.rst index 6732402347..5e7fc3992f 100644 --- a/Help/command/link_directories.rst +++ b/Help/command/link_directories.rst @@ -53,3 +53,9 @@ The command will apply only to targets created after it is called. where possible by using the :command:`target_link_directories` command rather than ``link_directories()``. The target-specific command can also control how the search directories propagate to other dependent targets. + +See Also +^^^^^^^^ + +* :command:`target_link_directories` +* :command:`target_link_libraries` diff --git a/Help/command/load_command.rst b/Help/command/load_command.rst index dc235994c8..4b3888ffcd 100644 --- a/Help/command/load_command.rst +++ b/Help/command/load_command.rst @@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0031`. Load a command into a running CMake. -:: +.. code-block:: cmake load_command(COMMAND_NAME <loc1> [loc2 ...]) @@ -15,7 +15,7 @@ added to the set of available CMake commands. Usually, :command:`try_compile` is used before this command to compile the module. If the command is successfully loaded a variable named -:: +.. code-block:: cmake CMAKE_LOADED_COMMAND_<COMMAND_NAME> diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 5fe4c00efa..2858622850 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -149,3 +149,9 @@ existing variable instead of the arguments. For example: Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected. If you want true CMake variables and/or better CMake scope control you should look at the function command. + +See Also +^^^^^^^^ + +* :command:`cmake_parse_arguments` +* :command:`endmacro` diff --git a/Help/command/make_directory.rst b/Help/command/make_directory.rst index 8469b0a96b..959749d6c1 100644 --- a/Help/command/make_directory.rst +++ b/Help/command/make_directory.rst @@ -5,7 +5,7 @@ make_directory Use the :command:`file(MAKE_DIRECTORY)` command instead. -:: +.. code-block:: cmake make_directory(directory) diff --git a/Help/command/message.rst b/Help/command/message.rst index 77d21c83c5..e8a4ea000c 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -14,6 +14,8 @@ Synopsis `Reporting checks`_ message(<checkState> "message text" ...) + `Configure Log`_ + message(CONFIGURE_LOG <text>...) General messages ^^^^^^^^^^^^^^^^ @@ -193,3 +195,56 @@ Output from the above would appear something like the following:: -- Finding partB -- Finding partB - not found -- Finding my things - missing components: B + +Configure Log +^^^^^^^^^^^^^ + +.. versionadded:: 3.26 + +.. code-block:: cmake + + message(CONFIGURE_LOG <text>...) + +Record a :ref:`configure-log message event <message configure-log event>` +with the specified ``<text>``. By convention, if the text contains more +than one line, the first line should be a summary of the event. + +This mode is intended to record the details of a system inspection check +or other one-time operation guarded by a cache entry, but that is not +performed using :command:`try_compile` or :command:`try_run`, which +automatically log their details. Projects should avoid calling it every +time CMake runs. For example: + +.. code-block:: cmake + + if (NOT DEFINED MY_CHECK_RESULT) + # Print check summary in configure output. + message(CHECK_START "My Check") + + # ... perform system inspection, e.g., with execute_process ... + + # Cache the result so we do not run the check again. + set(MY_CHECK_RESULT "${MY_CHECK_RESULT}" CACHE INTERNAL "My Check") + + # Record the check details in the cmake-configure-log. + message(CONFIGURE_LOG + "My Check Result: ${MY_CHECK_RESULT}\n" + "${details}" + ) + + # Print check result in configure output. + if(MY_CHECK_RESULT) + message(CHECK_PASS "passed") + else() + message(CHECK_FAIL "failed") + endif() + endif() + +If no project is currently being configured, such as in +:ref:`cmake -P <Script Processing Mode>` script mode, +this command does nothing. + +See Also +^^^^^^^^ + +* :command:`cmake_language(GET_MESSAGE_LOG_LEVEL)` diff --git a/Help/command/output_required_files.rst b/Help/command/output_required_files.rst index b3a6e8653b..fbe5dbd939 100644 --- a/Help/command/output_required_files.rst +++ b/Help/command/output_required_files.rst @@ -9,7 +9,7 @@ This command exists only because ancient CMake versions provided it. CMake handles preprocessor dependency scanning automatically using a more advanced scanner. -:: +.. code-block:: cmake output_required_files(srcfile outputfile) diff --git a/Help/command/project.rst b/Help/command/project.rst index 8f32fa3943..ab93f3d556 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -102,23 +102,9 @@ The options are: Can also be specified without ``LANGUAGES`` keyword per the first, short signature. Selects which programming languages are needed to build the project. - Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, - ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. - By default ``C`` and ``CXX`` are enabled if no language options are given. - Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, - to skip enabling any languages. - .. versionadded:: 3.8 - Added ``CUDA`` support. +.. include:: SUPPORTED_LANGUAGES.txt - .. versionadded:: 3.16 - Added ``OBJC`` and ``OBJCXX`` support. - - .. versionadded:: 3.18 - Added ``ISPC`` support. - - If enabling ``ASM``, list it last so that CMake can check whether - compilers for other languages like ``C`` work for assembly too. The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` options are intended for use as default values in package metadata and documentation. @@ -188,5 +174,6 @@ call exists, CMake will issue a warning and pretend there is a Call the ``project()`` command near the top of the top-level ``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`. It is important to establish version and policy settings before invoking - other commands whose behavior they may affect. + other commands whose behavior they may affect and for this reason the + ``project()`` command will issue a warning if this order is not kept. See also policy :policy:`CMP0000`. diff --git a/Help/command/remove.rst b/Help/command/remove.rst index 543d01671d..e12a9371b7 100644 --- a/Help/command/remove.rst +++ b/Help/command/remove.rst @@ -5,7 +5,7 @@ remove Use the :command:`list(REMOVE_ITEM)` command instead. -:: +.. code-block:: cmake remove(VAR VALUE VALUE ...) diff --git a/Help/command/return.rst b/Help/command/return.rst index 3013b52851..bb6d87d8f7 100644 --- a/Help/command/return.rst +++ b/Help/command/return.rst @@ -30,7 +30,7 @@ command. All arguments are ignored unless that policy is set to ``NEW``. with the :command:`block` command, as described below. The ``PROPAGATE`` option can be very useful in conjunction with the - :command:`block` command. A :command:`return` will propagate the + :command:`block` command. A ``return`` will propagate the specified variables through any enclosing block scopes created by the :command:`block` commands. Inside a function, this ensures the variables are propagated to the function's caller, regardless of any blocks within @@ -88,4 +88,5 @@ command. All arguments are ignored unless that policy is set to ``NEW``. See Also ^^^^^^^^ - * :command:`block` +* :command:`block` +* :command:`function` diff --git a/Help/command/set.rst b/Help/command/set.rst index 90b57d23f0..c724844813 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -111,3 +111,8 @@ environment variable. Arguments after ``<value>`` are ignored. If extra arguments are found, then an author warning is issued. + +See Also +^^^^^^^^ + +* :command:`unset` diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst index f02a8e6c7e..93ad39b3b4 100644 --- a/Help/command/set_directory_properties.rst +++ b/Help/command/set_directory_properties.rst @@ -13,3 +13,10 @@ See also the :command:`set_property(DIRECTORY)` command. See :ref:`Directory Properties` for the list of properties known to CMake and their individual documentation for the behavior of each property. + +See Also +^^^^^^^^ + +* :command:`define_property` +* :command:`get_directory_property` +* the more general :command:`set_property` command diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index b9b12c480b..d446a2d6fe 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -107,10 +107,15 @@ finding the initial value to append to. If the property is not already directly set in the nominated scope, the command will behave as though ``APPEND`` or ``APPEND_STRING`` had not been given. -See the :manual:`cmake-properties(7)` manual for a list of properties -in each scope. - .. note:: The :prop_sf:`GENERATED` source file property may be globally visible. See its documentation for details. + +See Also +^^^^^^^^ + +* :command:`define_property` +* :command:`get_property` +* The :manual:`cmake-properties(7)` manual for a list of properties + in each scope. diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index 61c69a2e9a..d937b33e9b 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -34,10 +34,15 @@ list. Use :command:`get_source_file_property` to get property values. See also the :command:`set_property(SOURCE)` command. -See :ref:`Source File Properties` for the list of properties known -to CMake. - .. note:: The :prop_sf:`GENERATED` source file property may be globally visible. See its documentation for details. + +See Also +^^^^^^^^ + +* :command:`define_property` +* :command:`get_source_file_property` +* :ref:`Source File Properties` for the list of properties known + to CMake diff --git a/Help/command/set_target_properties.rst b/Help/command/set_target_properties.rst index 597be231a7..856b92c654 100644 --- a/Help/command/set_target_properties.rst +++ b/Help/command/set_target_properties.rst @@ -15,6 +15,10 @@ set next. You can use any prop value pair you want and extract it later with the :command:`get_property` or :command:`get_target_property` command. -See also the :command:`set_property(TARGET)` command. +See Also +^^^^^^^^ -See :ref:`Target Properties` for the list of properties known to CMake. +* :command:`define_property` +* :command:`get_target_property` +* the more general :command:`set_property` command +* :ref:`Target Properties` for the list of properties known to CMake diff --git a/Help/command/set_tests_properties.rst b/Help/command/set_tests_properties.rst index eadde331c4..125e4607e4 100644 --- a/Help/command/set_tests_properties.rst +++ b/Help/command/set_tests_properties.rst @@ -14,6 +14,10 @@ Test property values may be specified using :manual:`generator expressions <cmake-generator-expressions(7)>` for tests created by the :command:`add_test(NAME)` signature. -See also the :command:`set_property(TEST)` command. +See Also +^^^^^^^^ -See :ref:`Test Properties` for the list of properties known to CMake. +* :command:`add_test` +* :command:`define_property` +* the more general :command:`set_property` command +* :ref:`Target Properties` for the list of properties known to CMake diff --git a/Help/command/string.rst b/Help/command/string.rst index 86136a6edd..c24b9bc16a 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -522,6 +522,17 @@ specifiers: ``%Y`` The current year. +``%z`` + .. versionadded:: 3.26 + + The offset of the time zone from UTC, in hours and minutes, + with format ``+hhmm`` or ``-hhmm``. + +``%Z`` + .. versionadded:: 3.26 + + The time zone name. + Unknown format specifiers will be ignored and copied to the output as-is. diff --git a/Help/command/subdir_depends.rst b/Help/command/subdir_depends.rst index 0c1b3c1ce9..2115b331c2 100644 --- a/Help/command/subdir_depends.rst +++ b/Help/command/subdir_depends.rst @@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0029`. Does nothing. -:: +.. code-block:: cmake subdir_depends(subdir dep1 dep2 ...) diff --git a/Help/command/subdirs.rst b/Help/command/subdirs.rst index 530951bd1a..ecc6d1fd68 100644 --- a/Help/command/subdirs.rst +++ b/Help/command/subdirs.rst @@ -7,7 +7,7 @@ subdirs Add a list of subdirectories to the build. -:: +.. code-block:: cmake subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...] [PREORDER] ) diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 2d292afdd9..2290efbc16 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -25,10 +25,8 @@ same ``<target>`` append items in the order called. .. versionadded:: 3.11 Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. -Arguments to ``target_compile_definitions`` 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. +.. |command_name| replace:: ``target_compile_definitions`` +.. include:: GENEX_NOTE.txt Any leading ``-D`` on an item will be removed. Empty items are ignored. For example, the following are all equivalent: @@ -48,3 +46,16 @@ Definitions may optionally have values: Note that many compilers treat ``-DFOO`` as equivalent to ``-DFOO=1``, but other tools may not recognize this in all circumstances (e.g. IntelliSense). + +See Also +^^^^^^^^ + +* :command:`add_compile_definitions` +* :command:`target_compile_features` +* :command:`target_compile_options` +* :command:`target_include_directories` +* :command:`target_link_libraries` +* :command:`target_link_directories` +* :command:`target_link_options` +* :command:`target_precompile_headers` +* :command:`target_sources` diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index 58502bfc2d..531af8159c 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -30,8 +30,20 @@ The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. -Arguments to ``target_compile_features`` may use "generator expressions" -with the syntax ``$<...>``. -See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. See the :manual:`cmake-compile-features(7)` manual for -information on compile features and a list of supported compilers. +.. |command_name| replace:: ``target_compile_features`` +.. |more_see_also| replace:: See the :manual:`cmake-compile-features(7)` + manual for information on compile features and a list of supported compilers. +.. include:: GENEX_NOTE.txt + :start-line: 1 + +See Also +^^^^^^^^ + +* :command:`target_compile_definitions` +* :command:`target_compile_options` +* :command:`target_include_directories` +* :command:`target_link_libraries` +* :command:`target_link_directories` +* :command:`target_link_options` +* :command:`target_precompile_headers` +* :command:`target_sources` diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 0d86c91e6b..698f62d60a 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -19,7 +19,8 @@ Arguments ^^^^^^^^^ If ``BEFORE`` is specified, the content will be prepended to the property -instead of being appended. +instead of being appended. See policy :policy:`CMP0101` which affects +whether ``BEFORE`` will be ignored in certain cases. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the :ref:`scope <Target Usage Requirements>` of the following arguments. @@ -32,21 +33,26 @@ The following arguments specify compile options. Repeated calls for the same .. versionadded:: 3.11 Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. -Arguments to ``target_compile_options`` 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. +.. |command_name| replace:: ``target_compile_options`` +.. include:: GENEX_NOTE.txt .. include:: OPTIONS_SHELL.txt See Also ^^^^^^^^ -This command can be used to add any options. However, for adding -preprocessor definitions and include directories it is recommended -to use the more specific commands :command:`target_compile_definitions` -and :command:`target_include_directories`. +* This command can be used to add any options. However, for adding + preprocessor definitions and include directories it is recommended + to use the more specific commands :command:`target_compile_definitions` + and :command:`target_include_directories`. -For directory-wide settings, there is the command :command:`add_compile_options`. +* For directory-wide settings, there is the command :command:`add_compile_options`. -For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`. +* For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`. + +* :command:`target_compile_features` +* :command:`target_link_libraries` +* :command:`target_link_directories` +* :command:`target_link_options` +* :command:`target_precompile_headers` +* :command:`target_sources` diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index f13ff290a5..2a410ec20c 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -40,10 +40,8 @@ If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be populated with the specified directories. -Arguments to ``target_include_directories`` 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. +.. |command_name| replace:: ``target_include_directories`` +.. include:: GENEX_NOTE.txt Specified include directories may be absolute paths or relative paths. A relative path will be interpreted as relative to the current source @@ -74,3 +72,16 @@ Creating Relocatable Packages .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt + +See Also +^^^^^^^^ + +* :command:`include_directories` +* :command:`target_compile_definitions` +* :command:`target_compile_features` +* :command:`target_compile_options` +* :command:`target_link_libraries` +* :command:`target_link_directories` +* :command:`target_link_options` +* :command:`target_precompile_headers` +* :command:`target_sources` diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst index b72f74606a..2854c96a6c 100644 --- a/Help/command/target_link_directories.rst +++ b/Help/command/target_link_directories.rst @@ -34,10 +34,8 @@ calls for the same ``<target>`` append items in the order called. If ``BEFORE`` is specified, the content will be prepended to the relevant property instead of being appended. -Arguments to ``target_link_directories`` 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. +.. |command_name| replace:: ``target_link_directories`` +.. include:: GENEX_NOTE.txt .. note:: @@ -56,3 +54,16 @@ manual for more on defining buildsystem properties. that expect to be found via ``RPATH`` mechanisms, but some linkers are not able to fully decode those paths (e.g. due to the presence of things like ``$ORIGIN``). + +See Also +^^^^^^^^ + +* :command:`link_directories` +* :command:`target_compile_definitions` +* :command:`target_compile_features` +* :command:`target_compile_options` +* :command:`target_include_directories` +* :command:`target_link_libraries` +* :command:`target_link_options` +* :command:`target_precompile_headers` +* :command:`target_sources` diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index bb7b5cc107..1d276606f9 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -293,8 +293,8 @@ will be included in the link too. .. _`Linking Object Libraries via $<TARGET_OBJECTS>`: -Linking Object Libraries via $<TARGET_OBJECTS> -"""""""""""""""""""""""""""""""""""""""""""""" +Linking Object Libraries via ``$<TARGET_OBJECTS>`` +"""""""""""""""""""""""""""""""""""""""""""""""""" .. versionadded:: 3.21 @@ -407,3 +407,15 @@ Creating Relocatable Packages .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt + +See Also +^^^^^^^^ + +* :command:`target_compile_definitions` +* :command:`target_compile_features` +* :command:`target_compile_options` +* :command:`target_include_directories` +* :command:`target_link_directories` +* :command:`target_link_options` +* :command:`target_precompile_headers` +* :command:`target_sources` diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index 3cd0e64e39..0d026f2456 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst @@ -42,13 +42,23 @@ The following arguments specify link options. Repeated calls for the same .. note:: :ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items. -Arguments to ``target_link_options`` 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. +.. |command_name| replace:: ``target_link_options`` +.. include:: GENEX_NOTE.txt .. include:: DEVICE_LINK_OPTIONS.txt .. include:: OPTIONS_SHELL.txt .. include:: LINK_OPTIONS_LINKER.txt + +See Also +^^^^^^^^ + +* :command:`target_compile_definitions` +* :command:`target_compile_features` +* :command:`target_compile_options` +* :command:`target_include_directories` +* :command:`target_link_libraries` +* :command:`target_link_directories` +* :command:`target_precompile_headers` +* :command:`target_sources` diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index 84f5d1225f..8e5c0e9c3a 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -70,17 +70,16 @@ included by absolute path. For example: <unordered_map> ) -Arguments to ``target_precompile_headers()`` may use "generator expressions" -with the syntax ``$<...>``. -See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. -The :genex:`$<COMPILE_LANGUAGE:...>` generator expression is particularly -useful for specifying a language-specific header to precompile for -only one language (e.g. ``CXX`` and not ``C``). In this case, header -file names that are not explicitly in double quotes or angle brackets -must be specified by absolute path. Also, when specifying angle brackets -inside a generator expression, be sure to encode the closing ``>`` as -``$<ANGLE-R>``. For example: +.. |command_name| replace:: ``target_compile_features`` +.. |more_see_also| replace:: The :genex:`$<COMPILE_LANGUAGE:...>` generator + expression is particularly useful for specifying a language-specific header + to precompile for only one language (e.g. ``CXX`` and not ``C``). In this + case, header file names that are not explicitly in double quotes or angle + brackets must be specified by absolute path. Also, when specifying angle + brackets inside a generator expression, be sure to encode the closing + ``>`` as :genex:`$<ANGLE-R>`. For example: +.. include:: GENEX_NOTE.txt + :start-line: 1 .. code-block:: cmake @@ -118,8 +117,17 @@ the ``REUSE_FROM`` form is used. See Also ^^^^^^^^ -To disable precompile headers for specific targets, see the -:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property. +* To disable precompile headers for specific targets, see the + :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property. -To prevent precompile headers from being used when compiling a specific -source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property. +* To prevent precompile headers from being used when compiling a specific + source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property. + +* :command:`target_compile_definitions` +* :command:`target_compile_features` +* :command:`target_compile_options` +* :command:`target_include_directories` +* :command:`target_link_libraries` +* :command:`target_link_directories` +* :command:`target_link_options` +* :command:`target_sources` diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 461175a16c..5d07f54c4c 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -202,3 +202,17 @@ Target properties related to include directories are also modified by of the file set is ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property. + +See Also +^^^^^^^^ + +* :command:`add_executable` +* :command:`add_library` +* :command:`target_compile_definitions` +* :command:`target_compile_features` +* :command:`target_compile_options` +* :command:`target_include_directories` +* :command:`target_link_libraries` +* :command:`target_link_directories` +* :command:`target_link_options` +* :command:`target_precompile_headers` diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 9e9f39fb4c..8abb6e06d3 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -14,18 +14,20 @@ Try Compiling Whole Projects .. code-block:: cmake - try_compile(<resultVar> PROJECT <projectName> + try_compile(<compileResultVar> PROJECT <projectName> SOURCE_DIR <srcdir> [BINARY_DIR <bindir>] [TARGET <targetName>] + [LOG_DESCRIPTION <text>] [NO_CACHE] + [NO_LOG] [CMAKE_FLAGS <flags>...] [OUTPUT_VARIABLE <var>]) .. versionadded:: 3.25 -Try building a project. The success or failure of the ``try_compile``, -i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. +Try building a project. Build success returns ``TRUE`` and build failure +returns ``FALSE`` in ``<compileResultVar>``. In this form, ``<srcdir>`` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>`` @@ -40,14 +42,18 @@ below for the meaning of other options. Previously this was only done by the :ref:`source file <Try Compiling Source Files>` signature. -This command also supports an alternate signature -which was present in older versions of CMake: +.. versionadded:: 3.26 + This command records a + :ref:`configure-log try_compile event <try_compile configure-log event>` + if the ``NO_LOG`` option is not specified. + +This command supports an alternate signature for CMake older than 3.25. +The signature above is recommended for clarity. .. code-block:: cmake - try_compile(<resultVar> <bindir> <srcdir> + try_compile(<compileResultVar> <bindir> <srcdir> <projectName> [<targetName>] - [NO_CACHE] [CMAKE_FLAGS <flags>...] [OUTPUT_VARIABLE <var>]) @@ -58,12 +64,14 @@ Try Compiling Source Files .. code-block:: cmake - try_compile(<resultVar> + try_compile(<compileResultVar> <SOURCES <srcfile...> | SOURCE_FROM_CONTENT <name> <content> | SOURCE_FROM_VAR <name> <var> | SOURCE_FROM_FILE <name> <path> >... + [LOG_DESCRIPTION <text>] [NO_CACHE] + [NO_LOG] [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -79,8 +87,8 @@ Try Compiling Source Files Try building an executable or static library from one or more source files (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` -variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or -``FALSE`` respectively, is returned in ``<resultVar>``. +variable). Build success returns ``TRUE`` and build failure returns ``FALSE`` +in ``<compileResultVar>``. In this form, one or more source files must be provided. Additionally, one of ``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords. @@ -105,17 +113,16 @@ contain something like the following: CMake automatically generates, for each ``try_compile`` operation, a unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch`` with an unspecified name. These directories are cleaned automatically unless -:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``. +:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to :program:`cmake`. Such directories from previous runs are also unconditionally cleaned at the -beginning of any ``cmake`` execution. +beginning of any :program:`cmake` execution. -This command also supports an alternate signature -which was present in older versions of CMake: +This command supports an alternate signature for CMake older than 3.25. +The signature above is recommended for clarity. .. code-block:: cmake - try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...> - [NO_CACHE] + try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -130,7 +137,7 @@ which was present in older versions of CMake: In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for its operation, and all such files will be cleaned automatically. For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be -passed to ``cmake`` to avoid this clean. However, multiple sequential +passed to :program:`cmake` to avoid this clean. However, multiple sequential ``try_compile`` operations, if given the same ``<bindir>``, will reuse this single output directory, such that you can only debug one such ``try_compile`` call at a time. Use of the newer signature is recommended to simplify @@ -171,6 +178,12 @@ The options are: set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. +``LOG_DESCRIPTION <text>`` + .. versionadded:: 3.26 + + Specify a non-empty text description of the purpose of the check. + This is recorded in the :manual:`cmake-configure-log(7)` entry. + ``NO_CACHE`` .. versionadded:: 3.25 @@ -191,6 +204,11 @@ The options are: the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid leaking the intermediate result variable into the cache. +``NO_LOG`` + .. versionadded:: 3.26 + + Do not record a :manual:`cmake-configure-log(7)` entry for this call. + ``OUTPUT_VARIABLE <var>`` Store the output from the build process in the given variable. @@ -271,13 +289,18 @@ Other Behavior Settings If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct behavior at link time, the ``check_pie_supported()`` command from the :module:`CheckPIESupported` module must be called before using the - :command:`try_compile` command. + ``try_compile`` command. The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated through to the generated test project. -Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose -a build configuration. +Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build +configuration: + +* For multi-config generators, this selects which configuration to build. + +* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in + the test project. .. versionadded:: 3.6 Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify @@ -327,3 +350,8 @@ a build configuration. If :policy:`CMP0141` is set to ``NEW``, one can use :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug information format. + +See Also +^^^^^^^^ + +* :command:`try_run` diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index cd41a4ba2f..3a4e203889 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -17,7 +17,9 @@ Try Compiling and Running Source Files SOURCE_FROM_CONTENT <name> <content> | SOURCE_FROM_VAR <name> <var> | SOURCE_FROM_FILE <name> <path> >... + [LOG_DESCRIPTION <text>] [NO_CACHE] + [NO_LOG] [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -30,32 +32,36 @@ Try Compiling and Running Source Files [RUN_OUTPUT_VARIABLE <var>] [RUN_OUTPUT_STDOUT_VARIABLE <var>] [RUN_OUTPUT_STDERR_VARIABLE <var>] - [OUTPUT_VARIABLE <var>] [WORKING_DIRECTORY <var>] [ARGS <args>...] ) .. versionadded:: 3.25 -Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success -or failure in ``<compileResultVar>``. If the compile succeeded, runs the -executable and returns its exit code in ``<runResultVar>``. If the -executable was built, but failed to run, then ``<runResultVar>`` will be -set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for -documentation of options common to both commands, and for information on how -the test project is constructed to build the source file. +Try building an executable from one or more source files. Build success +returns ``TRUE`` and build failure returns ``FALSE`` in ``<compileResultVar>``. +If the build succeeds, this runs the executable and stores the exit code in +``<runResultVar>``. If the executable was built, but failed to run, then +``<runResultVar>`` will be set to ``FAILED_TO_RUN``. See command +:command:`try_compile` for documentation of options common to both commands, +and for information on how the test project is constructed to build the source +file. One or more source files must be provided. Additionally, one of ``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords. -This command also supports an alternate signature -which was present in older versions of CMake: +.. versionadded:: 3.26 + This command records a + :ref:`configure-log try_run event <try_run configure-log event>` + if the ``NO_LOG`` option is not specified. + +This command supports an alternate signature for CMake older than 3.25. +The signature above is recommended for clarity. .. code-block:: cmake try_run(<runResultVar> <compileResultVar> <bindir> <srcfile|SOURCES srcfile...> - [NO_CACHE] [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -66,8 +72,6 @@ which was present in older versions of CMake: [<LANG>_STANDARD_REQUIRED <bool>] [<LANG>_EXTENSIONS <bool>] [RUN_OUTPUT_VARIABLE <var>] - [RUN_OUTPUT_STDOUT_VARIABLE <var>] - [RUN_OUTPUT_STDERR_VARIABLE <var>] [OUTPUT_VARIABLE <var>] [WORKING_DIRECTORY <var>] [ARGS <args>...] @@ -110,15 +114,19 @@ The options specific to ``try_run`` are: Other Behavior Settings ^^^^^^^^^^^^^^^^^^^^^^^ -Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose -a build configuration. +Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build +configuration: + +* For multi-config generators, this selects which configuration to build. + +* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in + the test project. Behavior when Cross Compiling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.3 - Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled - binaries. + Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled binaries. When cross compiling, the executable compiled in the first step usually cannot be run on the build host. The ``try_run`` command checks diff --git a/Help/command/unset.rst b/Help/command/unset.rst index 75210521ec..1cd1398ac7 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst @@ -39,3 +39,8 @@ Subsequent calls of ``$ENV{<variable>}`` will return the empty string. This command affects only the current CMake process, not the process from which CMake was called, nor the system environment at large, nor the environment of subsequent build or test processes. + +See Also +^^^^^^^^ + +* :command:`set` diff --git a/Help/command/use_mangled_mesa.rst b/Help/command/use_mangled_mesa.rst index 5b0e2ee069..bc84bb3d8e 100644 --- a/Help/command/use_mangled_mesa.rst +++ b/Help/command/use_mangled_mesa.rst @@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0030`. Copy mesa headers for use in combination with system GL. -:: +.. code-block:: cmake use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY) diff --git a/Help/command/utility_source.rst b/Help/command/utility_source.rst index 94d6a4e648..3c2bf39f22 100644 --- a/Help/command/utility_source.rst +++ b/Help/command/utility_source.rst @@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0034`. Specify the source tree of a third-party utility. -:: +.. code-block:: cmake utility_source(cache_entry executable_name path_to_source [file1 file2 ...]) diff --git a/Help/command/variable_requires.rst b/Help/command/variable_requires.rst index 322b154598..1dbb02d8a5 100644 --- a/Help/command/variable_requires.rst +++ b/Help/command/variable_requires.rst @@ -7,7 +7,7 @@ Use the :command:`if` command instead. Assert satisfaction of an option's required variables. -:: +.. code-block:: cmake variable_requires(TEST_VARIABLE RESULT_VARIABLE REQUIRED_VARIABLE1 diff --git a/Help/command/while.rst b/Help/command/while.rst index 0bafae5ada..cb0fa2d3d1 100644 --- a/Help/command/while.rst +++ b/Help/command/while.rst @@ -27,7 +27,7 @@ If used, it must be a verbatim repeat of the argument of the opening See Also ^^^^^^^^ - * :command:`break` - * :command:`continue` - * :command:`foreach` - * :command:`endwhile` +* :command:`break` +* :command:`continue` +* :command:`foreach` +* :command:`endwhile` diff --git a/Help/command/write_file.rst b/Help/command/write_file.rst index 4d476bd5a2..4d0bc63cb5 100644 --- a/Help/command/write_file.rst +++ b/Help/command/write_file.rst @@ -5,7 +5,7 @@ write_file Use the :command:`file(WRITE)` command instead. -:: +.. code-block:: cmake write_file(filename "message to write"... [APPEND]) diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index 9df3cc45e5..7f7921d97c 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -4,19 +4,19 @@ CPack Archive Generator CPack generator for packaging files into an archive, which can have any of the following formats: - - 7Z - 7zip - (.7z) - - TBZ2 (.tar.bz2) - - TGZ (.tar.gz) - - TXZ (.tar.xz) - - TZ (.tar.Z) - - TZST (.tar.zst) - - ZIP (.zip) + - 7Z - 7zip - (``.7z``) + - TBZ2 (``.tar.bz2``) + - TGZ (``.tar.gz``) + - TXZ (``.tar.xz``) + - TZ (``.tar.Z``) + - TZST (``.tar.zst``) + - ZIP (``.zip``) .. versionadded:: 3.1 - ``7Z`` and ``TXZ`` formats support. + 7Z and TXZ formats support. .. versionadded:: 3.16 - ``TZST`` format support. + TZST format support. When this generator is called from ``CPackSourceConfig.cmake`` (or through the ``package_source`` target), then the generated archive will contain all @@ -47,27 +47,34 @@ Variables specific to CPack Archive generator .. variable:: CPACK_ARCHIVE_FILE_NAME CPACK_ARCHIVE_<component>_FILE_NAME - Package file name without extension. The extension is determined from the - archive format (see list above) and automatically appended to the file name. - Note that ``<component>`` is all uppercase in the variable name. + Package file name without extension. - The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces - replaced by '-'. + :Default: The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces + replaced by '-'. + + The extension is determined from the archive format (see list above) and + automatically appended to the file name. Note that ``<component>`` is all + uppercase in the variable name. .. versionadded:: 3.9 - Per-component ``CPACK_ARCHIVE_<component>_FILE_NAME`` variables. + Per-component :variable:`!CPACK_ARCHIVE_<component>_FILE_NAME` variables. .. variable:: CPACK_ARCHIVE_FILE_EXTENSION .. versionadded:: 3.25 - Package file extension. Default values are given in the list above. + Package file extension. + + :Default: Default values are given in the list above. .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL - Enable component packaging. If enabled (ON), then the archive generator - creates multiple packages. The default is OFF, which means that a single - package containing files of all components is generated. + Enable component packaging. + + :Default: ``OFF`` + + If enabled (``ON``) multiple packages are generated. By default a single package + containing files of all components is generated. Variables used by CPack Archive generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -75,15 +82,18 @@ Variables used by CPack Archive generator These variables are used by the Archive generator, but are also available to CPack generators which are essentially archives at their core. These include: - - :cpack_gen:`CPack Cygwin Generator` - - :cpack_gen:`CPack FreeBSD Generator` +- :cpack_gen:`CPack Cygwin Generator` +- :cpack_gen:`CPack FreeBSD Generator` .. variable:: CPACK_ARCHIVE_THREADS + The number of threads to use when performing the compression. + .. versionadded:: 3.18 - The number of threads to use when performing the compression. If set to - ``0``, the number of available cores on the machine will be used instead. + :Default: ``1`` + + If set to ``0``, the number of available cores on the machine will be used instead. The default is ``1`` which limits compression to a single thread. Note that not all compression modes support threading in all environments. Currently, only the XZ compression may support it. diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index 1514dbc69e..705ec9ce50 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst @@ -8,16 +8,16 @@ Variables specific to CPack Debian (DEB) generator The CPack DEB generator may be used to create DEB package using :module:`CPack`. The CPack DEB generator is a :module:`CPack` generator thus it uses the -``CPACK_XXX`` variables used by :module:`CPack`. +:variable:`!CPACK_XXX` variables used by :module:`CPack`. The CPack DEB generator should work on any Linux host but it will produce better deb package when Debian specific tools ``dpkg-xxx`` are usable on the build system. The CPack DEB generator has specific features which are controlled by the -specifics ``CPACK_DEBIAN_XXX`` variables. +specifics :variable:`!CPACK_DEBIAN_XXX` variables. -``CPACK_DEBIAN_<COMPONENT>_XXXX`` variables may be used in order to have +:variable:`!CPACK_DEBIAN_<COMPONENT>_XXXX` variables may be used in order to have **component** specific values. Note however that ``<COMPONENT>`` refers to the **grouping name** written in upper case. It may be either a component name or a component GROUP name. @@ -34,10 +34,10 @@ List of CPack DEB generator specific variables: Enable component packaging for CPackDEB - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` - If enabled (ON) multiple packages are generated. By default a single package + If enabled (``ON``) multiple packages are generated. By default a single package containing files of all components is generated. .. variable:: CPACK_DEBIAN_PACKAGE_NAME @@ -46,16 +46,16 @@ List of CPack DEB generator specific variables: Set Package control field (variable is automatically transformed to lower case). - * Mandatory : YES - * Default : + :Mandatory: Yes + :Default: - :variable:`CPACK_PACKAGE_NAME` for non-component based installations - - :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with -<COMPONENT> + - :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with ``-<COMPONENT>`` for component-based installations. .. versionadded:: 3.5 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME` variables. See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source @@ -66,8 +66,8 @@ List of CPack DEB generator specific variables: Package file name. - * Mandatory : YES - * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb`` + :Mandatory: Yes + :Default: ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb`` This may be set to ``DEB-DEFAULT`` to allow the CPack DEB generator to generate package file name by itself in deb format:: @@ -98,8 +98,8 @@ List of CPack DEB generator specific variables: The Debian package epoch - * Mandatory : No - * Default : - + :Mandatory: No + :Default: None Optional number that should be incremented when changing versioning schemas or fixing mistakes in the version numbers of older packages. @@ -108,8 +108,8 @@ List of CPack DEB generator specific variables: The Debian package version - * Mandatory : YES - * Default : :variable:`CPACK_PACKAGE_VERSION` + :Mandatory: Yes + :Default: :variable:`CPACK_PACKAGE_VERSION` This variable may contain only alphanumerics (A-Za-z0-9) and the characters . + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If @@ -130,8 +130,8 @@ List of CPack DEB generator specific variables: The Debian package release - Debian revision number. - * Mandatory : No - * Default : - + :Mandatory: No + :Default: None This is the numbering of the DEB package itself, i.e. the version of the packaging and not the version of the content (see @@ -144,20 +144,20 @@ List of CPack DEB generator specific variables: The Debian package architecture - * Mandatory : YES - * Default : Output of ``dpkg --print-architecture`` (or ``i386`` + :Mandatory: Yes + :Default: Output of ``dpkg --print-architecture`` (or ``i386`` if ``dpkg`` is not found) .. versionadded:: 3.6 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE` variables. .. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS Sets the Debian dependencies of this package. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based @@ -165,7 +165,7 @@ List of CPack DEB generator specific variables: .. versionadded:: 3.3 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` variables. .. note:: @@ -178,7 +178,9 @@ List of CPack DEB generator specific variables: only the automatically discovered dependencies will be set for this component. - Example:: + Example: + + .. code-block:: cmake set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)") @@ -189,23 +191,23 @@ List of CPack DEB generator specific variables: Sets inter-component dependencies if listed with :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER The Debian package maintainer - * Mandatory : YES - * Default : ``CPACK_PACKAGE_CONTACT`` + :Mandatory: Yes + :Default: :variable:`!CPACK_PACKAGE_CONTACT` .. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION CPACK_DEBIAN_<COMPONENT>_DESCRIPTION The Debian package description - * Mandatory : YES - * Default : + :Mandatory: Yes + :Default: - :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` (component based installers only) if set, or :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set, or @@ -218,13 +220,13 @@ List of CPack DEB generator specific variables: line of description as defined in `Debian Policy Manual`_. .. versionadded:: 3.3 - Per-component ``CPACK_COMPONENT_<compName>_DESCRIPTION`` variables. + Per-component :variable:`!CPACK_COMPONENT_<compName>_DESCRIPTION` variables. .. versionadded:: 3.16 - Per-component ``CPACK_DEBIAN_<COMPONENT>_DESCRIPTION`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables. .. versionadded:: 3.16 - The ``CPACK_PACKAGE_DESCRIPTION_FILE`` variable. + The :variable:`!CPACK_PACKAGE_DESCRIPTION_FILE` variable. .. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description @@ -233,11 +235,11 @@ List of CPack DEB generator specific variables: Set Section control field e.g. admin, devel, doc, ... - * Mandatory : YES - * Default : "devel" + :Mandatory: Yes + :Default: ``devel`` .. versionadded:: 3.5 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` variables. See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections @@ -249,12 +251,10 @@ List of CPack DEB generator specific variables: The archive format used for creating the Debian package. - * Mandatory : YES - * Default : "gnutar" - - Possible value is: + :Mandatory: Yes + :Default: ``gnutar`` - - gnutar + Possible value is: ``gnutar`` .. note:: @@ -269,8 +269,8 @@ List of CPack DEB generator specific variables: The compression used for creating the Debian package. - * Mandatory : YES - * Default : "gzip" + :Mandatory: Yes + :Default: ``gzip`` Possible values are: @@ -298,11 +298,11 @@ List of CPack DEB generator specific variables: Set Priority control field e.g. required, important, standard, optional, extra - * Mandatory : YES - * Default : "optional" + :Mandatory: Yes + :Default: ``optional`` .. versionadded:: 3.5 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY` variables. See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities @@ -312,11 +312,11 @@ List of CPack DEB generator specific variables: site from which the original source can be obtained and any additional upstream documentation or information may be found. - * Mandatory : NO - * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL` + :Mandatory: No + :Default: :variable:`CMAKE_PROJECT_HOMEPAGE_URL` .. versionadded:: 3.12 - The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable. + The :variable:`!CMAKE_PROJECT_HOMEPAGE_URL` variable. .. note:: @@ -329,11 +329,11 @@ List of CPack DEB generator specific variables: May be set to ON in order to use ``dpkg-shlibdeps`` to generate better package dependency list. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or - - OFF + - ``OFF`` .. note:: @@ -350,7 +350,7 @@ List of CPack DEB generator specific variables: shared libraries that could not get resolved otherwise. .. versionadded:: 3.3 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` variables. .. versionadded:: 3.6 Correct handling of ``$ORIGIN`` in :variable:`CMAKE_INSTALL_RPATH`. @@ -363,8 +363,8 @@ List of CPack DEB generator specific variables: via its ``-l`` option. These will be searched by ``dpkg-shlibdeps`` in order to find private shared library dependencies. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: None .. note:: @@ -377,8 +377,8 @@ List of CPack DEB generator specific variables: May be set when invoking cpack in order to trace debug information during the CPack DEB generator run. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS @@ -389,58 +389,58 @@ List of CPack DEB generator specific variables: before even starting the installation of the package which declares the pre-dependency. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based installations. .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS` variables. See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps .. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES - Sets the `Enhances` field of the Debian package. + Sets the ``Enhances`` field of the Debian package. Similar to :variable:`Suggests <CPACK_DEBIAN_PACKAGE_SUGGESTS>` but works in the opposite direction: declares that a package can enhance the functionality of another package. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based installations. .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES` variables. See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps .. variable:: CPACK_DEBIAN_PACKAGE_BREAKS CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS - Sets the `Breaks` field of the Debian package. + Sets the ``Breaks`` field of the Debian package. When a binary package (P) declares that it breaks other packages (B), - ``dpkg`` will not allow the package (P) which declares `Breaks` be + ``dpkg`` will not allow the package (P) which declares ``Breaks`` be **unpacked** unless the packages that will be broken (B) are deconfigured first. As long as the package (P) is configured, the previously deconfigured packages (B) cannot be reconfigured again. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based installations. .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS` variables. See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks @@ -452,15 +452,15 @@ List of CPack DEB generator specific variables: field, ``dpkg`` will not allow them to be unpacked on the system at the same time. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based installations. .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS` variables. See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts @@ -479,15 +479,15 @@ List of CPack DEB generator specific variables: A virtual package is one which appears in the `Provides` control field of another package. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based installations. .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES` variables. See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual @@ -498,34 +498,34 @@ List of CPack DEB generator specific variables: Packages can declare in their control file that they should overwrite files in certain other packages, or completely replace other packages. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based installations. .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES` variables. See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps .. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS - Sets the `Recommends` field of the Debian package. + Sets the ``Recommends`` field of the Debian package. Allows packages to declare a strong, but not absolute, dependency on other packages. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based installations. .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS` variables. See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps @@ -535,15 +535,15 @@ List of CPack DEB generator specific variables: Sets the `Suggests` field of the Debian package. Allows packages to declare a suggested package install grouping. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based installations. .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS` variables. See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps @@ -551,8 +551,8 @@ List of CPack DEB generator specific variables: .. versionadded:: 3.6 - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` Allows to generate shlibs control file automatically. Compatibility is defined by :variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value. @@ -569,11 +569,11 @@ List of CPack DEB generator specific variables: Compatibility policy for auto-generated shlibs control file. - * Mandatory : NO - * Default : "=" + :Mandatory: No + :Default: ``=`` Defines compatibility policy for auto-generated shlibs control file. - Possible values: "=", ">=" + Possible values: ``=``, ``>=`` See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps @@ -584,16 +584,18 @@ List of CPack DEB generator specific variables: control.tar.gz. Typical usage is for conffiles, postinst, postrm, prerm. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None - Usage:: + Usage: + + .. code-block:: cmake set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm") .. versionadded:: 3.4 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA`` variables. + Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA` variables. .. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION @@ -603,10 +605,12 @@ List of CPack DEB generator specific variables: This variable indicates if the Debian policy on control files should be strictly followed. - * Mandatory : NO - * Default : FALSE + :Mandatory: No + :Default: ``FALSE`` + + Usage: - Usage:: + .. code-block:: cmake set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE) @@ -632,8 +636,8 @@ List of CPack DEB generator specific variables: source) the source from which the binary has been generated should be indicated with the field ``Source``. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: - An empty string for non-component based installations - :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based @@ -660,8 +664,8 @@ Dbgsym packaging has its own set of variables: Enable generation of dbgsym .ddeb package(s). - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` .. note:: @@ -683,7 +687,7 @@ Building Debian packages on Windows .. versionadded:: 3.10 To communicate UNIX file permissions from the install stage -to the CPack DEB generator the "cmake_mode_t" NTFS +to the CPack DEB generator the ``cmake_mode_t`` NTFS alternate data stream (ADT) is used. When a filesystem without ADT support is used only owner read/write @@ -694,7 +698,7 @@ Reproducible packages .. versionadded:: 3.13 -The environment variable ``SOURCE_DATE_EPOCH`` may be set to a UNIX +The environment variable :envvar:`!SOURCE_DATE_EPOCH` may be set to a UNIX timestamp, defined as the number of seconds, excluding leap seconds, since 01 Jan 1970 00:00:00 UTC. If set, the CPack DEB generator will use its value for timestamps in the package. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index cba7a00539..0bd52ec569 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -11,14 +11,19 @@ on macOS: .. variable:: CPACK_DMG_VOLUME_NAME - The volume name of the generated disk image. Defaults to - CPACK_PACKAGE_FILE_NAME. + The volume name of the generated disk image. + + :Default: :variable:`CPACK_PACKAGE_FILE_NAME` .. variable:: CPACK_DMG_FORMAT - The disk image format. Common values are ``UDRO`` (UDIF read-only), ``UDZO`` (UDIF + The disk image format. + + :Default: ``UDZO`` + + Common values are ``UDRO`` (UDIF read-only), ``UDZO`` (UDIF zlib-compressed) or ``UDBZ`` (UDIF bzip2-compressed). Refer to ``hdiutil(1)`` for - more information on other available formats. Defaults to ``UDZO``. + more information on other available formats. .. variable:: CPACK_DMG_DS_STORE @@ -41,6 +46,8 @@ on macOS: .. variable:: CPACK_DMG_BACKGROUND_IMAGE + :Default: + Path to an image file to be used as the background. This file will be copied to ``.background``/``background.<ext>``, where ``<ext>`` is the original image file extension. The background image is installed into the image before @@ -58,13 +65,15 @@ on macOS: .. versionadded:: 3.23 + :Default: ``OFF`` + Control whether :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a non-default value, is used as the license agreement provided when - mounting the DMG. If ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` is + mounting the DMG. If :variable:`!CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` is not set, :manual:`cpack(1)` defaults to off. In a CMake project that uses the :module:`CPack` module to generate - ``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` + ``CPackConfig.cmake``, :variable:`!CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` must be explicitly enabled by the project to activate the SLA. See policy :policy:`CMP0133`. @@ -82,8 +91,8 @@ on macOS: Directory where license and menu files for different languages are stored. Setting this causes CPack to look for a ``<language>.menu.txt`` and ``<language>.license.txt`` or ``<language>.license.rtf`` file for every - language defined in ``CPACK_DMG_SLA_LANGUAGES``. If both this variable and - ``CPACK_RESOURCE_FILE_LICENSE`` are set, CPack will only look for the menu + language defined in :variable:`CPACK_DMG_SLA_LANGUAGES`. If both this variable and + :variable:`CPACK_RESOURCE_FILE_LICENSE` are set, CPack will only look for the menu files and use the same license file for all languages. If both ``<language>.license.txt`` and ``<language>.license.rtf`` exist, the ``.txt`` file will be used. @@ -120,17 +129,18 @@ on macOS: .. versionadded:: 3.17 File name when packaging ``<component>`` as its own DMG - (``CPACK_COMPONENTS_GROUPING`` set to IGNORE). + (:variable:`CPACK_COMPONENTS_GROUPING` set to ``IGNORE``). - - Default: ``CPACK_PACKAGE_FILE_NAME-<component>`` + :Default: ``CPACK_PACKAGE_FILE_NAME-<component>`` .. variable:: CPACK_DMG_FILESYSTEM .. versionadded:: 3.21 + :Default: ``HFS+`` + The filesystem format. Common values are ``APFS`` and ``HFS+``. See ``man hdiutil`` for a full list of supported formats. - Defaults to ``HFS+``. .. variable:: CPACK_COMMAND_HDIUTIL diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst index faf8c74ff7..e97ba4909d 100644 --- a/Help/cpack_gen/freebsd.rst +++ b/Help/cpack_gen/freebsd.rst @@ -19,7 +19,7 @@ be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX, depending on the installed package-management tools -- using :module:`CPack`. The CPack FreeBSD generator is a :module:`CPack` generator and uses the -``CPACK_XXX`` variables used by :module:`CPack`. It tries to re-use packaging +:variable:`!CPACK_XXX` variables used by :module:`CPack`. It tries to re-use packaging information that may already be specified for Debian packages for the :cpack_gen:`CPack DEB Generator`. It also tries to re-use RPM packaging information when Debian does not specify. @@ -28,14 +28,14 @@ The CPack FreeBSD generator should work on any host with libpkg installed. The packages it produces are specific to the host architecture and ABI. The CPack FreeBSD generator sets package-metadata through -``CPACK_FREEBSD_XXX`` variables. The CPack FreeBSD generator, unlike the +:variable:`!CPACK_FREEBSD_XXX` variables. The CPack FreeBSD generator, unlike the CPack Deb generator, does not specially support componentized packages; a single package is created from all the software artifacts created through CMake. All of the variables can be set specifically for FreeBSD packaging in the CPackConfig file or in CMakeLists.txt, but most of them have defaults -that use general settings (e.g. CMAKE_PROJECT_NAME) or Debian-specific +that use general settings (e.g. :variable:`CMAKE_PROJECT_NAME`) or Debian-specific variables when those make sense (e.g. the homepage of an upstream project is usually unchanged by the flavor of packaging). When there is no Debian information to fall back on, but the RPM packaging has it, fall back to @@ -46,8 +46,8 @@ the RPM information (e.g. package license). Sets the package name (in the package manifest, but also affects the output filename). - * Mandatory: YES - * Default: + :Mandatory: Yes + :Default: - :variable:`CPACK_PACKAGE_NAME` (this is always set by CPack itself, based on CMAKE_PROJECT_NAME). @@ -57,8 +57,8 @@ the RPM information (e.g. package license). Sets the package comment. This is the short description displayed by pkg(8) in standard "pkg info" output. - * Mandatory: YES - * Default: + :Mandatory: Yes + :Default: - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set by CPack itself, if nothing else sets it explicitly). @@ -68,14 +68,14 @@ the RPM information (e.g. package license). Sets the package description. This is the long description of the package, given by "pkg info" with a specific package as argument. - * Mandatory: YES - * Default: + :Mandatory: Yes + :Default: - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already for Debian packaging, so it is used as a fallback). - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set by CPack itself, if nothing else sets it explicitly). - - :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION + - :variable:`PROJECT_DESCRIPTION` (this can be set with the ``DESCRIPTION`` parameter for :command:`project`). .. variable:: CPACK_FREEBSD_PACKAGE_WWW @@ -84,15 +84,15 @@ the RPM information (e.g. package license). site from which the original source can be obtained and any additional upstream documentation or information may be found. - * Mandatory: YES - * Default: + :Mandatory: Yes + :Default: - :variable:`CPACK_PACKAGE_HOMEPAGE_URL`, or if that is not set, - :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already for Debian packaging, so it is used as a fallback). .. versionadded:: 3.12 - The ``CPACK_PACKAGE_HOMEPAGE_URL`` variable. + The :variable:`!CPACK_PACKAGE_HOMEPAGE_URL` variable. .. variable:: CPACK_FREEBSD_PACKAGE_LICENSE @@ -100,8 +100,8 @@ the RPM information (e.g. package license). be one or more license-identifiers that pkg recognizes as acceptable license identifiers (e.g. "GPLv2"). - * Mandatory: YES - * Default: + :Mandatory: Yes + :Default: - :variable:`CPACK_RPM_PACKAGE_LICENSE` @@ -112,24 +112,24 @@ the RPM information (e.g. package license). Other acceptable values are determined by pkg -- those are "dual" or "multi" -- meaning choice (OR) or simultaneous (AND) application of the licenses. - * Mandatory: NO - * Default: single + :Mandatory: No + :Default: single .. variable:: CPACK_FREEBSD_PACKAGE_MAINTAINER - The FreeBSD maintainer (e.g. kde@freebsd.org) of this package. + The FreeBSD maintainer (e.g. ``kde@freebsd.org``) of this package. - * Mandatory: YES - * Default: none + :Mandatory: Yes + :Default: none .. variable:: CPACK_FREEBSD_PACKAGE_ORIGIN The origin (ports label) of this package; for packages built by CPack outside of the ports system this is of less importance. The default - puts the package somewhere under misc/, as a stopgap. + puts the package somewhere under ``misc/``, as a stopgap. - * Mandatory: YES - * Default: misc/<package name> + :Mandatory: Yes + :Default: ``misc/<package name>`` .. variable:: CPACK_FREEBSD_PACKAGE_CATEGORIES @@ -137,15 +137,15 @@ the RPM information (e.g. package license). from ports). If none is set a single category is determined based on the package origin. - * Mandatory: YES - * Default: derived from ORIGIN + :Mandatory: Yes + :Default: derived from ``ORIGIN`` .. variable:: CPACK_FREEBSD_PACKAGE_DEPS A list of package origins that should be added as package dependencies. - These are in the form <category>/<packagename>, e.g. x11/libkonq. + These are in the form ``<category>/<packagename>``, e.g. ``x11/libkonq``. No version information needs to be provided (this is not included in the manifest). - * Mandatory: NO - * Default: empty + :Mandatory: No + :Default: empty diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index 3bf7f84f6e..1f2e76281d 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -5,11 +5,11 @@ CPack NuGet Generator When build a NuGet package there is no direct way to control an output filename due a lack of the corresponding CLI option of NuGet, so there -is no ``CPACK_NUGET_PACKAGE_FILE_NAME`` variable. To form the output filename +is no :variable:`!CPACK_NUGET_PACKAGE_FILE_NAME` variable. To form the output filename NuGet uses the package name and the version according to its built-in rules. Also, be aware that including a top level directory -(``CPACK_INCLUDE_TOPLEVEL_DIRECTORY``) is ignored by this generator. +(:variable:`CPACK_INCLUDE_TOPLEVEL_DIRECTORY`) is ignored by this generator. Variables specific to CPack NuGet generator @@ -17,10 +17,10 @@ Variables specific to CPack NuGet generator The CPack NuGet generator may be used to create NuGet packages using :module:`CPack`. The CPack NuGet generator is a :module:`CPack` generator thus -it uses the ``CPACK_XXX`` variables used by :module:`CPack`. +it uses the :variable:`!CPACK_XXX` variables used by :module:`CPack`. The CPack NuGet generator has specific features which are controlled by the -specifics ``CPACK_NUGET_XXX`` variables. In the "one per group" mode +specifics :variable:`!CPACK_NUGET_XXX` variables. In the "one per group" mode (see :variable:`CPACK_COMPONENTS_GROUPING`), ``<compName>`` placeholder in the variables below would contain a group name (uppercased and turned into a "C" identifier). @@ -31,8 +31,8 @@ List of CPack NuGet generator specific variables: Enable component packaging for CPack NuGet generator - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` .. variable:: CPACK_NUGET_PACKAGE_NAME CPACK_NUGET_<compName>_PACKAGE_NAME @@ -40,26 +40,27 @@ List of CPack NuGet generator specific variables: The NUGET package name. ``CPACK_NUGET_PACKAGE_NAME`` is used as the package ``id`` on nuget.org_ - * Mandatory : YES - * Default : :variable:`CPACK_PACKAGE_NAME` + :Mandatory: Yes + :Default: :variable:`CPACK_PACKAGE_NAME` .. variable:: CPACK_NUGET_PACKAGE_VERSION CPACK_NUGET_<compName>_PACKAGE_VERSION The NuGet package version. - * Mandatory : YES - * Default : :variable:`CPACK_PACKAGE_VERSION` + :Mandatory: Yes + :Default: :variable:`CPACK_PACKAGE_VERSION` .. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION A long description of the package for UI display. - * Mandatory : YES - * Default : + :Mandatory: Yes + :Default: + - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION`, - - ``CPACK_COMPONENT_GROUP_<groupName>_DESCRIPTION``, + - :variable:`!CPACK_COMPONENT_GROUP_<groupName>_DESCRIPTION`, - :variable:`CPACK_PACKAGE_DESCRIPTION` .. variable:: CPACK_NUGET_PACKAGE_AUTHORS @@ -70,8 +71,8 @@ List of CPack NuGet generator specific variables: nuget.org_ and are used to cross-reference packages by the same authors. - * Mandatory : YES - * Default : :variable:`CPACK_PACKAGE_VENDOR` + :Mandatory: Yes + :Default: :variable:`CPACK_PACKAGE_VENDOR` .. variable:: CPACK_NUGET_PACKAGE_TITLE CPACK_NUGET_<compName>_PACKAGE_TITLE @@ -80,10 +81,11 @@ List of CPack NuGet generator specific variables: as on nuget.org_ and the Package Manager in Visual Studio. If not specified, the package ID is used. - * Mandatory : NO - * Default : + :Mandatory: No + :Default: + - :variable:`CPACK_COMPONENT_<compName>_DISPLAY_NAME`, - - ``CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME`` + - :variable:`!CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME` .. variable:: CPACK_NUGET_PACKAGE_OWNERS CPACK_NUGET_<compName>_PACKAGE_OWNERS @@ -92,8 +94,8 @@ List of CPack NuGet generator specific variables: on nuget.org_. This is often the same list as in authors, and is ignored when uploading the package to nuget.org_. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_HOMEPAGE_URL CPACK_NUGET_<compName>_PACKAGE_HOMEPAGE_URL @@ -101,8 +103,8 @@ List of CPack NuGet generator specific variables: An URL for the package's home page, often shown in UI displays as well as nuget.org_. - * Mandatory : NO - * Default : :variable:`CPACK_PACKAGE_HOMEPAGE_URL` + :Mandatory: No + :Default: :variable:`CPACK_PACKAGE_HOMEPAGE_URL` .. variable:: CPACK_NUGET_PACKAGE_LICENSEURL CPACK_NUGET_<compName>_PACKAGE_LICENSEURL @@ -116,8 +118,8 @@ List of CPack NuGet generator specific variables: An URL for the package's license, often shown in UI displays as well as on nuget.org_. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION @@ -131,24 +133,24 @@ List of CPack NuGet generator specific variables: ``MIT OR BSD-3-Clause``. See the `SPDX specification`_ for guidance on forming complex license expressions. - If ``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` is specified, - ``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` is ignored. + If :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified, + :variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME The package's license file in :file:`.txt` or :file:`.md` format. - If ``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` is specified, - ``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` is ignored. + If :variable:`!CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified, + :variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored. .. versionadded:: 3.20 - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_ICONURL CPACK_NUGET_<compName>_PACKAGE_ICONURL @@ -159,16 +161,16 @@ List of CPack NuGet generator specific variables: An URL for a 64x64 image with transparency background to use as the icon for the package in UI display. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE When set to a true value, the user will be prompted to accept the license before installing the package. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_ICON CPACK_NUGET_<compName>_PACKAGE_ICON @@ -178,8 +180,8 @@ List of CPack NuGet generator specific variables: The filename of a 64x64 image with transparency background to use as the icon for the package in UI display. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY @@ -187,8 +189,8 @@ List of CPack NuGet generator specific variables: A short description of the package for UI display. If omitted, a truncated version of description is used. - * Mandatory : NO - * Default : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + :Mandatory: No + :Default: :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` .. variable:: CPACK_NUGET_PACKAGE_RELEASE_NOTES CPACK_NUGET_<compName>_PACKAGE_RELEASE_NOTES @@ -197,16 +199,16 @@ List of CPack NuGet generator specific variables: often used in UI like the Updates tab of the Visual Studio Package Manager in place of the package description. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_COPYRIGHT CPACK_NUGET_<compName>_PACKAGE_COPYRIGHT Copyright details for the package. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_LANGUAGE CPACK_NUGET_<compName>_PACKAGE_LANGUAGE @@ -215,8 +217,8 @@ List of CPack NuGet generator specific variables: Locale specifier for the package, for example ``en_CA``. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_TAGS CPACK_NUGET_<compName>_PACKAGE_TAGS @@ -225,34 +227,33 @@ List of CPack NuGet generator specific variables: package and aid discoverability of packages through search and filtering. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES A list of package dependencies. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<dependency>_VERSION CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION A `version specification`_ for the particular dependency, where ``<dependency>`` is an item of the dependency list (see above) - transformed with ``MAKE_C_IDENTIFIER`` function of :command:`string` - command. + transformed with :command:`string(MAKE_C_IDENTIFIER)` command. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: None .. variable:: CPACK_NUGET_PACKAGE_DEBUG Enable debug messages while executing CPack NuGet generator. - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` .. _nuget.org: https://www.nuget.org diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index b1e0077bfe..7b91261f53 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -8,27 +8,27 @@ Variables specific to CPack RPM generator The CPack RPM generator may be used to create RPM packages using :module:`CPack`. The CPack RPM generator is a :module:`CPack` generator thus it uses the -``CPACK_XXX`` variables used by :module:`CPack`. +:variable:`!CPACK_XXX` variables used by :module:`CPack`. The CPack RPM generator has specific features which are controlled by the specifics -``CPACK_RPM_XXX`` variables. +:variable:`!CPACK_RPM_XXX` variables. -``CPACK_RPM_<COMPONENT>_XXXX`` variables may be used in order to have -**component** specific values. Note however that ``<COMPONENT>`` refers to the +:variable:`!CPACK_RPM_<COMPONENT>_XXXX` variables may be used in order to have +**component-specific** values. Note however that ``<COMPONENT>`` refers to the **grouping name** written in upper case. It may be either a component name or -a component GROUP name. Usually those variables correspond to RPM spec file +a component GROUP name. Usually, those variables correspond to RPM spec file entities. One may find information about spec files here -https://rpm.org/documentation +https://rpm.org/documentation. .. versionchanged:: 3.6 `<COMPONENT>` part of variables is preferred to be in upper case (e.g. if - component is named ``foo`` then use ``CPACK_RPM_FOO_XXXX`` variable name format) - as is with other ``CPACK_<COMPONENT>_XXXX`` variables. + component is named ``foo`` then use :variable:`!CPACK_RPM_FOO_XXXX` variable + name format) as is with other :variable:`!CPACK_<COMPONENT>_XXXX` variables. For the purposes of back compatibility (CMake/CPack version 3.5 and lower) support for same cased component (e.g. ``fOo`` would be used as - ``CPACK_RPM_fOo_XXXX``) is still supported for variables defined in older - versions of CMake/CPack but is not guaranteed for variables that + :variable:`!CPACK_RPM_fOo_XXXX`) is still supported for variables defined in + older versions of CMake/CPack but is not guaranteed for variables that will be added in the future. For the sake of back compatibility same cased component variables also override upper cased versions where both are present. @@ -45,8 +45,8 @@ List of CPack RPM generator specific variables: Enable component packaging for CPack RPM generator - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` If enabled (``ON``) multiple packages are generated. By default a single package containing files of all components is generated. @@ -56,22 +56,22 @@ List of CPack RPM generator specific variables: The RPM package summary. - * Mandatory : YES - * Default : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + :Mandatory: Yes + :Default: :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` .. versionadded:: 3.2 - Per-component ``CPACK_RPM_<component>_PACKAGE_SUMMARY`` variables. + Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_SUMMARY` variables. .. variable:: CPACK_RPM_PACKAGE_NAME CPACK_RPM_<component>_PACKAGE_NAME The RPM package name. - * Mandatory : YES - * Default : :variable:`CPACK_PACKAGE_NAME` + :Mandatory: Yes + :Default: :variable:`CPACK_PACKAGE_NAME` .. versionadded:: 3.5 - Per-component ``CPACK_RPM_<component>_PACKAGE_NAME`` variables. + Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_NAME` variables. .. variable:: CPACK_RPM_FILE_NAME CPACK_RPM_<component>_FILE_NAME @@ -80,8 +80,8 @@ List of CPack RPM generator specific variables: Package file name. - * Mandatory : YES - * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces + :Mandatory: Yes + :Default: ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces replaced by '-' This may be set to ``RPM-DEFAULT`` to allow ``rpmbuild`` tool to generate package @@ -105,8 +105,8 @@ List of CPack RPM generator specific variables: Main component that is packaged without component suffix. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: This variable can be set to any component or group name so that component or group rpm package is generated without component suffix in filename and @@ -118,8 +118,8 @@ List of CPack RPM generator specific variables: The RPM package epoch - * Mandatory : No - * Default : - + :Mandatory: No + :Default: Optional number that should be incremented when changing versioning schemas or fixing mistakes in the version numbers of older packages. @@ -128,28 +128,28 @@ List of CPack RPM generator specific variables: The RPM package version. - * Mandatory : YES - * Default : :variable:`CPACK_PACKAGE_VERSION` + :Mandatory: Yes + :Default: :variable:`CPACK_PACKAGE_VERSION` .. variable:: CPACK_RPM_PACKAGE_ARCHITECTURE CPACK_RPM_<component>_PACKAGE_ARCHITECTURE The RPM package architecture. - * Mandatory : YES - * Default : Native architecture output by ``uname -m`` + :Mandatory: Yes + :Default: Native architecture output by ``uname -m`` This may be set to ``noarch`` if you know you are building a ``noarch`` package. .. versionadded:: 3.3 - Per-component ``CPACK_RPM_<component>_PACKAGE_ARCHITECTURE`` variables. + Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variables. .. variable:: CPACK_RPM_PACKAGE_RELEASE The RPM package release. - * Mandatory : YES - * Default : 1 + :Mandatory: Yes + :Default: 1 This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see @@ -169,8 +169,8 @@ List of CPack RPM generator specific variables: The dist tag that is added RPM ``Release:`` field. - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` This is the reported ``%{dist}`` tag from the current distribution or empty ``%{dist}`` if RPM macro is not set. If this variable is set then RPM @@ -180,57 +180,61 @@ List of CPack RPM generator specific variables: The RPM package license policy. - * Mandatory : YES - * Default : "unknown" + :Mandatory: Yes + :Default: "unknown" .. variable:: CPACK_RPM_PACKAGE_GROUP CPACK_RPM_<component>_PACKAGE_GROUP The RPM package group. - * Mandatory : YES - * Default : "unknown" + :Mandatory: Yes + :Default: "unknown" .. versionadded:: 3.5 - Per-component ``CPACK_RPM_<component>_PACKAGE_GROUP`` variables. + Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_GROUP` variables. .. variable:: CPACK_RPM_PACKAGE_VENDOR The RPM package vendor. - * Mandatory : YES - * Default : CPACK_PACKAGE_VENDOR if set or "unknown" + :Mandatory: Yes + :Default: CPACK_PACKAGE_VENDOR if set or "unknown" .. variable:: CPACK_RPM_PACKAGE_URL CPACK_RPM_<component>_PACKAGE_URL The projects URL. - * Mandatory : NO - * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL` + :Mandatory: No + :Default: :variable:`CMAKE_PROJECT_HOMEPAGE_URL` .. versionadded:: 3.12 - The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable. + The :variable:`!CMAKE_PROJECT_HOMEPAGE_URL` variable. .. variable:: CPACK_RPM_PACKAGE_DESCRIPTION CPACK_RPM_<component>_PACKAGE_DESCRIPTION RPM package description. - * Mandatory : YES - * Default : :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component - based installers only) if set, :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` - if set or "no package description available" + :Mandatory: Yes + :Default: + + - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` + (component based installers only) if set, + - :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` + if set, or + - ``no package description available`` .. versionadded:: 3.2 - Per-component ``CPACK_RPM_<component>_PACKAGE_DESCRIPTION`` variables. + Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_DESCRIPTION` variables. .. variable:: CPACK_RPM_COMPRESSION_TYPE RPM compression type. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: (system default) May be used to override RPM compression type to be used to build the RPM. For example some Linux distribution now default to ``lzma`` or ``xz`` @@ -239,18 +243,25 @@ List of CPack RPM generator specific variables: Possible values are: - - lzma - - xz - - bzip2 - - gzip + ``lzma`` + Lempel–Ziv–Markov chain algorithm + + ``xz`` + XZ Utils compression + + ``bzip2`` + bzip2 Burrows–Wheeler algorithm + + ``gzip`` + GNU Gzip compression .. variable:: CPACK_RPM_PACKAGE_AUTOREQ CPACK_RPM_<component>_PACKAGE_AUTOREQ RPM spec autoreq field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to enable (``1``, ``yes``) or disable (``0``, ``no``) automatic shared libraries dependency detection. Dependencies are added to requires list. @@ -264,8 +275,8 @@ List of CPack RPM generator specific variables: RPM spec autoprov field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to enable (``1``, ``yes``) or disable (``0``, ``no``) automatic listing of shared libraries that are provided by the package. @@ -280,8 +291,8 @@ List of CPack RPM generator specific variables: RPM spec autoreqprov field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: Variable enables/disables autoreq and autoprov at the same time. See :variable:`CPACK_RPM_PACKAGE_AUTOREQ` and @@ -296,11 +307,13 @@ List of CPack RPM generator specific variables: RPM spec requires field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set RPM dependencies (requires). Note that you must enclose - the complete requires string between quotes, for example:: + the complete requires string between quotes, for example: + + .. code-block:: cmake set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8") @@ -313,11 +326,13 @@ List of CPack RPM generator specific variables: RPM spec conflicts field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set negative RPM dependencies (conflicts). Note that you must - enclose the complete requires string between quotes, for example:: + enclose the complete requires string between quotes, for example: + + .. code-block:: cmake set(CPACK_RPM_PACKAGE_CONFLICTS "libxml2") @@ -332,11 +347,13 @@ List of CPack RPM generator specific variables: RPM spec requires(pre) field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set RPM preinstall dependencies (requires(pre)). Note that - you must enclose the complete requires string between quotes, for example:: + you must enclose the complete requires string between quotes, for example: + + .. code-block:: cmake set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils, initscripts") @@ -347,11 +364,13 @@ List of CPack RPM generator specific variables: RPM spec requires(post) field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set RPM postinstall dependencies (requires(post)). Note that - you must enclose the complete requires string between quotes, for example:: + you must enclose the complete requires string between quotes, for example: + + .. code-block:: cmake set(CPACK_RPM_PACKAGE_REQUIRES_POST "shadow-utils, initscripts") @@ -362,12 +381,14 @@ List of CPack RPM generator specific variables: RPM spec requires(postun) field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set RPM postuninstall dependencies (requires(postun)). Note that you must enclose the complete requires string between quotes, for - example:: + example: + + .. code-block:: cmake set(CPACK_RPM_PACKAGE_REQUIRES_POSTUN "shadow-utils, initscripts") @@ -378,11 +399,13 @@ List of CPack RPM generator specific variables: RPM spec requires(preun) field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set RPM preuninstall dependencies (requires(preun)). Note that - you must enclose the complete requires string between quotes, for example:: + you must enclose the complete requires string between quotes, for example: + + .. code-block:: cmake set(CPACK_RPM_PACKAGE_REQUIRES_PREUN "shadow-utils, initscripts") @@ -391,8 +414,8 @@ List of CPack RPM generator specific variables: RPM spec suggest field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set weak RPM dependencies (suggests). If ``rpmbuild`` doesn't support the ``Suggests`` tag, CPack will emit a warning and ignore this @@ -404,8 +427,8 @@ List of CPack RPM generator specific variables: RPM spec provides field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set RPM dependencies (provides). The provided package list of an RPM file could be printed with:: @@ -417,8 +440,8 @@ List of CPack RPM generator specific variables: RPM spec obsoletes field. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set RPM packages that are obsoleted by this one. @@ -426,8 +449,8 @@ List of CPack RPM generator specific variables: build a relocatable RPM. - * Mandatory : NO - * Default : CPACK_PACKAGE_RELOCATABLE + :Mandatory: No + :Default: CPACK_PACKAGE_RELOCATABLE If this variable is set to TRUE or ON, the CPack RPM generator will try to build a relocatable RPM package. A relocatable RPM may @@ -442,11 +465,10 @@ List of CPack RPM generator specific variables: .. variable:: CPACK_RPM_SPEC_INSTALL_POST - Deprecated - use :variable:`CPACK_RPM_SPEC_MORE_DEFINE` instead. + .. deprecated:: 2.8.12 Use :variable:`CPACK_RPM_SPEC_MORE_DEFINE` instead. - * Mandatory : NO - * Default : - - * Deprecated: YES + :Mandatory: No + :Default: May be used to override the ``__spec_install_post`` section within the generated spec file. This affects the install step during package creation, @@ -458,12 +480,14 @@ List of CPack RPM generator specific variables: RPM extended spec definitions lines. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to add any ``%define`` lines to the generated spec file. An example of its use is to prevent stripping of executables (but note that - this may also disable other default post install processing):: + this may also disable other default post install processing): + + .. code-block:: cmake set(CPACK_RPM_SPEC_MORE_DEFINE "%define __spec_install_post /bin/true") @@ -471,8 +495,8 @@ List of CPack RPM generator specific variables: Toggle CPack RPM generator debug output. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be set when invoking cpack in order to trace debug information during CPack RPM run. For example you may launch CPack like this:: @@ -484,8 +508,8 @@ List of CPack RPM generator specific variables: A user provided spec file. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be set by the user in order to specify a USER binary spec file to be used by the CPack RPM generator instead of generating the file. @@ -495,8 +519,8 @@ List of CPack RPM generator specific variables: Spec file template. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: If set CPack will generate a template for USER specified binary spec file and stop with an error. For example launch CPack like this:: @@ -513,23 +537,23 @@ List of CPack RPM generator specific variables: Path to file containing pre install/uninstall/transaction script. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to embed a pre installation/uninstallation/transaction script in the spec file. The referred script file (or both) will be read and directly put after the ``%pre`` or ``%preun`` section If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction script for each component can be overridden with - ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``, - ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and - ``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE`` + :variable:`!CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`, + :variable:`!CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE`, and + :variable:`!CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE` One may verify which scriptlet has been included with:: rpm -qp --scripts package.rpm .. versionadded:: 3.18 - The ``CPACK_RPM_PRE_TRANS_SCRIPT_FILE`` variable. + The :variable:`!CPACK_RPM_PRE_TRANS_SCRIPT_FILE` variable. .. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE @@ -537,35 +561,35 @@ List of CPack RPM generator specific variables: Path to file containing post install/uninstall/transaction script. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to embed a post installation/uninstallation/transaction script in the spec file. The referred script file (or both) will be read and directly put after the ``%post`` or ``%postun`` section. If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction script for each component can be overridden with - ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``, - ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and - ``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE`` + :variable:`!CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`, + :variable:`!CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE`, and + :variable:`!CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE` One may verify which scriptlet has been included with:: rpm -qp --scripts package.rpm .. versionadded:: 3.18 - The ``CPACK_RPM_POST_TRANS_SCRIPT_FILE`` variable. + The :variable:`!CPACK_RPM_POST_TRANS_SCRIPT_FILE` variable. .. variable:: CPACK_RPM_USER_FILELIST CPACK_RPM_<COMPONENT>_USER_FILELIST - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to explicitly specify ``%(<directive>)`` file line in the spec file. Like ``%config(noreplace)`` or any other directive that be found in the ``%files`` section. Since the CPack RPM generator is generating the list of files (and directories) the - user specified files of the ``CPACK_RPM_<COMPONENT>_USER_FILELIST`` list will + user specified files of the :variable:`!CPACK_RPM_<COMPONENT>_USER_FILELIST` list will be removed from the generated list. If referring to directories do not add a trailing slash. @@ -577,8 +601,8 @@ List of CPack RPM generator specific variables: RPM changelog file. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to embed a changelog in the spec file. The referred file will be read and directly put after the ``%changelog`` @@ -588,10 +612,20 @@ List of CPack RPM generator specific variables: list of path to be excluded. - * Mandatory : NO - * Default : /etc /etc/init.d /usr /usr/bin /usr/include /usr/lib - /usr/libx32 /usr/lib64 /usr/share /usr/share/aclocal - /usr/share/doc + :Mandatory: No + :Default: + The following paths are excluded by default: + - ``/etc`` + - ``/etc/init.d`` + - ``/usr`` + - ``/usr/bin`` + - ``/usr/include`` + - ``/usr/lib`` + - ``/usr/libx32`` + - ``/usr/lib64`` + - ``/usr/share`` + - ``/usr/share/aclocal`` + - ``/usr/share/doc`` May be used to exclude path (directories or files) from the auto-generated list of paths discovered by CPack RPM. The default value contains a @@ -607,8 +641,8 @@ List of CPack RPM generator specific variables: additional list of path to be excluded. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to add more exclude path (directories or files) from the initial default list of excluded paths. See @@ -620,8 +654,8 @@ List of CPack RPM generator specific variables: Packages relocation paths list. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to specify more than one relocation path per relocatable RPM. Variable contains a list of relocation paths that if relative are prefixed @@ -637,7 +671,7 @@ List of CPack RPM generator specific variables: no files/directories/symbolic links on any of the provided prefix locations. Packages that either do not contain any relocation paths or contain files/directories/symbolic links that are outside relocation paths print - out an ``AUTHOR_WARNING`` that RPM will be partially relocatable. + out an :command:`AUTHOR_WARNING <message>` that RPM will be partially relocatable. .. variable:: CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX @@ -645,8 +679,8 @@ List of CPack RPM generator specific variables: Per component relocation path install prefix. - * Mandatory : NO - * Default : CPACK_PACKAGING_INSTALL_PREFIX + :Mandatory: No + :Default: :variable:`CPACK_PACKAGING_INSTALL_PREFIX` May be used to set per component :variable:`CPACK_PACKAGING_INSTALL_PREFIX` for relocatable RPM packages. @@ -658,19 +692,33 @@ List of CPack RPM generator specific variables: Removal of default install prefix from relocation paths list. - * Mandatory : NO - * Default : CPACK_PACKAGING_INSTALL_PREFIX or CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX - are treated as one of relocation paths + :Mandatory: No + :Default: :variable:`CPACK_PACKAGING_INSTALL_PREFIX` or + :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` + are treated as one of relocation paths - May be used to remove CPACK_PACKAGING_INSTALL_PREFIX and CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX + May be used to remove :variable:`CPACK_PACKAGING_INSTALL_PREFIX` and + :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` from relocatable RPM prefix paths. .. variable:: CPACK_RPM_ADDITIONAL_MAN_DIRS .. versionadded:: 3.3 - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: + Regular expressions that are added by default were taken from ``brp-compress`` RPM macro: + - ``/usr/man/man.*`` + - ``/usr/man/.*/man.*`` + - ``/usr/info.*`` + - ``/usr/share/man/man.*`` + - ``/usr/share/man/.*/man.*`` + - ``/usr/share/info.*`` + - ``/usr/kerberos/man.*`` + - ``/usr/X11R6/man/man.*`` + - ``/usr/lib/perl5/man/man.*`` + - ``/usr/share/doc/.*/man/man.*`` + - ``/usr/lib/.*/man/man.*`` May be used to set additional man dirs that could potentially be compressed by brp-compress RPM macro. Variable content must be a list of regular @@ -679,21 +727,6 @@ List of CPack RPM generator specific variables: present in brp-compress RPM script and that brp-compress script must be added to RPM configuration by the operating system. - Regular expressions that are added by default were taken from brp-compress - RPM macro: - - - /usr/man/man.* - - /usr/man/.*/man.* - - /usr/info.* - - /usr/share/man/man.* - - /usr/share/man/.*/man.* - - /usr/share/info.* - - /usr/kerberos/man.* - - /usr/X11R6/man/man.* - - /usr/lib/perl5/man/man.* - - /usr/share/doc/.*/man/man.* - - /usr/lib/.*/man/man.* - .. variable:: CPACK_RPM_DEFAULT_USER CPACK_RPM_<compName>_DEFAULT_USER @@ -701,11 +734,11 @@ List of CPack RPM generator specific variables: default user ownership of RPM content - * Mandatory : NO - * Default : root + :Mandatory: No + :Default: ``root`` Value should be user name and not UID. - Note that <compName> must be in upper-case. + Note that ``<compName>`` must be in upper-case. .. variable:: CPACK_RPM_DEFAULT_GROUP CPACK_RPM_<compName>_DEFAULT_GROUP @@ -714,11 +747,11 @@ List of CPack RPM generator specific variables: default group ownership of RPM content - * Mandatory : NO - * Default : root + :Mandatory: No + :Default: root Value should be group name and not GID. - Note that <compName> must be in upper-case. + Note that ``<compName>`` must be in upper-case. .. variable:: CPACK_RPM_DEFAULT_FILE_PERMISSIONS CPACK_RPM_<compName>_DEFAULT_FILE_PERMISSIONS @@ -727,23 +760,23 @@ List of CPack RPM generator specific variables: default permissions used for packaged files - * Mandatory : NO - * Default : - (system default) + :Mandatory: No + :Default: (system default) - Accepted values are lists with ``PERMISSIONS``. Valid permissions + Accepted values are lists with PERMISSIONS. Valid permissions are: - - OWNER_READ - - OWNER_WRITE - - OWNER_EXECUTE - - GROUP_READ - - GROUP_WRITE - - GROUP_EXECUTE - - WORLD_READ - - WORLD_WRITE - - WORLD_EXECUTE + - ``OWNER_READ`` + - ``OWNER_WRITE`` + - ``OWNER_EXECUTE`` + - ``GROUP_READ`` + - ``GROUP_WRITE`` + - ``GROUP_EXECUTE`` + - ``WORLD_READ`` + - ``WORLD_WRITE`` + - ``WORLD_EXECUTE`` - Note that <compName> must be in upper-case. + Note that ``<compName>`` must be in upper-case. .. variable:: CPACK_RPM_DEFAULT_DIR_PERMISSIONS CPACK_RPM_<compName>_DEFAULT_DIR_PERMISSIONS @@ -752,12 +785,12 @@ List of CPack RPM generator specific variables: default permissions used for packaged directories - * Mandatory : NO - * Default : - (system default) + :Mandatory: No + :Default: (system default) Accepted values are lists with PERMISSIONS. Valid permissions are the same as for :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`. - Note that <compName> must be in upper-case. + Note that ``<compName>`` must be in upper-case. .. variable:: CPACK_RPM_INSTALL_WITH_EXEC @@ -765,8 +798,8 @@ List of CPack RPM generator specific variables: force execute permissions on programs and shared libraries - * Mandatory : NO - * Default : - (system default) + :Mandatory: No + :Default: (system default) Force set owner, group and world execute permissions on programs and shared libraries. This can be used for creating valid rpm packages on systems such @@ -782,7 +815,9 @@ Packaging of Symbolic Links .. versionadded:: 3.3 -The CPack RPM generator supports packaging of symbolic links:: +The CPack RPM generator supports packaging of symbolic links: + +.. code-block:: cmake execute_process(COMMAND ${CMAKE_COMMAND} -E create_symlink <relative_path_location> <symlink_name>) @@ -832,8 +867,8 @@ Debuginfo RPM packaging has its own set of variables: Enable generation of debuginfo RPM package(s). - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` .. note:: @@ -855,8 +890,8 @@ Debuginfo RPM packaging has its own set of variables: Provides locations of root directories of source files from which binaries were built. - * Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set - * Default : - + :Mandatory: Yes if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set + :Default: .. note:: @@ -873,15 +908,15 @@ Debuginfo RPM packaging has its own set of variables: Prefix of location where sources will be placed during package installation. - * Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set - * Default : "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>" and - for component packaging "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>-<component>" + :Mandatory: Yes if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set + :Default: ``/usr/src/debug/${CPACK_PACKAGE_FILE_NAME}`` and + for component packaging ``/usr/src/debug/${CPACK_PACKAGE_FILE_NAME}-<component>`` .. note:: Each source path prefix is additionally suffixed by ``src_<index>`` where index is index of the path used from :variable:`CPACK_BUILD_SOURCE_DIRS` - variable. This produces ``<CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX>/src_<index>`` + variable. This produces ``${CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX}/src_<index>`` replacement path. Limitation is that replaced path part must be shorter or of equal length than the length of its replacement. If that is not the case either @@ -892,8 +927,12 @@ Debuginfo RPM packaging has its own set of variables: Directories containing sources that should be excluded from debuginfo packages. - * Mandatory : NO - * Default : "/usr /usr/src /usr/src/debug" + :Mandatory: No + :Default: + The following paths are excluded by default: + - ``/usr`` + - ``/usr/src`` + - ``/usr/src/debug`` Listed paths are owned by other RPM packages and should therefore not be deleted on debuginfo package uninstallation. @@ -903,8 +942,8 @@ Debuginfo RPM packaging has its own set of variables: Paths that should be appended to :variable:`CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS` for exclusion. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: .. variable:: CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE @@ -912,8 +951,8 @@ Debuginfo RPM packaging has its own set of variables: Create a single debuginfo package even if components packaging is set. - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` When this variable is enabled it produces a single debuginfo package even if component packaging is enabled. @@ -935,8 +974,8 @@ Debuginfo RPM packaging has its own set of variables: Debuginfo package file name. - * Mandatory : NO - * Default : rpmbuild tool generated package file name + :Mandatory: No + :Default: rpmbuild tool generated package file name Alternatively provided debuginfo package file name must end with ``.rpm`` suffix and should differ from file names of other generated packages. @@ -1003,8 +1042,8 @@ Source RPM packaging has its own set of variables: Should the content be packaged as a source rpm (default is binary rpm). - * Mandatory : NO - * Default : OFF + :Mandatory: No + :Default: ``OFF`` .. note:: @@ -1016,27 +1055,29 @@ Source RPM packaging has its own set of variables: Additional command-line parameters provided to :manual:`cmake(1)` executable. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: .. variable:: CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX Packaging install prefix that would be provided in :variable:`CPACK_PACKAGING_INSTALL_PREFIX` variable for producing binary RPM packages. - * Mandatory : YES - * Default : "/" + :Mandatory: Yes + :Default: ``/`` .. variable:: CPACK_RPM_BUILDREQUIRES List of source rpm build dependencies. - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to set source RPM build dependencies (BuildRequires). Note that you must enclose the complete build requirements string between quotes, for - example:: + example: + + .. code-block:: cmake set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8") @@ -1044,11 +1085,13 @@ Source RPM packaging has its own set of variables: .. versionadded:: 3.22 - * Mandatory : NO - * Default : - + :Mandatory: No + :Default: May be used to keep the dependency generator from scanning specific files or directories for dependencies. Note that you can use a regular - expression that matches all of the directories or files, for example:: + expression that matches all of the directories or files, for example: + + .. code-block:: cmake set(CPACK_RPM_REQUIRES_EXCLUDE_FROM "bin/libqsqloci.*\\.so.*") diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index 03eb0762b5..c7581e85cc 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst @@ -18,12 +18,37 @@ C++20 Module APIs ================= Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` -Value: ``3c375311-a3c9-4396-a187-3227ef642046`` +Value: ``2182bf5c-ef0d-489a-91da-49dbc3090d2a`` In order to support C++20 modules, there are a number of behaviors that have CMake APIs to provide the required features to build and export them from a project. +Limitations +----------- + +There are a number of known limitations of the current C++20 module support in +CMake. This does not document known limitations or bugs in compilers as these +can change over time. + +For all generators: + +- Only in-project modules may be used. While there is some support for + exporting module information, there is no mechanism for using it at the + moment. + +For the Ninja Generators: + +- ``ninja`` 1.10 or newer is required. + +For the Visual Studio Generators: + +- Only Visual Studio 2022 and toolchains newer than 19.34 (Visual Studio + 17.4). +- No support for exporting or installing BMI or module information. +- No diagnosis of using modules provided by ``PRIVATE`` sources from + ``PUBLIC`` module sources. + C++20 Module Dependencies ========================= @@ -32,17 +57,36 @@ dependency scanning. This is similar to the Fortran modules support, but relies on external tools to scan C++20 translation units for module dependencies. The approach is described by Kitware's `D1483r1`_ paper. -The ``CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP`` variable can be set to ``1`` -in order to activate this undocumented experimental infrastructure. This -is **intended to make the functionality available to compiler writers** so -they can use it to develop and test their dependency scanning tool. -The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` variable must also be set -to tell CMake how to invoke the C++20 module dependency scanning tool. +In order to activate CMake's experimental support for C++20 module +dependencies, set the following variables: -MSVC 19.34 (provided with Visual Studio 17.4) and above contains the support -that CMake needs and has these variables already set up as required and only -the UUID and the ``CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP`` variables need to be -set. +``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + Set this to the UUID documented above. + +``CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP`` + Set this to ``1`` in order to activate this undocumented experimental + infrastructure. This is **intended to make the functionality available + to compiler writers** so they can use it to develop and test their + dependency scanning tool. + +Some compilers already have support for module dependency scanning: + +* MSVC 19.34 and newer (provided with Visual Studio 17.4 and newer) +* LLVM/Clang 16.0 and newer + +For those, only the above variables need to be set by project code. +For compilers with in-development support, additional variables must +be set as follows. + +``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` + Set this to tell CMake how to invoke the C++20 module dependency + scanning tool. + +``CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FORMAT`` + Set this for compilers that generate module maps. See below. + +``CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG`` + Set this for compilers that generate module maps. See below. For example, add code like the following to a test project: @@ -77,9 +121,9 @@ For compilers that generate module maps, tell CMake as follows: set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG "${compiler_flags_for_module_map} -fmodule-mapper=<MODULE_MAP_FILE>") -Currently, the only supported formats are ``gcc`` and ``msvc``. The ``gcc`` -format is described in the GCC documentation, but the relevant section for the -purposes of CMake is: +Currently, the only supported formats are, ``clang``, ``gcc``, and ``msvc``. +The ``gcc`` format is described in the GCC documentation, but the relevant +section for the purposes of CMake is: A mapping file consisting of space-separated module-name, filename pairs, one per line. Only the mappings for the direct imports and any @@ -94,6 +138,9 @@ The ``msvc`` format is a response file containing flags required to compile any module interfaces properly as well as find any required files to satisfy ``import`` statements as required for Microsoft's Visual Studio toolchains. +Similarly, the ``clang`` format is a response file containing flags using +Clang's module flags. + .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html .. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 53be91f005..de19aa8fee 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -345,6 +345,7 @@ policies added for that version. Commit with a message such as:: Update the ``cmake_minimum_required`` version range in CMake itself: * ``CMakeLists.txt`` +* ``Source/Checks/Curses/CMakeLists.txt`` * ``Utilities/Doxygen/CMakeLists.txt`` * ``Utilities/Sphinx/CMakeLists.txt`` diff --git a/Help/dev/source.rst b/Help/dev/source.rst index f488b3e1af..68ca7436ce 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -9,7 +9,7 @@ See documentation on `CMake Development`_ for more information. C++ Code Style ============== -We use `clang-format`_ version **6.0** to define our style for C++ code in +We use `clang-format`_ version **15** to define our style for C++ code in the CMake source tree. See the `.clang-format`_ configuration file for our style settings. Use the `Utilities/Scripts/clang-format.bash`_ script to format source code. It automatically runs ``clang-format`` on the set of diff --git a/Help/envvar/ASM_DIALECT.rst b/Help/envvar/ASM_DIALECT.rst index c89515ee44..11dbe5aceb 100644 --- a/Help/envvar/ASM_DIALECT.rst +++ b/Help/envvar/ASM_DIALECT.rst @@ -4,8 +4,14 @@ ASM<DIALECT> .. include:: ENV_VAR.txt Preferred executable for compiling a specific dialect of assembly language -files. ``ASM<DIALECT>`` can be ``ASM``, ``ASM_NASM`` (Netwide Assembler), -``ASM_MASM`` (Microsoft Assembler) or ``ASM-ATT`` (Assembler AT&T). +files. ``ASM<DIALECT>`` can be one of: + +* ``ASM`` +* ``ASM_NASM`` (Netwide Assembler) +* ``ASM_MASM`` (Microsoft Assembler) +* ``ASM_MARMASM`` (Microsoft ARM Assembler) +* ``ASM-ATT`` (Assembler AT&T) + Will only be used by CMake on the first configuration to determine ``ASM<DIALECT>`` compiler, after which the value for ``ASM<DIALECT>`` is stored in the cache as diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst index 2af4b58576..f13efbb96e 100644 --- a/Help/envvar/ASM_DIALECTFLAGS.rst +++ b/Help/envvar/ASM_DIALECTFLAGS.rst @@ -9,6 +9,7 @@ of an assembly language. ``ASM<DIALECT>FLAGS`` can be one of: * ``ASMFLAGS`` * ``ASM_NASMFLAGS`` * ``ASM_MASMFLAGS`` +* ``ASM_MARMASMFLAGS`` * ``ASM-ATTFLAGS`` .. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>` diff --git a/Help/envvar/CTEST_NO_TESTS_ACTION.rst b/Help/envvar/CTEST_NO_TESTS_ACTION.rst new file mode 100644 index 0000000000..2bc86dc6cd --- /dev/null +++ b/Help/envvar/CTEST_NO_TESTS_ACTION.rst @@ -0,0 +1,14 @@ +CTEST_NO_TESTS_ACTION +--------------------- + +.. versionadded:: 3.26 + +.. include:: ENV_VAR.txt + +Environment variable that controls how :manual:`ctest <ctest(1)>` handles +cases when there are no tests to run. Possible values are: ``error``, +``ignore``, empty or unset. + +The :option:`--no-tests=\<action\> <ctest --no-tests>` option to +:manual:`ctest <ctest(1)>` overrides this environment variable if both +are given. diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst index 0cdd3847a9..fa8c385f4c 100644 --- a/Help/envvar/PackageName_ROOT.rst +++ b/Help/envvar/PackageName_ROOT.rst @@ -7,10 +7,10 @@ Calls to :command:`find_package(<PackageName>)` will search in prefixes specified by the ``<PackageName>_ROOT`` environment variable, where -``<PackageName>`` is the name given to the :command:`find_package` call -and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search -prefixes specified in the ``Foo_ROOT`` environment variable (if set). -See policy :policy:`CMP0074`. +``<PackageName>`` is the (case-preserved) name given to the +:command:`find_package` call and ``_ROOT`` is literal. +For example, ``find_package(Foo)`` will search prefixes specified in the +``Foo_ROOT`` environment variable (if set). See policy :policy:`CMP0074`. This variable may hold a single prefix or a list of prefixes separated by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst index 2cf823ac3b..f50bb55635 100644 --- a/Help/generator/Ninja Multi-Config.rst +++ b/Help/generator/Ninja Multi-Config.rst @@ -106,14 +106,14 @@ If either ``OUTPUT`` or ``BYPRODUCTS`` names a path that is common to more than one configuration (e.g. it does not use any generator expressions), all arguments are evaluated in the command config by default. If all ``OUTPUT`` and ``BYPRODUCTS`` paths are unique to each configuration -(e.g. by using the ``$<CONFIG>`` generator expression), the first argument of +(e.g. by using the :genex:`$<CONFIG>` generator expression), the first argument of ``COMMAND`` is still evaluated in the command config by default, while all subsequent arguments, as well as the arguments to ``DEPENDS`` and ``WORKING_DIRECTORY``, are evaluated in the output config. These defaults can -be overridden with the ``$<OUTPUT_CONFIG:...>`` and ``$<COMMAND_CONFIG:...>`` +be overridden with the :genex:`$<OUTPUT_CONFIG:...>` and :genex:`$<COMMAND_CONFIG:...>` generator-expressions. Note that if a target is specified by its name in ``DEPENDS``, or as the first argument of ``COMMAND``, it is always evaluated -in the command config, even if it is wrapped in ``$<OUTPUT_CONFIG:...>`` +in the command config, even if it is wrapped in :genex:`$<OUTPUT_CONFIG:...>` (because its plain name is not a generator expression). As an example, consider the following: @@ -122,8 +122,15 @@ As an example, consider the following: add_custom_command( OUTPUT "$<CONFIG>.txt" - COMMAND generator "$<CONFIG>.txt" "$<OUTPUT_CONFIG:$<CONFIG>>" "$<COMMAND_CONFIG:$<CONFIG>>" - DEPENDS tgt1 "$<TARGET_FILE:tgt2>" "$<OUTPUT_CONFIG:$<TARGET_FILE:tgt3>>" "$<COMMAND_CONFIG:$<TARGET_FILE:tgt4>>" + COMMAND + generator "$<CONFIG>.txt" + "$<OUTPUT_CONFIG:$<CONFIG>>" + "$<COMMAND_CONFIG:$<CONFIG>>" + DEPENDS + tgt1 + "$<TARGET_FILE:tgt2>" + "$<OUTPUT_CONFIG:$<TARGET_FILE:tgt3>>" + "$<COMMAND_CONFIG:$<TARGET_FILE:tgt4>>" ) Assume that ``generator``, ``tgt1``, ``tgt2``, ``tgt3``, and ``tgt4`` are all @@ -144,18 +151,23 @@ the ``build-Release.ninja`` file) unless they have no ``BYPRODUCTS`` or their add_custom_command( TARGET exe POST_BUILD - COMMAND ${CMAKE_COMMAND} -E echo "Running no-byproduct command" + COMMAND + ${CMAKE_COMMAND} -E echo "Running no-byproduct command" ) add_custom_command( TARGET exe POST_BUILD - COMMAND ${CMAKE_COMMAND} -E echo "Running separate-byproduct command for $<CONFIG>" + COMMAND + ${CMAKE_COMMAND} -E echo + "Running separate-byproduct command for $<CONFIG>" BYPRODUCTS $<CONFIG>.txt ) add_custom_command( TARGET exe POST_BUILD - COMMAND ${CMAKE_COMMAND} -E echo "Running common-byproduct command for $<CONFIG>" + COMMAND + ${CMAKE_COMMAND} -E echo + "Running common-byproduct command for $<CONFIG>" BYPRODUCTS exe.txt ) diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst index 9dd50155c1..ab369d5fd0 100644 --- a/Help/generator/Xcode.rst +++ b/Help/generator/Xcode.rst @@ -41,7 +41,7 @@ Swift Support .. versionadded:: 3.4 -When using the :generator:`Xcode` generator with Xcode 6.1 or higher, +When using the ``Xcode`` generator with Xcode 6.1 or higher, one may enable the ``Swift`` language with the :command:`enable_language` command or the :command:`project`. diff --git a/Help/guide/importing-exporting/index.rst b/Help/guide/importing-exporting/index.rst index dd3efb8bb9..51a09c0368 100644 --- a/Help/guide/importing-exporting/index.rst +++ b/Help/guide/importing-exporting/index.rst @@ -563,8 +563,7 @@ include directories should be specified as relative paths to the $<INSTALL_INTERFACE:include/TgtName> ) -The ``$<INSTALL_PREFIX>`` -:manual:`generator expression <cmake-generator-expressions(7)>` may be used as +The :genex:`$<INSTALL_PREFIX>` generator expression may be used as a placeholder for the install prefix without resulting in a non-relocatable package. This is necessary if complex generator expressions are used: diff --git a/Help/guide/tutorial/Adding Export Configuration.rst b/Help/guide/tutorial/Adding Export Configuration.rst index eb14f42849..6c83276a4c 100644 --- a/Help/guide/tutorial/Adding Export Configuration.rst +++ b/Help/guide/tutorial/Adding Export Configuration.rst @@ -102,7 +102,7 @@ but prepended with a ``PACKAGE_`` prefix. :end-before: # generate the version file The :command:`write_basic_package_version_file` is next. This command writes -a file which is used by the "find_package" document the version and +a file which is used by :command:`find_package`, documenting the version and compatibility of the desired package. Here, we use the ``Tutorial_VERSION_*`` variables and say that it is compatible with ``AnyNewerVersion``, which denotes that this version or any higher one are compatible with the requested @@ -133,8 +133,8 @@ the following to the bottom of the top level ``CMakeLists.txt``: :caption: CMakeLists.txt :name: CMakeLists.txt-export :language: cmake - :start-after: # needs to be after the install(TARGETS ) command + :start-after: # needs to be after the install(TARGETS) command -With this export call we now generate a ``Targets.cmake``, allowing the +With this export call we now generate a ``MathFunctionsTargets.cmake``, allowing the configured ``MathFunctionsConfig.cmake`` in the build directory to be used by other projects, without needing it to be installed. diff --git a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst index 45d5976981..787e777dc4 100644 --- a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst +++ b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst @@ -4,33 +4,40 @@ Step 6: Adding Support for a Testing Dashboard Adding support for submitting our test results to a dashboard is simple. We already defined a number of tests for our project in :ref:`Testing Support <Tutorial Testing Support>`. Now we just have to run -those tests and submit them to a dashboard. To include support for dashboards -we include the :module:`CTest` module in our top-level ``CMakeLists.txt``. +those tests and submit them to CDash. -Replace: -.. literalinclude:: Step6/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-enable_testing-remove - :language: cmake - :start-after: # enable testing - :end-before: # does the application run +Exercise 1 - Send Results to a Testing Dashboard +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -With: +Goal +---- -.. literalinclude:: Step7/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-include-CTest - :language: cmake - :start-after: # enable testing - :end-before: # does the application run +Display our CTest results with CDash. + +Helpful Resources +----------------- + +* :manual:`ctest(1)` +* :command:`include` +* :module:`CTest` + +Files to Edit +------------- -The :module:`CTest` module will automatically call ``enable_testing()``, so we -can remove it from our CMake files. +* ``CMakeLists.txt`` + +Getting Started +--------------- + +For this exercise, complete ``TODO 1`` in the top-level ``CMakeLists.txt`` by +including the :module:`CTest` module. This will enable testing with CTest as +well as dashboard submissions to CDash, so we can safely remove the call to +:command:`enable_testing`. We will also need to acquire a ``CTestConfig.cmake`` file to be placed in the -top-level directory where we can specify information to CTest about the -project. It contains: +top-level directory. When run, the :manual:`ctest <ctest(1)>` executable will +read this file to gather information about the testing dashboard. It contains: * The project name @@ -41,9 +48,10 @@ project. It contains: * The URL of the CDash instance where the submission's generated documents will be sent -One has been provided for you in this directory. It would normally be -downloaded from the ``Settings`` page of the project on the CDash -instance that will host and display the test results. Once downloaded from +For this tutorial, a public dashboard server is used and its corresponding +``CTestConfig.cmake`` file is provided for you in this step's root directory. +In practice, this file would be downloaded from a project's ``Settings`` page +on the CDash instance intended to host the test results. Once downloaded from CDash, the file should not be modified locally. .. literalinclude:: Step7/CTestConfig.cmake @@ -51,11 +59,16 @@ CDash, the file should not be modified locally. :name: CTestConfig.cmake :language: cmake -The :manual:`ctest <ctest(1)>` executable will read in this file when it runs. -To create a simple dashboard you can run the :manual:`cmake <cmake(1)>` -executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project, -but do not build it yet. Instead, change directory to the binary tree, and then -run: + +Build and Run +------------- + +Note that as part of the CDash submission some information about your +development system (e.g. site name or full pathnames) may displayed publicly. + +To create a simple test dashboard, run the :manual:`cmake <cmake(1)>` +executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project +but do not build it yet. Instead, navigate to the build directory and run: .. code-block:: console @@ -70,6 +83,28 @@ type must be specified: Or, from an IDE, build the ``Experimental`` target. -The :manual:`ctest <ctest(1)>` executable will build and test the project and -submit the results to Kitware's public dashboard: +The :manual:`ctest <ctest(1)>` executable will build the project, run any +tests, and submit the results to Kitware's public dashboard: https://my.cdash.org/index.php?project=CMakeTutorial. + +Solution +-------- + +The only CMake code changed needed in this step was to enable dashboard +submissions to CDash by including the :module:`CTest` module in our top-level +``CMakeLists.txt``: + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step7/CMakeLists.txt + :caption: TODO 1: CMakeLists.txt + :name: CMakeLists.txt-include-CTest + :language: cmake + :start-after: # enable testing + :end-before: # does the application run + +.. raw:: html + + </details> diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst index ba91df47ea..b69abd2920 100644 --- a/Help/guide/tutorial/Adding System Introspection.rst +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -7,53 +7,156 @@ depends on whether or not the target platform has the ``log`` and ``exp`` functions. Of course almost every platform has these functions but for this tutorial assume that they are not common. -If the platform has ``log`` and ``exp`` then we will use them to compute the -square root in the ``mysqrt`` function. We first test for the availability of -these functions using the :module:`CheckCXXSourceCompiles` module in +Exercise 1 - Assessing Dependency Availability +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Goal +---- + +Change implementation based on available system dependencies. + +Helpful Resources +----------------- + +* :module:`CheckCXXSourceCompiles` +* :command:`target_compile_definitions` + +Files to Edit +------------- + +* ``MathFunctions/CMakeLists.txt`` +* ``MathFunctions/mysqrt.cxx`` + +Getting Started +--------------- + +The starting source code is provided in the ``Step7`` directory. In this +exercise, complete ``TODO 1`` through ``TODO 5``. + +Start by editing ``MathFunctions/CMakeLists.txt``. Include the +:module:`CheckCXXSourceCompiles` module. Then, use +``check_cxx_source_compiles`` to determine whether ``log`` and ``exp`` are +available from ``cmath``. If they are available, use +:command:`target_compile_definitions` to specify ``HAVE_LOG`` and ``HAVE_EXP`` +as compile definitions. + +In the ``MathFunctions/mysqrt.cxx``, include ``cmath``. Then, if the system has +``log`` and ``exp``, use them to compute the square root. + +Build and Run +------------- + +Make a new directory called ``Step7_build``. Run the +:manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool and run the ``Tutorial`` executable. + +This can look like the following: + +.. code-block:: console + + mkdir Step7_build + cd Step7_build + cmake ../Step7 + cmake --build . + +Which function gives better results now, ``sqrt`` or ``mysqrt``? + +Solution +-------- + +In this exercise we will use functions from the +:module:`CheckCXXSourceCompiles` module so first we must include it in ``MathFunctions/CMakeLists.txt``. -Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``, -after the call to :command:`target_include_directories`: +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> .. literalinclude:: Step8/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt + :caption: TODO 1: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-include-check_cxx_source_compiles + :language: cmake + :start-after: # does this system provide the log and exp functions? + :end-before: check_cxx_source_compiles + +.. raw:: html + + </details> + +Then test for the availability of +``log`` and ``exp`` using ``check_cxx_compiles_source``. This function +lets us try compiling simple code with the required dependency prior to +the true source code compilation. The resulting variables ``HAVE_LOG`` +and ``HAVE_EXP`` represent whether those dependencies are available. + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt + :caption: TODO 2: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-check_cxx_source_compiles :language: cmake - :start-after: # to find MathFunctions.h, while we don't. + :start-after: include(CheckCXXSourceCompiles) :end-before: # add compile definitions -If available, use :command:`target_compile_definitions` to specify +.. raw:: html + + </details> + +Next, we need to pass these CMake variables to our source code. This way, +our source code can tell what resources are available. If both ``log`` and +``exp`` are available, use :command:`target_compile_definitions` to specify ``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + .. literalinclude:: Step8/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt + :caption: TODO 3: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-target_compile_definitions :language: cmake :start-after: # add compile definitions :end-before: # install libs -If ``log`` and ``exp`` are available on the system, then we will use them to -compute the square root in the ``mysqrt`` function. Add the following code to -the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the -``#endif`` before returning the result!): +.. raw:: html -.. literalinclude:: Step8/MathFunctions/mysqrt.cxx - :caption: MathFunctions/mysqrt.cxx - :name: MathFunctions/mysqrt.cxx-ifdef - :language: c++ - :start-after: // if we have both log and exp then use them - :end-before: // do ten iterations + </details> + +Since we may be using ``log`` and ``exp``, we need to modify +``mysqrt.cxx`` to include ``cmath``. + +.. raw:: html -We will also need to modify ``mysqrt.cxx`` to include ``cmath``. + <details><summary>TODO 4: Click to show/hide answer</summary> .. literalinclude:: Step8/MathFunctions/mysqrt.cxx - :caption: MathFunctions/mysqrt.cxx + :caption: TODO 4: MathFunctions/mysqrt.cxx :name: MathFunctions/mysqrt.cxx-include-cmath :language: c++ :end-before: #include <iostream> -Run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool and run the Tutorial executable. +.. raw:: html -Which function gives better results now, ``sqrt`` or ``mysqrt``? + </details> + +If ``log`` and ``exp`` are available on the system, then use them to +compute the square root in the ``mysqrt`` function. The ``mysqrt`` function in +``MathFunctions/mysqrt.cxx`` will look as follows: + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> + +.. literalinclude:: Step8/MathFunctions/mysqrt.cxx + :caption: TODO 5: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-ifdef + :language: c++ + :start-after: // if we have both log and exp then use them + :end-before: // do ten iterations + +.. raw:: html + + </details> diff --git a/Help/guide/tutorial/Installing and Testing.rst b/Help/guide/tutorial/Installing and Testing.rst index fa13040aec..7a59fcba21 100644 --- a/Help/guide/tutorial/Installing and Testing.rst +++ b/Help/guide/tutorial/Installing and Testing.rst @@ -1,8 +1,6 @@ Step 5: Installing and Testing ============================== -.. _`Tutorial Testing Support`: - Exercise 1 - Install Rules ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -145,7 +143,7 @@ are similar. To the end of the top-level ``CMakeLists.txt`` we add: :name: TODO 3,4: CMakeLists.txt-install-TARGETS :language: cmake :start-after: # add the install targets - :end-before: # enable testing + :end-before: # TODO 1: Replace enable_testing() with include(CTest) .. raw:: html @@ -154,6 +152,8 @@ are similar. To the end of the top-level ``CMakeLists.txt`` we add: That is all that is needed to create a basic local install of the tutorial. +.. _`Tutorial Testing Support`: + Exercise 2 - Testing Support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -195,7 +195,7 @@ Build and Run ------------- Navigate to the build directory and rebuild the application. Then, run the -``ctest`` executable: :option:`ctest -N` and :option:`ctest -VV`. For +:program:`ctest` executable: :option:`ctest -N` and :option:`ctest -VV`. For multi-config generators (e.g. Visual Studio), the configuration type must be specified with the :option:`-C \<mode\> <ctest -C>` flag. For example, to run tests in Debug mode use ``ctest -C Debug -VV`` from the build directory diff --git a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst index 1c49c23a5e..7befe1d3fd 100644 --- a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst +++ b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst @@ -65,7 +65,7 @@ At this point, if you build everything, you may notice that linking fails as we are combining a static library without position independent code with a library that has position independent code. The solution to this is to explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of -SqrtLibrary to be ``True`` no matter the build type. +SqrtLibrary to be ``True`` when building shared libraries. .. literalinclude:: Step11/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt index 220ed4b646..1d8b5a6e82 100644 --- a/Help/guide/tutorial/Step12/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -94,7 +94,7 @@ install(EXPORT MathFunctionsTargets ) include(CMakePackageConfigHelpers) -# generate the config file that is includes the exports +# generate the config file that includes the exports configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" INSTALL_DESTINATION "lib/cmake/example" @@ -116,7 +116,7 @@ install(FILES ) # generate the export targets for the build tree -# needs to be after the install(TARGETS ) command +# needs to be after the install(TARGETS) command export(EXPORT MathFunctionsTargets FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt index a8f241adc1..279ddf93a3 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -42,7 +42,7 @@ target_include_directories(Tutorial PUBLIC # TODO 3: Install Tutorial in the bin directory # Hint: Use the TARGETS and DESTINATION parameters -# TODO 4: Install Tutorial.h to the include directory +# TODO 4: Install TutorialConfig.h to the include directory # Hint: Use the FILES and DESTINATION parameters # TODO 5: Enable testing @@ -61,4 +61,4 @@ target_include_directories(Tutorial PUBLIC # Hint: Use the PASS_REGULAR_EXPRESSION property with "4 is 2" # TODO 9: Add more tests. Create a function called do_test to avoid copy + -# paste. Test the following values: 4, 9, 5, 7, 25, -25 and 0.00001. +# paste. Test the following values: 4, 9, 5, 7, 25, -25 and 0.0001. diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index da9e8521e3..c11e307736 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -45,6 +45,7 @@ install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" DESTINATION include ) +# TODO 1: Replace enable_testing() with include(CTest) # enable testing enable_testing() diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt index b4724c4a10..e5bdc4da15 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt @@ -9,6 +9,26 @@ target_include_directories(MathFunctions # link our compiler flags interface library target_link_libraries(MathFunctions tutorial_compiler_flags) +# TODO 1: Include CheckCXXSourceCompiles + +# TODO 2: Use check_cxx_source_compiles with simple C++ code to verify +# availability of: +# * std::log +# * std::exp +# Store the results in HAVE_LOG and HAVE_EXP respectively. + +# Hint: Sample C++ code which uses log: +# #include <cmath> +# int main() { +# std::log(1.0); +# return 0; +# } + +# TODO 3: Conditionally on HAVE_LOG and HAVE_EXP, add private compile +# definitions "HAVE_LOG" and "HAVE_EXP" to the MathFunctions target. + +#Hint: Use target_compile_definitions() + # install libs set(installable_libs MathFunctions tutorial_compiler_flags) install(TARGETS ${installable_libs} DESTINATION lib) diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx index abe767d5ae..3d2492a648 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx @@ -1,5 +1,6 @@ #include <iostream> +// TODO 4: include cmath #include "MathFunctions.h" // a hack square root calculation using simple operations @@ -9,6 +10,14 @@ double mysqrt(double x) return 0; } + // TODO 5: If both HAVE_LOG and HAVE_EXP are defined, use the following: + //// double result = std::exp(std::log(x) * 0.5); + //// std::cout << "Computing sqrt of " << x << " to be " << result + //// << " using log and exp" << std::endl; + // else, use the existing logic. + + // Hint: Don't forget the #endif before returning the result! + double result = x; // do ten iterations @@ -20,5 +29,6 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } + return result; } diff --git a/Help/guide/using-dependencies/index.rst b/Help/guide/using-dependencies/index.rst index bb519ad135..8b270aad48 100644 --- a/Help/guide/using-dependencies/index.rst +++ b/Help/guide/using-dependencies/index.rst @@ -277,7 +277,7 @@ for more): FetchContent_Declare( Catch2 GIT_REPOSITORY https://github.com/catchorg/Catch2.git - GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4 + GIT_TAG 605a34765aa5d5ecbf476b4598a862ada971b0cc # v3.0.1 ) FetchContent_MakeAvailable(googletest Catch2) diff --git a/Help/index.rst b/Help/index.rst index fdbf847a9b..16c8f25cc5 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -57,6 +57,7 @@ Reference Manuals /manual/cmake-buildsystem.7 /manual/cmake-commands.7 /manual/cmake-compile-features.7 + /manual/cmake-configure-log.7 /manual/cmake-developer.7 /manual/cmake-env-variables.7 /manual/cmake-file-api.7 diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index cd66d51224..a09857b3a7 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -13,7 +13,7 @@ Synopsis Description =========== -The **ccmake** executable is the CMake curses interface. Project +The :program:`ccmake` executable is the CMake curses interface. Project configuration settings may be specified interactively through this GUI. Brief instructions are provided at the bottom of the terminal when the program is running. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 3c09e869e4..b9d621bafa 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -99,7 +99,7 @@ target property to create an macOS or iOS Framework Bundle. A library with the ``FRAMEWORK`` target property should also set the :prop_tgt:`FRAMEWORK_VERSION` target property. This property is typically set to the value of "A" by macOS conventions. -The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key +The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets the ``CFBundleIdentifier`` key and it uniquely identifies the bundle. .. code-block:: cmake @@ -119,7 +119,7 @@ Object Libraries The ``OBJECT`` library type defines a non-archival collection of object files resulting from compiling the given source files. The object files collection may be used as source inputs to other targets by using the syntax -``$<TARGET_OBJECTS:name>``. This is a +:genex:`$<TARGET_OBJECTS:name>`. This is a :manual:`generator expression <cmake-generator-expressions(7)>` that can be used to supply the ``OBJECT`` library content to other targets: @@ -854,7 +854,7 @@ the generator used. For example: In the presence of :prop_tgt:`IMPORTED` targets, the content of :prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also -accounted for by the above ``$<CONFIG:Debug>`` expression. +accounted for by the above :genex:`$<CONFIG:Debug>` expression. Case Sensitivity @@ -862,7 +862,7 @@ Case Sensitivity :variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are just like other variables in that any string comparisons made with their -values will be case-sensitive. The ``$<CONFIG>`` generator expression also +values will be case-sensitive. The :genex:`$<CONFIG>` generator expression also preserves the casing of the configuration as set by the user or CMake defaults. For example: @@ -887,7 +887,7 @@ For example: In contrast, CMake treats the configuration type case-insensitively when using it internally in places that modify behavior based on the configuration. -For example, the ``$<CONFIG:Debug>`` generator expression will evaluate to 1 +For example, the :genex:`$<CONFIG:Debug>` generator expression will evaluate to 1 for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or even ``DeBuG``. Therefore, you can specify configuration types in :variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 8073511a93..1e87ec6cf6 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -282,3 +282,25 @@ versions specified for each: * ``Clang``: Clang compiler 5.0+. * ``NVIDIA``: NVIDIA nvcc compiler 7.5+. + +.. _`Language Standard Flags`: + +Language Standard Flags +======================= + +In order to satisfy requirements specified by the +:command:`target_compile_features` command or the +:variable:`CMAKE_<LANG>_STANDARD` variable, CMake may pass a +language standard flag to the compiler, such as ``-std=c++11``. + +For :ref:`Visual Studio Generators`, CMake cannot precisely control +the placement of the language standard flag on the compiler command line. +For :ref:`Ninja Generators`, :ref:`Makefile Generators`, and +:generator:`Xcode`, CMake places the language standard flag just after +the language-wide flags from :variable:`CMAKE_<LANG>_FLAGS` +and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`. + +.. versionchanged:: 3.26 + The language standard flag is placed before flags specified by other + abstractions such as the :command:`target_compile_options` command. + Prior to CMake 3.26, the language standard flag was placed after them. diff --git a/Help/manual/cmake-configure-log.7.rst b/Help/manual/cmake-configure-log.7.rst new file mode 100644 index 0000000000..4d64506742 --- /dev/null +++ b/Help/manual/cmake-configure-log.7.rst @@ -0,0 +1,334 @@ +.. cmake-manual-description: CMake Configure Log + +cmake-configure-log(7) +********************** + +.. versionadded:: 3.26 + +.. only:: html + + .. contents:: + +Introduction +============ + +CMake writes a running log, known as the *configure log*, +of certain events that occur during the Configure step. +The configure log does *not* contain a log of all output, errors, +or messages printed while configuring a project. It is a log of +detailed information about specific events, such as toolchain inspection +by :command:`try_compile`, meant for use in debugging the configuration +of a build tree. + +For human use, this version of CMake writes the configure log to the file:: + + ${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml + +However, the *location and name of the log file may change* in future +versions of CMake. Tools that read the configure log should get its +location using a :ref:`configureLog <file-api configureLog>` query to +the :manual:`cmake-file-api(7)`. +See the `Log Versioning`_ section below for details. + +Log Structure +============= + +The configure log is designed to be both machine- and human-readable. + +The log file is a YAML document stream containing zero or more YAML +documents separated by document markers. Each document begins +with a ``---`` document marker line, contains a single YAML mapping +that logs events from one CMake "configure" step, and, if the configure +step finished normally, ends with a ``...`` document marker line: + +.. code-block:: yaml + + --- + events: + - + kind: "try_compile-v1" + # (other fields omitted) + - + kind: "try_compile-v1" + # (other fields omitted) + ... + +A new document is appended to the log every time CMake configures +the build tree and logs new events. + +The keys of the each document root mapping are: + +``events`` + A YAML block sequence of nodes corresponding to events logged during + one CMake "configure" step. Each event is a YAML node containing one + of the `Event Kinds`_ documented below. + +Log Versioning +-------------- + +Each of the `Event Kinds`_ is versioned independently. The set of +keys an event's log entry provides is specific to its major version. +When an event is logged, the latest version of its event kind that is +known to the running version of CMake is always written to the log. + +Tools reading the configure log must ignore event kinds and versions +they do not understand: + +* A future version of CMake may introduce a new event kind or version. + +* If an existing build tree is re-configured with a different version of + CMake, the log may contain different versions of the same event kind. + +* If :manual:`cmake-file-api(7)` queries request one or more + :ref:`configureLog <file-api configureLog>` object versions, + the log may contain multiple entries for the same event, each + with a different version of its event kind. + +IDEs should write a :manual:`cmake-file-api(7)` query requesting a +specific :ref:`configureLog <file-api configureLog>` object version, +before running CMake, and then read the configure log only as described +by the file-api reply. + +Text Block Encoding +------------------- + +In order to make the log human-readable, text blocks are always +represented using YAML literal block scalars (``|``). +Since literal block scalars do not support escaping, backslashes +and non-printable characters are encoded at the application layer: + +* ``\\`` encodes a backslash. +* ``\xXX`` encodes a byte using two hexadecimal digits, ``XX``. + +.. _`configure-log event kinds`: + +Event Kinds +=========== + +Every event kind is represented by a YAML mapping of the form: + +.. code-block:: yaml + + kind: "<kind>-v<major>" + backtrace: + - "<file>:<line> (<function>)" + checks: + - "Checking for something" + #...event-specific keys... + +The keys common to all events are: + +``kind`` + A string identifying the event kind and major version. + +``backtrace`` + A YAML block sequence reporting the call stack of CMake source + locations at which the event occurred, from most-recent to + least-recent. Each node is a string specifying one location + formatted as ``<file>:<line> (<function>)``. + +``checks`` + An optional key that is present when the event occurred with + at least one pending :command:`message(CHECK_START)`. Its value + is a YAML block sequence reporting the stack of pending checks, + from most-recent to least-recent. Each node is a string containing + a pending check message. + +Additional mapping keys are specific to each (versioned) event kind, +described below. + +.. _`message configure-log event`: + +Event Kind ``message`` +---------------------- + +The :command:`message(CONFIGURE_LOG)` command logs ``message`` events. + +There is only one ``message`` event major version, version 1. + +.. _`message-v1 event`: + +``message-v1`` Event +^^^^^^^^^^^^^^^^^^^^ + +A ``message-v1`` event is a YAML mapping: + +.. code-block:: yaml + + kind: "message-v1" + backtrace: + - "CMakeLists.txt:123 (message)" + checks: + - "Checking for something" + message: | + # ... + +The keys specific to ``message-v1`` mappings are: + +``message`` + A YAML literal block scalar containing the message text, + represented using our `Text Block Encoding`_. + +.. _`try_compile configure-log event`: + +Event Kind ``try_compile`` +-------------------------- + +The :command:`try_compile` command logs ``try_compile`` events. + +There is only one ``try_compile`` event major version, version 1. + +.. _`try_compile-v1 event`: + +``try_compile-v1`` Event +^^^^^^^^^^^^^^^^^^^^^^^^ + +A ``try_compile-v1`` event is a YAML mapping: + +.. code-block:: yaml + + kind: "try_compile-v1" + backtrace: + - "CMakeLists.txt:123 (try_compile)" + checks: + - "Checking for something" + description: "Explicit LOG_DESCRIPTION" + directories: + source: "/path/to/.../TryCompile-01234" + binary: "/path/to/.../TryCompile-01234" + cmakeVariables: + SOME_VARIABLE: "Some Value" + buildResult: + variable: "COMPILE_RESULT" + cached: true + stdout: | + # ... + exitCode: 0 + +The keys specific to ``try_compile-v1`` mappings are: + +``description`` + An optional key that is present when the ``LOG_DESCRIPTION <text>`` option + was used. Its value is a string containing the description ``<text>``. + +``directories`` + A mapping describing the directories associated with the + compilation attempt. It has the following keys: + + ``source`` + String specifying the source directory of the + :command:`try_compile` project. + + ``binary`` + String specifying the binary directory of the + :command:`try_compile` project. + For non-project invocations, this is often the same as + the source directory. + +``cmakeVariables`` + An optional key that is present when CMake propagates variables + into the test project, either automatically or due to the + :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable. + Its value is a mapping from variable names to their values. + +``buildResult`` + A mapping describing the result of compiling the test code. + It has the following keys: + + ``variable`` + A string specifying the name of the CMake variable + storing the result of trying to build the test project. + + ``cached`` + A boolean indicating whether the above result ``variable`` + is stored in the CMake cache. + + ``stdout`` + A YAML literal block scalar containing the output from building + the test project, represented using our `Text Block Encoding`_. + This contains build output from both stdout and stderr. + + ``exitCode`` + An integer specifying the build tool exit code from trying + to build the test project. + +.. _`try_run configure-log event`: + +Event Kind ``try_run`` +---------------------- + +The :command:`try_run` command logs ``try_run`` events. + +There is only one ``try_run`` event major version, version 1. + +.. _`try_run-v1 event`: + +``try_run-v1`` Event +^^^^^^^^^^^^^^^^^^^^ + +A ``try_run-v1`` event is a YAML mapping: + +.. code-block:: yaml + + kind: "try_run-v1" + backtrace: + - "CMakeLists.txt:456 (try_run)" + checks: + - "Checking for something" + description: "Explicit LOG_DESCRIPTION" + directories: + source: "/path/to/.../TryCompile-56789" + binary: "/path/to/.../TryCompile-56789" + buildResult: + variable: "COMPILE_RESULT" + cached: true + stdout: | + # ... + exitCode: 0 + runResult: + variable: "RUN_RESULT" + cached: true + stdout: | + # ... + stderr: | + # ... + exitCode: 0 + +The keys specific to ``try_run-v1`` mappings include those +documented by the `try_compile-v1 event`_, plus: + +``runResult`` + A mapping describing the result of running the test code. + It has the following keys: + + ``variable`` + A string specifying the name of the CMake variable + storing the result of trying to run the test executable. + + ``cached`` + A boolean indicating whether the above result ``variable`` + is stored in the CMake cache. + + ``stdout`` + An optional key that is present when the test project built successfully. + Its value is a YAML literal block scalar containing output from running + the test executable, represented using our `Text Block Encoding`_. + + If ``RUN_OUTPUT_VARIABLE`` was used, stdout and stderr are captured + together, so this will contain both. Otherwise, this will contain + only the stdout output. + + ``stderr`` + An optional key that is present when the test project built successfully + and the ``RUN_OUTPUT_VARIABLE`` option was not used. + Its value is a YAML literal block scalar containing output from running + the test executable, represented using our `Text Block Encoding`_. + + If ``RUN_OUTPUT_VARIABLE`` was used, stdout and stderr are captured + together in the ``stdout`` key, and this key will not be present. + Otherwise, this will contain the stderr output. + + ``exitCode`` + An optional key that is present when the test project built successfully. + Its value is an integer specifying the exit code, or a string containing + an error message, from trying to run the test executable. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 0f3c30a1c1..a09bd14529 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -560,7 +560,7 @@ The ``RELEASE`` variant should be listed first in the property so that the variant is chosen if the user uses a configuration which is not an exact match for any listed ``IMPORTED_CONFIGURATIONS``. -Most of the cache variables should be hidden in the ``ccmake`` interface unless +Most of the cache variables should be hidden in the :program:`ccmake` interface unless the user explicitly asks to edit them. .. code-block:: cmake diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 50fcf756cb..4c29b80f13 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -92,6 +92,7 @@ Environment Variables for CTest /envvar/CMAKE_CONFIG_TYPE /envvar/CTEST_INTERACTIVE_DEBUG_MODE + /envvar/CTEST_NO_TESTS_ACTION /envvar/CTEST_OUTPUT_ON_FAILURE /envvar/CTEST_PARALLEL_LEVEL /envvar/CTEST_PROGRESS_OUTPUT diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 4b8ac65035..7ff9728a5f 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -258,8 +258,8 @@ The members are: ``paths`` A JSON object specifying paths to things that come with CMake. - It has members for ``cmake``, ``ctest``, and ``cpack`` whose values - are JSON strings specifying the absolute path to each tool, + It has members for :program:`cmake`, :program:`ctest`, and :program:`cpack` + whose values are JSON strings specifying the absolute path to each tool, represented with forward slashes. It also has a ``root`` member for the absolute path to the directory containing CMake resources like the ``Modules/`` directory (see :variable:`CMAKE_ROOT`). @@ -371,7 +371,7 @@ v1 Reply Files Reply files containing specific `Object Kinds`_ are written by CMake. The names of these files are unspecified and must not be interpreted by clients. Clients must first read the `v1 Reply Index File`_ and -and follow references to the names of the desired response objects. +follow references to the names of the desired response objects. Reply files (including the index file) will never be replaced by files of the same name but different content. This allows a client @@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from { "kind": "codemodel", - "version": { "major": 2, "minor": 4 }, + "version": { "major": 2, "minor": 5 }, "paths": { "source": "/path/to/top-level-source-dir", "build": "/path/to/top-level-build-dir" @@ -1071,6 +1071,27 @@ with members: available. The value is an unsigned integer 0-based index into the ``backtraceGraph`` member's ``nodes`` array. +``fileSets`` + A JSON array of entries corresponding to the target's file sets. Each entry + is a JSON object with members: + + ``name`` + A string specifying the name of the file set. + + ``type`` + A string specifying the type of the file set. See + :command:`target_sources` supported file set types. + + ``visibility`` + A string specifying the visibility of the file set; one of ``PUBLIC``, + ``PRIVATE``, or ``INTERFACE``. + + ``baseDirectories`` + A JSON array of strings specifying the base directories containing sources + in the file set. + + This field was added in codemodel version 2.5. + ``sources`` A JSON array of entries corresponding to the target's source files. Each entry is a JSON object with members: @@ -1096,6 +1117,13 @@ with members: Optional member that is present with boolean value ``true`` if the source is :prop_sf:`GENERATED`. + ``fileSetIndex`` + Optional member that is present when the source is part of a file set. + The value is an unsigned integer 0-based index into the ``fileSets`` + array. + + This field was added in codemodel version 2.5. + ``backtrace`` Optional member that is present when a CMake language backtrace to the :command:`target_sources`, :command:`add_executable`, @@ -1270,6 +1298,45 @@ elsewhere in the containing object. The backtrace graph object members are: directory then the path is specified relative to that directory. Otherwise the path is absolute. +.. _`file-api configureLog`: + +Object Kind "configureLog" +-------------------------- + +The ``configureLog`` object kind describes the location and contents of +a :manual:`cmake-configure-log(7)` file. + +There is only one ``configureLog`` object major version, version 1. + +"configureLog" version 1 +^^^^^^^^^^^^^^^^^^^^^^^^ + +``configureLog`` object version 1 is a JSON object: + +.. code-block:: json + + { + "kind": "configureLog", + "version": { "major": 1, "minor": 0 }, + "path": "/path/to/top-level-build-dir/CMakeFiles/CMakeConfigureLog.yaml", + "eventKindNames": [ "try_compile-v1", "try_run-v1" ] + } + +The members specific to ``configureLog`` objects are: + +``path`` + A string specifying the path to the configure log file. + Clients must read the log file from this path, which may be + different than the path documented by :manual:`cmake-configure-log(7)`. + The log file may not exist if no events are logged. + +``eventKindNames`` + A JSON array whose entries are each a JSON string naming one + of the :manual:`cmake-configure-log(7)` versioned event kinds. + At most one version of each configure log event kind will be listed. + Although the configure log may contain other (versioned) event kinds, + clients must ignore those that are not listed in this field. + Object Kind "cache" ------------------- diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 69e3f20e56..c3e87d77c9 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -142,9 +142,9 @@ to generate debug messages is to add a custom target: add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") -After running ``cmake``, you can then build the ``genexdebug`` target to print +After running :program:`cmake`, you can then build the ``genexdebug`` target to print the result of the ``$<...>`` expression (i.e. run the command -``cmake --build ... --target genexdebug``). +:option:`cmake --build ... --target genexdebug <cmake--build --target>`). Another way is to write debug messages to a file with :command:`file(GENERATE)`: @@ -1401,6 +1401,13 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. + .. versionchanged:: 3.26 + When encountered during evaluation of :ref:`Target Usage Requirements`, + typically in an ``INTERFACE_*`` target property, lookup of the ``tgt`` + name occurs in the directory of the target specifying the requirement, + rather than the directory of the consuming target for which the + expression is being evaluated. + .. genex:: $<TARGET_PROPERTY:prop> Value of the property ``prop`` on the target for which the expression @@ -1666,8 +1673,8 @@ In the following, the phrase "the ``tgt`` filename" means the name of the **On non-DLL platforms, this expression always evaluates to an empty string**. This generator expression can be used to copy all of the DLLs that a target - depends on into its output directory in a ``POST_BUILD`` custom command. For - example: + depends on into its output directory in a ``POST_BUILD`` custom command using + the :option:`cmake -E copy -t <cmake-E copy>` command. For example: .. code-block:: cmake @@ -1676,7 +1683,7 @@ In the following, the phrase "the ``tgt`` filename" means the name of the add_executable(exe main.c) target_link_libraries(exe PRIVATE foo::foo foo::bar) add_custom_command(TARGET exe POST_BUILD - COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> + COMMAND ${CMAKE_COMMAND} -E copy -t $<TARGET_FILE_DIR:exe> $<TARGET_RUNTIME_DLLS:exe> COMMAND_EXPAND_LISTS ) @@ -1689,6 +1696,9 @@ In the following, the phrase "the ``tgt`` filename" means the name of the section for details. Many :ref:`Find Modules` produce imported targets with the ``UNKNOWN`` type and therefore will be ignored. +On platforms that support runtime paths (``RPATH``), refer to the +:prop_tgt:`INSTALL_RPATH` target property. +On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property. Export And Install Expressions ------------------------------ @@ -1704,6 +1714,13 @@ Export And Install Expressions when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. +.. genex:: $<BUILD_LOCAL_INTERFACE:...> + + .. versionadded:: 3.26 + + Content of ``...`` when the target is used by another target in the same + buildsystem. Expands to the empty string otherwise. + .. genex:: $<INSTALL_PREFIX> Content of the install prefix when the target is exported via diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index dd0eecab39..cdb860f3ff 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -16,7 +16,7 @@ Synopsis Description =========== -The **cmake-gui** executable is the CMake GUI. Project configuration +The :program:`cmake-gui` executable is the CMake GUI. Project configuration settings may be specified interactively. Brief instructions are provided at the bottom of the window when the program is running. diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 0bd561f42c..d0774cb989 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -37,10 +37,10 @@ Scripts An individual ``<script>.cmake`` source file may be processed in *script mode* by using the :manual:`cmake(1)` command-line tool -with the ``-P`` option. Script mode simply runs the commands in -the given CMake Language source file and does not generate a -build system. It does not allow CMake commands that define build -targets or actions. +with the :option:`-P <cmake -P>` option. Script mode simply runs +the commands in the given CMake Language source file and does not +generate a build system. It does not allow CMake commands that +define build targets or actions. Modules ------- @@ -206,7 +206,7 @@ enclosed content, such as `Escape Sequences`_ or `Variable References`_, is performed. A bracket argument is always given to the command invocation as exactly one argument. -.. No code-block syntax highlighting in the following example +.. ATTENTION No code-block syntax highlighting in the following example (long string literal not supported by our cmake.py) For example:: @@ -254,7 +254,7 @@ closing quotes. Both `Escape Sequences`_ and `Variable References`_ are evaluated. A quoted argument is always given to the command invocation as exactly one argument. -.. No code-block syntax highlighting in the following example +.. ATTENTION No code-block syntax highlighting in the following example (escape \" not supported by our cmake.py) For example: @@ -268,7 +268,7 @@ For example: It does end in an unescaped double quote. ") -.. No code-block syntax highlighting in the following example +.. ATTENTION No code-block syntax highlighting in the following example (for conformity with the two above examples) The final ``\`` on any line ending in an odd number of backslashes @@ -530,6 +530,9 @@ of alphanumeric characters plus ``_`` and ``-``. Variables have dynamic scope. Each variable "set" or "unset" creates a binding in the current scope: +Block Scope + The :command:`block` command may create a new scope for variable bindings. + Function Scope `Command Definitions`_ created by the :command:`function` command create commands that, when invoked, process the recorded commands @@ -542,8 +545,8 @@ Directory Scope bindings. Before processing the ``CMakeLists.txt`` file for a directory, CMake copies all variable bindings currently defined in the parent directory, if any, to initialize the new directory - scope. CMake `Scripts`_, when processed with ``cmake -P``, bind - variables in one "directory" scope. + scope. CMake `Scripts`_, when processed with :option:`cmake -P`, + bind variables in one "directory" scope. A variable "set" or "unset" not inside a function call binds to the current directory scope. @@ -597,11 +600,11 @@ Initialization Changed values are not written back to the calling process, and they are not seen by subsequent build or test processes. - See the :ref:`cmake -E env <Run a Command-Line Tool>` command-line + See the :option:`cmake -E env <cmake-E env>` command-line tool to run a command in a modified environment. Inspection - See the :ref:`cmake -E environment <Run a Command-Line Tool>` command-line + See the :option:`cmake -E environment <cmake-E environment>` command-line tool to display all current environment variables. The :manual:`cmake-env-variables(7)` manual documents environment diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index d161a284f0..448d8ba56e 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -161,7 +161,6 @@ They are normally called through the :command:`find_package` command. /module/FindICU /module/FindImageMagick /module/FindIntl - /module/FindITK /module/FindJasper /module/FindJava /module/FindJNI @@ -252,8 +251,6 @@ They are normally called through the :command:`find_package` command. /module/FindTclStub /module/FindThreads /module/FindTIFF - /module/FindUnixCommands - /module/FindVTK /module/FindVulkan /module/FindWget /module/FindWish @@ -296,9 +293,12 @@ Deprecated Find Modules :maxdepth: 1 /module/FindCUDA + /module/FindITK /module/FindPythonInterp /module/FindPythonLibs /module/FindQt + /module/FindUnixCommands + /module/FindVTK /module/FindwxWindows Legacy CPack Modules diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index d6a30ffd06..22e9eb2b6d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,13 @@ 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.26 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0143: USE_FOLDERS global property is treated as ON by default. </policy/CMP0143> Policies Introduced by CMake 3.25 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index b17be82395..fb84f5ae2d 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -77,8 +77,6 @@ Properties on Directories /prop_dir/IMPORTED_TARGETS /prop_dir/INCLUDE_DIRECTORIES /prop_dir/INCLUDE_REGULAR_EXPRESSION - /prop_dir/INTERPROCEDURAL_OPTIMIZATION - /prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_dir/LABELS /prop_dir/LINK_DIRECTORIES /prop_dir/LINK_OPTIONS @@ -195,6 +193,7 @@ Properties on Targets /prop_tgt/CXX_MODULE_SET /prop_tgt/CXX_MODULE_SET_NAME /prop_tgt/CXX_MODULE_SETS + /prop_tgt/CXX_SCAN_FOR_MODULES /prop_tgt/CXX_STANDARD /prop_tgt/CXX_STANDARD_REQUIRED /prop_tgt/DEBUG_POSTFIX @@ -300,6 +299,7 @@ Properties on Targets /prop_tgt/JOB_POOL_PRECOMPILE_HEADER /prop_tgt/LABELS /prop_tgt/LANG_CLANG_TIDY + /prop_tgt/LANG_CLANG_TIDY_EXPORT_FIXES_DIR /prop_tgt/LANG_COMPILER_LAUNCHER /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT @@ -533,6 +533,7 @@ Properties on Source Files /prop_sf/COMPILE_DEFINITIONS /prop_sf/COMPILE_FLAGS /prop_sf/COMPILE_OPTIONS + /prop_sf/CXX_SCAN_FOR_MODULES /prop_sf/EXTERNAL_OBJECT /prop_sf/Fortran_FORMAT /prop_sf/Fortran_PREPROCESS @@ -618,6 +619,8 @@ Deprecated Properties on Directories /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES /prop_dir/COMPILE_DEFINITIONS_CONFIG + /prop_dir/INTERPROCEDURAL_OPTIMIZATION + /prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_dir/TEST_INCLUDE_FILE diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index cd46615ec3..23d8256622 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -131,6 +131,7 @@ Variables that Provide Information /variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER /variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION + /variable/CMAKE_VS_VERSION_BUILD_NUMBER /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_BUILD_SYSTEM @@ -417,6 +418,7 @@ Variables that Control the Build /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS /variable/CMAKE_CUDA_RUNTIME_LIBRARY /variable/CMAKE_CUDA_SEPARABLE_COMPILATION + /variable/CMAKE_CXX_SCAN_FOR_MODULES /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_DEFAULT_BUILD_TYPE /variable/CMAKE_DEFAULT_CONFIGS @@ -449,6 +451,7 @@ Variables that Control the Build /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_CLANG_TIDY + /variable/CMAKE_LANG_CLANG_TIDY_EXPORT_FIXES_DIR /variable/CMAKE_LANG_COMPILER_LAUNCHER /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index b31ad118af..e48ecd972d 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -39,20 +39,20 @@ Synopsis Description =========== -The **cmake** executable is the command-line interface of the cross-platform +The :program:`cmake` executable is the command-line interface of the cross-platform buildsystem generator CMake. The above `Synopsis`_ lists various actions the tool can perform as described in sections below. To build a software project with CMake, `Generate a Project Buildsystem`_. -Optionally use **cmake** to `Build a Project`_, `Install a Project`_ or just -run the corresponding build tool (e.g. ``make``) directly. **cmake** can also +Optionally use :program:`cmake` to `Build a Project`_, `Install a Project`_ or just +run the corresponding build tool (e.g. ``make``) directly. :program:`cmake` can also be used to `View Help`_. The other actions are meant for use by software developers writing scripts in the :manual:`CMake language <cmake-language(7)>` to support their builds. -For graphical user interfaces that may be used in place of **cmake**, +For graphical user interfaces that may be used in place of :program:`cmake`, see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`. For command-line interfaces to the CMake testing and packaging facilities, see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`. @@ -193,7 +193,7 @@ build tool to build the project. For example, after using the $ make $ make install -Alternatively, one may use **cmake** to `Build a Project`_ by +Alternatively, one may use :program:`cmake` to `Build a Project`_ by automatically choosing and invoking the appropriate native build tool. .. _`CMake Options`: @@ -362,9 +362,8 @@ Options separated by a newline ( ``\n`` ). It is guaranteed that no newline characters will be present inside a JSON document. - JSON trace format: - .. code-block:: json + :caption: JSON trace format { "file": "/full/path/to/the/CMake/file.txt", @@ -417,9 +416,8 @@ Options Additionally, the first JSON document outputted contains the ``version`` key for the current major and minor version of the - JSON trace format: - .. code-block:: json + :caption: JSON version format { "version": { @@ -850,17 +848,21 @@ Available commands are: .. program:: cmake-E -.. option:: copy <file>... <destination> +.. option:: copy <file>... <destination>, copy -t <destination> <file>... Copy files to ``<destination>`` (either file or directory). - If multiple files are specified, the ``<destination>`` must be - directory and it must exist. Wildcards are not supported. - ``copy`` does follow symlinks. That means it does not copy symlinks, - but the files or directories it point to. + If multiple files are specified, or if ``-t`` is specified, the + ``<destination>`` must be directory and it must exist. If ``-t`` is not + specified, the last argument is assumed to be the ``<destination>``. + Wildcards are not supported. ``copy`` does follow symlinks. That means it + does not copy symlinks, but the files or directories it point to. .. versionadded:: 3.5 Support for multiple input files. + .. versionadded:: 3.26 + Support for ``-t`` argument. + .. option:: copy_directory <dir>... <destination> Copy content of ``<dir>...`` directories to ``<destination>`` directory. @@ -874,6 +876,16 @@ Available commands are: The command now fails when the source directory does not exist. Previously it succeeded by creating an empty destination directory. +.. option:: copy_directory_if_different <dir>... <destination> + + .. versionadded:: 3.26 + + Copy changed content of ``<dir>...`` directories to ``<destination>`` directory. + If ``<destination>`` directory does not exist it will be created. + + ``copy_directory_if_different`` does follow symlinks. + The command fails when the source directory does not exist. + .. option:: copy_if_different <file>... <destination> Copy files to ``<destination>`` (either file or directory) if @@ -939,7 +951,7 @@ Available commands are: The ``NAME=VALUE`` and ``--unset=NAME`` options are equivalent to ``--modify NAME=set:VALUE`` and ``--modify NAME=unset:``, respectively. Note that ``--modify NAME=reset:`` resets ``NAME`` to the value it had - when ``cmake`` launched (or unsets it), not to the most recent + when :program:`cmake` launched (or unsets it), not to the most recent ``NAME=VALUE`` option. .. option:: -- @@ -1068,10 +1080,6 @@ Available commands are: situations instead. Use ``--`` to stop interpreting options and treat all remaining arguments as paths, even if they start with ``-``. -.. option:: server - - Launch :manual:`cmake-server(7)` mode. - .. option:: sleep <number>... .. versionadded:: 3.0 @@ -1319,7 +1327,7 @@ To view the presets available for a project, use Return Value (Exit Code) ======================== -Upon regular termination, the ``cmake`` executable returns the exit code ``0``. +Upon regular termination, the :program:`cmake` executable returns the exit code ``0``. If termination is caused by the command :command:`message(FATAL_ERROR)`, or another error condition, then a non-zero exit code is returned. diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 3f26d728e5..1a101a4d56 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -13,10 +13,10 @@ Synopsis Description =========== -The **cpack** executable is the CMake packaging program. It generates +The :program:`cpack` executable is the CMake packaging program. It generates installers and source packages in a variety of formats. -For each installer or package format, **cpack** has a specific backend, +For each installer or package format, :program:`cpack` has a specific backend, called "generator". A generator is responsible for generating the required inputs and invoking the specific package creation tools. These installer or package generators are not to be confused with the makefile generators @@ -28,7 +28,7 @@ list of generators supported for the target platform. Which of them are to be used can be selected through the :variable:`CPACK_GENERATOR` variable or through the command-line option :option:`-G <cpack -G>`. -The **cpack** program is steered by a configuration file written in the +The :program:`cpack` program is steered by a configuration file written in the :manual:`CMake language <cmake-language(7)>`. Unless chosen differently through the command-line option :option:`--config <cpack --config>`, the file ``CPackConfig.cmake`` in the current directory is used. @@ -45,7 +45,7 @@ Options .. option:: -G <generators> ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>` - of generator names. ``cpack`` will iterate through this list and produce + of generator names. :program:`cpack` will iterate through this list and produce package(s) in that generator's format according to the details provided in the ``CPackConfig.cmake`` configuration file. If this option is not given, the :variable:`CPACK_GENERATOR` variable determines the default set of @@ -58,30 +58,30 @@ Options :ref:`semicolon-separated list <CMake Language Lists>`. When the CMake project uses a multi-configuration generator such as Xcode or Visual Studio, this option is needed to tell - ``cpack`` which built executables to include in the package. + :program:`cpack` which built executables to include in the package. The user is responsible for ensuring that the configuration(s) listed - have already been built before invoking ``cpack``. + have already been built before invoking :program:`cpack`. .. option:: -D <var>=<value> Set a CPack variable. This will override any value set for ``<var>`` in the - input file read by ``cpack``. + input file read by :program:`cpack`. .. option:: --config <configFile> - Specify the configuration file read by ``cpack`` to provide the packaging + Specify the configuration file read by :program:`cpack` to provide the packaging details. By default, ``CPackConfig.cmake`` in the current directory will be used. .. option:: -V, --verbose - Run ``cpack`` with verbose output. This can be used to show more details + Run :program:`cpack` with verbose output. This can be used to show more details from the package generation tools and is suitable for project developers. .. option:: --debug - Run ``cpack`` with debug output. This option is intended mainly for the - developers of ``cpack`` itself and is not normally needed by project + Run :program:`cpack` with debug output. This option is intended mainly for the + developers of :program:`cpack` itself and is not normally needed by project developers. .. option:: --trace diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 3497a9fc17..5e82faae0d 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -32,7 +32,7 @@ Synopsis Description =========== -The **ctest** executable is the CMake test driver program. +The :program:`ctest` executable is the CMake test driver program. CMake-generated build trees created for projects that use the :command:`enable_testing` and :command:`add_test` commands have testing support. This program will run the tests and report results. @@ -69,7 +69,7 @@ Run Tests Enable short progress output from tests. - When the output of **ctest** is being sent directly to a terminal, the + When the output of :program:`ctest` is being sent directly to a terminal, the progress through the set of tests is reported by updating the same line rather than printing start and end messages for each test on new lines. This can significantly reduce the verbosity of the test output. @@ -137,7 +137,7 @@ Run Tests :ref:`resource specification file <ctest-resource-specification-file>` specified in ``<file>``. - When ``ctest`` is run as a `Dashboard Client`_ this sets the + When :program:`ctest` is run as a `Dashboard Client`_ this sets the ``ResourceSpecFile`` option of the `CTest Test Step`_. .. option:: --test-load <level> @@ -146,7 +146,7 @@ Run Tests not to start tests when they may cause the CPU load to pass above a given threshold. - When ``ctest`` is run as a `Dashboard Client`_ this sets the + When :program:`ctest` is run as a `Dashboard Client`_ this sets the ``TestLoad`` option of the `CTest Test Step`_. .. option:: -Q, --quiet @@ -435,6 +435,11 @@ Run Tests unifies the behavior of CTest by either returning an error code if no tests were found or by ignoring it. + .. versionadded:: 3.26 + + This option can also be set by setting the :envvar:`CTEST_NO_TESTS_ACTION` + environment variable. + View Help ========= @@ -473,7 +478,7 @@ with the following labels: * *test4* has label *wednesday* * *test5* has labels *friday* and *test* -Running ``ctest`` with ``-L tuesday -L test`` will select *test2*, which has +Running :program:`ctest` with ``-L tuesday -L test`` will select *test2*, which has both labels. Running CTest with ``-L test`` will select *test2* and *test5*, because both of them have a label that matches that regular expression. @@ -832,7 +837,7 @@ Dashboard Client via CTest Command-Line --------------------------------------- CTest can perform testing on an already-generated build tree. -Run the ``ctest`` command with the current working directory set +Run the :program:`ctest` command with the current working directory set to the build tree and use one of these signatures:: ctest -D <mode>[<step>] @@ -865,7 +870,7 @@ Dashboard Client via CTest Script CTest can perform testing driven by a :manual:`cmake-language(7)` script that creates and maintains the source and build tree as -well as performing the testing steps. Run the ``ctest`` command +well as performing the testing steps. Run the :program:`ctest` command with the current working directory set outside of any build tree and use one of these signatures:: @@ -1142,7 +1147,7 @@ Configuration settings include: When the build system to be launched allows build-time selection of the configuration (e.g. ``Debug``, ``Release``), this specifies the default configuration to be built when no :option:`-C <ctest -C>` - option is given to the ``ctest`` command. The value will be substituted + option is given to the :program:`ctest` command. The value will be substituted into the value of ``MakeCommand`` to replace the literal string ``${CTEST_CONFIGURATION_TYPE}`` if it appears. @@ -1624,7 +1629,7 @@ resource allocation feature. Tests should check the resource allocation is activated. This variable will always (and only) be defined if resource allocation is activated. If resource allocation is not activated, then the ``CTEST_RESOURCE_GROUP_COUNT`` variable will not exist, -even if it exists for the parent ``ctest`` process. If a test absolutely must +even if it exists for the parent :program:`ctest` process. If a test absolutely must have resource allocation, then it can return a failing exit code or use the :prop_test:`SKIP_RETURN_CODE` or :prop_test:`SKIP_REGULAR_EXPRESSION` properties to indicate a skipped test. diff --git a/Help/policy/CMP0053.rst b/Help/policy/CMP0053.rst index 9b18b2dfd0..58500d6aa1 100644 --- a/Help/policy/CMP0053.rst +++ b/Help/policy/CMP0053.rst @@ -20,7 +20,7 @@ cleaned up to simplify the behavior. Specifically: the characters ``_``, ``.``, ``/``, ``-``, and ``+``. Note that ``$`` is technically allowed in the ``NEW`` behavior, but is invalid for ``OLD`` behavior. This is due to an oversight during the - implementation of :policy:`CMP0053` and its use as a literal variable + implementation of ``CMP0053`` and its use as a literal variable reference is discouraged for this reason. Variables with other characters in their name may still be referenced indirectly, e.g. diff --git a/Help/policy/CMP0101.rst b/Help/policy/CMP0101.rst index f02bccc881..67810796f5 100644 --- a/Help/policy/CMP0101.rst +++ b/Help/policy/CMP0101.rst @@ -3,16 +3,24 @@ CMP0101 .. versionadded:: 3.17 -:command:`target_compile_options` now honors ``BEFORE`` keyword in all scopes. +:command:`target_compile_options` now always honors the ``BEFORE`` keyword. -In CMake 3.16 and below the :command:`target_compile_options` ignores the -``BEFORE`` keyword in private scope. CMake 3.17 and later honors -``BEFORE`` keyword in all scopes. This policy provides compatibility for -projects that have not been updated to expect the new behavior. +In CMake 3.16 and below, the :command:`target_compile_options` command +ignores the ``BEFORE`` keyword when inserting items into the +:prop_tgt:`COMPILE_OPTIONS` target property (``PRIVATE`` and ``PUBLIC`` +items). CMake 3.17 and later honors the ``BEFORE`` keyword in all cases. +This policy provides compatibility for projects that have not been updated +to expect the new behavior. -The ``OLD`` behavior for this policy is to not honor ``BEFORE`` keyword in -private scope. The ``NEW`` behavior of this policy is to honor -``BEFORE`` keyword in all scopes. +The behavior of inserting items into the :prop_tgt:`INTERFACE_COMPILE_OPTIONS` +target property (``PUBLIC`` and ``INTERFACE`` items) is not affected by this +policy. The ``BEFORE`` keyword has always been honored when adding items to +:prop_tgt:`INTERFACE_COMPILE_OPTIONS`. + +The ``OLD`` behavior for this policy is to not honor the ``BEFORE`` keyword +when inserting into the :prop_tgt:`COMPILE_OPTIONS` property. +The ``NEW`` behavior for this policy is to honor the ``BEFORE`` keyword in +all cases. This policy was introduced in CMake version 3.17. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. diff --git a/Help/policy/CMP0143.rst b/Help/policy/CMP0143.rst new file mode 100644 index 0000000000..24fdc27ea8 --- /dev/null +++ b/Help/policy/CMP0143.rst @@ -0,0 +1,30 @@ +CMP0143 +------- + +.. versionadded:: 3.26 + +:prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default. + +When using CMake 3.25 or earlier, :prop_gbl:`USE_FOLDERS` is treated +as ``OFF`` by default unless projects enable the feature. For example: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.25) + project(foobar LANGUAGES CXX) + set_property(GLOBAL PROPERTY USE_FOLDERS ON) + +CMake 3.26 and later prefer to enable the feature by default. + +Note that it is the policy setting at the `end` of the top level +``CMakeLists.txt`` file that matters. The policy setting applies globally +to the whole project. + +This policy provides compatibility with projects that have not been updated +to expect enabling of folders. Enabling folders causes projects to appear +differently in IDEs. The policy was introduced in CMake version 3.26. 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_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst index b6f6160997..a19cc4ee28 100644 --- a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst +++ b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst @@ -10,7 +10,7 @@ Additional files to remove during the clean stage. A :ref:`;-list <CMake Language Lists>` of files that will be removed as a part of the ``make clean`` target. -Arguments to :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` may use +Arguments to ``ADDITIONAL_MAKE_CLEAN_FILES`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. This property only works for the Makefile generators. diff --git a/Help/prop_dir/COMPILE_DEFINITIONS.rst b/Help/prop_dir/COMPILE_DEFINITIONS.rst index 18f4567c5c..5a12c1eaa0 100644 --- a/Help/prop_dir/COMPILE_DEFINITIONS.rst +++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst @@ -19,6 +19,9 @@ directory's parent. CMake will automatically drop some definitions that are not supported by the native build tool. +.. versionadded:: 3.26 + Any leading ``-D`` on an item will be removed. + .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt Contents of ``COMPILE_DEFINITIONS`` may use "generator expressions" with diff --git a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst index 0c78dfbe7f..6693a43cc7 100644 --- a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst +++ b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst @@ -1,7 +1,6 @@ INTERPROCEDURAL_OPTIMIZATION ---------------------------- -Enable interprocedural optimization for targets in a directory. +This directory property does not exist anymore. -If set to true, enables interprocedural optimizations if they are -known to be supported by the compiler. +See the target property :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` instead. diff --git a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst index 840a1dbc70..7ef1bb4490 100644 --- a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst +++ b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -1,8 +1,6 @@ INTERPROCEDURAL_OPTIMIZATION_<CONFIG> ------------------------------------- -Per-configuration interprocedural optimization for a directory. +This directory property does not exist anymore. -This is a per-configuration version of ``INTERPROCEDURAL_OPTIMIZATION``. -If set, this property overrides the generic property for the named -configuration. +See the target property :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` instead. diff --git a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst index 07c732bd47..600a64a400 100644 --- a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst +++ b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst @@ -9,7 +9,7 @@ Name of the :command:`source_group` for :prop_tgt:`AUTOMOC`, Files generated by :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` are not always known at configure time and therefore can't be passed to :command:`source_group`. -:prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used instead to generate or select +``AUTOGEN_SOURCE_GROUP`` can be used instead to generate or select a source group for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` generated files. diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst index 21da4662d2..5dfe6de33d 100644 --- a/Help/prop_gbl/JOB_POOLS.rst +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -5,8 +5,8 @@ Ninja only: List of available pools. A pool is a named integer property and defines the maximum number of concurrent jobs which can be started by a rule assigned to the pool. -The :prop_gbl:`JOB_POOLS` property is a semicolon-separated list of -pairs using the syntax NAME=integer (without a space after the equality sign). +The ``JOB_POOLS`` property is a semicolon-separated list of +pairs using the syntax ``NAME=integer`` (without a space after the equality sign). For instance: @@ -21,7 +21,7 @@ or per target by setting the target properties :command:`Custom commands <add_custom_command>` and :command:`custom targets <add_custom_target>` can specify pools using the option ``JOB_POOL``. -Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes +Using a pool that is not defined by ``JOB_POOLS`` causes an error by ninja at build time. If not set, this property uses the value of the :variable:`CMAKE_JOB_POOLS` diff --git a/Help/prop_gbl/USE_FOLDERS.rst b/Help/prop_gbl/USE_FOLDERS.rst index 591972327f..6f5a083fbc 100644 --- a/Help/prop_gbl/USE_FOLDERS.rst +++ b/Help/prop_gbl/USE_FOLDERS.rst @@ -1,10 +1,17 @@ USE_FOLDERS ----------- -Use the :prop_tgt:`FOLDER` target property to organize targets into -folders. +Controls whether to use the :prop_tgt:`FOLDER` target property to organize +targets into folders. The value of ``USE_FOLDERS`` at the end of the top level +``CMakeLists.txt`` file is what determines the behavior. -If not set, CMake treats this property as ``OFF`` by default. CMake -generators that are capable of organizing into a hierarchy of folders -use the values of the :prop_tgt:`FOLDER` target property to name those -folders. See also the documentation for the :prop_tgt:`FOLDER` target property. +.. versionchanged:: 3.26 + + CMake treats this property as ``ON`` by default. + See policy :policy:`CMP0143`. + +Not all CMake generators support recording folder details for targets. +The :generator:`Xcode` and :ref:`Visual Studio <Visual Studio Generators>` +generators are examples of generators that do. Similarly, not all IDEs +support presenting targets using folder hierarchies, even if the CMake +generator used provides the necessary information. diff --git a/Help/prop_sf/COMPILE_DEFINITIONS.rst b/Help/prop_sf/COMPILE_DEFINITIONS.rst index 63176901e3..2af896ebf4 100644 --- a/Help/prop_sf/COMPILE_DEFINITIONS.rst +++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst @@ -16,6 +16,9 @@ CMake will automatically drop some definitions that are not supported by the native build tool. Xcode does not support per-configuration definitions on source files. +.. versionadded:: 3.26 + Any leading ``-D`` on an item will be removed. + .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt Contents of ``COMPILE_DEFINITIONS`` may use :manual:`cmake-generator-expressions(7)` diff --git a/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst b/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst new file mode 100644 index 0000000000..23c48597d3 --- /dev/null +++ b/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst @@ -0,0 +1,24 @@ +CXX_SCAN_FOR_MODULES +-------------------- + +.. versionadded:: 3.26 + +``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan the +source for C++ module dependencies. See also the +:prop_tgt:`CXX_SCAN_FOR_MODULES` for target-wide settings. + +When this property is set ``ON``, CMake will scan the source at build time and +add module dependency information to the compile line as necessary. When this +property is set ``OFF``, CMake will not scan the source at build time. When +this property is unset, the :prop_tgt:`CXX_SCAN_FOR_MODULES` property is +consulted. + +Note that scanning is only performed if C++20 or higher is enabled for the +target and the source uses the ``CXX`` language. Scanning for modules in +sources belonging to file sets of type ``CXX_MODULES`` and +``CXX_MODULES_HEADER_UNITS`` is always performed. + +.. note :: + + This setting is meaningful only when experimental support for C++ modules + has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate. diff --git a/Help/prop_sf/SKIP_AUTOUIC.rst b/Help/prop_sf/SKIP_AUTOUIC.rst index ae9725acdd..45ed3f8a52 100644 --- a/Help/prop_sf/SKIP_AUTOUIC.rst +++ b/Help/prop_sf/SKIP_AUTOUIC.rst @@ -5,7 +5,7 @@ SKIP_AUTOUIC Exclude the source file from :prop_tgt:`AUTOUIC` processing (for Qt projects). -:prop_sf:`SKIP_AUTOUIC` can be set on C++ header and source files and on +``SKIP_AUTOUIC`` can be set on C++ header and source files and on ``.ui`` files. For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`. diff --git a/Help/prop_test/LABELS.rst b/Help/prop_test/LABELS.rst index d827adc08b..02e2fae860 100644 --- a/Help/prop_test/LABELS.rst +++ b/Help/prop_test/LABELS.rst @@ -2,7 +2,7 @@ LABELS ------ Specify a list of text labels associated with a test. The labels are -reported in both the ``ctest`` output summary and in dashboard submissions. +reported in both the :program:`ctest` output summary and in dashboard submissions. They can also be used to filter the set of tests to be executed (see the :option:`ctest -L` and :option:`ctest -LE` options). diff --git a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst index 726dcab405..aa175904e4 100644 --- a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst +++ b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst @@ -28,14 +28,14 @@ variable if either of these are set. Because the test's start time is reset, its execution time will not include any time that was spent waiting for the matching output. -:prop_test:`TIMEOUT_AFTER_MATCH` is useful for avoiding spurious +``TIMEOUT_AFTER_MATCH`` is useful for avoiding spurious timeouts when your test must wait for some system resource to become available before it can execute. Set :prop_test:`TIMEOUT` to a longer duration that accounts for resource acquisition and use -:prop_test:`TIMEOUT_AFTER_MATCH` to control how long the actual test +``TIMEOUT_AFTER_MATCH`` to control how long the actual test is allowed to run. If the required resource can be controlled by CTest you should use -:prop_test:`RESOURCE_LOCK` instead of :prop_test:`TIMEOUT_AFTER_MATCH`. +:prop_test:`RESOURCE_LOCK` instead of ``TIMEOUT_AFTER_MATCH``. This property should be used when only the test itself can determine when its required resources are available. diff --git a/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst b/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst index ff42ae8651..1ca0969b69 100644 --- a/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst +++ b/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst @@ -13,7 +13,7 @@ When unset or empty the directory ``<dir>/<target-name>_autogen`` is used where ``<dir>`` is :variable:`CMAKE_CURRENT_BINARY_DIR` and ``<target-name>`` is :prop_tgt:`NAME`. -By default :prop_tgt:`AUTOGEN_BUILD_DIR` is unset. +By default ``AUTOGEN_BUILD_DIR`` is unset. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst index 563190ad2c..9350a4f014 100644 --- a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst @@ -11,16 +11,16 @@ Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property ``moc`` and ``uic`` files. As this ``_autogen`` target is created at generate-time, it is not possible to define dependencies of it using e.g. :command:`add_dependencies`. Instead the -:prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property decides whether the origin +``AUTOGEN_ORIGIN_DEPENDS`` target property decides whether the origin target dependencies should be forwarded to the ``_autogen`` target or not. -By default :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is initialized from +By default ``AUTOGEN_ORIGIN_DEPENDS`` is initialized from :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` which is ``ON`` by default. In total the dependencies of the ``_autogen`` target are composed from - forwarded origin target dependencies - (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) + (enabled by default via ``AUTOGEN_ORIGIN_DEPENDS``) - additional user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS` See the :manual:`cmake-qt(7)` manual for more information on using CMake @@ -29,12 +29,12 @@ with Qt. Note ^^^^ -Disabling :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is useful to avoid building of +Disabling ``AUTOGEN_ORIGIN_DEPENDS`` is useful to avoid building of origin target dependencies when building the ``_autogen`` target only. This is especially interesting when a :variable:`global autogen target <CMAKE_GLOBAL_AUTOGEN_TARGET>` is enabled. When the ``_autogen`` target doesn't require all the origin target's -dependencies, and :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is disabled, it might be +dependencies, and ``AUTOGEN_ORIGIN_DEPENDS`` is disabled, it might be necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` to add missing dependencies. diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index 92b52a3e18..5286d2d0b0 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -8,7 +8,7 @@ Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property ``moc`` and ``uic`` files. As this ``_autogen`` target is created at generate-time, it is not possible to define dependencies of it using e.g. :command:`add_dependencies`. Instead the -:prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property can be set to a +``AUTOGEN_TARGET_DEPENDS`` target property can be set to a :ref:`;-list <CMake Language Lists>` of additional dependencies for the ``_autogen`` target. Dependencies can be target names or file names. @@ -16,7 +16,7 @@ In total the dependencies of the ``_autogen`` target are composed from - forwarded origin target dependencies (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) -- additional user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS` +- additional user defined dependencies from ``AUTOGEN_TARGET_DEPENDS`` See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. @@ -33,4 +33,4 @@ If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or - a file that isn't in the origin target's sources -it must be added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. +it must be added to ``AUTOGEN_TARGET_DEPENDS``. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index ed8b2626b4..0feb2e8403 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -3,7 +3,7 @@ AUTOMOC Should the target be processed with auto-moc (for Qt projects). -:prop_tgt:`AUTOMOC` is a boolean specifying whether CMake will handle the Qt +``AUTOMOC`` is a boolean specifying whether CMake will handle the Qt ``moc`` preprocessor automatically, i.e. without having to use commands like :module:`QT4_WRAP_CPP() <FindQt4>`, ``QT5_WRAP_CPP()``, etc. Currently, Qt versions 4 to 6 are supported. @@ -19,7 +19,7 @@ Header file processing ^^^^^^^^^^^^^^^^^^^^^^ At configuration time, a list of header files that should be scanned by -:prop_tgt:`AUTOMOC` is computed from the target's sources. +``AUTOMOC`` is computed from the target's sources. - All header files in the target's sources are added to the scan list. - For all C++ source files ``<source_base>.<source_extension>`` in the @@ -146,7 +146,7 @@ which is added to the target's sources. Qt version detection ^^^^^^^^^^^^^^^^^^^^ -:prop_tgt:`AUTOMOC` enabled targets need to know the Qt major and minor +``AUTOMOC`` enabled targets need to know the Qt major and minor version they're working with. The major version usually is provided by the ``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[456]Core`` library, that the target links to. To find the minor version, CMake builds a list of @@ -173,7 +173,7 @@ entry in the list is taken. A ``find_package(Qt[456]...)`` call sets the ``QT/Qt[56]Core_VERSION_MAJOR/MINOR`` variables. If the call is in a different context than the :command:`add_executable` or :command:`add_library` call, e.g. in a function, -then the version variables might not be available to the :prop_tgt:`AUTOMOC` +then the version variables might not be available to the ``AUTOMOC`` enabled target. In that case the version variables can be forwarded from the ``find_package(Qt[456]...)`` calling context to the :command:`add_executable` @@ -221,25 +221,25 @@ Compiler pre definitions for ``moc`` are written to the ``moc_predefs.h`` file. The generation of this file can be enabled or disabled in this target property. :prop_sf:`SKIP_AUTOMOC`: -Sources and headers can be excluded from :prop_tgt:`AUTOMOC` processing by +Sources and headers can be excluded from ``AUTOMOC`` processing by setting this source file property. :prop_sf:`SKIP_AUTOGEN`: -Source files can be excluded from :prop_tgt:`AUTOMOC`, +Source files can be excluded from ``AUTOMOC``, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by setting this source file property. :prop_gbl:`AUTOGEN_SOURCE_GROUP`: This global property can be used to group files generated by -:prop_tgt:`AUTOMOC` or :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. +``AUTOMOC`` or :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. :prop_gbl:`AUTOGEN_TARGETS_FOLDER`: -This global property can be used to group :prop_tgt:`AUTOMOC`, +This global property can be used to group ``AUTOMOC``, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE, e.g. in MSVS. :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: -A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or +A global ``autogen`` target, that depends on all ``AUTOMOC`` or :prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project, will be generated when this variable is ``ON``. diff --git a/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst index 89982845a2..82aa61e8b3 100644 --- a/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst +++ b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst @@ -12,14 +12,14 @@ from the output of the command defined in when - :prop_tgt:`AUTOMOC` is enabled, -- :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is enabled, +- ``AUTOMOC_COMPILER_PREDEFINES`` is enabled, - :variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` isn't empty and - the Qt version is greater or equal 5.8. The ``moc_predefs.h`` file, which is generated in :prop_tgt:`AUTOGEN_BUILD_DIR`, is passed to ``moc`` as the argument to the ``--include`` option. -By default :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is initialized from +By default ``AUTOMOC_COMPILER_PREDEFINES`` is initialized from :variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES`, which is ON by default. See the :manual:`cmake-qt(7)` manual for more information on using CMake diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst index 1f317009d5..c4277d74cc 100644 --- a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -25,7 +25,7 @@ target's sources, then it might be necessary to add it to the ``_autogen`` target dependencies. See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference. -By default :prop_tgt:`AUTOMOC_DEPEND_FILTERS` is initialized from +By default ``AUTOMOC_DEPEND_FILTERS`` is initialized from :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default. From Qt 5.15.0 on this variable is ignored as moc is able to output the correct diff --git a/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst b/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst index f4b839653a..a6d5aa03e6 100644 --- a/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst +++ b/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst @@ -3,7 +3,7 @@ AUTOMOC_EXECUTABLE .. versionadded:: 3.14 -:prop_tgt:`AUTOMOC_EXECUTABLE` is file path pointing to the ``moc`` +``AUTOMOC_EXECUTABLE`` is file path pointing to the ``moc`` executable to use for :prop_tgt:`AUTOMOC` enabled files. Setting this property will make CMake skip the automatic detection of the ``moc`` binary as well as the sanity-tests normally run to ensure diff --git a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst index a53810d156..072e7f732a 100644 --- a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -10,7 +10,7 @@ This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` for this target. When running :prop_tgt:`AUTOMOC`, CMake searches for the strings listed in -:prop_tgt:`AUTOMOC_MACRO_NAMES` in C++ source and header files. +``AUTOMOC_MACRO_NAMES`` in C++ source and header files. If any of the strings is found - as the first non space string on a new line or @@ -18,7 +18,7 @@ If any of the strings is found then the file will be processed by ``moc``. -By default :prop_tgt:`AUTOMOC_MACRO_NAMES` is initialized from +By default ``AUTOMOC_MACRO_NAMES`` is initialized from :variable:`CMAKE_AUTOMOC_MACRO_NAMES`. See the :manual:`cmake-qt(7)` manual for more information on using CMake diff --git a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst index 836d9535d0..dcddcaebb4 100644 --- a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst +++ b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst @@ -14,7 +14,7 @@ compute the relative path accordingly. If the header is not in the the ``-p`` path prefix option. ``moc`` usually generates a relative include path in that case. -:prop_tgt:`AUTOMOC_PATH_PREFIX` is initialized from the variable +``AUTOMOC_PATH_PREFIX`` is initialized from the variable :variable:`CMAKE_AUTOMOC_PATH_PREFIX`, which is ``OFF`` by default. See the :manual:`cmake-qt(7)` manual for more information on using CMake @@ -26,7 +26,7 @@ Reproducible builds For reproducible builds it is recommended to keep headers that are ``moc`` compiled in one of the target :command:`include directories <target_include_directories>` and set -:prop_tgt:`AUTOMOC_PATH_PREFIX` to ``ON``. This ensures that: +``AUTOMOC_PATH_PREFIX`` to ``ON``. This ensures that: - ``moc`` output files are identical on different build setups, - ``moc`` output files will compile correctly when the source and/or diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index 0a0c2a1195..33de352d3e 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -3,7 +3,7 @@ AUTORCC Should the target be processed with auto-rcc (for Qt projects). -:prop_tgt:`AUTORCC` is a boolean specifying whether CMake will handle +``AUTORCC`` is a boolean specifying whether CMake will handle the Qt ``rcc`` code generator automatically, i.e. without having to use commands like :module:`QT4_ADD_RESOURCES() <FindQt4>`, ``QT5_ADD_RESOURCES()``, etc. Currently, Qt versions 4 to 6 are supported. @@ -13,7 +13,7 @@ as target sources at build time and invoke ``rcc`` accordingly. This property is initialized by the value of the :variable:`CMAKE_AUTORCC` variable if it is set when a target is created. -By default :prop_tgt:`AUTORCC` is processed by a +By default ``AUTORCC`` is processed by a :command:`custom command <add_custom_command>`. If the ``.qrc`` file is :prop_sf:`GENERATED`, a :command:`custom target <add_custom_target>` is used instead. @@ -37,25 +37,25 @@ property. The corresponding :prop_sf:`AUTORCC_OPTIONS` source file property can be used to specify options to be applied only to a specific ``.qrc`` file. :prop_sf:`SKIP_AUTORCC`: -``.qrc`` files can be excluded from :prop_tgt:`AUTORCC` processing by +``.qrc`` files can be excluded from ``AUTORCC`` processing by setting this source file property. :prop_sf:`SKIP_AUTOGEN`: Source files can be excluded from :prop_tgt:`AUTOMOC`, -:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by +:prop_tgt:`AUTOUIC` and ``AUTORCC`` processing by setting this source file property. :prop_gbl:`AUTOGEN_SOURCE_GROUP`: This global property can be used to group files generated by -:prop_tgt:`AUTOMOC` or :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. +:prop_tgt:`AUTOMOC` or ``AUTORCC`` together in an IDE, e.g. in MSVS. :prop_gbl:`AUTOGEN_TARGETS_FOLDER`: This global property can be used to group :prop_tgt:`AUTOMOC`, -:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE, +:prop_tgt:`AUTOUIC` and ``AUTORCC`` targets together in an IDE, e.g. in MSVS. :variable:`CMAKE_GLOBAL_AUTORCC_TARGET`: -A global ``autorcc`` target that depends on all :prop_tgt:`AUTORCC` targets +A global ``autorcc`` target that depends on all ``AUTORCC`` targets in the project will be generated when this variable is ``ON``. See the :manual:`cmake-qt(7)` manual for more information on using CMake diff --git a/Help/prop_tgt/AUTORCC_EXECUTABLE.rst b/Help/prop_tgt/AUTORCC_EXECUTABLE.rst index 4f85fbaa9a..68942e67e9 100644 --- a/Help/prop_tgt/AUTORCC_EXECUTABLE.rst +++ b/Help/prop_tgt/AUTORCC_EXECUTABLE.rst @@ -3,7 +3,7 @@ AUTORCC_EXECUTABLE .. versionadded:: 3.14 -:prop_tgt:`AUTORCC_EXECUTABLE` is file path pointing to the ``rcc`` +``AUTORCC_EXECUTABLE`` is file path pointing to the ``rcc`` executable to use for :prop_tgt:`AUTORCC` enabled files. Setting this property will make CMake skip the automatic detection of the ``rcc`` binary as well as the sanity-tests normally run to ensure diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index e0cea97a0a..dc854b2ae3 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -3,7 +3,7 @@ AUTOUIC Should the target be processed with auto-uic (for Qt projects). -:prop_tgt:`AUTOUIC` is a boolean specifying whether CMake will handle +``AUTOUIC`` is a boolean specifying whether CMake will handle the Qt ``uic`` code generator automatically, i.e. without having to use commands like :module:`QT4_WRAP_UI() <FindQt4>`, ``QT5_WRAP_UI()``, etc. Currently, Qt versions 4 to 6 are supported. @@ -59,22 +59,22 @@ can be used to specify options to be applied only to a specific ``<base_name>.ui`` file. :prop_sf:`SKIP_AUTOUIC`: -Source files can be excluded from :prop_tgt:`AUTOUIC` processing by setting +Source files can be excluded from ``AUTOUIC`` processing by setting this source file property. :prop_sf:`SKIP_AUTOGEN`: Source files can be excluded from :prop_tgt:`AUTOMOC`, -:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by +``AUTOUIC`` and :prop_tgt:`AUTORCC` processing by setting this source file property. :prop_gbl:`AUTOGEN_TARGETS_FOLDER`: This global property can be used to group :prop_tgt:`AUTOMOC`, -:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE, +``AUTOUIC`` and :prop_tgt:`AUTORCC` targets together in an IDE, e.g. in MSVS. :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or -:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project, +``AUTOUIC`` generated ``<ORIGIN>_autogen`` targets in the project, will be generated when this variable is ``ON``. :prop_tgt:`AUTOGEN_PARALLEL`: diff --git a/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst b/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst index 596632650d..be79290945 100644 --- a/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst +++ b/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst @@ -3,7 +3,7 @@ AUTOUIC_EXECUTABLE .. versionadded:: 3.14 -:prop_tgt:`AUTOUIC_EXECUTABLE` is file path pointing to the ``uic`` +``AUTOUIC_EXECUTABLE`` is file path pointing to the ``uic`` executable to use for :prop_tgt:`AUTOUIC` enabled files. Setting this property will make CMake skip the automatic detection of the ``uic`` binary as well as the sanity-tests normally run to ensure diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst index 1f917a519c..902e2f7af1 100644 --- a/Help/prop_tgt/BUILD_RPATH.rst +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -3,13 +3,34 @@ BUILD_RPATH .. versionadded:: 3.8 -A :ref:`semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``) -entries to add to binaries linked in the build tree (for platforms that -support it). The entries will *not* be used for binaries in the install -tree. See also the :prop_tgt:`INSTALL_RPATH` target property. +A :ref:`semicolon-separated list <CMake Language Lists>` specifying +runtime path (``RPATH``) entries to add to binaries linked in the +build tree (for platforms that support it). By default, CMake sets +the runtime path of binaries in the build tree to contain search +paths it knows are needed to find the shared libraries they link. +Projects may set ``BUILD_RPATH`` to specify additional search paths. + +The build-tree runtime path will *not* be used for binaries in the +install tree. It will be replaced with the install-tree runtime path +during the installation step. See also the :prop_tgt:`INSTALL_RPATH` +target property. This property is initialized by the value of the variable :variable:`CMAKE_BUILD_RPATH` if it is set when a target is created. This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`. + +Other settings that affect the build-tree runtime path include: + +* The :variable:`CMAKE_SKIP_RPATH` variable completely disables runtime + paths in both the build tree and install tree. + +* The :prop_tgt:`SKIP_BUILD_RPATH` target property disables setting any + runtime path in the build tree. + +* The :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property causes the + automatically-generated runtime path to use entries relative to ``$ORIGIN``. + +* The :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property causes binaries + in the build tree to be built with the install-tree runtime path. diff --git a/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst b/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst index adfa6f77a1..7ce0023c81 100644 --- a/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst +++ b/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst @@ -7,13 +7,30 @@ By setting this target property, the target is configured to build with ``C++/CLI`` support. The Visual Studio generator defines the ``clr`` parameter depending on -the value of ``COMMON_LANGUAGE_RUNTIME``: +the value of the ``COMMON_LANGUAGE_RUNTIME`` target property: -* property not set: native C++ (i.e. default) -* property set but empty: mixed unmanaged/managed C++ -* property set to any non empty value: managed C++ +Not Set (default) -Supported values: ``""``, ``"pure"``, ``"safe"`` + Native C++. + +``""`` (set but empty) + + Mixed unmanaged/managed C++ using .NET Framework. + +``netcore`` + .. versionadded:: 3.26 + + Mixed unmanaged/managed C++ using .NET Core. + + This required VS 2019's v142 toolset or higher. + +``pure`` + + Managed C++. + +``safe`` + + Managed C++. This property is only evaluated :ref:`Visual Studio Generators` for VS 2010 and above. diff --git a/Help/prop_tgt/COMPILE_DEFINITIONS.rst b/Help/prop_tgt/COMPILE_DEFINITIONS.rst index 059f9137f6..c128a9be0f 100644 --- a/Help/prop_tgt/COMPILE_DEFINITIONS.rst +++ b/Help/prop_tgt/COMPILE_DEFINITIONS.rst @@ -13,6 +13,9 @@ values). CMake will automatically drop some definitions that are not supported by the native build tool. +.. versionadded:: 3.26 + Any leading ``-D`` on an item will be removed. + .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt Contents of ``COMPILE_DEFINITIONS`` may use "generator expressions" with the diff --git a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst index 819ce3ea92..58072e1f0a 100644 --- a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst +++ b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -14,8 +14,13 @@ executable is generated, allowing for multiple static libraries to resolve device symbols at the same time when they are used by a shared library or executable. -By default static library targets have this property is disabled, -while shared, module, and executable targets have this property enabled. +If this property or :variable:`CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS` is unset, +static libraries are treated as if it is disabled while shared, module, +and executable targets behave as if it is on. + +If :variable:`CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS` has been defined, +this property is initialized to the value the variable and overriding +the default behavior. Note that device linking is not supported for :ref:`Object Libraries`. diff --git a/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst b/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst new file mode 100644 index 0000000000..e2127c2843 --- /dev/null +++ b/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst @@ -0,0 +1,27 @@ +CXX_SCAN_FOR_MODULES +-------------------- + +.. versionadded:: 3.26 + +``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan C++ +sources in the target for module dependencies. See also the +:prop_sf:`CXX_SCAN_FOR_MODULES` for per-source settings which, if set, +overrides the target-wide settings. + +This property is initialized by the value of the +:variable:`CMAKE_CXX_SCAN_FOR_MODULES` variable if it is set when a target is +created. + +When this property is set ``ON`` or unset, CMake will scan the target's +``CXX`` sources at build time and add module dependency information to the +compile line as necessary. When this property is set ``OFF``, CMake will not +scan the target's ``CXX`` sources at build time. + +Note that scanning is only performed if C++20 or higher is enabled for the +target. Scanning for modules in the target's sources belonging to file sets +of type ``CXX_MODULES`` and ``CXX_MODULES_HEADER_UNITS`` is always performed. + +.. note :: + + This setting is meaningful only when experimental support for C++ modules + has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate. diff --git a/Help/prop_tgt/DEFINE_SYMBOL.rst b/Help/prop_tgt/DEFINE_SYMBOL.rst index eb7f93735c..775cf898cb 100644 --- a/Help/prop_tgt/DEFINE_SYMBOL.rst +++ b/Help/prop_tgt/DEFINE_SYMBOL.rst @@ -8,4 +8,10 @@ compiling sources in a shared library. If not set here then it is set to ``target_EXPORTS`` by default (with some substitutions if the target is not a valid C identifier). This is useful for headers to know whether they are being included from inside their library or outside to -properly setup dllexport/dllimport decorations. +properly setup dllexport/dllimport decorations on Windows. + +On POSIX platforms, this can optionally be used to control the visibility +of symbols. + +CMake provides support for such decorations with the :module:`GenerateExportHeader` +module. diff --git a/Help/prop_tgt/FOLDER.rst b/Help/prop_tgt/FOLDER.rst index f6be9e6735..616b96253d 100644 --- a/Help/prop_tgt/FOLDER.rst +++ b/Help/prop_tgt/FOLDER.rst @@ -1,13 +1,20 @@ FOLDER ------ -Set the folder name. Use to organize targets in an IDE. +For IDEs that present targets using a folder hierarchy, this property +specifies the name of the folder to place the target under. +To nest folders, use ``FOLDER`` values such as ``GUI/Dialogs`` with ``/`` +characters separating folder levels. Targets with no ``FOLDER`` property +will appear as top level entities. Targets with the same ``FOLDER`` +property value will appear in the same folder as siblings. -Targets with no ``FOLDER`` property will appear as top level entities in -IDEs like Visual Studio. Targets with the same ``FOLDER`` property value -will appear next to each other in a folder of that name. To nest -folders, use ``FOLDER`` values such as 'GUI/Dialogs' with '/' characters -separating folder levels. +Only some CMake generators honor the ``FOLDER`` property +(e.g. :generator:`Xcode` or any of the +:ref:`Visual Studio <Visual Studio Generators>` generators). +Those generators that don't will simply ignore it. This property is initialized by the value of the variable :variable:`CMAKE_FOLDER` if it is set when a target is created. + +The global property :prop_gbl:`USE_FOLDERS` must be set to true, otherwise +the ``FOLDER`` property is ignored. diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index 47a003774f..84310b9a93 100644 --- a/Help/prop_tgt/INSTALL_NAME_DIR.rst +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -6,8 +6,9 @@ Directory name for installed targets on Apple platforms. ``INSTALL_NAME_DIR`` is a string specifying the directory portion of the "install_name" field of shared libraries on Apple platforms for installed targets. When not set, the default directory used is determined -by :prop_tgt:`MACOSX_RPATH`. Policies :policy:`CMP0068` and :policy:`CMP0042` -are also relevant. +by :prop_tgt:`MACOSX_RPATH`. If the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` +property is set, this will be used already in the build tree. +Policies :policy:`CMP0068` and :policy:`CMP0042` are also relevant. This property is initialized by the value of the variable :variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is @@ -16,3 +17,7 @@ created. This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`. In particular, the :genex:`$<INSTALL_PREFIX>` generator expression can be used to set the directory relative to the install-time prefix. + +On platforms that support runtime paths (``RPATH``), refer to the +:prop_tgt:`INSTALL_RPATH` target property. +Under Windows, the :genex:`TARGET_RUNTIME_DLLS` generator expression is related. diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst index 4549b92283..e5110b8937 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -3,10 +3,27 @@ INSTALL_RPATH The rpath to use for installed targets. -A semicolon-separated list specifying the rpath to use in installed +By default, the install rpath is empty. It can be set using this property, +which is a semicolon-separated list specifying the rpath to use in installed targets (for platforms that support it). This property is initialized -by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set when -a target is created. +by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set +when a target is created. +Beside setting the install rpath manually, using the +:prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` target property it can also be +generated automatically by CMake. + +Normally CMake uses the build tree for the RPATH when building executables +etc on systems that use RPATH, see the :prop_tgt:`BUILD_RPATH` target +property. When the software is installed +the targets are edited (or relinked) by CMake (see +:variable:`CMAKE_NO_BUILTIN_CHRPATH`) to have the install RPATH. +This editing during installation can be avoided via +the :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property. + +For handling toolchain-dependent RPATH entries the +:prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` can be used. +Runtime paths can be disabled completely via the :variable:`CMAKE_SKIP_RPATH` +variable. Because the rpath may contain ``${ORIGIN}``, which coincides with CMake syntax, the contents of ``INSTALL_RPATH`` are properly escaped in the @@ -14,3 +31,6 @@ the contents of ``INSTALL_RPATH`` are properly escaped in the This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`. + +On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property. +Under Windows, the :genex:`TARGET_RUNTIME_DLLS` generator expression is related. diff --git a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst index d16a7a1c61..ef859cf2d2 100644 --- a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst @@ -3,7 +3,7 @@ INSTALL_RPATH_USE_LINK_PATH Add paths to linker search and installed rpath. -``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` +``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``TRUE`` will append to the runtime search path (rpath) of installed binaries any directories outside the project that are in the linker search path or contain linked library files. The directories are appended after the diff --git a/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst b/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst index c74a31901a..9cc12a1e90 100644 --- a/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst +++ b/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst @@ -5,5 +5,4 @@ INTERFACE_COMPILE_DEFINITIONS .. |command_name| replace:: :command:`target_compile_definitions` .. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_DEFINITIONS`` .. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_DEFINITIONS` -.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_DEFINITIONS>`` .. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst index 0db3b0cbdc..50d6161a3a 100644 --- a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst +++ b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst @@ -7,7 +7,6 @@ INTERFACE_COMPILE_FEATURES .. |command_name| replace:: :command:`target_compile_features` .. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_FEATURES`` .. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_FEATURES` -.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_FEATURES>`` .. include:: INTERFACE_BUILD_PROPERTY.txt See the :manual:`cmake-compile-features(7)` manual for information on compile diff --git a/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst b/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst index 7f0b38534f..2af7a9911c 100644 --- a/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst @@ -5,5 +5,4 @@ INTERFACE_COMPILE_OPTIONS .. |command_name| replace:: :command:`target_compile_options` .. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_OPTIONS`` .. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_OPTIONS` -.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_OPTIONS>`` .. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst index b1c40b2245..8795c80ab6 100644 --- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -5,7 +5,6 @@ INTERFACE_INCLUDE_DIRECTORIES .. |command_name| replace:: :command:`target_include_directories` .. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` .. |PROPERTY_LINK| replace:: :prop_tgt:`INCLUDE_DIRECTORIES` -.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_INCLUDE_DIRECTORIES>`` .. include:: INTERFACE_BUILD_PROPERTY.txt Include directories usage requirements commonly differ between the build-tree diff --git a/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst index de1dabbcf6..45b3225cff 100644 --- a/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst @@ -7,5 +7,4 @@ INTERFACE_LINK_DIRECTORIES .. |command_name| replace:: :command:`target_link_directories` .. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_DIRECTORIES`` .. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_DIRECTORIES` -.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_DIRECTORIES>`` .. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst index 4245fe9f2d..785b17cfa5 100644 --- a/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst +++ b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst @@ -7,5 +7,4 @@ INTERFACE_LINK_OPTIONS .. |command_name| replace:: :command:`target_link_options` .. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_OPTIONS`` .. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_OPTIONS` -.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_OPTIONS>`` .. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst index d3a5e94147..0a4ac9aa5f 100644 --- a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst @@ -11,3 +11,7 @@ if interprocedural optimization is enabled but not supported. This property is initialized by the :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable if it is set when a target is created. + +There is also the per-configuration :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` +target property, which overrides :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` +if it is set. diff --git a/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst b/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst index 42cace0283..fab142c7ab 100644 --- a/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst +++ b/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst @@ -18,6 +18,6 @@ For instance: This property is initialized by the value of :variable:`CMAKE_JOB_POOL_PRECOMPILE_HEADER`. -If neither :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` nor +If neither ``JOB_POOL_PRECOMPILE_HEADER`` nor :variable:`CMAKE_JOB_POOL_PRECOMPILE_HEADER` are set then :prop_tgt:`JOB_POOL_COMPILE` will be used for this task. diff --git a/Help/prop_tgt/LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst b/Help/prop_tgt/LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst new file mode 100644 index 0000000000..fc88f0f302 --- /dev/null +++ b/Help/prop_tgt/LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst @@ -0,0 +1,29 @@ +<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR +---------------------------------- + +.. versionadded:: 3.26 + +This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, ``OBJC`` +or ``OBJCXX``, and only has an effect when :prop_tgt:`<LANG>_CLANG_TIDY` is +set. + +Specify a directory for the ``clang-tidy`` tool to put ``.yaml`` files +containing its suggested changes in. This can be used for automated mass +refactoring by ``clang-tidy``. Each object file that gets compiled will have a +corresponding ``.yaml`` file in this directory. After the build is completed, +you can run ``clang-apply-replacements`` on this directory to simultaneously +apply all suggested changes to the code base. If this property is not an +absolute directory, it is assumed to be relative to the target's binary +directory. This property should be preferred over adding an ``--export-fixes`` +or ``--fix`` argument directly to the :prop_tgt:`<LANG>_CLANG_TIDY` property. + +When this property is set, CMake takes ownership of the specified directory, +and may create, modify, or delete files and directories within the directory +at any time during configure or build time. Users should use a dedicated +directory for exporting clang-tidy fixes to avoid having files deleted or +overwritten by CMake. Users should not create, modify, or delete files in this +directory. + +This property is initialized by the value of +the :variable:`CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst index 27eadf92db..fcdac59039 100644 --- a/Help/prop_tgt/LINK_OPTIONS.rst +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -9,8 +9,8 @@ libraries need to use the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. These options are used for both normal linking and device linking (see policy :policy:`CMP0105`). To control link options for normal and device -link steps, ``$<HOST_LINK>`` and ``$<DEVICE_LINK>`` -:manual:`generator expressions <cmake-generator-expressions(7)>` can be used. +link steps, :genex:`$<HOST_LINK>` and :genex:`$<DEVICE_LINK>` generator +expressions can be used. This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options specified so far for its target. Use the :command:`target_link_options` diff --git a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst index 2a15dec906..9a629fd92f 100644 --- a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst +++ b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst @@ -15,7 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. If the property is not set, and the project has set the :prop_tgt:`CXX_EXTENSIONS`, -the value of :prop_tgt:`CXX_EXTENSIONS` is set for :prop_tgt:`OBJCXX_EXTENSIONS`. +the value of :prop_tgt:`CXX_EXTENSIONS` is set for ``OBJCXX_EXTENSIONS``. This property is initialized by the value of the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if set when a target is diff --git a/Help/prop_tgt/OBJCXX_STANDARD.rst b/Help/prop_tgt/OBJCXX_STANDARD.rst index 6ac82169c5..03108e133c 100644 --- a/Help/prop_tgt/OBJCXX_STANDARD.rst +++ b/Help/prop_tgt/OBJCXX_STANDARD.rst @@ -53,7 +53,7 @@ Additionally, the :prop_tgt:`OBJCXX_EXTENSIONS` target property may be used to control whether compiler-specific extensions are enabled on a per-target basis. If the property is not set, and the project has set the :prop_tgt:`CXX_STANDARD`, -the value of :prop_tgt:`CXX_STANDARD` is set for :prop_tgt:`OBJCXX_STANDARD`. +the value of :prop_tgt:`CXX_STANDARD` is set for ``OBJCXX_STANDARD``. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst index 3cee740417..2c3c77cd5e 100644 --- a/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst @@ -12,7 +12,7 @@ treated as optional and may "decay" to a previous standard if the requested is not available. If the property is not set, and the project has set the :prop_tgt:`CXX_STANDARD_REQUIRED`, -the value of :prop_tgt:`CXX_STANDARD_REQUIRED` is set for :prop_tgt:`OBJCXX_STANDARD_REQUIRED`. +the value of :prop_tgt:`CXX_STANDARD_REQUIRED` is set for ``OBJCXX_STANDARD_REQUIRED``. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/OBJC_EXTENSIONS.rst b/Help/prop_tgt/OBJC_EXTENSIONS.rst index cd72e5fcca..2914045fb4 100644 --- a/Help/prop_tgt/OBJC_EXTENSIONS.rst +++ b/Help/prop_tgt/OBJC_EXTENSIONS.rst @@ -12,7 +12,7 @@ property is ``ON`` by default. The basic OBJC standard level is controlled by the :prop_tgt:`OBJC_STANDARD` target property. If the property is not set, and the project has set the :prop_tgt:`C_EXTENSIONS`, -the value of :prop_tgt:`C_EXTENSIONS` is set for :prop_tgt:`OBJC_EXTENSIONS`. +the value of :prop_tgt:`C_EXTENSIONS` is set for ``OBJC_EXTENSIONS``. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/OBJC_STANDARD.rst b/Help/prop_tgt/OBJC_STANDARD.rst index 2d27bcf000..0609239f5a 100644 --- a/Help/prop_tgt/OBJC_STANDARD.rst +++ b/Help/prop_tgt/OBJC_STANDARD.rst @@ -36,7 +36,7 @@ Additionally, the :prop_tgt:`OBJC_EXTENSIONS` target property may be used to control whether compiler-specific extensions are enabled on a per-target basis. If the property is not set, and the project has set the :prop_tgt:`C_STANDARD`, -the value of :prop_tgt:`C_STANDARD` is set for :prop_tgt:`OBJC_STANDARD`. +the value of :prop_tgt:`C_STANDARD` is set for ``OBJC_STANDARD``. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst index 11547c8362..8b0a9284d6 100644 --- a/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst @@ -12,7 +12,7 @@ treated as optional and may "decay" to a previous standard if the requested is not available. If the property is not set, and the project has set the :prop_tgt:`C_STANDARD_REQUIRED`, -the value of :prop_tgt:`C_STANDARD_REQUIRED` is set for :prop_tgt:`OBJC_STANDARD_REQUIRED`. +the value of :prop_tgt:`C_STANDARD_REQUIRED` is set for ``OBJC_STANDARD_REQUIRED``. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/SKIP_BUILD_RPATH.rst b/Help/prop_tgt/SKIP_BUILD_RPATH.rst index 7086b1bc46..1fe170ca6b 100644 --- a/Help/prop_tgt/SKIP_BUILD_RPATH.rst +++ b/Help/prop_tgt/SKIP_BUILD_RPATH.rst @@ -4,6 +4,7 @@ SKIP_BUILD_RPATH Should rpaths be used for the build tree. ``SKIP_BUILD_RPATH`` is a boolean specifying whether to skip automatic -generation of an rpath allowing the target to run from the build tree. +generation of an rpath allowing the target to run from the build tree, +see also the :prop_tgt:`BUILD_RPATH` target property. This property is initialized by the value of the variable :variable:`CMAKE_SKIP_BUILD_RPATH` if it is set when a target is created. diff --git a/Help/prop_tgt/UNITY_BUILD_MODE.rst b/Help/prop_tgt/UNITY_BUILD_MODE.rst index 003451ee42..d3d1fccbba 100644 --- a/Help/prop_tgt/UNITY_BUILD_MODE.rst +++ b/Help/prop_tgt/UNITY_BUILD_MODE.rst @@ -56,5 +56,5 @@ which has the following acceptable values: PROPERTIES UNITY_GROUP "bucket2" ) -If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will +If no explicit ``UNITY_BUILD_MODE`` has been specified, CMake will default to ``BATCH``. diff --git a/Help/prop_tgt/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst index e8383c2403..da744c2e10 100644 --- a/Help/prop_tgt/XCODE_EMBED_type.rst +++ b/Help/prop_tgt/XCODE_EMBED_type.rst @@ -16,9 +16,21 @@ The supported values for ``<type>`` are: ``APP_EXTENSIONS`` .. versionadded:: 3.21 - The specified items will be added to the ``Embed App Extensions`` build phase. + The specified items will be added to the ``Embed App Extensions`` build + phase, with ``Destination`` set to ``PlugIns and Foundation Extensions`` They must be CMake target names. +``EXTENSIONKIT_EXTENSIONS`` + .. versionadded:: 3.26 + + The specified items will be added to the ``Embed App Extensions`` build + phase, with ``Destination`` set to ``ExtensionKit Extensions`` + They must be CMake target names, and should likely have the + ``XCODE_PRODUCT_TYPE`` target property set to + ``com.apple.product-type.extensionkit-extension`` + as well as the ``XCODE_EXPLICIT_FILE_TYPE`` to + ``wrapper.extensionkit-extension`` + ``PLUGINS`` .. versionadded:: 3.23 diff --git a/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst index cb449ac492..ca35c2551f 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst @@ -14,6 +14,9 @@ The supported values for ``<type>`` are: ``APP_EXTENSIONS`` .. versionadded:: 3.21 +``EXTENSIONKIT_EXTENSIONS`` + .. versionadded:: 3.26 + ``PLUGINS`` .. versionadded:: 3.23 diff --git a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst index 160f765ace..5a5c65f30f 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst @@ -17,5 +17,8 @@ The supported values for ``<type>`` are: ``APP_EXTENSIONS`` .. versionadded:: 3.21 +``EXTENSIONKIT_EXTENSIONS`` + .. versionadded:: 3.26 + ``PLUGINS`` .. versionadded:: 3.23 diff --git a/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst index e3a7cedd11..da8f61bb4c 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst @@ -19,5 +19,11 @@ The supported values for ``<type>`` are: If the ``XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY`` property is not defined, headers WILL be removed on copy by default. +``EXTENSIONKIT_EXTENSIONS`` + .. versionadded:: 3.26 + + If the ``XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY`` property is not + defined, headers WILL be removed on copy by default. + ``PLUGINS`` .. versionadded:: 3.23 diff --git a/Help/release/3.15.rst b/Help/release/3.15.rst index 6b1a8007a0..de3ced0c6d 100644 --- a/Help/release/3.15.rst +++ b/Help/release/3.15.rst @@ -243,46 +243,42 @@ Modules Generator Expressions --------------------- -* The :manual:`generator expressions <cmake-generator-expressions(7)>` - ``C_COMPILER_ID``, ``CXX_COMPILER_ID``, ``CUDA_COMPILER_ID``, - ``Fortran_COMPILER_ID``, ``COMPILE_LANGUAGE``, ``COMPILE_LANG_AND_ID``, and - ``PLATFORM_ID`` learned to support matching one value from a comma-separated - list. +* The generator expressions :genex:`$<C_COMPILER_ID>`, + :genex:`$<CXX_COMPILER_ID>`, :genex:`$<CUDA_COMPILER_ID>`, + :genex:`$<Fortran_COMPILER_ID>`, :genex:`$<COMPILE_LANGUAGE>`, + :genex:`$<COMPILE_LANG_AND_ID>`, and :genex:`$<PLATFORM_ID>` learned to + support matching one value from a comma-separated list. -* The ``$<CUDA_COMPILER_ID:...>`` and ``$<CUDA_COMPILER_VERSION:...>`` - :manual:`generator expressions <cmake-generator-expressions(7)>` were added. +* The :genex:`$<CUDA_COMPILER_ID:...>` and :genex:`$<CUDA_COMPILER_VERSION:...>` + generator expressions were added. -* The ``$<COMPILE_LANG_AND_ID:...>`` generator expression was introduced to +* The :genex:`$<COMPILE_LANG_AND_ID:...>` generator expression was introduced to allow specification of compile options for target files based on the :variable:`CMAKE_<LANG>_COMPILER_ID` and :prop_sf:`LANGUAGE` of each source file. -* A ``$<FILTER:list,INCLUDE|EXCLUDE,regex>`` - :manual:`generator expression <cmake-generator-expressions(7)>` - has been added. +* A :genex:`$<FILTER:list,INCLUDE|EXCLUDE,regex>` generator expression has + been added. -* A ``$<REMOVE_DUPLICATES:list>`` - :manual:`generator expression <cmake-generator-expressions(7)>` - has been added. +* A :genex:`$<REMOVE_DUPLICATES:list>` generator expression has been added. -* The ``$<SHELL_PATH:...>`` :manual:`generator expression - <cmake-generator-expressions(7)>` gained support for a list of paths. +* The :genex:`$<SHELL_PATH:...>` generator expression gained support for a + list of paths. * New ``$<TARGET_FILE*>`` :manual:`generator expressions <cmake-generator-expressions(7)>` were added to retrieve the prefix, base name, and suffix of the file names of various artifacts: - * ``$<TARGET_FILE_PREFIX:...>`` - * ``$<TARGET_FILE_BASE_NAME:...>`` - * ``$<TARGET_FILE_SUFFIX:...>`` - * ``$<TARGET_LINKER_FILE_PREFIX:...>`` - * ``$<TARGET_LINKER_FILE_BASE_NAME:...>`` - * ``$<TARGET_LINKER_FILE_SUFFIX:...>`` - * ``$<TARGET_PDB_FILE_BASE_NAME:...>`` - -* The ``$<TARGET_OBJECTS:...>`` :manual:`generator expression - <cmake-generator-expressions(7)>` is now supported on ``SHARED``, - ``STATIC``, ``MODULE`` libraries and executables. + * :genex:`$<TARGET_FILE_PREFIX:...>` + * :genex:`$<TARGET_FILE_BASE_NAME:...>` + * :genex:`$<TARGET_FILE_SUFFIX:...>` + * :genex:`$<TARGET_LINKER_FILE_PREFIX:...>` + * :genex:`$<TARGET_LINKER_FILE_BASE_NAME:...>` + * :genex:`$<TARGET_LINKER_FILE_SUFFIX:...>` + * :genex:`$<TARGET_PDB_FILE_BASE_NAME:...>` + +* The :genex:`$<TARGET_OBJECTS:...>` generator expression is now supported + on ``SHARED``, ``STATIC``, ``MODULE`` libraries and executables. CTest ----- diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst index 1aa475f3b6..a27d638a8e 100644 --- a/Help/release/3.17.rst +++ b/Help/release/3.17.rst @@ -140,7 +140,7 @@ Properties * 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 + In particular, the :genex:`$<INSTALL_PREFIX>` generator expression can be used to set the directory relative to the install-time prefix. * Target properties :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and diff --git a/Help/release/3.18.rst b/Help/release/3.18.rst index f97e4dfa0b..c120b9fc83 100644 --- a/Help/release/3.18.rst +++ b/Help/release/3.18.rst @@ -211,12 +211,11 @@ Modules Generator Expressions --------------------- -* The ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>`` - :manual:`generator expressions <cmake-generator-expressions(7)>` were added - to manage device and host link steps. +* The :genex:`$<DEVICE_LINK:...>` and :genex:`$<HOST_LINK:...>` + generator expressions were added to manage device and host link steps. -* The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>`` - :manual:`generator expressions <cmake-generator-expressions(7)>` were added. +* The :genex:`$<LINK_LANGUAGE:...>` and :genex:`$<LINK_LANG_AND_ID:...>` + generator expressions were added. CTest ----- diff --git a/Help/release/3.20.rst b/Help/release/3.20.rst index 40cac41d79..ebd0f91c2e 100644 --- a/Help/release/3.20.rst +++ b/Help/release/3.20.rst @@ -86,8 +86,8 @@ Commands in their ``OUTPUT`` and ``BYPRODUCTS`` options. Their ``COMMAND``, ``WORKING_DIRECTORY``, and ``DEPENDS`` options gained - support for new generator expressions ``$<COMMAND_CONFIG:...>`` and - ``$<OUTPUT_CONFIG:...>`` that control cross-config handling when using + support for new generator expressions :genex:`$<COMMAND_CONFIG:...>` and + :genex:`$<OUTPUT_CONFIG:...>` that control cross-config handling when using the :generator:`Ninja Multi-Config` generator. * The :command:`add_custom_command` command gained ``DEPFILE`` support on diff --git a/Help/release/3.23.rst b/Help/release/3.23.rst index 6376d77a5d..5d8577732b 100644 --- a/Help/release/3.23.rst +++ b/Help/release/3.23.rst @@ -274,8 +274,8 @@ Other Changes * tries to detect invalid architectures and issue an error. * ``CUDA`` with Clang now implements policy :policy:`CMP0105` and - the ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>`` - :manual:`generator expressions <cmake-generator-expressions(7)>`. + the :genex:`$<DEVICE_LINK:...>` and :genex:`$<HOST_LINK:...>` + generator expressions. * The :command:`define_property` command's ``BRIEF_DOCS`` and ``FULL_DOCS`` arguments are now optional. diff --git a/Help/release/3.26.rst b/Help/release/3.26.rst new file mode 100644 index 0000000000..67ace4a459 --- /dev/null +++ b/Help/release/3.26.rst @@ -0,0 +1,183 @@ +CMake 3.26 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.25 include the following. + +New Features +============ + +Languages +--------- + +* The ``ASM_MARMASM`` language was added to support the + Microsoft ARM assembler language. + +Command-Line +------------ + +* The :option:`cmake -E copy <cmake-E copy>` command-line tool now + supports a ``-t`` argument. + +* The :option:`cmake -E copy_directory_if_different + <cmake-E copy_directory_if_different>` command-line tool was added. + +Configure Log +------------- + +* CMake now writes a YAML log of configure-time checks to + ``CMakeFiles/CMakeConfigureLog.yaml`` under the top of the build tree. + See the :manual:`cmake-configure-log(7)` manual. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has + been updated to 2.5. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object + gained a new ``fileSets`` field and associated ``fileSetIndex`` + field to ``sources`` objects. + +* The :manual:`cmake-file-api(7)` gained a new "configureLog" object kind + that enables stable access to the :manual:`cmake-configure-log(7)`. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` commands + now support :manual:`generator expressions <cmake-generator-expressions(7)>` + in their ``COMMENT`` option. + +* The :command:`message` command gained a ``CONFIGURE_LOG`` mode to + record an entry in the :manual:`cmake-configure-log(7)`. + +* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands + now support the ``%z`` and ``%Z`` specifiers for the time zone. + +* The :command:`try_compile` and :command:`try_run` commands gained + a ``LOG_DESCRIPTION`` option specifying text to be recorded in the + :manual:`cmake-configure-log(7)`. + +* The :command:`try_compile` and :command:`try_run` commands gained a + ``NO_LOG`` option to skip recording a :manual:`cmake-configure-log(7)` + entry. + +Variables +--------- + +* The :variable:`CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT` variable is now + set for ``GNU``, ``MSVC``, and ``AppleClang`` compilers that have only + one frontend variant. + +* A :variable:`CMAKE_VS_VERSION_BUILD_NUMBER` variable is now set by + :ref:`Visual Studio Generators` for VS 2017 and above to report the + four-component Visual Studio version number. + +Properties +---------- + +* The :prop_tgt:`<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` target property was + added to allow the ``clang-tidy`` tool to export its suggested fixes to a + set of ``.yaml`` files. A new + :variable:`CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` variable was created to + initialize this property. + +* The :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS <XCODE_EMBED_<type>>` + target property was added to tell the :generator:`Xcode` generator to embed + ExtensionKit-based extensions such as extensions using the Background + Assets framework. Aspects of the embedding can be customized with: + + * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_PATH <XCODE_EMBED_<type>>` + * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` + * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>` + +Modules +------- + +* The :module:`ExternalProject` module's :command:`ExternalProject_Add` command + gained an ``INSTALL_BYPRODUCTS`` option to specify files generated by the + ``install`` step. + +* The :module:`FindCUDAToolkit` module: + + * gained support for the ``sbsa-linux`` cross compilation target, and + + * now provides an imported target for ``nvrtc_static``, if found. + +* The :module:`FindImageMagick` module now provides imported targets. + +* The :module:`FindPython3` and :module:`FindPython` modules gained + support for the `Stable Application Binary Interface`_. + +* The :module:`UseSWIG` module gained support for the ``perl5`` language. + +.. _`Stable Application Binary Interface`: https://docs.python.org/3/c-api/stable.html + +Generator Expressions +--------------------- + +* The :genex:`$<BUILD_LOCAL_INTERFACE:...>` generator expression was added to + prevent usage requirements from being exported to dependent projects. + +CTest +----- + +* The :envvar:`CTEST_NO_TESTS_ACTION` environment variable was added to + provide a default value for the + :option:`--no-tests=\<action\> <ctest --no-tests>` command line + argument of :manual:`ctest(1)`. + +Deprecated and Removed Features +=============================== + +* The ``CMakeFiles/CMakeOutput.log`` and ``CMakeFiles/CMakeError.log`` + files are no longer populated by CMake's built-in modules. + :manual:`cmake(1)` no longer suggests looking at them after a + ``CMake Error`` occurs. Information previously logged to those + files is instead logged to the :manual:`cmake-configure-log(7)`. + +* On CYGWIN, the undocumented ``CMAKE_LEGACY_CYGWIN_WIN32`` mode for + compatibility with CMake versions older than 2.8.4 has been removed. + +Other Changes +============= + +* :ref:`Language Standard Flags`, such as ``-std=c++11``, when generated due + to :command:`target_compile_features` or :variable:`CMAKE_<LANG>_STANDARD`, + are now placed before flags added by :command:`target_compile_options`, + rather than after them. + +* For all ``COMPILE_DEFINITIONS`` properties, any leading ``-D`` on an item + is removed whether or not it was specified by a generator expression. + +* The ``compile_commands.json`` database enabled by + :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` now provides the ``output`` + field in the compile commands objects. This allows multi-config + generators, such as the :generator:`Ninja Multi-Config` generator, + to provide the compile commands for all configurations. + +* The :prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default. + See policy :policy:`CMP0143`. + +* The top-level :command:`project` call will now emit an author warning if the + documented command order in relation to :command:`cmake_minimum_required` is + not respected. + +* The :option:`cmake --trace` option now follows :command:`try_compile` and + :command:`try_run` invocations. + +Updates +======= + +Changes made since CMake 3.26.0 include the following. + +3.26.1, 3.26.2 +-------------- + +* These versions made no changes to documented features or interfaces. + Some implementation updates were made to support ecosystem changes + and/or fix regressions. diff --git a/Help/release/3.9.rst b/Help/release/3.9.rst index 89da627517..09e4ea6969 100644 --- a/Help/release/3.9.rst +++ b/Help/release/3.9.rst @@ -256,11 +256,11 @@ Other :command:`file(GENERATE)` commands. * Two new informational generator expressions to retrieve Apple Bundle - directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>`` + directories have been added. The first one :genex:`$<TARGET_BUNDLE_DIR:tgt>` outputs the full path to the Bundle directory, the other one - ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the + :genex:`$<TARGET_BUNDLE_CONTENT_DIR:tgt>` outputs the full path to the ``Contents`` directory of macOS Bundles and App Bundles. For all other - bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``. + bundle types and SDKs it is identical with :genex:`$<TARGET_BUNDLE_DIR:tgt>`. The new expressions are helpful to query Bundle locations independent of the different Bundle types and layouts on macOS and iOS. diff --git a/Help/release/index.rst b/Help/release/index.rst index b6ecf7b097..c82889f3a0 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,7 @@ Releases .. toctree:: :maxdepth: 1 + 3.26 <3.26> 3.25 <3.25> 3.24 <3.24> 3.23 <3.23> diff --git a/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst index c24e46261d..f490974750 100644 --- a/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst +++ b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst @@ -10,4 +10,4 @@ This variable is used to initialize the :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` property on all the targets. See that target property for additional information. -By default :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` is ``ON``. +By default ``CMAKE_AUTOGEN_ORIGIN_DEPENDS`` is ``ON``. diff --git a/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst index 2ada012ec9..8e68579b8f 100644 --- a/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst +++ b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst @@ -9,4 +9,4 @@ Number of parallel ``moc`` or ``uic`` processes to start when using This variable is used to initialize the :prop_tgt:`AUTOGEN_PARALLEL` property on all the targets. See that target property for additional information. -By default :variable:`CMAKE_AUTOGEN_PARALLEL` is unset. +By default ``CMAKE_AUTOGEN_PARALLEL`` is unset. diff --git a/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst index f77ed6afb9..246bd37f09 100644 --- a/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst +++ b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst @@ -7,9 +7,9 @@ Sets the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC`. A positive integer value or a true boolean value lets the ``AUTO*`` generators output additional processing information. -Setting :variable:`CMAKE_AUTOGEN_VERBOSE` has the same effect +Setting ``CMAKE_AUTOGEN_VERBOSE`` has the same effect as setting the ``VERBOSE`` environment variable during generation (e.g. by calling ``make VERBOSE=1``). The extra verbosity is limited to the ``AUTO*`` generators though. -By default :variable:`CMAKE_AUTOGEN_VERBOSE` is unset. +By default ``CMAKE_AUTOGEN_VERBOSE`` is unset. diff --git a/Help/variable/CMAKE_BINARY_DIR.rst b/Help/variable/CMAKE_BINARY_DIR.rst index e601eb816f..96c63190eb 100644 --- a/Help/variable/CMAKE_BINARY_DIR.rst +++ b/Help/variable/CMAKE_BINARY_DIR.rst @@ -8,6 +8,6 @@ tree. For an in-source build, this would be the same as :variable:`CMAKE_SOURCE_DIR`. When run in :option:`cmake -P` script mode, CMake sets the variables -:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, +``CMAKE_BINARY_DIR``, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst index 5b59a6ef2c..839771a221 100644 --- a/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst @@ -9,3 +9,6 @@ installed the executables etc are relinked by CMake to have the install ``RPATH``. If this variable is set to true then the software is always built with the install path for the ``RPATH`` and does not need to be relinked when installed. + +This is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property +for all targets. diff --git a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst index 75ff8a12a7..887eb2f0ef 100644 --- a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst +++ b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst @@ -3,7 +3,8 @@ CMAKE_CONFIGURATION_TYPES Specifies the available build types (configurations) on multi-config generators (e.g. :ref:`Visual Studio <Visual Studio Generators>`, -:generator:`Xcode`, or :generator:`Ninja Multi-Config`). Typical values +:generator:`Xcode`, or :generator:`Ninja Multi-Config`) as a +:ref:`semicolon-separated list <CMake Language Lists>`. Typical entries include ``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, but custom build types can also be defined. diff --git a/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst index 474baeec6d..bd5691143b 100644 --- a/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst +++ b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -4,5 +4,7 @@ CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS .. versionadded:: 3.16 Default value for :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target -property. This variable is used to initialize the property on each target as +property when defined. By default this variable is not defined. + +This variable is used to initialize the property on each target as it is created. diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst index 15f81d2ccf..1d7a111610 100644 --- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -11,5 +11,5 @@ current source directory being processed. When run in :option:`cmake -P` script mode, CMake sets the variables :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, -:variable:`CMAKE_CURRENT_BINARY_DIR` and +``CMAKE_CURRENT_BINARY_DIR`` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst index 5b860268a5..4205efb1c2 100644 --- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -9,4 +9,4 @@ processed by cmake. When run in :option:`cmake -P` script mode, CMake sets the variables :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and -:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. +``CMAKE_CURRENT_SOURCE_DIR`` to the current working directory. diff --git a/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst b/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst new file mode 100644 index 0000000000..a40bf7524a --- /dev/null +++ b/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst @@ -0,0 +1,15 @@ +CMAKE_CXX_SCAN_FOR_MODULES +-------------------------- + +.. versionadded:: 3.26 + +Whether to scan C++ source files for module dependencies. + +This variable is used to initialize the :prop_tgt:`CXX_SCAN_FOR_MODULES` +property on all the targets. See that target property for additional +information. + +.. note :: + + This setting is meaningful only when experimental support for C++ modules + has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate. diff --git a/Help/variable/CMAKE_DEFAULT_CONFIGS.rst b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst index 65a5f0ddf5..2f42b235ee 100644 --- a/Help/variable/CMAKE_DEFAULT_CONFIGS.rst +++ b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst @@ -10,7 +10,7 @@ configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If it is not specified, it defaults to :variable:`CMAKE_DEFAULT_BUILD_TYPE`. For example, if you set :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``, -but set :variable:`CMAKE_DEFAULT_CONFIGS` to ``Debug`` or ``all``, all +but set ``CMAKE_DEFAULT_CONFIGS`` to ``Debug`` or ``all``, all ``<target>`` aliases in ``build.ninja`` will resolve to ``<target>:Debug`` or ``<target>:all``, but custom commands will still use the ``Release`` configuration. diff --git a/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst b/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst index bdad59eaf1..ada4ba6f28 100644 --- a/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst +++ b/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst @@ -6,4 +6,4 @@ CMAKE_DEPENDS_USE_COMPILER For the :ref:`Makefile Generators`, source dependencies are now, for a selection of compilers, generated by the compiler itself. By defining this variable with value ``FALSE``, you can restore the legacy behavior (i.e. using -``CMake`` for dependencies discovery). +CMake for dependencies discovery). diff --git a/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst b/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst index fc28ebbeb0..612ab8a119 100644 --- a/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst +++ b/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst @@ -9,5 +9,5 @@ This cache variable is used by the Eclipse project generator. See If this variable is set to TRUE, the Eclipse project generator will generate an Eclipse project in :variable:`CMAKE_SOURCE_DIR` . This project can then be used in Eclipse e.g. for the version control functionality. -:variable:`CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT` defaults to FALSE; so +``CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT`` defaults to ``FALSE``; so nothing is written into the source directory. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst index 8d86a94296..5392ad1980 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -18,7 +18,7 @@ unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option is provided. In some cases, for example to locate only system wide installations, it is not desirable to use the :ref:`User Package Registry` when searching -for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` +for packages. If the ``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` variable is ``TRUE``, all the :command:`find_package` commands will skip the :ref:`User Package Registry` as if they were called with the ``NO_CMAKE_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst index cc67f08d26..21b0230a89 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -18,7 +18,7 @@ unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` option is provided. In some cases, it is not desirable to use the :ref:`System Package Registry` when searching for packages. If the -:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable is +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` variable is ``TRUE``, all the :command:`find_package` commands will skip the :ref:`System Package Registry` as if they were called with the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst index a5eec7af20..b058ba09cc 100644 --- a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -18,7 +18,7 @@ This variable takes precedence over In some cases, for example to locate only system wide installations, it is not desirable to use the :ref:`User Package Registry` when searching -for packages. If the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` +for packages. If the ``CMAKE_FIND_USE_PACKAGE_REGISTRY`` variable is ``FALSE``, all the :command:`find_package` commands will skip the :ref:`User Package Registry` as if they were called with the ``NO_CMAKE_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst index 6bfabe0515..4317622abc 100644 --- a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -43,24 +43,8 @@ Supported pairs are: .. versionadded:: 3.23 Specify the 4-component VS Build Version, a.k.a. Build Number. - The components are: - ``<major>.<minor>`` - - The VS major and minor version numbers. - These are the same as the release version numbers. - - ``<date>`` - - A build date in the format ``MMMDD``, where ``MMM`` is a month index - since an epoch used by Microsoft, and ``DD`` is a day in that month. - - ``<build>`` - - A build index on the day represented by ``<date>``. - - The build number is reported by ``vswhere`` as ``installationVersion``. - For example, VS 16.11.10 has build number ``16.11.32126.315``. + .. include:: CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt .. versionadded:: 3.23 @@ -75,3 +59,6 @@ to hold the value persistently. If an environment variable of the form is set and points to the ``Common7/Tools`` directory within one of the VS instances, that instance will be used. Otherwise, if more than one VS instance is installed we do not define which one is chosen by default. + +The VS version build number of the selected VS instance is provided in +the :variable:`CMAKE_VS_VERSION_BUILD_NUMBER` variable. diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst index 96e9907383..7d3f9c36dd 100644 --- a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst @@ -5,7 +5,7 @@ CMAKE_GLOBAL_AUTOGEN_TARGET Switch to enable generation of a global ``autogen`` target. -When :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled, a custom target +When ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is enabled, a custom target ``autogen`` is generated. This target depends on all :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project. By building the global ``autogen`` target, all :prop_tgt:`AUTOMOC` and @@ -14,7 +14,7 @@ By building the global ``autogen`` target, all :prop_tgt:`AUTOMOC` and The name of the global ``autogen`` target can be changed by setting :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`. -By default :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is unset. +By default ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is unset. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst index 4af4bc38fd..d970d56161 100644 --- a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst @@ -6,10 +6,10 @@ CMAKE_GLOBAL_AUTOGEN_TARGET_NAME Change the name of the global ``autogen`` target. When :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled, a global custom target -named ``autogen`` is created. :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME` +named ``autogen`` is created. ``CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`` allows to set a different name for that target. -By default :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME` is unset. +By default ``CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`` is unset. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst index efea5bec81..0b8c309246 100644 --- a/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst +++ b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst @@ -5,7 +5,7 @@ CMAKE_GLOBAL_AUTORCC_TARGET Switch to enable generation of a global ``autorcc`` target. -When :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is enabled, a custom target +When ``CMAKE_GLOBAL_AUTORCC_TARGET`` is enabled, a custom target ``autorcc`` is generated. This target depends on all :prop_tgt:`AUTORCC` generated ``<ORIGIN>_arcc_<QRC>`` targets in the project. By building the global ``autorcc`` target, all :prop_tgt:`AUTORCC` @@ -14,7 +14,7 @@ files in the project will be generated. The name of the global ``autorcc`` target can be changed by setting :variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME`. -By default :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is unset. +By default ``CMAKE_GLOBAL_AUTORCC_TARGET`` is unset. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst index 4d2e313ffd..742425f738 100644 --- a/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst +++ b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst @@ -6,10 +6,10 @@ CMAKE_GLOBAL_AUTORCC_TARGET_NAME Change the name of the global ``autorcc`` target. When :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is enabled, a global custom target -named ``autorcc`` is created. :variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME` +named ``autorcc`` is created. ``CMAKE_GLOBAL_AUTORCC_TARGET_NAME`` allows to set a different name for that target. -By default :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME` is unset. +By default ``CMAKE_GLOBAL_AUTORCC_TARGET_NAME`` is unset. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst index aad99e4406..f864c2074d 100644 --- a/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -7,7 +7,7 @@ Default permissions for directories created implicitly during installation of files by :command:`install` and :command:`file(INSTALL)`. If ``make install`` is invoked and directories are implicitly created they -get permissions set by :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +get permissions set by ``CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`` variable or platform specific default permissions if the variable is not set. Implicitly created directories are created if they are not explicitly installed @@ -15,7 +15,7 @@ by :command:`install` command but are needed to install a file on a certain path. Example of such locations are directories created due to the setting of :variable:`CMAKE_INSTALL_PREFIX`. -Expected content of the :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +Expected content of the ``CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`` variable is a list of permissions that can be used by :command:`install` command `PERMISSIONS` section. diff --git a/Help/variable/CMAKE_LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst b/Help/variable/CMAKE_LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst new file mode 100644 index 0000000000..60b7f40c4d --- /dev/null +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst @@ -0,0 +1,15 @@ +CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR +---------------------------------------- + +.. versionadded:: 3.26 + +Default value for :prop_tgt:`<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` target +property when ``<LANG>`` is ``C``, ``CXX``, ``OBJC`` or ``OBJCXX``. + +This variable is used to initialize the property on each target as it is +created. For example: + +.. code-block:: cmake + + set(CMAKE_CXX_CLANG_TIDY_EXPORT_FIXES_DIR clang-tidy-fixes) + add_executable(foo foo.cxx) diff --git a/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst index 128b1fbbeb..a414463176 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst @@ -16,3 +16,7 @@ the compiler whose frontend it resembles. .. note:: In other words, this variable describes what command line options and language extensions the compiler frontend expects. + +.. versionchanged:: 3.26 + This variable is set for ``GNU``, ``MSVC``, and ``AppleClang`` + compilers that have only one frontend variant. diff --git a/Help/variable/CMAKE_MODULE_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst index 4dcf6b5260..3021b49f8f 100644 --- a/Help/variable/CMAKE_MODULE_PATH.rst +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -1,7 +1,8 @@ CMAKE_MODULE_PATH ----------------- -:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path -for CMake modules to be loaded by the :command:`include` or -:command:`find_package` commands before checking the default modules that come -with CMake. By default it is empty, it is intended to be set by the project. +:ref:`Semicolon-separated list <CMake Language Lists>` of directories, +represented using forward slashes, specifying a search path for CMake modules +to be loaded by the :command:`include` or :command:`find_package` commands +before checking the default modules that come with CMake. By default it is +empty. It is intended to be set by the project. diff --git a/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst index b9b045e7de..483ec5f600 100644 --- a/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst +++ b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst @@ -10,6 +10,9 @@ a builtin editor to change the runtime search path in the installed copy. If this variable is set to true then CMake will relink the binary before installation instead of using its builtin editor. +For more information on RPATH handling see +the :prop_tgt:`INSTALL_RPATH` and :prop_tgt:`BUILD_RPATH` target properties. + .. versionadded:: 3.20 This variable also applies to XCOFF binaries' LIBPATH. Prior to the diff --git a/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst index 8da6100300..dd3e2a0485 100644 --- a/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst +++ b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst @@ -6,5 +6,13 @@ Do not include RPATHs in the build tree. Normally CMake uses the build tree for the RPATH when building executables etc on systems that use RPATH. When the software is installed the executables etc are relinked by CMake to have the -install RPATH. If this variable is set to true then the software is +install RPATH. If this variable is set to ``TRUE`` then the software is always built with no RPATH. + +This is used to initialize the :prop_tgt:`SKIP_BUILD_RPATH` target property +for all targets. For more information on RPATH handling see +the :prop_tgt:`INSTALL_RPATH` and :prop_tgt:`BUILD_RPATH` target properties. + +See also the :variable:`CMAKE_SKIP_INSTALL_RPATH` variable. +To omit RPATH in both the build and install steps, use +:variable:`CMAKE_SKIP_RPATH` instead. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst b/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst index 80a68c972a..e88db36323 100644 --- a/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst +++ b/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst @@ -6,6 +6,6 @@ Don't make the ``install`` target depend on the ``all`` target. By default, the ``install`` target depends on the ``all`` target. This has the effect, that when ``make install`` is invoked or ``INSTALL`` is built, first the ``all`` target is built, then the installation starts. -If :variable:`CMAKE_SKIP_INSTALL_ALL_DEPENDENCY` is set to ``TRUE``, this +If ``CMAKE_SKIP_INSTALL_ALL_DEPENDENCY`` is set to ``TRUE``, this dependency is not created, so the installation process will start immediately, independent from whether the project has been completely built or not. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst index cc0ac21ee3..465fdae58c 100644 --- a/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst +++ b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst @@ -10,5 +10,10 @@ install RPATH. If this variable is set to true then the software is always installed without RPATH, even if RPATH is enabled when building. This can be useful for example to allow running tests from the build directory with RPATH enabled before the installation step. + +See also the :variable:`CMAKE_SKIP_BUILD_RPATH` variable. To omit RPATH in both the build and install steps, use :variable:`CMAKE_SKIP_RPATH` instead. + +For more information on RPATH handling see the :prop_tgt:`INSTALL_RPATH` +and :prop_tgt:`BUILD_RPATH` target properties. diff --git a/Help/variable/CMAKE_SKIP_RPATH.rst b/Help/variable/CMAKE_SKIP_RPATH.rst index d7ce8e43d7..43f6401cc3 100644 --- a/Help/variable/CMAKE_SKIP_RPATH.rst +++ b/Help/variable/CMAKE_SKIP_RPATH.rst @@ -7,4 +7,8 @@ If this is set to ``TRUE``, then the rpath information is not added to compiled executables. The default is to add rpath information if the platform supports it. This allows for easy running from the build tree. To omit RPATH in the install step, but not the build step, use -:variable:`CMAKE_SKIP_INSTALL_RPATH` instead. +:variable:`CMAKE_SKIP_INSTALL_RPATH` instead. To omit RPATH in the build step, +use :variable:`CMAKE_SKIP_BUILD_RPATH`. + +For more information on RPATH handling see the :prop_tgt:`INSTALL_RPATH` +and :prop_tgt:`BUILD_RPATH` target properties. diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst index 7210f75c51..f1d1beef4b 100644 --- a/Help/variable/CMAKE_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -8,6 +8,6 @@ tree. For an in-source build, this would be the same as :variable:`CMAKE_BINARY_DIR`. When run in :option:`cmake -P` script mode, CMake sets the variables -:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, +:variable:`CMAKE_BINARY_DIR`, ``CMAKE_SOURCE_DIR``, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_STAGING_PREFIX.rst b/Help/variable/CMAKE_STAGING_PREFIX.rst index bdb97faef2..7b1048bdc6 100644 --- a/Help/variable/CMAKE_STAGING_PREFIX.rst +++ b/Help/variable/CMAKE_STAGING_PREFIX.rst @@ -5,10 +5,10 @@ This variable may be set to a path to install to when cross-compiling. This can be useful if the path in :variable:`CMAKE_SYSROOT` is read-only, or otherwise should remain pristine. -The :variable:`CMAKE_STAGING_PREFIX` location is also used as a search prefix +The ``CMAKE_STAGING_PREFIX`` location is also used as a search prefix by the ``find_*`` commands. This can be controlled by setting the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. If any ``RPATH``/``RUNPATH`` entries passed to the linker contain the -:variable:`CMAKE_STAGING_PREFIX`, the matching path fragments are replaced +``CMAKE_STAGING_PREFIX``, the matching path fragments are replaced with the :variable:`CMAKE_INSTALL_PREFIX`. diff --git a/Help/variable/CMAKE_TASKING_TOOLSET.rst b/Help/variable/CMAKE_TASKING_TOOLSET.rst index 6bd14798d7..53b2c09e27 100644 --- a/Help/variable/CMAKE_TASKING_TOOLSET.rst +++ b/Help/variable/CMAKE_TASKING_TOOLSET.rst @@ -14,7 +14,7 @@ the compiler features correctly. If no toolset is specified, Due to the different versioning schemes, the compiler version (:variable:`CMAKE_<LANG>_COMPILER_VERSION`) depends on the toolset and architecture in use. If projects can be built with multiple toolsets or -architectures, the specified :variable:`CMAKE_TASKING_TOOLSET` and the +architectures, the specified ``CMAKE_TASKING_TOOLSET`` and the automatically determined :variable:`CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID` must be taken into account when comparing against the :variable:`CMAKE_<LANG>_COMPILER_VERSION`. diff --git a/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst new file mode 100644 index 0000000000..f86ed7c150 --- /dev/null +++ b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst @@ -0,0 +1,14 @@ +CMAKE_VS_VERSION_BUILD_NUMBER +----------------------------- + +.. versionadded:: 3.26 + +Visual Studio version. + +:ref:`Visual Studio Generators` for VS 2017 and above set this +variable to the Visual Studio version build number in the format +``<major>.<minor>.<date>.<build>``. + +.. include:: CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt + +See also the :variable:`CMAKE_GENERATOR_INSTANCE` variable. diff --git a/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt new file mode 100644 index 0000000000..6bdede71d2 --- /dev/null +++ b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt @@ -0,0 +1,18 @@ +The components are: + +``<major>.<minor>`` + + The VS major and minor version numbers. + These are the same as the release version numbers. + +``<date>`` + + A build date in the format ``MMMDD``, where ``MMM`` is a month index + since an epoch used by Microsoft, and ``DD`` is a day in that month. + +``<build>`` + + A build index on the day represented by ``<date>``. + +The build number is reported by ``vswhere`` as ``installationVersion``. +For example, VS 16.11.10 has build number ``16.11.32126.315``. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst index d9f136c609..f1a1977448 100644 --- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst @@ -5,7 +5,7 @@ CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM Override the :ref:`Windows 10 SDK Maximum Version for VS 2015` and beyond. -The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable may +The ``CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`` variable may be set to a false value (e.g. ``OFF``, ``FALSE``, or ``0``) or the SDK version to use as the maximum (e.g. ``10.0.14393.0``). If unset, the default depends on which version of Visual Studio is targeted by the current generator. diff --git a/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst index cd65ae3279..b8ea1e998a 100644 --- a/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst +++ b/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst @@ -2,6 +2,6 @@ CTEST_CUSTOM_ERROR_EXCEPTION ---------------------------- A list of regular expressions which will be used to exclude when detecting -error messages in build outputs by the :command:`ctest_test` command. +error messages in build outputs by the :command:`ctest_build` command. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst b/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst index 558f5e5801..e8f4ad4230 100644 --- a/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst +++ b/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst @@ -2,6 +2,6 @@ CTEST_CUSTOM_ERROR_MATCH ------------------------ A list of regular expressions which will be used to detect error messages in -build outputs by the :command:`ctest_test` command. +build outputs by the :command:`ctest_build` command. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst b/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst index 614859bc82..31c99e7785 100644 --- a/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst +++ b/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst @@ -2,6 +2,6 @@ CTEST_CUSTOM_ERROR_POST_CONTEXT ------------------------------- The number of lines to include as context which follow an error message by the -:command:`ctest_test` command. The default is 10. +:command:`ctest_build` command. The default is 10. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst b/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst index 74dc47ad2a..ae03a5c980 100644 --- a/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst +++ b/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst @@ -2,6 +2,6 @@ CTEST_CUSTOM_ERROR_PRE_CONTEXT ------------------------------ The number of lines to include as context which precede an error message by -the :command:`ctest_test` command. The default is 10. +the :command:`ctest_build` command. The default is 10. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/GHSMULTI.rst b/Help/variable/GHSMULTI.rst index 3daef5ddfb..7a90b8401b 100644 --- a/Help/variable/GHSMULTI.rst +++ b/Help/variable/GHSMULTI.rst @@ -6,4 +6,4 @@ GHSMULTI ``1`` when using :generator:`Green Hills MULTI` generator. Also, Set to ``1`` when the target system is a Green Hills platform -(i.e. When CMAKE_SYSTEM_NAME is ``GHS-MULTI``). +(i.e. When :variable:`CMAKE_SYSTEM_NAME` is ``GHS-MULTI``). diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt index aea1be8f62..9158631e99 100644 --- a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -49,14 +49,14 @@ * ``[/path/to/]FwName.framework/Versions/*/FwName[suffix]`` Note that CMake recognizes and automatically handles framework targets, - even without using the ``$<LINK_LIBRARY:FRAMEWORK,...>`` expression. + even without using the :genex:`$<LINK_LIBRARY:FRAMEWORK,...>` expression. The generator expression can still be used with a CMake target if the project wants to be explicit about it, but it is not required to do so. The linker command line may have some differences between using the generator expression or not, but the final result should be the same. On the other hand, if a file path is given, CMake will recognize some paths automatically, but not all cases. The project may want to use - ``$<LINK_LIBRARY:FRAMEWORK,...>`` for file paths so that the expected + :genex:`$<LINK_LIBRARY:FRAMEWORK,...>` for file paths so that the expected behavior is clear. .. versionadded:: 3.25 diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst index 98ba20e080..6b17be3bad 100644 --- a/Help/variable/PackageName_ROOT.rst +++ b/Help/variable/PackageName_ROOT.rst @@ -5,10 +5,10 @@ Calls to :command:`find_package(<PackageName>)` will search in prefixes specified by the ``<PackageName>_ROOT`` CMake variable, where -``<PackageName>`` is the name given to the :command:`find_package` call -and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search -prefixes specified in the ``Foo_ROOT`` CMake variable (if set). -See policy :policy:`CMP0074`. +``<PackageName>`` is the (case-preserved) name given to the +:command:`find_package` call and ``_ROOT`` is literal. +For example, ``find_package(Foo)`` will search prefixes specified in the +``Foo_ROOT`` CMake variable (if set). See policy :policy:`CMP0074`. This variable may hold a single prefix or a :ref:`semicolon-separated list <CMake Language Lists>` of multiple prefixes. |