diff options
Diffstat (limited to 'Help')
20 files changed, 175 insertions, 21 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index b45a079..ec73f9f 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -271,9 +271,47 @@ The options are: ``DEPFILE`` .. versionadded:: 3.7 - Specify a ``.d`` depfile which holds dependencies for the custom command. - It is usually emitted by the custom command itself. This keyword may only - be used if the generator supports it, as detailed below. + Specify a depfile which holds dependencies for the custom command. It is + usually emitted by the custom command itself. This keyword may only be used + if the generator supports it, as detailed below. + + The expected format, compatible with what is generated by ``gcc`` with the + option ``-M``, is independent of the generator or platform. + + The formal syntax, as specified using + `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with + the regular extensions, is the following: + + .. raw:: latex + + \begin{small} + + .. productionlist:: depfile + depfile: `rule`* + rule: `targets` (`:` (`separator` `dependencies`?)?)? `eol` + targets: `target` (`separator` `target`)* `separator`* + target: `pathname` + dependencies: `dependency` (`separator` `dependency`)* `separator`* + dependency: `pathname` + separator: (space | line_continue)+ + line_continue: '\' `eol` + space: ' ' | '\t' + pathname: `character`+ + character: `std_character` | `dollar` | `hash` | `whitespace` + std_character: <any character except '$', '#' or ' '> + dollar: '$$' + hash: '\#' + whitespace: '\ ' + eol: '\r'? '\n' + + .. raw:: latex + + \end{small} + + .. note:: + + As part of ``pathname``, any slash and backslash is interpreted as + a directory separator. .. versionadded:: 3.7 The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 8f7439b..cd75dea 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -8,8 +8,9 @@ Define and document custom properties. define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | TEST | VARIABLE | CACHED_VARIABLE> PROPERTY <name> [INHERITED] - BRIEF_DOCS <brief-doc> [docs...] - FULL_DOCS <full-doc> [docs...]) + [BRIEF_DOCS <brief-doc> [docs...]] + [FULL_DOCS <full-doc> [docs...]] + [INITIALIZE_FROM_VARIABLE <variable>]) Defines one property in a scope for use with the :command:`set_property` and :command:`get_property` commands. This is primarily useful to associate @@ -57,3 +58,12 @@ The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be associated with the property as its brief and full documentation. Corresponding options to the :command:`get_property` command will retrieve the documentation. + +.. versionchanged:: 3.23 + + The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional. + +The ``INITIALIZE_FROM_VARIABLE`` option is followed by the name of a variable +from which to initialize the property. The variable name must end with the +property name, must have a prefix before the property name, and must not begin +with ``CMAKE_`` or ``_CMAKE_``. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index 1f05618..b4ef5a2 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -54,6 +54,27 @@ on macOS: Default behavior is to include a symlink to ``/Applications`` in the DMG. Set this option to ``ON`` to avoid adding the symlink. +.. variable:: CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE + + .. versionadded:: 3.23 + + 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 + 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`` + is automatically enabled by default if it is not set and + :variable:`CPACK_RESOURCE_FILE_LICENSE` is set to a non-default value. + + .. note:: + + This option was added in response to macOS 12.0's deprecation of + the ``hdiutil udifrez`` command to make its use optional. + CPack 3.22 and below always use :variable:`CPACK_RESOURCE_FILE_LICENSE`, + if set to a non-default value, as the DMG license. + .. variable:: CPACK_DMG_SLA_DIR .. versionadded:: 3.5 diff --git a/Help/envvar/CUDAARCHS.rst b/Help/envvar/CUDAARCHS.rst index 82369cd..e9e6a42 100644 --- a/Help/envvar/CUDAARCHS.rst +++ b/Help/envvar/CUDAARCHS.rst @@ -6,8 +6,7 @@ CUDAARCHS .. include:: ENV_VAR.txt Value used to initialize :variable:`CMAKE_CUDA_ARCHITECTURES` on the first -configuration if it's not already defined. Subsequent runs will use the value -stored in the cache. +configuration. Subsequent runs will use the value stored in the cache. This is a semicolon-separated list of architectures as described in :prop_tgt:`CUDA_ARCHITECTURES`. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst index cf65927..74f5d48 100644 --- a/Help/envvar/CUDAHOSTCXX.rst +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -8,9 +8,8 @@ CUDAHOSTCXX Preferred executable for compiling host code when compiling ``CUDA`` language files. Will only be used by CMake on the first configuration to determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is -stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any -configuration run (including the first), the environment variable will be -ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. +stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment +variable is preferred over :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment variable is primarily meant for use with projects that enable ``CUDA`` as a first-class language. diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index 0d818c2..8473481 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst @@ -130,3 +130,31 @@ obtain this information and use it to present the user with a list of tests. IDEs should not invoke the ``test`` target of the generated buildsystem. Instead, they should invoke :manual:`ctest(1)` directly. + +IDEs with CMake integration +=========================== + +The following IDEs support CMake natively: + +* `CLion`_ +* `KDevelop`_ +* `QtCreator`_ +* `Vim`_ (via a plugin) +* `Visual Studio`_ +* `VSCode`_ (via a plugin) + +.. _CLion: https://www.jetbrains.com/clion/ +.. _KDevelop: https://www.kdevelop.org/ +.. _QtCreator: https://www.qt.io/product/development-tools +.. _Vim: https://www.vim.org/ +.. _Visual Studio: https://visualstudio.microsoft.com/ +.. _VSCode: https://code.visualstudio.com/ + +Additionally, CMake has builtin support for some IDEs: + +* :ref:`IDE Build Tool Generators`: + Generate IDE native build systems such as Visual Studio or Xcode. +* :ref:`Extra Generators`: + Extend :ref:`Command-Line Build Tool Generators` to generate IDE + project files that hook into the command-line build system. + Superseded by the :manual:`File API <cmake-file-api(7)>`. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 663b18d..034e218 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -102,6 +102,8 @@ Other Generators /generator/Green Hills MULTI /generator/Xcode +.. _`Extra Generators`: + Extra Generators ================ diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index b43c915..31bd9c0 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -37,10 +37,9 @@ a file may be included multiple times from the same file or from different files. If ``CMakePresets.json`` and ``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json`` implicitly includes ``CMakePresets.json``, even with no ``include`` field, in all versions of the format. Files directly or -indirectly included from ``CMakePresets.json`` must be inside the project -directory. This restriction does not apply to ``CMakeUserPresets.json`` and -files that it includes, unless those files are also included by -``CMakePresets.json``. +indirectly included from ``CMakePresets.json`` should be guaranteed to be +provided by the project. ``CMakeUserPresets.json`` may include files from +anywhere. Format ====== diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 8c43c22..04c5a53 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -582,8 +582,6 @@ Variables for Languages /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE /variable/CMAKE_LANG_LINK_EXECUTABLE - /variable/CMAKE_LANG_LINKER_PREFERENCE - /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_OUTPUT_EXTENSION @@ -728,6 +726,8 @@ are subject to change, and not recommended for use in project code. /variable/CMAKE_LANG_COMPILER_ABI /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL + /variable/CMAKE_LANG_LINKER_PREFERENCE + /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION diff --git a/Help/prop_tgt/DEPRECATION.rst b/Help/prop_tgt/DEPRECATION.rst index 45ca848..2945c98 100644 --- a/Help/prop_tgt/DEPRECATION.rst +++ b/Help/prop_tgt/DEPRECATION.rst @@ -7,3 +7,8 @@ Deprecation message from imported target's developer. ``DEPRECATION`` is the message regarding a deprecation status to be displayed to downstream users of a target. + +The message is formatted as follows: + +* Lines that do not start in whitespace are wrapped as paragraph text. +* Lines that start in whitespace are preserved as preformatted text. diff --git a/Help/prop_tgt/LANG_STANDARD.rst b/Help/prop_tgt/LANG_STANDARD.rst index bd377ec..c83da01 100644 --- a/Help/prop_tgt/LANG_STANDARD.rst +++ b/Help/prop_tgt/LANG_STANDARD.rst @@ -15,6 +15,13 @@ newer standard is specified than is supported by the compiler, then it will fallback to the latest supported standard. This "decay" behavior may be controlled with the :prop_tgt:`<LANG>_STANDARD_REQUIRED` target property. +Note that the actual language standard used may be higher than that specified +by ``<LANG>_STANDARD``, regardless of the value of +:prop_tgt:`<LANG>_STANDARD_REQUIRED`. In particular, +:ref:`transitive usage requirements <Target Usage Requirements>` or the use of +:manual:`compile features <cmake-compile-features(7)>` can raise the required +language standard above what ``<LANG>_STANDARD`` specifies. + These properties are initialized by the value of the :variable:`CMAKE_<LANG>_STANDARD` variable if it is set when a target is created. diff --git a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst index 56ecef8..e61125b 100644 --- a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst @@ -11,16 +11,22 @@ The variations are: * :prop_tgt:`OBJCXX_STANDARD_REQUIRED` These properties specify whether the value of :prop_tgt:`<LANG>_STANDARD` is a -requirement. When ``OFF`` or unset, the :prop_tgt:`<LANG>_STANDARD` target +requirement. When false or unset, the :prop_tgt:`<LANG>_STANDARD` target property is treated as optional and may "decay" to a previous standard if the -requested is not available. +requested standard is not available. When ``<LANG>_STANDARD_REQUIRED`` is set +to true, :prop_tgt:`<LANG>_STANDARD` becomes a hard requirement and a fatal +error will be issued if that requirement cannot be met. + +Note that the actual language standard used may be higher than that specified +by :prop_tgt:`<LANG>_STANDARD`, regardless of the value of +``<LANG>_STANDARD_REQUIRED``. In particular, +:ref:`transitive usage requirements <Target Usage Requirements>` or the use of +:manual:`compile features <cmake-compile-features(7)>` can raise the required +language standard above what :prop_tgt:`<LANG>_STANDARD` specifies. These properties are initialized by the value of the :variable:`CMAKE_<LANG>_STANDARD_REQUIRED` variable if it is set when a target is created. -For supported CMake versions see the respective pages. -To control language standard versions see :prop_tgt:`<LANG>_STANDARD`. - See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/release/dev/CheckPIESupported-supports-SYSROOT.rst b/Help/release/dev/CheckPIESupported-supports-SYSROOT.rst new file mode 100644 index 0000000..0f7f7de --- /dev/null +++ b/Help/release/dev/CheckPIESupported-supports-SYSROOT.rst @@ -0,0 +1,6 @@ +CheckPIESupported-supports-SYSROOT +---------------------------------- + +* The :module:`CheckPIESupported` module now takes care of any ``SYSROOT`` + settings and gains the support of ``OBJC``, ``OBJCXX``, ``CUDA``, and ``HIP`` + languages. diff --git a/Help/release/dev/FindCUDAToolkit-target-for-cufft_static_nocallback.rst b/Help/release/dev/FindCUDAToolkit-target-for-cufft_static_nocallback.rst new file mode 100644 index 0000000..91c3feb --- /dev/null +++ b/Help/release/dev/FindCUDAToolkit-target-for-cufft_static_nocallback.rst @@ -0,0 +1,5 @@ +FindCUDAToolkit-target-for-cufft_static_nocallback +-------------------------------------------------- + +* The :module:`FindCUDAToolkit` module now provides a target for + ``libcufft_static_nocallback``, if found. diff --git a/Help/release/dev/ccmake-windows.rst b/Help/release/dev/ccmake-windows.rst new file mode 100644 index 0000000..acb6d29 --- /dev/null +++ b/Help/release/dev/ccmake-windows.rst @@ -0,0 +1,6 @@ +ccmake-windows +-------------- + +* :manual:`ccmake(1)` may now be enabled on Windows when building + CMake from source. This is experimental, and so is not included + in official distributions. diff --git a/Help/release/dev/cpack-dmg-sla.rst b/Help/release/dev/cpack-dmg-sla.rst new file mode 100644 index 0000000..c6a3596 --- /dev/null +++ b/Help/release/dev/cpack-dmg-sla.rst @@ -0,0 +1,9 @@ +cpack-dmg-sla +------------- + +* The :cpack_gen:`CPack DragNDrop Generator` no longer attaches + :variable:`CPACK_RESOURCE_FILE_LICENSE` as the license agreement in + the generated ``.dmg`` unless explicitly activated by a + :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option. + In CMake projects, the :module:`CPack` module enables the option + by default for compatibility. diff --git a/Help/release/dev/define-property-optional-args.rst b/Help/release/dev/define-property-optional-args.rst new file mode 100644 index 0000000..b1cbf5e --- /dev/null +++ b/Help/release/dev/define-property-optional-args.rst @@ -0,0 +1,5 @@ +define-property-optional-args +----------------------------- + +* The :command:`define_property` ``BRIEF_DOCS`` and ``FULL_DOCS`` arguments are + now optional. diff --git a/Help/release/dev/target-properties-from-variables.rst b/Help/release/dev/target-properties-from-variables.rst new file mode 100644 index 0000000..99857c4 --- /dev/null +++ b/Help/release/dev/target-properties-from-variables.rst @@ -0,0 +1,5 @@ +target-properties-from-variables +-------------------------------- + +* The :command:`define_property` command gained a new + ``INITIALIZE_FROM_VARIABLE`` argument. diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst index ff82f8b..a4035bd 100644 --- a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst @@ -1,6 +1,8 @@ CMAKE_<LANG>_LINKER_PREFERENCE ------------------------------ +An internal variable subject to change. + Preference value for linker language selection. The "linker language" for executable, shared library, and module diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst index dbbeb0a..df33edb 100644 --- a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst @@ -1,6 +1,8 @@ CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES ----------------------------------------- +An internal variable subject to change. + True if :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` propagates across targets. This is used when CMake selects a linker language for a target. |