diff options
Diffstat (limited to 'Help')
94 files changed, 1700 insertions, 306 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 5fe4326..2bb1390 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -373,6 +373,11 @@ The options are: :manual:`generator expressions <cmake-generator-expressions(7)>` was also added. + .. versionadded:: 3.29 + The :ref:`Ninja Generators` will now incorporate the dependencies into its + "deps log" database if the file is not listed in ``OUTPUTS`` or + ``BYPRODUCTS``. + Using ``DEPFILE`` with generators other than those listed above is an error. If the ``DEPFILE`` argument is relative, it should be relative to diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index d9ea0da..b6833b4 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -10,15 +10,28 @@ Add an executable to the project using the specified source files. Normal Executables ^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake +.. signature:: + add_executable(<name> <options>... <sources>...) + :target: normal - add_executable(<name> [WIN32] [MACOSX_BUNDLE] - [EXCLUDE_FROM_ALL] - [source1] [source2 ...]) + Add an executable target called ``<name>`` to be built from the source + files listed in the command invocation. -Adds an executable target called ``<name>`` to be built from the source -files listed in the command invocation. The -``<name>`` corresponds to the logical target name and must be globally + The options are: + + ``WIN32`` + Set the :prop_tgt:`WIN32_EXECUTABLE` target property automatically. + See documentation of that target property for details. + + ``MACOSX_BUNDLE`` + Set the :prop_tgt:`MACOSX_BUNDLE` target property automatically. + See documentation of that target property for details. + + ``EXCLUDE_FROM_ALL`` + Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically. + See documentation of that target property for details. + +The ``<name>`` corresponds to the logical target name and must be globally unique within a project. The actual file name of the executable built is constructed based on conventions of the native platform (such as ``<name>.exe`` or just ``<name>``). @@ -39,18 +52,6 @@ command was invoked. See documentation of the location. See documentation of the :prop_tgt:`OUTPUT_NAME` target property to change the ``<name>`` part of the final file name. -If ``WIN32`` is given the property :prop_tgt:`WIN32_EXECUTABLE` will be -set on the target created. See documentation of that target property for -details. - -If ``MACOSX_BUNDLE`` is given the corresponding property will be set on -the created target. See documentation of the :prop_tgt:`MACOSX_BUNDLE` -target property for details. - -If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on -the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` -target property for details. - See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. @@ -61,17 +62,25 @@ within IDE. Imported Executables ^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: add_executable(<name> IMPORTED [GLOBAL]) + :target: IMPORTED + + Add an :ref:`IMPORTED executable target <Imported Targets>` to reference + an executable file located outside the project. The target name may be + referenced like any target built within the project, except that by + default it is visible only in the directory in which it is created, + and below. + + The options are: + + ``GLOBAL`` + Make the target name globally visible. + +No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED` +target property is ``True``. Imported executables are useful for convenient +reference from commands like :command:`add_custom_command`. -An :ref:`IMPORTED executable target <Imported Targets>` references an -executable file located outside the project. No rules are generated to -build it, and the :prop_tgt:`IMPORTED` target property is ``True``. The -target name has scope in the directory in which it is created and below, but -the ``GLOBAL`` option extends visibility. It may be referenced like any -target built within the project. ``IMPORTED`` executables are useful -for convenient reference from commands like :command:`add_custom_command`. Details about the imported executable are specified by setting properties whose names begin in ``IMPORTED_``. The most important such property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration version @@ -82,14 +91,14 @@ properties for more information. Alias Executables ^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: add_executable(<name> ALIAS <target>) + :target: ALIAS -Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can -be used to refer to ``<target>`` in subsequent commands. The ``<name>`` -does not appear in the generated buildsystem as a make target. The -``<target>`` may not be an ``ALIAS``. + Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can + be used to refer to ``<target>`` in subsequent commands. The ``<name>`` + does not appear in the generated buildsystem as a make target. The + ``<target>`` may not be an ``ALIAS``. .. versionadded:: 3.11 An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>` diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 07c8bab..5b22cb1 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -10,18 +10,39 @@ Add a library to the project using the specified source files. Normal Libraries ^^^^^^^^^^^^^^^^ -.. code-block:: cmake +.. signature:: + add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...) + :target: normal + + Add a library target called ``<name>`` to be built from the source files + listed in the command invocation. + + The optional ``<type>`` specifies the type of library to be created: + + ``STATIC`` + An archive of object files for use when linking other targets. + + ``SHARED`` + A dynamic library that may be linked by other targets and loaded + at runtime. + + ``MODULE`` + A plugin that may not be linked by other targets, but may be + dynamically loaded at runtime using dlopen-like functionality. + + If no ``<type>`` is given the default is ``STATIC`` or ``SHARED`` + based on the value of the :variable:`BUILD_SHARED_LIBS` variable. - add_library(<name> [STATIC | SHARED | MODULE] - [EXCLUDE_FROM_ALL] - [<source>...]) + The options are: -Adds a library target called ``<name>`` to be built from the source files -listed in the command invocation. The ``<name>`` -corresponds to the logical target name and must be globally unique within -a project. The actual file name of the library built is constructed based -on conventions of the native platform (such as ``lib<name>.a`` or -``<name>.lib``). + ``EXCLUDE_FROM_ALL`` + Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically. + See documentation of that target property for details. + +The ``<name>`` corresponds to the logical target name and must be globally +unique within a project. The actual file name of the library built is +constructed based on conventions of the native platform (such as +``lib<name>.a`` or ``<name>.lib``). .. versionadded:: 3.1 Source arguments to ``add_library`` may use "generator expressions" with @@ -32,15 +53,8 @@ on conventions of the native platform (such as ``lib<name>.a`` or The source files can be omitted if they are added later using :command:`target_sources`. -``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of -library to be created. ``STATIC`` libraries are archives of object files -for use when linking other targets. ``SHARED`` libraries are linked -dynamically and loaded at runtime. ``MODULE`` libraries are plugins that -are not linked into other targets but may be loaded dynamically at runtime -using dlopen-like functionality. If no type is given explicitly the -type is ``STATIC`` or ``SHARED`` based on whether the current value of the -variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and -``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target +For ``SHARED`` and ``MODULE`` libraries the +:prop_tgt:`POSITION_INDEPENDENT_CODE` target property is set to ``ON`` automatically. A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` target property to create an macOS Framework. @@ -63,10 +77,6 @@ invoked. See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, location. See documentation of the :prop_tgt:`OUTPUT_NAME` target property to change the ``<name>`` part of the final file name. -If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on -the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` -target property for details. - See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. @@ -77,14 +87,15 @@ within IDE. Object Libraries ^^^^^^^^^^^^^^^^ -.. code-block:: cmake +.. signature:: + add_library(<name> OBJECT <sources>...) + :target: OBJECT - add_library(<name> OBJECT [<source>...]) + Add an :ref:`Object Library <Object Libraries>` to compile source files + without archiving or linking their object files into a library. -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 ``add_library`` or -:command:`add_executable` may reference the objects using an expression of the +Other targets created by ``add_library`` or :command:`add_executable` +may reference the objects using an expression of the form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where ``objlib`` is the object library name. For example: @@ -109,46 +120,48 @@ consider adding at least one real source file to any target that references Interface Libraries ^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: add_library(<name> INTERFACE) - -Creates an :ref:`Interface Library <Interface Libraries>`. -An ``INTERFACE`` library target does not compile sources and does -not produce a library artifact on disk. However, it may have -properties set on it and it may be installed and exported. -Typically, ``INTERFACE_*`` properties are populated on an interface -target using the commands: - -* :command:`set_property`, -* :command:`target_link_libraries(INTERFACE)`, -* :command:`target_link_options(INTERFACE)`, -* :command:`target_include_directories(INTERFACE)`, -* :command:`target_compile_options(INTERFACE)`, -* :command:`target_compile_definitions(INTERFACE)`, and -* :command:`target_sources(INTERFACE)`, - -and then it is used as an argument to :command:`target_link_libraries` -like any other target. - -An interface library created with the above signature has no source files -itself and is not included as a target in the generated buildsystem. - -.. versionadded:: 3.15 - An interface library can have :prop_tgt:`PUBLIC_HEADER` and - :prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those - properties can be installed using the :command:`install(TARGETS)` command. - -.. versionadded:: 3.19 - An interface library target may be created with source files: - - .. code-block:: cmake - - add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL]) - - Source files may be listed directly in the ``add_library`` call or added - later by calls to :command:`target_sources` with the ``PRIVATE`` or - ``PUBLIC`` keywords. + :target: INTERFACE + + Add an :ref:`Interface Library <Interface Libraries>` target that may + specify usage requirements for dependents but does not compile sources + and does not produce a library artifact on disk. + + An interface library with no source files is not included as a target + in the generated buildsystem. However, it may have + properties set on it and it may be installed and exported. + Typically, ``INTERFACE_*`` properties are populated on an interface + target using the commands: + + * :command:`set_property`, + * :command:`target_link_libraries(INTERFACE)`, + * :command:`target_link_options(INTERFACE)`, + * :command:`target_include_directories(INTERFACE)`, + * :command:`target_compile_options(INTERFACE)`, + * :command:`target_compile_definitions(INTERFACE)`, and + * :command:`target_sources(INTERFACE)`, + + and then it is used as an argument to :command:`target_link_libraries` + like any other target. + + .. versionadded:: 3.15 + An interface library can have :prop_tgt:`PUBLIC_HEADER` and + :prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those + properties can be installed using the :command:`install(TARGETS)` command. + +.. signature:: + add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...) + :target: INTERFACE-with-sources + + .. versionadded:: 3.19 + + Add an :ref:`Interface Library <Interface Libraries>` target with + source files (in addition to usage requirements and properties as + documented by the :command:`above signature <add_library(INTERFACE)>`). + Source files may be listed directly in the ``add_library`` call + or added later by calls to :command:`target_sources` with the + ``PRIVATE`` or ``PUBLIC`` keywords. If an interface library has source files (i.e. the :prop_tgt:`SOURCES` target property is set), or header sets (i.e. the :prop_tgt:`HEADER_SETS` @@ -158,92 +171,106 @@ itself and is not included as a target in the generated buildsystem. but does contain build rules for custom commands created by the :command:`add_custom_command` command. -.. note:: - In most command signatures where the ``INTERFACE`` keyword appears, - the items listed after it only become part of that target's usage - requirements and are not part of the target's own settings. However, - in this signature of ``add_library``, the ``INTERFACE`` keyword refers - to the library type only. Sources listed after it in the ``add_library`` - call are ``PRIVATE`` to the interface library and do not appear in its - :prop_tgt:`INTERFACE_SOURCES` target property. + The options are: + + ``EXCLUDE_FROM_ALL`` + Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically. + See documentation of that target property for details. + + .. note:: + In most command signatures where the ``INTERFACE`` keyword appears, + the items listed after it only become part of that target's usage + requirements and are not part of the target's own settings. However, + in this signature of ``add_library``, the ``INTERFACE`` keyword refers + to the library type only. Sources listed after it in the ``add_library`` + call are ``PRIVATE`` to the interface library and do not appear in its + :prop_tgt:`INTERFACE_SOURCES` target property. .. _`add_library imported libraries`: Imported Libraries ^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: add_library(<name> <type> IMPORTED [GLOBAL]) - -Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``. -No rules are generated to build it, and the :prop_tgt:`IMPORTED` target -property is ``True``. The target name has scope in the directory in which -it is created and below, but the ``GLOBAL`` option extends visibility. -It may be referenced like any target built within the project. -``IMPORTED`` libraries are useful for convenient reference from commands -like :command:`target_link_libraries`. Details about the imported library -are specified by setting properties whose names begin in ``IMPORTED_`` and -``INTERFACE_``. - -The ``<type>`` must be one of: - -``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN`` - References a library file located outside the project. The - :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration - variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the - location of the main library file on disk: - - * For a ``SHARED`` library on most non-Windows platforms, the main library - file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic - loaders. If the referenced library file has a ``SONAME`` (or on macOS, - has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field - should be set in the :prop_tgt:`IMPORTED_SONAME` target property. - If the referenced library file does not have a ``SONAME``, but the - platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target - property should be set. - - * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB` - target property (or its per-configuration variant - :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the - DLL import library file (``.lib`` or ``.dll.a``) on disk, and the - ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime - library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS` - generator expression). - - Additional usage requirements may be specified in ``INTERFACE_*`` properties. - - An ``UNKNOWN`` library type is typically only used in the implementation of - :ref:`Find Modules`. It allows the path to an imported library (often found - using the :command:`find_library` command) to be used without having to know - what type of library it is. This is especially useful on Windows where a - static library and a DLL's import library both have the same file extension. - -``OBJECT`` - References a set of object files located outside the project. - The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration - variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of - object files on disk. - Additional usage requirements may be specified in ``INTERFACE_*`` properties. - -``INTERFACE`` - Does not reference any library or object files on disk, but may - specify usage requirements in ``INTERFACE_*`` properties. - -See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties -for more information. + :target: IMPORTED + + Add an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``. + The target name may be referenced like any target built within the project, + except that by default it is visible only in the directory in which it is + created, and below. + + The ``<type>`` must be one of: + + ``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN`` + References a library file located outside the project. The + :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration + variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the + location of the main library file on disk: + + * For a ``SHARED`` library on most non-Windows platforms, the main library + file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic + loaders. If the referenced library file has a ``SONAME`` (or on macOS, + has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field + should be set in the :prop_tgt:`IMPORTED_SONAME` target property. + If the referenced library file does not have a ``SONAME``, but the + platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target + property should be set. + + * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB` + target property (or its per-configuration variant + :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the + DLL import library file (``.lib`` or ``.dll.a``) on disk, and the + ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime + library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS` + generator expression). + + Additional usage requirements may be specified in ``INTERFACE_*`` + properties. + + An ``UNKNOWN`` library type is typically only used in the implementation + of :ref:`Find Modules`. It allows the path to an imported library + (often found using the :command:`find_library` command) to be used + without having to know what type of library it is. This is especially + useful on Windows where a static library and a DLL's import library + both have the same file extension. + + ``OBJECT`` + References a set of object files located outside the project. + The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration + variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of + object files on disk. + Additional usage requirements may be specified in ``INTERFACE_*`` + properties. + + ``INTERFACE`` + Does not reference any library or object files on disk, but may + specify usage requirements in ``INTERFACE_*`` properties. + + The options are: + + ``GLOBAL`` + Make the target name globally visible. + +No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED` +target property is ``True``. Imported libraries are useful for convenient +reference from commands like :command:`target_link_libraries`. + +Details about the imported library are specified by setting properties whose +names begin in ``IMPORTED_`` and ``INTERFACE_``. See documentation of +such properties for more information. Alias Libraries ^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: add_library(<name> ALIAS <target>) + :target: ALIAS -Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be -used to refer to ``<target>`` in subsequent commands. The ``<name>`` does -not appear in the generated buildsystem as a make target. The ``<target>`` -may not be an ``ALIAS``. + Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be + used to refer to ``<target>`` in subsequent commands. The ``<name>`` does + not appear in the generated buildsystem as a make target. The ``<target>`` + may not be an ``ALIAS``. .. versionadded:: 3.11 An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>` diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 02dd3986..557c858 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -27,9 +27,37 @@ directory the test is created in. ``add_test`` options are: ``COMMAND`` - Specify the test command-line. If ``<command>`` specifies an executable - target created by :command:`add_executable`, it will automatically be - replaced by the location of the executable created at build time. + Specify the test command-line. + + If ``<command>`` specifies an executable target created by + :command:`add_executable`: + + * It will automatically be replaced by the location of the executable + created at build time. + + * .. versionadded:: 3.3 + + The target's :prop_tgt:`CROSSCOMPILING_EMULATOR`, if set, will be + used to run the command on the host:: + + <emulator> <command> + + .. versionchanged:: 3.29 + + The emulator is used only when + :variable:`cross-compiling <CMAKE_CROSSCOMPILING>`. + See policy :policy:`CMP0158`. + + * .. versionadded:: 3.29 + + The target's :prop_tgt:`TEST_LAUNCHER`, if set, will be + used to launch the command:: + + <launcher> <command> + + If the :prop_tgt:`CROSSCOMPILING_EMULATOR` is also set, both are used:: + + <launcher> <emulator> <command> The command may be specified using :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index dad0833..0d2f75e 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -265,7 +265,7 @@ Example: .. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes. -.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html +.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/latest/os-release.html .. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html .. _Query Windows registry: diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 3af6b9c..4b64eb6 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -317,7 +317,7 @@ be one of the ``<methods>`` that was specified when setting the provider. implementation as part of its processing, it can do so by including the ``BYPASS_PROVIDER`` keyword as one of the arguments. -``FETCHCONTENT_MAKEAVAILABE_SERIAL`` +``FETCHCONTENT_MAKEAVAILABLE_SERIAL`` The ``<method-specific-args>`` will be everything passed to the :command:`FetchContent_Declare` call that corresponds to the requested dependency, with the following exceptions: diff --git a/Help/command/export.rst b/Help/command/export.rst index cc927bc..f190df7 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -15,12 +15,13 @@ Synopsis export(`TARGETS`_ <target>... [...]) export(`EXPORT`_ <export-name> [...]) export(`PACKAGE`_ <PackageName>) + export(`SETUP`_ <export-name> [...]) Exporting Targets ^^^^^^^^^^^^^^^^^ -.. _`export(TARGETS)`: -.. _TARGETS: +.. signature:: + export(TARGETS <target>... [...]) .. code-block:: cmake @@ -62,7 +63,7 @@ The options are: This signature requires all targets to be listed explicitly. If a library target is included in the export, but a target to which it links is not -included, the behavior is unspecified. See the `export(EXPORT)`_ signature +included, the behavior is unspecified. See the :command:`export(EXPORT)` signature to automatically export the same targets from the build tree as :command:`install(EXPORT)` would from an install tree. @@ -102,27 +103,33 @@ that policy is set to OLD for one of the targets. Exporting Targets matching install(EXPORT) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _`export(EXPORT)`: -.. _EXPORT: +.. signature:: + export(EXPORT <export-name> [...]) .. code-block:: cmake export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>] - [CXX_MODULES_DIRECTORY <directory>]) + [CXX_MODULES_DIRECTORY <directory>] [EXPORT_PACKAGE_DEPENDENCIES]) Creates a file ``<filename>`` that may be included by outside projects to import targets from the current project's build tree. This is the same -as the `export(TARGETS)`_ signature, except that the targets are not +as the :command:`export(TARGETS)` signature, except that the targets are not explicitly listed. Instead, it exports the targets associated with the installation export ``<export-name>``. Target installations may be associated with the export ``<export-name>`` using the ``EXPORT`` option of the :command:`install(TARGETS)` command. +``EXPORT_PACKAGE_DEPENDENCIES`` + .. versionadded:: 3.29 + + Specify that :command:`find_dependency` calls should be exported. See + :command:`install(EXPORT)` for details on how this works. + Exporting Packages ^^^^^^^^^^^^^^^^^^ -.. _`export(PACKAGE)`: -.. _PACKAGE: +.. signature:: + export(PACKAGE <PackageName>) .. code-block:: cmake @@ -149,3 +156,62 @@ registry. outside the source and build trees. Set the :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to the CMake user package registry. + +Configuring Exports +^^^^^^^^^^^^^^^^^^^ + +.. signature:: + export(SETUP <export-name> [...]) + +.. code-block:: cmake + + export(SETUP <export-name> + [PACKAGE_DEPENDENCY <dep> + [ENABLED (<bool-true>|<bool-false>|AUTO)] + [EXTRA_ARGS <args>...] + ] [...] + [TARGET <target> + [XCFRAMEWORK_LOCATION <location>] + ] [...] + ) + +.. versionadded:: 3.29 + +Configure the parameters of an export. The arguments are as follows: + +``PACKAGE_DEPENDENCY <dep>`` + Specify a package dependency to configure. This changes how + :command:`find_dependency` calls are written during + :command:`export(EXPORT)` and :command:`install(EXPORT)`. ``<dep>`` is the + name of a package to export. This argument accepts the following additional + arguments: + + ``ENABLED`` + Manually control whether or not the dependency is exported. This accepts + the following values: + + ``<bool-true>`` + Any value that CMake recognizes as "true". Always export the dependency, + even if no exported targets depend on it. This can be used to manually + add :command:`find_dependency` calls to the export. + + ``<bool-false>`` + Any value that CMake recognizes as "false". Never export the dependency, + even if an exported target depends on it. + + ``AUTO`` + Only export the dependency if an exported target depends on it. + + ``EXTRA_ARGS <args>`` + Specify additional arguments to pass to :command:`find_dependency` after + the ``REQUIRED`` argument. + +``TARGET <target>`` + Specify a target to configure in this export. This argument accepts the + following additional arguments: + + ``XCFRAMEWORK_LOCATION`` + Specify the location of an ``.xcframework`` which contains the library from + this target. If specified, the generated code will check to see if the + ``.xcframework`` exists, and if it does, it will use the ``.xcframework`` + as its imported location instead of the installed library. diff --git a/Help/command/file.rst b/Help/command/file.rst index f9d1a79..957b8b5 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -32,14 +32,14 @@ Synopsis `Writing`_ file({`WRITE`_ | `APPEND`_} <filename> <content>...) - file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) + file({`TOUCH`_ | `TOUCH_NOCREATE`_} <file>...) file(`GENERATE`_ OUTPUT <output-file> [...]) file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...]) `Filesystem`_ - file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) - file(`MAKE_DIRECTORY`_ [<dir>...]) - file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) + file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] <globbing-expr>...) + file(`MAKE_DIRECTORY`_ <directories>...) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } <files>...) file(`RENAME`_ <oldname> <newname> [...]) file(`COPY_FILE`_ <oldname> <newname> [...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) @@ -80,7 +80,7 @@ Reading (``a`` through ``f``) are in lowercase. .. signature:: - file(STRINGS <filename> <variable> [<options>...]) + file(STRINGS <filename> <variable> <options>...) Parse a list of ASCII strings from ``<filename>`` and store it in ``<variable>``. Binary data in the file are ignored. Carriage return @@ -165,17 +165,17 @@ Reading [RESOLVED_DEPENDENCIES_VAR <deps_var>] [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] - [EXECUTABLES [<executable_files>...]] - [LIBRARIES [<library_files>...]] - [MODULES [<module_files>...]] - [DIRECTORIES [<directories>...]] + [EXECUTABLES <executable_files>...] + [LIBRARIES <library_files>...] + [MODULES <module_files>...] + [DIRECTORIES <directories>...] [BUNDLE_EXECUTABLE <bundle_executable_file>] - [PRE_INCLUDE_REGEXES [<regexes>...]] - [PRE_EXCLUDE_REGEXES [<regexes>...]] - [POST_INCLUDE_REGEXES [<regexes>...]] - [POST_EXCLUDE_REGEXES [<regexes>...]] - [POST_INCLUDE_FILES [<files>...]] - [POST_EXCLUDE_FILES [<files>...]] + [PRE_INCLUDE_REGEXES <regexes>...] + [PRE_EXCLUDE_REGEXES <regexes>...] + [POST_INCLUDE_REGEXES <regexes>...] + [POST_EXCLUDE_REGEXES <regexes>...] + [POST_INCLUDE_FILES <files>...] + [POST_EXCLUDE_FILES <files>...] ) Please note that this sub-command is not intended to be used in project mode. @@ -210,7 +210,7 @@ Reading of paths that were found for that filename are stored in ``<conflicting_deps_prefix>_<filename>``. - ``EXECUTABLES <executable_files>`` + ``EXECUTABLES <executable_files>...`` List of executable files to read for dependencies. These are executables that are typically created with :command:`add_executable`, but they do not have to be created by CMake. On Apple platforms, the paths to these @@ -218,14 +218,14 @@ Reading resolving the libraries. Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here will result in undefined behavior. - ``LIBRARIES <library_files>`` + ``LIBRARIES <library_files>...`` List of library files to read for dependencies. These are libraries that are typically created with :command:`add_library(SHARED)`, but they do not have to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` libraries, or executables here will result in undefined behavior. - ``MODULES <module_files>`` + ``MODULES <module_files>...`` List of loadable module files to read for dependencies. These are modules that are typically created with :command:`add_library(MODULE)`, but they do not have to be created by CMake. They are typically used by calling @@ -233,7 +233,7 @@ Reading Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here will result in undefined behavior. - ``DIRECTORIES <directories>`` + ``DIRECTORIES <directories>...`` List of additional directories to search for dependencies. On Linux platforms, these directories are searched if the dependency is not found in any of the other usual paths. If it is found in such a directory, a @@ -256,30 +256,30 @@ Reading The following arguments specify filters for including or excluding libraries to be resolved. See below for a full description of how they work. - ``PRE_INCLUDE_REGEXES <regexes>`` + ``PRE_INCLUDE_REGEXES <regexes>...`` List of pre-include regexes through which to filter the names of not-yet-resolved dependencies. - ``PRE_EXCLUDE_REGEXES <regexes>`` + ``PRE_EXCLUDE_REGEXES <regexes>...`` List of pre-exclude regexes through which to filter the names of not-yet-resolved dependencies. - ``POST_INCLUDE_REGEXES <regexes>`` + ``POST_INCLUDE_REGEXES <regexes>...`` List of post-include regexes through which to filter the names of resolved dependencies. - ``POST_EXCLUDE_REGEXES <regexes>`` + ``POST_EXCLUDE_REGEXES <regexes>...`` List of post-exclude regexes through which to filter the names of resolved dependencies. - ``POST_INCLUDE_FILES <files>`` + ``POST_INCLUDE_FILES <files>...`` .. versionadded:: 3.21 List of post-include filenames through which to filter the names of resolved dependencies. Symlinks are resolved when attempting to match these filenames. - ``POST_EXCLUDE_FILES <files>`` + ``POST_EXCLUDE_FILES <files>...`` .. versionadded:: 3.21 List of post-exclude filenames through which to filter the names of @@ -486,8 +486,8 @@ Writing to update the file only when its content changes. .. signature:: - file(TOUCH [<files>...]) - file(TOUCH_NOCREATE [<files>...]) + file(TOUCH <files>...) + file(TOUCH_NOCREATE <files>...) .. versionadded:: 3.12 @@ -638,10 +638,10 @@ Filesystem .. signature:: file(GLOB <variable> [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] - [<globbing-expressions>...]) + <globbing-expressions>...) file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] - [<globbing-expressions>...]) + <globbing-expressions>...) Generate a list of files that match the ``<globbing-expressions>`` and store it into the ``<variable>``. Globbing expressions are similar to @@ -703,13 +703,13 @@ Filesystem ============== ====================================================== .. signature:: - file(MAKE_DIRECTORY [<directories>...]) + file(MAKE_DIRECTORY <directories>...) Create the given directories and their parents as needed. .. signature:: - file(REMOVE [<files>...]) - file(REMOVE_RECURSE [<files>...]) + file(REMOVE <files>...) + file(REMOVE_RECURSE <files>...) Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given files and directories, including non-empty directories. No error is emitted @@ -1012,8 +1012,8 @@ Transfer ^^^^^^^^ .. signature:: - file(DOWNLOAD <url> [<file>] [<options>...]) - file(UPLOAD <file> <url> [<options>...]) + file(DOWNLOAD <url> [<file>] <options>...) + file(UPLOAD <file> <url> <options>...) The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``. The ``UPLOAD`` mode uploads a local ``<file>`` to a given diff --git a/Help/command/if.rst b/Help/command/if.rst index 5d85a1f..1afbe04 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -178,6 +178,47 @@ File Operations False if the given path is an empty string. + .. warning:: + To check the readability of a file, use preferably ``if(IS_READABLE)`` + because this test will evolve to check file existence only in a future + release. + +.. signature:: if(IS_READABLE <path-to-file-or-directory>) + + .. versionadded:: 3.29 + + True if the named file or directory is readable. Behavior + is well-defined only for explicit full paths (a leading ``~/`` is not + expanded as a home directory and is considered a relative path). + Resolves symbolic links, i.e. if the named file or directory is a + symbolic link, returns true if the target of the symbolic link is readable. + + False if the given path is an empty string. + +.. signature:: if(IS_WRITABLE <path-to-file-or-directory>) + + .. versionadded:: 3.29 + + True if the named file or directory is writable. Behavior + is well-defined only for explicit full paths (a leading ``~/`` is not + expanded as a home directory and is considered a relative path). + Resolves symbolic links, i.e. if the named file or directory is a + symbolic link, returns true if the target of the symbolic link is writable. + + False if the given path is an empty string. + +.. signature:: if(IS_EXECUTABLE <path-to-file-or-directory>) + + .. versionadded:: 3.29 + + True if the named file or directory is executable. Behavior + is well-defined only for explicit full paths (a leading ``~/`` is not + expanded as a home directory and is considered a relative path). + Resolves symbolic links, i.e. if the named file or directory is a + symbolic link, returns true if the target of the symbolic link is executable. + + False if the given path is an empty string. + .. signature:: if(<file1> IS_NEWER_THAN <file2>) :target: IS_NEWER_THAN diff --git a/Help/command/install.rst b/Help/command/install.rst index b0698dd..0c2a32a 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -784,7 +784,8 @@ Signatures [CXX_MODULES_DIRECTORY <directory>] [EXPORT_LINK_INTERFACE_LIBRARIES] [COMPONENT <component>] - [EXCLUDE_FROM_ALL]) + [EXCLUDE_FROM_ALL] + [EXPORT_PACKAGE_DEPENDENCIES]) install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...]) The ``EXPORT`` form generates and installs a CMake file containing code to @@ -848,6 +849,34 @@ Signatures without this information, none of the C++ modules which are part of the targets in the export set will support being imported in consuming targets. + ``EXPORT_PACKAGE_DEPENDENCIES`` + .. versionadded:: 3.29 + + Specify that :command:`find_dependency` calls should be exported. If this + argument is specified, CMake examines all targets in the export set and + gathers their ``INTERFACE`` link targets. If any such targets either were + found with :command:`find_package` or have the + :prop_tgt:`EXPORT_FIND_PACKAGE_NAME` property set, and such package + dependency was not disabled by passing ``ENABLED OFF`` to + :command:`export(SETUP)`, then a :command:`find_dependency` call is + written with the target's corresponding package name, a ``REQUIRED`` + argument, and any additional arguments specified by the ``EXTRA_ARGS`` + argument of :command:`export(SETUP)`. Any package dependencies that were + manually specified by passing ``ENABLED ON`` to :command:`export(SETUP)` + are also added, even if the exported targets don't depend on any targets + from them. + + The :command:`find_dependency` calls are written in the following order: + + 1. Any package dependencies that were listed in :command:`export(SETUP)` + are written in the order they were first specified, regardless of + whether or not they contain ``INTERFACE`` dependencies of the + exported targets. + 2. Any package dependencies that contain ``INTERFACE`` link dependencies + of the exported targets and that were never specified in + :command:`export(SETUP)` are written in the order they were first + found. + The ``EXPORT`` form is useful to help outside projects use targets built and installed by the current project. For example, the code diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 0255b4d..f44a4e8 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -77,6 +77,7 @@ Try Compiling Source Files [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] + [LINKER_LANGUAGE <lang>] [OUTPUT_VARIABLE <var>] [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] [<LANG>_STANDARD <std>] @@ -177,6 +178,9 @@ The options for the above signatures are: If this option is specified, any ``-DLINK_LIBRARIES=...`` value given to the ``CMAKE_FLAGS`` option will be ignored. + .. versionadded:: 3.29 + Alias targets to imported libraries are also supported. + ``LINK_OPTIONS <options>...`` .. versionadded:: 3.14 @@ -184,6 +188,14 @@ The options for the above signatures are: set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. +``LINKER_LANGUAGE <lang>``` + .. versionadded:: 3.29 + + Specify the :prop_tgt:`LINKER_LANGUAGE` target property of the generated + project. When using multiple source files with different languages, set + this to the language of the source file containing the program entry point, + e.g., ``main``. + ``LOG_DESCRIPTION <text>`` .. versionadded:: 3.26 diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 1b5087d..c466a81 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -67,6 +67,7 @@ The signature above is recommended for clarity. [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] + [LINKER_LANGUAGE <lang>] [COMPILE_OUTPUT_VARIABLE <var>] [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] [<LANG>_STANDARD <std>] diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index 705ec9c..23436de 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst @@ -69,28 +69,32 @@ List of CPack DEB generator specific variables: :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:: + This may be set to: - <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb + ``DEB-DEFAULT`` + Tell CPack to automatically generate the package file name in deb format:: - Alternatively provided package file name must end - with either ``.deb`` or ``.ipk`` suffix. + <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb - .. versionadded:: 3.10 - ``.ipk`` suffix used by OPKG packaging system. + This setting recommended as the preferred behavior, but for backward + compatibility with the CPack DEB generator in CMake prior to version 3.6, + this is not the default. Without this, duplicate names may occur. + Duplicate files get overwritten and it is up to the packager to set + the variables in a manner that will prevent such errors. - .. note:: + ``<file-name>[.deb]`` + Use the given file name. - Preferred setting of this variable is ``DEB-DEFAULT`` but for backward - compatibility with the CPack DEB generator in CMake prior to version 3.6 this - feature is disabled by default. + .. versionchanged:: 3.29 - .. note:: + The ``.deb`` suffix will be automatically added if the file name does + not end in ``.deb`` or ``.ipk``. Previously the suffix was required. + + ``<file-name>.ipk`` + .. versionadded:: 3.10 - By using non default filenames duplicate names may occur. Duplicate files - get overwritten and it is up to the packager to set the variables in a - manner that will prevent such errors. + Use the given file name. + The ``.ipk`` suffix is used by the OPKG packaging system. .. variable:: CPACK_DEBIAN_PACKAGE_EPOCH diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 7b91261..4a2ce5f 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -84,9 +84,18 @@ List of CPack RPM generator specific variables: :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 - file name by itself. - Alternatively provided package file name must end with ``.rpm`` suffix. + This may be set to: + + ``RPM-DEFAULT`` + Tell ``rpmbuild`` to automatically generate the package file name. + + ``<file-name>[.rpm]`` + Use the given file name. + + .. versionchanged:: 3.29 + + The ``.rpm`` suffix will be automatically added if missing. + Previously the suffix was required. .. note:: diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index af01252..cb56c9d 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -119,7 +119,8 @@ Windows using WiX. If this variable is set, the specified template will be used to generate the WiX wxs file. This should be used if further customization of the - output is required. + output is required. The template contents will override the effect of most + ``CPACK_WIX_`` variables. If this variable is not set, the default MSI template included with CMake will be used. @@ -337,3 +338,31 @@ Windows using WiX. of the installer. May for example be set to ``x64`` or ``arm64``. When unspecified, CPack will default to ``x64`` or ``x86``. + +.. variable:: CPACK_WIX_INSTALL_SCOPE + + .. versionadded:: 3.29 + + This variable can be optionally set to specify the ``InstallScope`` + of the installer: + + ``perMachine`` (default) + Create an installer that installs for all users and requires + administrative privileges. Start menu entries created by the + installer are visible to all users. + + ``perUser`` + Not yet supported. This is reserved for future use. + + ``NONE`` + Create an installer without any ``InstallScope`` attribute. + + .. deprecated:: 3.29 + + This value is only for compatibility with the inconsistent behavior used + by CPack 3.28 and older. The resulting installer requires administrative + privileges and installs into the system-wide ``ProgramFiles`` directory, + but the start menu entry and uninstaller registration are created only + for the current user. + + See https://wixtoolset.org/docs/v3/xsd/wix/package/ diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 81e0e6f..c904673 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -8,6 +8,13 @@ See documentation on `CMake Development`_ for more information. .. contents:: Maintainer Processes: +Governance +========== + +CMake has no formal governance body. Maintainers expect one another to +cooperate constructively and make decisions in good faith. In cases of +disagreement, the chief maintainer retains final authority. + Review a Merge Request ====================== @@ -332,15 +339,16 @@ Commit with a message such as:: away from setting policies to OLD. Update the ``cmake_policy`` version range generated by ``install(EXPORT)`` -in ``cmExportFileGenerator::GeneratePolicyHeaderCode`` to end at the +in ``cmExportFileGenerator::GeneratePolicyHeaderCode`` and +``install_jar_exports`` in ``javaTargets.cmake.in`` to end at the previous release. We use one release back since we now know all the policies added for that version. Commit with a message such as:: export: Increase maximum policy version in exported files to $prev - The files generated by `install(EXPORT)` and `export()` commands - are known to work with policies as of CMake $prev, so enable them - in sufficiently new CMake versions. + The files generated by `install(EXPORT)`, `export()`, and + `install_jar_exports()` commands are known to work with policies + as of CMake $prev, so enable them in sufficiently new CMake versions. Update the ``cmake_minimum_required`` version range in CMake itself: diff --git a/Help/dev/try_compile-linker-language.rst b/Help/dev/try_compile-linker-language.rst new file mode 100644 index 0000000..8482dee --- /dev/null +++ b/Help/dev/try_compile-linker-language.rst @@ -0,0 +1,6 @@ +try_compile-linker-language +--------------------------- + +* The :command:`try_compile` and :command:`try_run` commands gained a + ``LINKER_LANGUAGE`` option to specify the :prop_tgt:`LINKER_LANGUAGE` + target property in the generated test project. diff --git a/Help/envvar/CMAKE_TEST_LAUNCHER.rst b/Help/envvar/CMAKE_TEST_LAUNCHER.rst new file mode 100644 index 0000000..d620ce5 --- /dev/null +++ b/Help/envvar/CMAKE_TEST_LAUNCHER.rst @@ -0,0 +1,11 @@ +CMAKE_TEST_LAUNCHER +------------------- + +.. versionadded:: 3.29 + +.. include:: ENV_VAR.txt + +The default value for the :variable:`CMAKE_TEST_LAUNCHER` variable when there +is no explicit configuration given on the first run while creating a new +build tree. On later runs in an existing build tree the value persists in +the cache as :variable:`CMAKE_TEST_LAUNCHER`. diff --git a/Help/manual/CTEST_EXAMPLE_MAKEFILE_JOB_SERVER.make b/Help/manual/CTEST_EXAMPLE_MAKEFILE_JOB_SERVER.make new file mode 100644 index 0000000..a17673a --- /dev/null +++ b/Help/manual/CTEST_EXAMPLE_MAKEFILE_JOB_SERVER.make @@ -0,0 +1,2 @@ +test: + +ctest -j 8 diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 55f07b7..5272ab9 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -56,6 +56,7 @@ Environment Variables that Control the Build /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/CMAKE_TEST_LAUNCHER /envvar/CMAKE_TOOLCHAIN_FILE /envvar/DESTDIR /envvar/LDFLAGS diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 88a7bab..c249ee2 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -431,7 +431,7 @@ Version 1 does not exist to avoid confusion with that from { "kind": "codemodel", - "version": { "major": 2, "minor": 6 }, + "version": { "major": 2, "minor": 7 }, "paths": { "source": "/path/to/top-level-source-dir", "build": "/path/to/top-level-build-dir" @@ -998,6 +998,36 @@ with members: destination is available. The value is an unsigned integer 0-based index into the ``backtraceGraph`` member's ``nodes`` array. +``launchers`` + Optional member that is present on executable targets that have + at least one launcher specified by the project. The value is a + JSON array of entries corresponding to the specified launchers. + Each entry is a JSON object with members: + + ``command`` + A string specifying the path to the launcher on disk, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + + ``arguments`` + Optional member that is present when the launcher command has + arguments preceding the executable to be launched. The value + is a JSON array of strings representing the arguments. + + ``type`` + A string specifying the type of launcher. The value is one of + the following: + + ``emulator`` + An emulator for the target platform when cross-compiling. + See the :prop_tgt:`CROSSCOMPILING_EMULATOR` target property. + + ``test`` + A start program for the execution of tests. + See the :prop_tgt:`TEST_LAUNCHER` target property. + + This field was added in codemodel version 2.7. + ``link`` Optional member that is present for executables and shared library targets that link into a runtime binary. The value is a JSON object diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index d4a43de..3e58b31 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1053,6 +1053,10 @@ related to most of the expressions in this sub-section. ``1`` if CMake's compiler id of the C compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. + .. versionchanged:: 3.15 + Multiple ``compiler_ids`` can be specified. + CMake 3.14 and earlier only accepted a single compiler ID. + .. genex:: $<CXX_COMPILER_ID> CMake's compiler id of the CXX compiler used. @@ -1063,6 +1067,10 @@ related to most of the expressions in this sub-section. ``1`` if CMake's compiler id of the CXX compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. + .. versionchanged:: 3.15 + Multiple ``compiler_ids`` can be specified. + CMake 3.14 and earlier only accepted a single compiler ID. + .. genex:: $<CUDA_COMPILER_ID> .. versionadded:: 3.15 @@ -1115,6 +1123,10 @@ related to most of the expressions in this sub-section. ``1`` if CMake's compiler id of the Fortran compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. + .. versionchanged:: 3.15 + Multiple ``compiler_ids`` can be specified. + CMake 3.14 and earlier only accepted a single compiler ID. + .. genex:: $<HIP_COMPILER_ID> .. versionadded:: 3.21 diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 46707ff..35b4497 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,16 @@ 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.29 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0158: add_test() honors CMAKE_CROSSCOMPILING_EMULATOR only when cross-compiling. </policy/CMP0158> + CMP0157: Swift compilation mode is selected by an abstraction. </policy/CMP0157> + CMP0156: De-duplicate libraries on link lines based on linker capabilities. </policy/CMP0156> + Policies Introduced by CMake 3.28 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 0ff2f2a..458cb73 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -130,6 +130,7 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX /prop_tgt/AUTOGEN_ORIGIN_DEPENDS /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS @@ -211,6 +212,7 @@ Properties on Targets /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXPORT_COMPILE_COMMANDS + /prop_tgt/EXPORT_FIND_PACKAGE_NAME /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_NO_SYSTEM /prop_tgt/EXPORT_PROPERTIES @@ -334,6 +336,7 @@ Properties on Targets /prop_tgt/LINK_SEARCH_START_STATIC /prop_tgt/LINK_WHAT_YOU_USE /prop_tgt/LINKER_LANGUAGE + /prop_tgt/LINKER_TYPE /prop_tgt/LOCATION /prop_tgt/LOCATION_CONFIG /prop_tgt/MACHO_COMPATIBILITY_VERSION @@ -389,11 +392,13 @@ Properties on Targets /prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG /prop_tgt/STATIC_LIBRARY_OPTIONS /prop_tgt/SUFFIX + /prop_tgt/Swift_COMPILATION_MODE /prop_tgt/Swift_DEPENDENCIES_FILE /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME /prop_tgt/SYSTEM + /prop_tgt/TEST_LAUNCHER /prop_tgt/TYPE /prop_tgt/UNITY_BUILD /prop_tgt/UNITY_BUILD_BATCH_SIZE diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index d9df773..0e778f8 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -55,7 +55,6 @@ Variables that Provide Information /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX /variable/CMAKE_EXECUTABLE_SUFFIX_LANG - /variable/CMAKE_EXTRA_GENERATOR /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_DEBUG_MODE /variable/CMAKE_FIND_PACKAGE_NAME @@ -74,6 +73,10 @@ Variables that Provide Information /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT + /variable/CMAKE_LANG_COMPILER_LINKER + /variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT + /variable/CMAKE_LANG_COMPILER_LINKER_ID + /variable/CMAKE_LANG_COMPILER_LINKER_VERSION /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX @@ -111,8 +114,10 @@ Variables that Provide Information /variable/CMAKE_SOURCE_DIR /variable/CMAKE_STATIC_LIBRARY_PREFIX /variable/CMAKE_STATIC_LIBRARY_SUFFIX + /variable/CMAKE_Swift_COMPILATION_MODE /variable/CMAKE_Swift_MODULE_DIRECTORY /variable/CMAKE_Swift_NUM_THREADS + /variable/CMAKE_TEST_LAUNCHER /variable/CMAKE_TOOLCHAIN_FILE /variable/CMAKE_TWEAK_VERSION /variable/CMAKE_VERBOSE_MAKEFILE @@ -126,6 +131,7 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_TOOLSET /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR + /variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER @@ -169,8 +175,6 @@ Variables that Change Behavior /variable/CMAKE_ABSOLUTE_DESTINATION_FILES /variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY /variable/CMAKE_APPBUNDLE_PATH - /variable/CMAKE_AUTOMOC_RELAXED_MODE - /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE /variable/CMAKE_CLANG_VFS_OVERLAY /variable/CMAKE_CODEBLOCKS_COMPILER_ID @@ -198,8 +202,6 @@ Variables that Change Behavior /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES /variable/CMAKE_FIND_NO_INSTALL_PREFIX - /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY - /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS /variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL @@ -251,6 +253,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY + /variable/CMAKE_SKIP_TEST_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE @@ -336,15 +339,6 @@ Variables that Describe the System /variable/LINUX /variable/MINGW /variable/MSVC - /variable/MSVC10 - /variable/MSVC11 - /variable/MSVC12 - /variable/MSVC14 - /variable/MSVC60 - /variable/MSVC70 - /variable/MSVC71 - /variable/MSVC80 - /variable/MSVC90 /variable/MSVC_IDE /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION @@ -395,6 +389,7 @@ Variables that Control the Build /variable/CMAKE_APPLE_SILICON_PROCESSOR /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX /variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS /variable/CMAKE_AUTOGEN_PARALLEL /variable/CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE @@ -439,6 +434,7 @@ Variables that Control the Build /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS_INIT + /variable/CMAKE_EXPORT_FIND_PACKAGE_NAME /variable/CMAKE_FOLDER /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY @@ -459,7 +455,6 @@ Variables that Control the Build /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION /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 @@ -474,6 +469,8 @@ Variables that Control the Build /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_LINKER_LAUNCHER + /variable/CMAKE_LANG_USING_LINKER_MODE + /variable/CMAKE_LANG_USING_LINKER_TYPE /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -490,6 +487,7 @@ Variables that Control the Build /variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LINK_WHAT_YOU_USE /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK + /variable/CMAKE_LINKER_TYPE /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG @@ -534,7 +532,6 @@ Variables that Control the Build /variable/CMAKE_UNITY_BUILD /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /variable/CMAKE_UNITY_BUILD_UNIQUE_ID - /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_DEBUGGER_COMMAND @@ -571,9 +568,6 @@ Variables for Languages /variable/CMAKE_C_EXTENSIONS /variable/CMAKE_C_STANDARD /variable/CMAKE_C_STANDARD_REQUIRED - /variable/CMAKE_COMPILER_IS_GNUCC - /variable/CMAKE_COMPILER_IS_GNUCXX - /variable/CMAKE_COMPILER_IS_GNUG77 /variable/CMAKE_CUDA_ARCHITECTURES /variable/CMAKE_CUDA_COMPILE_FEATURES /variable/CMAKE_CUDA_EXTENSIONS @@ -693,7 +687,6 @@ Variables for CTest /variable/CTEST_CUSTOM_TESTS_IGNORE /variable/CTEST_CUSTOM_WARNING_EXCEPTION /variable/CTEST_CUSTOM_WARNING_MATCH - /variable/CTEST_CVS_CHECKOUT /variable/CTEST_CVS_COMMAND /variable/CTEST_CVS_UPDATE_OPTIONS /variable/CTEST_DROP_LOCATION @@ -722,7 +715,6 @@ Variables for CTest /variable/CTEST_P4_UPDATE_OPTIONS /variable/CTEST_RESOURCE_SPEC_FILE /variable/CTEST_RUN_CURRENT_SCRIPT - /variable/CTEST_SCP_COMMAND /variable/CTEST_SCRIPT_DIRECTORY /variable/CTEST_SITE /variable/CTEST_SOURCE_DIRECTORY @@ -733,7 +725,6 @@ Variables for CTest /variable/CTEST_SVN_UPDATE_OPTIONS /variable/CTEST_TEST_LOAD /variable/CTEST_TEST_TIMEOUT - /variable/CTEST_TRIGGER_SITE /variable/CTEST_UPDATE_COMMAND /variable/CTEST_UPDATE_OPTIONS /variable/CTEST_UPDATE_VERSION_ONLY @@ -786,3 +777,67 @@ are subject to change, and not recommended for use in project code. /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION + +Deprecated Variables that Provide Information +============================================= + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_EXTRA_GENERATOR + +Deprecated Variables that Change Behavior +========================================= + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_AUTOMOC_RELAXED_MODE + /variable/CMAKE_BACKWARDS_COMPATIBILITY + /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY + /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY + +Deprecated Variables that Describe the System +============================================= + +.. toctree:: + :maxdepth: 1 + + /variable/MSVC10 + /variable/MSVC11 + /variable/MSVC12 + /variable/MSVC14 + /variable/MSVC60 + /variable/MSVC70 + /variable/MSVC71 + /variable/MSVC80 + /variable/MSVC90 + +Deprecated Variables that Control the Build +=========================================== + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_IOS_INSTALL_COMBINED + /variable/CMAKE_USE_RELATIVE_PATHS + +Deprecated Variables for Languages +================================== + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_COMPILER_IS_GNUCC + /variable/CMAKE_COMPILER_IS_GNUCXX + /variable/CMAKE_COMPILER_IS_GNUG77 + +Deprecated Variables for CTest +============================== + +.. toctree:: + :maxdepth: 1 + + /variable/CTEST_CVS_CHECKOUT + /variable/CTEST_SCP_COMMAND + /variable/CTEST_TRIGGER_SITE diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 5223acb..621c005 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -891,6 +891,10 @@ Available commands are: ``-`` will result in an error. Use ``--`` to indicate the end of options, in case a file starts with ``-``. + .. versionadded:: 3.29 + + ``cat`` can now print the standard input by passing the ``-`` argument. + .. program:: cmake-E .. option:: chdir <dir> <cmd> [<arg>...] @@ -1311,6 +1315,7 @@ The following ``cmake -E`` commands are available only on Windows: Write Windows registry value. +.. _`Find-Package Tool Mode`: Run the Find-Package Tool ========================= diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 5512c61..0917191 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -354,6 +354,8 @@ Run Tests .. option:: --test-dir <dir> + .. versionadded:: 3.20 + Specify the directory in which to look for tests, typically a CMake project build directory. If not specified, the current directory is used. @@ -1847,6 +1849,31 @@ fixture in their :prop_test:`FIXTURES_REQUIRED`, and a resource spec file may not be specified with the ``--resource-spec-file`` argument or the :variable:`CTEST_RESOURCE_SPEC_FILE` variable. +.. _`ctest-job-server-integration`: + +Job Server Integration +====================== + +.. versionadded:: 3.29 + +On POSIX systems, when running under the context of a `Job Server`_, +CTest shares its job slots. This is independent of the :prop_test:`PROCESSORS` +test property, which still counts against CTest's :option:`-j <ctest -j>` +parallel level. CTest acquires exactly one token from the job server before +running each test, and returns it when the test finishes. + +For example, consider the ``Makefile``: + +.. literalinclude:: CTEST_EXAMPLE_MAKEFILE_JOB_SERVER.make + :language: make + +When invoked via ``make -j 2 test``, ``ctest`` connects to the job server, +acquires a token for each test, and runs at most 2 tests concurrently. + +On Windows systems, job server integration is not yet implemented. + +.. _`Job Server`: https://www.gnu.org/software/make/manual/html_node/Job-Slots.html + See Also ======== diff --git a/Help/policy/CMP0156.rst b/Help/policy/CMP0156.rst new file mode 100644 index 0000000..fa97519 --- /dev/null +++ b/Help/policy/CMP0156.rst @@ -0,0 +1,47 @@ +CMP0156 +------- + +.. versionadded:: 3.29 + +De-duplicate libraries on link lines based on linker capabilities. + +Traditional linkers maintain a set of undefined symbols during linking. The +linker processes each file in the order in which it appears on the command +line, until the set of undefined symbols becomes empty. An object file is +linked into the output object when it is encountered, with its undefined +symbols added to the set. Upon encountering an archive file a traditional +linker searches the objects contained therein, and processes those that satisfy +symbols in the unresolved set. + +Handling mutually dependent archives may be awkward when using a traditional +linker. Archive files may have to be specified multiple times. + +Some linkers (for instance Apple or Windows linkers, as well as``LLVM LLD``) +records all symbols found in objects and archives as it iterates over command +line arguments. When one of these linkers encounters an undefined symbol that +can be resolved by an object file contained in a previously processed archive +file, it immediately extracts and links it into the output object. + +CMake 3.28 and below may generate link lines that repeat static libraries as +a traditional linker would need, even when using a linker does not need it. +They may also de-duplicate shared libraries by keeping their last occurrence, +which on Windows platforms can change DLL load order. + +CMake 3.29 and above prefer to apply different strategies based on linker +capabilities. So, when targeting Apple and Windows platforms, all +libraries are de-duplicated. Moreover, on Windows platforms, libraries +are de-duplicated by keeping their fist occurrence, thus respecting the +project-specified order. This policy provides compatibility with projects +that have not been updated to expect the latter behavior. + +The ``OLD`` behavior for this policy is to always repeat static libraries +as if using a traditional linker, and always de-duplicate shared libraries +by keeping the last occurrence of each. The ``NEW`` behavior for this policy +is to apply different strategies based on linker capabilities. + +This policy was introduced in CMake version 3.29. 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/policy/CMP0157.rst b/Help/policy/CMP0157.rst new file mode 100644 index 0000000..a8f8210 --- /dev/null +++ b/Help/policy/CMP0157.rst @@ -0,0 +1,48 @@ +CMP0157 +------- + +.. versionadded:: 3.29 + +Swift compilation mode is selected by an abstraction. + +The Swift compiler can compile modules in different modes. The desired build +mode depends whether the developer is iterating and wants to incrementally make +changes, or if they are building a release for distribution and want more +optimizations applied to the resulting binary. + +CMake versions 3.26 through 3.28 build Swift binaries with whole-module +optimizations enabled when configured in a non-debug build type. +For CMake versions earlier than 3.26, the developer needs to specify +the necessary flag manually for the :ref:`Ninja Generators`, and cannot +not specify whole-module optimizations to the :generator:`Xcode` generator. + +CMake versions 3.29 and above prefer to set the compilation mode using +the :prop_tgt:`Swift_COMPILATION_MODE` target property, which can be +initialized by the :variable:`CMAKE_Swift_COMPILATION_MODE` variable. + +This policy provides compatibility for projects that have not been updated. +The policy setting takes effect as of the first :command:`project` or +:command:`enable_language` command that enables the ``Swift`` language. + +.. note:: + + Once the policy has taken effect at the top of a project, that choice + must be used throughout the tree. In projects that have nested projects + in subdirectories, be sure to convert everything together. + +The ``OLD`` behavior for this policy builds all Swift targets in +``wholemodule`` mode for non-debug configurations. :ref:`Ninja Generators` +prepend the ``-wmo`` flag to the default set of Swift flags. +The :generator:`Xcode` generator sets the ``SWIFT_COMPILATION_MODE`` +attribute to ``wholemodule`` in the generated Xcode project file. + +The ``NEW`` behavior for this policy is to apply the compilation mode specified +in the :prop_tgt:`Swift_COMPILATION_MODE` target property, initialized as each +target is created by the :variable:`CMAKE_Swift_COMPILATION_MODE` variable. + +This policy was introduced in CMake version 3.29. 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/policy/CMP0158.rst b/Help/policy/CMP0158.rst new file mode 100644 index 0000000..4289c6d --- /dev/null +++ b/Help/policy/CMP0158.rst @@ -0,0 +1,27 @@ +CMP0158 +------- + +.. versionadded:: 3.29 + +:command:`add_test` honors :variable:`CMAKE_CROSSCOMPILING_EMULATOR` only +when :variable:`cross-compiling <CMAKE_CROSSCOMPILING>`. + +In CMake 3.28 and below, :command:`add_test` unconditionally used the +:prop_tgt:`CROSSCOMPILING_EMULATOR` target property (initialized by the +:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable) to run test commands +naming executable targets. CMake 3.29 and above prefer to use the emulator +only when the :variable:`CMAKE_CROSSCOMPILING` variable is enabled. The +:variable:`CMAKE_TEST_LAUNCHER` variable may be used instead when not +cross-compiling. This policy provides compatibility for projects that +have not been updated. + +The ``OLD`` behavior for this policy is for :command:`add_test` to use +the :prop_tgt:`CROSSCOMPILING_EMULATOR` target property unconditionally. +The ``NEW`` behavior for this policy is for :command:`add_test` to use +the :prop_tgt:`CROSSCOMPILING_EMULATOR` target property only when +:variable:`cross-compiling <CMAKE_CROSSCOMPILING>`. + +This policy was introduced in CMake version 3.29. 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. diff --git a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst index 1ec4517..e94856d 100644 --- a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst @@ -1,15 +1,22 @@ FAIL_REGULAR_EXPRESSION ----------------------- -If the output matches this regular expression the test will fail, -regardless of the process exit code. +If the test output (stdout or stderr) matches this regular expression the test +will fail, regardless of the process exit code. Tests that exceed the timeout +specified by :prop_test:`TIMEOUT` fail regardless of +``FAIL_REGULAR_EXPRESSION``. Any non-zero return code or system-level test +failures including segmentation faults, signal abort, or heap errors fail the +test even if the regular expression does not match. -If set, if the output matches one of specified regular expressions, -the test will fail. Example: +If set, if the output matches one of specified regular expressions, the test +will fail. Example: .. code-block:: cmake - set_tests_properties(mytest PROPERTIES + # test would pass, except for FAIL_REGULAR_EXPRESSION + add_test(NAME mytest COMMAND ${CMAKE_COMMAND} -E echo "Failed") + + set_property(TEST mytest PROPERTY FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed" ) diff --git a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst index 96468c0..b19e637 100644 --- a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst @@ -1,20 +1,50 @@ PASS_REGULAR_EXPRESSION ----------------------- -The output must match this regular expression for the test to pass. -The process exit code is ignored. +The test output (stdout or stderr) must match this regular expression +for the test to pass. The process exit code is ignored. Tests that exceed +the timeout specified by :prop_test:`TIMEOUT` still fail regardless of +``PASS_REGULAR_EXPRESSION``. System-level test failures including +segmentation faults, signal abort, or heap errors may fail the test even +if ``PASS_REGULAR_EXPRESSION`` is matched. -If set, the test output will be checked against the specified regular -expressions and at least one of the regular expressions has to match, -otherwise the test will fail. Example: +Example: .. code-block:: cmake - set_tests_properties(mytest PROPERTIES - PASS_REGULAR_EXPRESSION "TestPassed;All ok" + add_test(NAME mytest COMMAND ${CMAKE_COMMAND} -E echo "Passed this test") + + set_property(TEST mytest PROPERTY + PASS_REGULAR_EXPRESSION "pass;Passed" ) ``PASS_REGULAR_EXPRESSION`` expects a list of regular expressions. +To run a test that may have a system-level failure, but still pass if +``PASS_REGULAR_EXPRESSION`` matches, use a CMake command to wrap the +executable run. Note that this will prevent automatic handling of the +:prop_tgt:`CROSSCOMPILING_EMULATOR` and :prop_tgt:`TEST_LAUNCHER` +target property. + +.. code-block:: cmake + + add_executable(main main.c) + + add_test(NAME sigabrt COMMAND ${CMAKE_COMMAND} -E env $<TARGET_FILE:main>) + + set_property(TEST sigabrt PROPERTY PROPERTY_REGULAR_EXPRESSION "pass;Passed") + +.. code-block:: c + + #include <signal.h> + #include <stdio.h> + + int main(void){ + fprintf(stdout, "Passed\n"); + fflush(stdout); /* ensure the output buffer is seen */ + raise(SIGABRT); + return 0; + } + See also the :prop_test:`FAIL_REGULAR_EXPRESSION` and :prop_test:`SKIP_REGULAR_EXPRESSION` test properties. diff --git a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst index 60038e4..8717a0a 100644 --- a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst @@ -3,19 +3,45 @@ SKIP_REGULAR_EXPRESSION .. versionadded:: 3.16 -If the output matches this regular expression the test will be marked as skipped. +If the test output (stderr or stdout) matches this regular expression the test +will be marked as skipped, regardless of the process exit code. Tests that +exceed the timeout specified by :prop_test:`TIMEOUT` still fail regardless of +``SKIP_REGULAR_EXPRESSION``. System-level test failures including segmentation +faults, signal abort, or heap errors may fail the test even if the regular +expression matches. -If set, if the output matches one of specified regular expressions, -the test will be marked as skipped. Example: +Example: .. code-block:: cmake + add_test(NAME mytest COMMAND ${CMAKE_COMMAND} -E echo "Skipped this test") + set_property(TEST mytest PROPERTY SKIP_REGULAR_EXPRESSION "[^a-z]Skip" "SKIP" "Skipped" ) ``SKIP_REGULAR_EXPRESSION`` expects a list of regular expressions. +To run a test that may have a system-level failure, but still skip if +``SKIP_REGULAR_EXPRESSION`` matches, use a CMake command to wrap the +executable run. Note that this will prevent automatic handling of the +:prop_tgt:`CROSSCOMPILING_EMULATOR` and :prop_tgt:`TEST_LAUNCHER` +target property. + +.. code-block:: cmake + + add_executable(main main.c) + + add_test(NAME sigabrt COMMAND ${CMAKE_COMMAND} -E env $<TARGET_FILE:main>) + + set_property(TEST sigabrt PROPERTY SKIP_REGULAR_EXPRESSION "SIGABRT;[aA]bort") + +.. code-block:: c + + #include <signal.h> + + int main(void){ raise(SIGABRT); return 0; } + See also the :prop_test:`SKIP_RETURN_CODE`, :prop_test:`PASS_REGULAR_EXPRESSION`, and :prop_test:`FAIL_REGULAR_EXPRESSION` test properties. diff --git a/Help/prop_test/SKIP_RETURN_CODE.rst b/Help/prop_test/SKIP_RETURN_CODE.rst index 23c4c62..57fc031 100644 --- a/Help/prop_test/SKIP_RETURN_CODE.rst +++ b/Help/prop_test/SKIP_RETURN_CODE.rst @@ -9,4 +9,40 @@ a return code of the process can be specified that will mark the test as ``Not Run`` if it is encountered. Valid values are in the range of 0 to 255, inclusive. -See also the :prop_test:`SKIP_REGULAR_EXPRESSION` property. +Tests that exceed the timeout specified by :prop_test:`TIMEOUT` still fail +regardless of ``SKIP_RETURN_CODE``. +System-level test failures including segmentation faults, +signal abort, or heap errors may fail the test even if the return code matches. + +.. code-block:: cmake + + # cmake (1) defines this to return code 1 + add_test(NAME r1 COMMAND ${CMAKE_COMMAND} -E false) + + set_tests_properties(r1 PROPERTIES SKIP_RETURN_CODE 1) + + +To run a test that may have a system-level failure, but still skip if +``SKIP_RETURN_CODE`` matches, use a CMake command to wrap the executable run. +Note that this will prevent automatic handling of the +:prop_tgt:`CROSSCOMPILING_EMULATOR` and :prop_tgt:`TEST_LAUNCHER` target +property. + +.. code-block:: cmake + + add_executable(main main.c) + + # cmake -E env <command> returns 1 if the command fails in any way + add_test(NAME sigabrt COMMAND ${CMAKE_COMMAND} -E env $<TARGET_FILE:main>) + + set_property(TEST sigabrt PROPERTY SKIP_RETURN_CODE 1) + +.. code-block:: c + + #include <signal.h> + + int main(void){ raise(SIGABRT); return 0; } + + +To handle multiple types of cases that may need to be skipped, consider the +:prop_test:`SKIP_REGULAR_EXPRESSION` property. diff --git a/Help/prop_test/WILL_FAIL.rst b/Help/prop_test/WILL_FAIL.rst index 4926f40..9d61ab7 100644 --- a/Help/prop_test/WILL_FAIL.rst +++ b/Help/prop_test/WILL_FAIL.rst @@ -1,8 +1,37 @@ WILL_FAIL --------- -If set to true, this will invert the pass/fail flag of the test. +If ``true``, inverts the pass / fail test criteria. Tests for which +``WILL_FAIL`` is ``true`` fail with return code 0 and pass with non-zero +return code. Tests that exceed the timeout specified by :prop_test:`TIMEOUT` +still fail regardless of ``WILL_FAIL``. +System-level test failures including segmentation faults, +signal abort, or heap errors may fail the test even if ``WILL_FAIL`` is true. -This property can be used for tests that are expected to fail and return a -non-zero return code. Note that system-level test failures such as segmentation -faults or heap errors will still fail the test even if ``WILL_FALL`` is true. +Example of a test that would ordinarily pass, but fails because ``WILL_FAIL`` +is ``true``: + +.. code-block:: cmake + + add_test(NAME failed COMMAND ${CMAKE_COMMAND} -E true) + set_property(TEST failed PROPERTY WILL_FAIL true) + +To run a test that may have a system-level failure, but still pass if +``WILL_FAIL`` is set, use a CMake command to wrap the executable run. +Note that this will prevent automatic handling of the +:prop_tgt:`CROSSCOMPILING_EMULATOR` and :prop_tgt:`TEST_LAUNCHER` +target property. + +.. code-block:: cmake + + add_executable(main main.c) + + add_test(NAME sigabrt COMMAND ${CMAKE_COMMAND} -E env $<TARGET_FILE:main>) + + set_property(TEST sigabrt PROPERTY WILL_FAIL TRUE) + +.. code-block:: c + + #include <signal.h> + + int main(void){ raise(SIGABRT); return 0; } diff --git a/Help/prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst b/Help/prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst new file mode 100644 index 0000000..f1e51a7 --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst @@ -0,0 +1,18 @@ +AUTOGEN_COMMAND_LINE_LENGTH_MAX +------------------------------- + +.. versionadded:: 3.29 + +Command line length limit for autogen targets, i.e. ``moc`` or ``uic``, +that triggers the use of response files on Windows instead of passing all +arguments to the command line. + +- An empty (or unset) value sets the limit to 32000 +- A positive non zero integer value sets the exact command line length + limit. + +By default ``AUTOGEN_COMMAND_LINE_LENGTH_MAX`` is initialized from +:variable:`CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX`. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 0feb2e8..6f58afb 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -247,5 +247,9 @@ will be generated when this variable is ``ON``. This target property controls the number of ``moc`` or ``uic`` processes to start in parallel during builds. +:prop_tgt:`AUTOGEN_COMMAND_LINE_LENGTH_MAX`: +This target property controls the limit when to use response files for +``moc`` or ``uic`` processes on Windows. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index dc854b2..95366ee 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -81,5 +81,9 @@ will be generated when this variable is ``ON``. This target property controls the number of ``moc`` or ``uic`` processes to start in parallel during builds. +:prop_tgt:`AUTOGEN_COMMAND_LINE_LENGTH_MAX`: +This target property controls the limit when to use response files for +``moc`` or ``uic`` processes on Windows. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst b/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst new file mode 100644 index 0000000..b49f005 --- /dev/null +++ b/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst @@ -0,0 +1,12 @@ +EXPORT_FIND_PACKAGE_NAME +------------------------ + +.. versionadded:: 3.29 + +Control the package name associated with a dependency target when exporting a +:command:`find_dependency` call in :command:`install(EXPORT)` or +:command:`export(EXPORT)`. This can be used to assign a package name to a +package that is built by CMake and exported, or to override the package in the +:command:`find_package` call that created the target. + +This property is initialized by :variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME`. diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst index 2351374..b162253 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -32,7 +32,7 @@ listed in the :prop_tgt:`IMPORTED_CONFIGURATIONS` target property may be selected and its :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` value used. To get the location of an imported target read one of the :prop_tgt:`LOCATION` -or ``LOCATION_<CONFIG>`` properties. +or :prop_tgt:`LOCATION_<CONFIG>` properties. For platforms with import libraries (e.g. Windows, AIX or Apple) see also :prop_tgt:`IMPORTED_IMPLIB`. diff --git a/Help/prop_tgt/LINKER_TYPE.rst b/Help/prop_tgt/LINKER_TYPE.rst new file mode 100644 index 0000000..90a663d --- /dev/null +++ b/Help/prop_tgt/LINKER_TYPE.rst @@ -0,0 +1,26 @@ +LINKER_TYPE +----------- + +.. versionadded:: 3.29 + +Specify which linker will be used for the link step. The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +.. code-block:: cmake + + add_library(lib1 SHARED ...) + set_property(TARGET lib1 PROPERTY LINKER_TYPE LLD) + +This specifies that ``lib1`` should use linker type ``LLD`` for the link step. +The implementation details will be provided by the variable +:variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` with ``<TYPE>`` having the value +``LLD``. + +This property is not supported on :generator:`Green Hills MULTI` and +:generator:`Visual Studio 9 2008` generators. + +.. note:: + It is assumed that the linker specified is fully compatible with the standard + one. CMake will not do any options translation. + +.. include:: ../variable/LINKER_PREDEFINED_TYPES.txt diff --git a/Help/prop_tgt/Swift_COMPILATION_MODE-VALUES.txt b/Help/prop_tgt/Swift_COMPILATION_MODE-VALUES.txt new file mode 100644 index 0000000..b94380a --- /dev/null +++ b/Help/prop_tgt/Swift_COMPILATION_MODE-VALUES.txt @@ -0,0 +1,19 @@ +``incremental`` + Compiles each Swift source in the module separately, resulting in better + parallelism in the build. The compiler emits additional information into + the build directory improving rebuild performance when small changes are made + to the source between rebuilds. This is the best option to use while + iterating on changes in a project. + +``wholemodule`` + Whole-module optimizations are slowest to compile, but results in the most + optimized library. The entire context is loaded into once instance of the + compiler, so there is no parallelism across source files in the module. + +``singlefile`` + Compiles each source in a Swift modules separately, resulting in better + parallelism. Unlike the ``incremental`` build mode, no additional information + is emitted by the compiler during the build, so rebuilding after making small + changes to the source file will not run faster. This option should be used + sparingly, preferring ``incremental`` builds, unless working around a compiler + bug. diff --git a/Help/prop_tgt/Swift_COMPILATION_MODE.rst b/Help/prop_tgt/Swift_COMPILATION_MODE.rst new file mode 100644 index 0000000..e26474a --- /dev/null +++ b/Help/prop_tgt/Swift_COMPILATION_MODE.rst @@ -0,0 +1,33 @@ +Swift_COMPILATION_MODE +---------------------- + +.. versionadded:: 3.29 + +Specify how Swift compiles a target. + +The allowed values are: + +.. include:: Swift_COMPILATION_MODE-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to support +per-configuration specification. For example, the code: + +.. code-block:: cmake + + add_library(foo foo.swift) + set_property(TARGET foo PROPERTY + Swift_COMPILATION_MODE "$<IF:$<CONFIG:Release>,wholemodule,incremental>") + +sets the Swift compilation mode to wholemodule mode in the release configuration +and sets the property to incremental mode in other configurations. + +The property is initialized from the value of the +:variable:`CMAKE_Swift_COMPILATION_MODE` variable, if it is set. If the property +is not set or is empty, then CMake uses the default value ``incremental`` to +specify the swift compilation mode. + +.. note:: + + This property only has effect when policy :policy:`CMP0157` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables the Swift language. diff --git a/Help/prop_tgt/TEST_LAUNCHER.rst b/Help/prop_tgt/TEST_LAUNCHER.rst new file mode 100644 index 0000000..2e44492 --- /dev/null +++ b/Help/prop_tgt/TEST_LAUNCHER.rst @@ -0,0 +1,20 @@ +TEST_LAUNCHER +------------- + +.. versionadded:: 3.29 + +Use the given launcher to run executables. +This command will be added as a prefix to :command:`add_test` commands +for build target system executables and is meant to be run on the host +machine. + +It effectively acts as a run script for tests in a similar way +to how :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` works for compilation. + +If this property contains a :ref:`semicolon-separated list <CMake Language +Lists>`, then the first value is the command and remaining values are its +arguments. + +This property is initialized by the value of the +:variable:`CMAKE_TEST_LAUNCHER` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst index f827a20..52f4714 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -30,11 +30,23 @@ values: If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will default to ``BATCH``. -Unity builds are not currently supported for all languages. CMake version -|release| supports combining ``C`` and ``CXX`` source files. For targets that -mix source files from more than one language, CMake will separate the languages -such that each generated unity source file only contains sources for a single -language. +Unity builds are supported for the following languages: + +``C`` + .. versionadded:: 3.16 + +``CXX`` + .. versionadded:: 3.16 + +``OBJC`` + .. versionadded:: 3.29 + +``OBJCXX`` + .. versionadded:: 3.29 + +For targets that mix source files from more than one language, CMake +separates the languages such that each generated unity source file only +contains sources for a single language. This property is initialized by the value of the :variable:`CMAKE_UNITY_BUILD` variable when a target is created. diff --git a/Help/prop_tgt/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst index e27d905..0354f97 100644 --- a/Help/prop_tgt/XCODE_EMBED_type.rst +++ b/Help/prop_tgt/XCODE_EMBED_type.rst @@ -43,6 +43,28 @@ The supported values for ``<type>`` are: The specified items will be added to the ``Embed Resources`` build phase. They must be CMake target names or folder paths. +``XPC_SERVICES`` + .. versionadded:: 3.29 + + The specified items will be added to the ``Embed XPC Services`` build phase. + They must be CMake target names. + +When listing a target as any of the things to embed, Xcode must see that target +as part of the same Xcode project, or a sub-project of the one defining the +bundle. In order to satisfy this constraint, the CMake project must ensure +at least one of the following: + +* The :variable:`CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable is set + to true in the top level ``CMakeLists.txt`` file. This is the simplest and + most robust approach. +* Define the target-to-embed in a subdirectory of the one that defines the + target being embedded into. +* If the target-to-embed and the target being embedded into are in separate, + unrelated directories (i.e. they are siblings, not one a parent of the + other), ensure they have a common :command:`project` call in a parent + directory and no other :command:`project` calls between themselves and that + common :command:`project` call. + See also :prop_tgt:`XCODE_EMBED_<type>_PATH`, :prop_tgt:`XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` and :prop_tgt:`XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`. diff --git a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst index ef04d14..255aa68 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst @@ -25,3 +25,6 @@ The supported values for ``<type>`` are: ``RESOURCES`` .. versionadded:: 3.28 + +``XPC_SERVICES`` + .. versionadded:: 3.29 diff --git a/Help/release/3.22.rst b/Help/release/3.22.rst index eba5d66..2d060ac 100644 --- a/Help/release/3.22.rst +++ b/Help/release/3.22.rst @@ -19,7 +19,7 @@ Commands * The :command:`string(TIMESTAMP)` command now supports the ``%V`` specifier for ISO 8601 week numbers. -.. _`OS identification variables`: https://www.freedesktop.org/software/systemd/man/os-release.html +.. _`OS identification variables`: https://www.freedesktop.org/software/systemd/man/latest/os-release.html Variables --------- diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/Linker-user-selection.rst b/Help/release/dev/Linker-user-selection.rst new file mode 100644 index 0000000..ed78099 --- /dev/null +++ b/Help/release/dev/Linker-user-selection.rst @@ -0,0 +1,6 @@ +Linker-user-selection +--------------------- + +* The linker tool can now be specified for a selection of compilers/platforms + by setting :variable:`CMAKE_LINKER_TYPE` variable or :prop_tgt:`LINKER_TYPE` + target property. diff --git a/Help/release/dev/cmake-E-cat-stdin.rst b/Help/release/dev/cmake-E-cat-stdin.rst new file mode 100644 index 0000000..43a8aed --- /dev/null +++ b/Help/release/dev/cmake-E-cat-stdin.rst @@ -0,0 +1,5 @@ +cmake-E-cat-stdin +----------------- + +* :manual:`cmake(1)` :option:`-E cat <cmake-E cat>` can now print the standard + input by passing the ``-`` argument. diff --git a/Help/release/dev/cmake-test-launcher.rst b/Help/release/dev/cmake-test-launcher.rst new file mode 100644 index 0000000..a82a8ad --- /dev/null +++ b/Help/release/dev/cmake-test-launcher.rst @@ -0,0 +1,11 @@ +cmake-test-launcher +------------------- + +* A :variable:`CMAKE_TEST_LAUNCHER` variable and corresponding + :prop_tgt:`TEST_LAUNCHER` target property were added to specify + a launcher to be used by executable targets when invoked by + tests added by the :command:`add_test` command. + +* The :command:`add_test` command now honors + :variable:`CMAKE_CROSSCOMPILING_EMULATOR` only when cross-compiling. + See policy :policy:`CMP0158`. diff --git a/Help/release/dev/compiler-linker.rst b/Help/release/dev/compiler-linker.rst new file mode 100644 index 0000000..4783656 --- /dev/null +++ b/Help/release/dev/compiler-linker.rst @@ -0,0 +1,8 @@ +compiler-linker +--------------- + +* The linker effectively used for the link step is now documented with the + :variable:`CMAKE_<LANG>_COMPILER_LINKER`, + :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID`, + :variable:`CMAKE_<LANG>_COMPILER_LINKER_VERSION` and + :variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables. diff --git a/Help/release/dev/cpack-auto-suffixes.rst b/Help/release/dev/cpack-auto-suffixes.rst new file mode 100644 index 0000000..f3fd2af --- /dev/null +++ b/Help/release/dev/cpack-auto-suffixes.rst @@ -0,0 +1,10 @@ +cpack-auto-suffixes +------------------- + +* The :cpack_gen:`CPack DEB Generator` :variable:`CPACK_DEBIAN_FILE_NAME` + variable may now be set without any suffix, and the ``.deb`` suffix + will be added automatically. + +* The :cpack_gen:`CPack RPM Generator` :variable:`CPACK_RPM_FILE_NAME` + variable may now be set without any suffix, and the ``.rpm`` suffix + will be added automatically. diff --git a/Help/release/dev/create_test_sourcelist-full-filepath.rst b/Help/release/dev/create_test_sourcelist-full-filepath.rst new file mode 100644 index 0000000..1afa82c --- /dev/null +++ b/Help/release/dev/create_test_sourcelist-full-filepath.rst @@ -0,0 +1,5 @@ +create_test_sourcelist-full-filepath +------------------------------------ + +* The :command:`create_test_sourcelist` command now provides a full path to + the generated driver source file. diff --git a/Help/release/dev/ctest-jobserver-client.rst b/Help/release/dev/ctest-jobserver-client.rst new file mode 100644 index 0000000..37e22c0 --- /dev/null +++ b/Help/release/dev/ctest-jobserver-client.rst @@ -0,0 +1,5 @@ +ctest-jobserver-client +---------------------- + +* :manual:`ctest(1)` now supports :ref:`job server integration + <ctest-job-server-integration>` on POSIX systems. diff --git a/Help/release/dev/export-find_dependency-calls.rst b/Help/release/dev/export-find_dependency-calls.rst new file mode 100644 index 0000000..58064b7 --- /dev/null +++ b/Help/release/dev/export-find_dependency-calls.rst @@ -0,0 +1,16 @@ +export-find_dependency-calls +---------------------------- + +* :command:`install(EXPORT)` and :command:`export(EXPORT)` learned a new + ``EXPORT_PACKAGE_DEPENDENCIES`` argument, which can be used to generate + :command:`find_dependency` calls based on what targets the exported targets + depend on. +* A new :command:`export(SETUP)` signature was created to configure export + sets. This can be used to configure how :command:`find_dependency` calls are + exported. +* A new :prop_tgt:`EXPORT_FIND_PACKAGE_NAME` target property was created to + allow targets to specify what package name to pass when exporting + :command:`find_dependency` calls. This property is initialized with a new + :variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable. +* :command:`FetchContent_MakeAvailable` now sets the + :variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable for CMake projects. diff --git a/Help/release/dev/fileapi-exe-launcher.rst b/Help/release/dev/fileapi-exe-launcher.rst new file mode 100644 index 0000000..09fc2ae --- /dev/null +++ b/Help/release/dev/fileapi-exe-launcher.rst @@ -0,0 +1,7 @@ +fileapi-exe-launcher +-------------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has + been updated to 2.7. +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained + a new "launchers" field. diff --git a/Help/release/dev/find-rustc-importlibs.rst b/Help/release/dev/find-rustc-importlibs.rst new file mode 100644 index 0000000..646afff --- /dev/null +++ b/Help/release/dev/find-rustc-importlibs.rst @@ -0,0 +1,6 @@ +find-rustc-importlibs +--------------------- + +* On Windows, when targeting the MSVC ABI, the :command:`find_library` command + now considers ``.dll.lib`` file names before ``.lib``. This is the default + suffix for DLL import libraries created by Rust toolchains for the MSVC ABI. diff --git a/Help/release/dev/if-check-file-permissions.rst b/Help/release/dev/if-check-file-permissions.rst new file mode 100644 index 0000000..ec69b00 --- /dev/null +++ b/Help/release/dev/if-check-file-permissions.rst @@ -0,0 +1,5 @@ +if-check-file-permissions +------------------------- + +* The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE`` + and ``IS_EXECUTABLE`` to check file or directory permissions. diff --git a/Help/release/dev/install-export-xcframework.rst b/Help/release/dev/install-export-xcframework.rst new file mode 100644 index 0000000..513a552 --- /dev/null +++ b/Help/release/dev/install-export-xcframework.rst @@ -0,0 +1,9 @@ +install-export-xcframework +-------------------------- + +* The :command:`export(SETUP)` command gained a new ``XCFRAMEWORK_LOCATION`` + argument, which can be used to specify the location of a ``.xcframework`` + that can be substituted for the installed library. +* The :module:`CMakePackageConfigHelpers` module gained a new + :command:`generate_apple_platform_selection_file` function, which can be + used to generate a file that includes another Apple-platform-specific file. diff --git a/Help/release/dev/link-deduplicate-libs.rst b/Help/release/dev/link-deduplicate-libs.rst new file mode 100644 index 0000000..4a03f2c --- /dev/null +++ b/Help/release/dev/link-deduplicate-libs.rst @@ -0,0 +1,5 @@ +link-deduplicate-libs +--------------------- + +* CMake learned to de-duplicate libraries on link lines based on linker + capabilities. See policy :policy:`CMP0156`. diff --git a/Help/release/dev/make-test-depend-on-all.rst b/Help/release/dev/make-test-depend-on-all.rst new file mode 100644 index 0000000..ef43faf --- /dev/null +++ b/Help/release/dev/make-test-depend-on-all.rst @@ -0,0 +1,6 @@ +make-test-depend-on-all +----------------------- + +* The :variable:`CMAKE_SKIP_TEST_ALL_DEPENDENCY` variable was added + to control whether the ``test`` (or ``RUN_TESTS``) buildsystem + target depends on the ``all`` (or ``ALL_BUILD``) target. diff --git a/Help/release/dev/package-dispatch-apple.rst b/Help/release/dev/package-dispatch-apple.rst new file mode 100644 index 0000000..d49cce1 --- /dev/null +++ b/Help/release/dev/package-dispatch-apple.rst @@ -0,0 +1,7 @@ +package-dispatch-apple +---------------------- + +* The :module:`CMakePackageConfigHelpers` module gained a new + :command:`generate_apple_architecture_selection_file` function, which can be + used to generate a file that includes an architecture-specific implementation + of a package for an Apple platform. diff --git a/Help/release/dev/project-include-multiple.rst b/Help/release/dev/project-include-multiple.rst new file mode 100644 index 0000000..3f7b360 --- /dev/null +++ b/Help/release/dev/project-include-multiple.rst @@ -0,0 +1,11 @@ +project-include-multiple +------------------------ + +* The :variable:`CMAKE_PROJECT_INCLUDE`, + :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, + :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and + :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables learned + to support a :ref:`semicolon-separated list <CMake Language Lists>` of + CMake language files to be included sequentially. These variables can also + reference module names to be found in :variable:`CMAKE_MODULE_PATH` or + builtin to CMake. diff --git a/Help/release/dev/unity-build-objc.rst b/Help/release/dev/unity-build-objc.rst new file mode 100644 index 0000000..ce6460b --- /dev/null +++ b/Help/release/dev/unity-build-objc.rst @@ -0,0 +1,5 @@ +unity-build-objc +---------------- + +* The :prop_tgt:`UNITY_BUILD` target property now supports the + Objective C (``OBJC``) and Objective C++ (``OBJCXX``) languages. diff --git a/Help/release/dev/vs-ifx.rst b/Help/release/dev/vs-ifx.rst new file mode 100644 index 0000000..9e72cc7 --- /dev/null +++ b/Help/release/dev/vs-ifx.rst @@ -0,0 +1,7 @@ +vs-ifx +------ + +* :ref:`Visual Studio Generators` now support selecting between the + Intel oneAPI Fortran compiler (``ifx``) and the Intel classic Fortran + compiler (``ifort``) using a ``fortran=`` field in + :variable:`CMAKE_GENERATOR_TOOLSET`. diff --git a/Help/release/dev/wix-installscope.rst b/Help/release/dev/wix-installscope.rst new file mode 100644 index 0000000..1978698 --- /dev/null +++ b/Help/release/dev/wix-installscope.rst @@ -0,0 +1,13 @@ +wix-installscope +---------------- + +* The :cpack_gen:`CPack WIX Generator` gained a new variable, + :variable:`CPACK_WIX_INSTALL_SCOPE`, to control the + ``InstallScope`` property of WiX MSI installers. + +* The :cpack_gen:`CPack WIX Generator` now produces WiX MSI installers + that create start menu and uninstall entries for all users by default, + as documented by the :variable:`CPACK_WIX_INSTALL_SCOPE` variable + ``perMachine`` value. Previously, without a custom WiX template, + it produced installers that would only create start menu and uninstall + entries for the current user, even though they install for all users. diff --git a/Help/release/dev/xcode-embed-xpc-services b/Help/release/dev/xcode-embed-xpc-services new file mode 100644 index 0000000..f758285 --- /dev/null +++ b/Help/release/dev/xcode-embed-xpc-services @@ -0,0 +1,6 @@ +xcode-embed-xpc-services +------------------------ + +* The :prop_tgt:`XCODE_EMBED_XPC_SERVICES <XCODE_EMBED_<type>>` target property + was added to tell the :generator:`Xcode` generator what targets to put in + the ``Embed XPC Resources`` build phase. diff --git a/Help/release/index.rst b/Help/release/index.rst index b84bdb4..ea13fdc 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst b/Help/variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst new file mode 100644 index 0000000..eabda43 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX +------------------------------------- + +.. versionadded:: 3.29 + +Command line length limit for autogen targets, i.e. ``moc`` or ``uic``, +that triggers the use of response files on Windows instead of passing all +arguments to the command line. + +By default ``CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX`` is unset. diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst index 58818f4..b375b77 100644 --- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -15,4 +15,14 @@ variables which have been stored in the cache will still be there. In that case it is recommended to remove the cache variables for this package from the cache using the cache editor or :option:`cmake -U`. +Note that this variable can lead to inconsistent results within the project. +Consider the case where a dependency is requested via :command:`find_package` +from two different places within the project. If the first call does not +have the ``REQUIRED`` keyword, it will not find the dependency when +``CMAKE_DISABLE_FIND_PACKAGE_<PackageName>`` is set to true for that +dependency. The project will proceed under the assumption that the dependency +isn't available. If the second call elsewhere in the project *does* have the +``REQUIRED`` keyword, it can succeed. Two different parts of the same project +have then seen opposite results for the same dependency. + See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_EXPORT_FIND_PACKAGE_NAME.rst b/Help/variable/CMAKE_EXPORT_FIND_PACKAGE_NAME.rst new file mode 100644 index 0000000..b6c8b76 --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_FIND_PACKAGE_NAME.rst @@ -0,0 +1,6 @@ +CMAKE_EXPORT_FIND_PACKAGE_NAME +------------------------------ + +.. versionadded:: 3.29 + +Initializes the value of :prop_tgt:`EXPORT_FIND_PACKAGE_NAME`. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst index c2c2609..d78dd15 100644 --- a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst +++ b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst @@ -5,8 +5,8 @@ Suffixes to append when looking for libraries. This specifies what suffixes to add to library names when the :command:`find_library` command looks for libraries. On Windows systems this -is typically ``.lib`` and, depending on the compiler, ``.dll.a``, ``.a`` -(e.g. GCC and Clang), so when it tries to find the ``foo`` library, it will -look for ``[<prefix>]foo.lib`` and/or ``[<prefix>]foo[.dll].a``, depending on -the compiler used and the ``<prefix>`` specified in the -:variable:`CMAKE_FIND_LIBRARY_PREFIXES`. +is typically ``.lib`` and, depending on the compiler, ``.dll.lib``, ``.dll.a``, +``.a`` (e.g. rustc, GCC, or Clang), so when it tries to find the ``foo`` +library, it will look for ``[<prefix>]foo[.dll].lib`` and/or +``[<prefix>]foo[.dll].a``, depending on the compiler used and the ``<prefix>`` +specified in the :variable:`CMAKE_FIND_LIBRARY_PREFIXES`. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 4855477..b83fa01 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -48,6 +48,20 @@ Supported pairs are: See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` and :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR` variables. +``fortran=<compiler>`` + .. versionadded:: 3.29 + + Specify the Fortran compiler to use, among those that integrate with VS. + The value may be one of: + + ``ifort`` + Intel classic Fortran compiler. + + ``ifx`` + Intel oneAPI Fortran compiler. + + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_FORTRAN` variable. + ``host=<arch>`` Specify the host tools architecture as ``x64`` or ``x86``. Supported by VS 2013 and above. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER.rst new file mode 100644 index 0000000..c0ae1cd --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER.rst @@ -0,0 +1,15 @@ +CMAKE_<LANG>_COMPILER_LINKER +---------------------------- + +.. versionadded:: 3.29 + +The full path to the linker for ``LANG``. + +This is the command that will be used as the ``<LANG>`` linker. + +This variable is not guaranteed to be defined for all linkers or languages. + +.. note:: + This variable is read-only. It must not be set by the user. To select a + specific linker, use the :variable:`CMAKE_LINKER_TYPE` variable or the + :prop_tgt:`LINKER_TYPE` target property. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst new file mode 100644 index 0000000..d7d028a --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst @@ -0,0 +1,21 @@ +CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT +--------------------------------------------- + +.. versionadded:: 3.29 + +Identification string of the linker frontend variant. + +Some linkers have multiple, different frontends for accepting command +line options. (For example ``LLCM LLD`` originally only had a frontend +compatible with the ``GNU`` compiler but since its port to Windows +(``lld-link``) it now also supports a frontend compatible with ``MSVC``.) +When CMake detects such a linker it sets this variable to what would have been +the :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID` for the linker whose frontend +it resembles. + +.. note:: + In other words, this variable describes what command line options + and language extensions the linker frontend expects. + + This variable is set for ``GNU``, ``MSVC``, ``MOLD`` and ``AppleClang`` + linkers that have only one frontend variant. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst new file mode 100644 index 0000000..0607aea --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst @@ -0,0 +1,33 @@ +CMAKE_<LANG>_COMPILER_LINKER_ID +------------------------------- + +.. versionadded:: 3.29 + +Linker identification string. + +A short string unique to the linker vendor. Possible values +include: + +=============================== =============================================== +Value Name +=============================== =============================================== +``AppleClang`` Apple Clang +``LLD`` `LLVM LLD`_ +``GNU`` `GNU Binutils - ld linker`_ (also known as + ``bfd``) +``GNUgold`` `GNU Binutils - gold linker`_ +``MSVC`` `Microsoft Visual Studio`_ +``MOLD`` `mold: A Modern Linker`_ or, on Apple, `sold`_ + linker +``AIX`` AIX system linker +``Solaris`` SunOS system linker +=============================== =============================================== + +This variable is not guaranteed to be defined for all linkers or languages. + +.. _LLVM LLD: https://lld.llvm.org +.. _GNU Binutils - ld linker: https://sourceware.org/binutils +.. _GNU Binutils - gold linker: https://sourceware.org/binutils +.. _Microsoft Visual Studio: https://visualstudio.microsoft.com +.. _mold\: A Modern Linker: https://github.com/rui314/mold +.. _sold: https://github.com/bluewhalesystems/sold diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER_VERSION.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER_VERSION.rst new file mode 100644 index 0000000..72b0551 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER_VERSION.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_COMPILER_LINKER_VERSION +------------------------------------ + +.. versionadded:: 3.29 + +Linker version string. + +Linker version in major[.minor[.patch[.tweak]]] format. This +variable is not guaranteed to be defined for all linkers or +languages. diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst new file mode 100644 index 0000000..c9b6779 --- /dev/null +++ b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst @@ -0,0 +1,15 @@ +CMAKE_<LANG>_USING_LINKER_MODE +------------------------------ + +.. versionadded:: 3.29 + +This variable specify what is the type of data stored in variable + :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>`. There are two possible values: + +``FLAG`` + :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds compiler flags. This is + the default. + +``TOOL`` + :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds the path to the linker + tool. diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst new file mode 100644 index 0000000..e4d9fa6 --- /dev/null +++ b/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst @@ -0,0 +1,30 @@ +CMAKE_<LANG>_USING_LINKER_<TYPE> +-------------------------------- + +.. versionadded:: 3.29 + +This variable defines how to specify the linker for the link step for the type +as specified by the variable :variable:`CMAKE_LINKER_TYPE` or the target +property :prop_tgt:`LINKER_TYPE`. It can hold compiler flags for the link step +or directly the linker tool. The type of data is given by the variable +:variable:`CMAKE_<LANG>_USING_LINKER_MODE`. + +For example, to specify the ``LLVM`` linker for ``GNU`` compilers, we have: + +.. code-block:: cmake + + set(CMAKE_C_USING_LINKER_LLD "-fuse-ld=lld") + +Or on ``Windows`` platform, for ``Clang`` compilers simulating ``MSVC``, we +have: + +.. code-block:: cmake + + set(CMAKE_C_USING_LINKER_LLD "-fuse-ld=lld-link") + +And for the ``MSVC`` compiler, linker is directly used, so we have: + +.. code-block:: cmake + + set(CMAKE_C_USING_LINKER_LLD "/path/to/lld-link.exe") + set(CMAKE_C_USING_LINKER_MODE TOOL) diff --git a/Help/variable/CMAKE_LINKER_TYPE.rst b/Help/variable/CMAKE_LINKER_TYPE.rst new file mode 100644 index 0000000..17ea947 --- /dev/null +++ b/Help/variable/CMAKE_LINKER_TYPE.rst @@ -0,0 +1,18 @@ +CMAKE_LINKER_TYPE +----------------- + +.. versionadded:: 3.29 + +Specify which linker will be used for the link step. + +.. note:: + It is assumed that the linker specified is fully compatible with the standard + one. CMake will not do any options translation. + +This variable is used to initialize the :prop_tgt:`LINKER_TYPE` target +property when they are created by calls to :command:`add_library` or +:command:`add_executable` commands. It is meaningful only for targets having a +link step. If set, its value is also used by the :command:`try_compile` +command. + +.. include:: LINKER_PREDEFINED_TYPES.txt diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst index 76b9d92..217604f 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -3,12 +3,17 @@ CMAKE_PROJECT_INCLUDE .. versionadded:: 3.15 -A CMake language file or module to be included as the last step of all +A CMake language file to be included as the last step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. See :ref:`Code Injection` for a more detailed discussion of files potentially included during a :command:`project` call. +.. versionadded:: 3.29 + This variable can be a :ref:`semicolon-separated list <CMake Language Lists>` + of CMake language files to be included sequentially. It can also now refer to + module names to be found in :variable:`CMAKE_MODULE_PATH` or builtin to CMake. + See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, and diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst index 9a8c4b5..1dc0241 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -3,12 +3,17 @@ CMAKE_PROJECT_INCLUDE_BEFORE .. versionadded:: 3.15 -A CMake language file or module to be included as the first step of all +A CMake language file to be included as the first step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. See :ref:`Code Injection` for a more detailed discussion of files potentially included during a :command:`project` call. +.. versionadded:: 3.29 + This variable can be a :ref:`semicolon-separated list <CMake Language Lists>` + of CMake language files to be included sequentially. It can also now refer to + module names to be found in :variable:`CMAKE_MODULE_PATH` or builtin to CMake. + See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, :variable:`CMAKE_PROJECT_INCLUDE`, and diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index 3bb5cd8..6d37c1a 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -1,12 +1,17 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE ------------------------------------ -A CMake language file or module to be included as the last step of any +A CMake language file to be included as the last step of any :command:`project` command calls that specify ``<PROJECT-NAME>`` as the project name. This is intended for injecting custom code into project builds without modifying their source. See :ref:`Code Injection` for a more detailed discussion of files potentially included during a :command:`project` call. +.. versionadded:: 3.29 + This variable can be a :ref:`semicolon-separated list <CMake Language Lists>` + of CMake language files to be included sequentially. It can also now refer to + module names to be found in :variable:`CMAKE_MODULE_PATH` or builtin to CMake. + See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, :variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst index ca584c1..96ddbf6 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -3,12 +3,17 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE .. versionadded:: 3.17 -A CMake language file or module to be included as the first step of any +A CMake language file to be included as the first step of any :command:`project` command calls that specify ``<PROJECT-NAME>`` as the project name. This is intended for injecting custom code into project builds without modifying their source. See :ref:`Code Injection` for a more detailed discussion of files potentially included during a :command:`project` call. +.. versionadded:: 3.29 + This variable can be a :ref:`semicolon-separated list <CMake Language Lists>` + of CMake language files to be included sequentially. It can also now refer to + module names to be found in :variable:`CMAKE_MODULE_PATH` or builtin to CMake. + See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst index 2010b08..54f530e 100644 --- a/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst +++ b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst @@ -12,6 +12,10 @@ including things like :variable:`CMAKE_<LANG>_COMPILER`, might not be set. See :ref:`Code Injection` for a more detailed discussion of files potentially included during a :command:`project` call. +.. versionadded:: 3.29 + This variable can also now refer to module names to be found in + :variable:`CMAKE_MODULE_PATH` or builtin to CMake. + This variable is intended for specifying files that perform one-time setup for the build. It provides an injection point for things like configuring package managers, adding logic the user shares between projects (e.g. defining diff --git a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst index 893f1ae..52bf30a 100644 --- a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst @@ -11,4 +11,35 @@ turned into ``REQUIRED`` by setting the variable This can be used to assert assumptions about build environment and to ensure the build will fail early if they do not hold. +Note that setting this variable to true breaks some commonly used patterns. +Multiple calls to :command:`find_package` are sometimes used to obtain a +different search order to the default. +For example, projects can force checking a known path for a particular +package first before searching any of the other default search paths: + +.. code:: cmake + + find_package(something PATHS /some/local/path NO_DEFAULT_PATH) + find_package(something) + +In the above, the first call looks for the ``something`` package in a specific +directory. If ``CMAKE_REQUIRE_FIND_PACKAGE_something`` is set to true, then +this first call must succeed, otherwise a fatal error occurs. The second call +never gets a chance to provide a fall-back to using the default search +locations. + +A similar pattern is used even by some of CMake's own Find modules to search +for a config package first: + +.. code:: cmake + + find_package(something CONFIG QUIET) + if(NOT something_FOUND) + # Fall back to searching using typical Find module logic... + endif() + +Again, if ``CMAKE_REQUIRE_FIND_PACKAGE_something`` is true, the first call +must succeed. It effectively means a config package must be found for the +dependency, and the Find module logic is never used. + See also the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst b/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst index e88db36..69c762b 100644 --- a/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst +++ b/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst @@ -9,3 +9,5 @@ built, first the ``all`` target is built, then the installation starts. 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. + +See also :variable:`CMAKE_SKIP_TEST_ALL_DEPENDENCY`. diff --git a/Help/variable/CMAKE_SKIP_TEST_ALL_DEPENDENCY.rst b/Help/variable/CMAKE_SKIP_TEST_ALL_DEPENDENCY.rst new file mode 100644 index 0000000..bae8e99 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_TEST_ALL_DEPENDENCY.rst @@ -0,0 +1,19 @@ +CMAKE_SKIP_TEST_ALL_DEPENDENCY +------------------------------ + +.. versionadded:: 3.29 + +Control whether the ``test`` target depends on the ``all`` target. + +If this variable is not defined, or is set to ``TRUE``, then the +``test`` (or ``RUN_TESTS``) target does not depend on the +``all`` (or ``ALL_BUILD``) target. When the ``test`` target is built, +e.g., via ``make test``, the test process will start immediately, +regardless of whether the project has been completely built or not. + +If ``CMAKE_SKIP_TEST_ALL_DEPENDENCY`` is explicitly set to ``FALSE``, +then the ``test`` target will depend on the ``all`` target. When the +``test`` target is built, e.g., via ``make test``, the ``all`` target +will be built first, and then the tests will run. + +See also :variable:`CMAKE_SKIP_INSTALL_ALL_DEPENDENCY`. diff --git a/Help/variable/CMAKE_Swift_COMPILATION_MODE.rst b/Help/variable/CMAKE_Swift_COMPILATION_MODE.rst new file mode 100644 index 0000000..5e55d8c --- /dev/null +++ b/Help/variable/CMAKE_Swift_COMPILATION_MODE.rst @@ -0,0 +1,32 @@ +CMAKE_Swift_COMPILATION_MODE +---------------------------- + +.. versionadded:: 3.29 + +Specify how Swift compiles a target. This variable is used to initialize the +:prop_tgt:`Swift_COMPILATION_MODE` property on targets as they are created. + +The allowed values are: + +.. include:: ../prop_tgt/Swift_COMPILATION_MODE-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to support +per-configuration specification. For example, the code: + +.. code-block:: cmake + + set(CMAKE_Swift_COMPILATION_MODE + "$<IF:$<CONFIG:Release>,wholemodule,incremental>") + +sets the default Swift compilation mode to wholemodule mode when building a +release configuration and to incremental mode in other configurations. + +If this variable is not set then the :prop_tgt:`Swift_COMPILATION_MODE` target +property will not be set automatically. If that property is unset then CMake +uses the default value ``incremental`` to build the Swift source files. + +.. note:: + + This property only has effect when policy :policy:`CMP0157` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables the Swift language. diff --git a/Help/variable/CMAKE_TEST_LAUNCHER.rst b/Help/variable/CMAKE_TEST_LAUNCHER.rst new file mode 100644 index 0000000..c527188 --- /dev/null +++ b/Help/variable/CMAKE_TEST_LAUNCHER.rst @@ -0,0 +1,16 @@ +CMAKE_TEST_LAUNCHER +------------------- + +.. versionadded:: 3.29 + +This variable is used to specify a launcher for running tests, added +by the :command:`add_test` command, that run an executable target. +If this variable contains a :ref:`semicolon-separated list <CMake Language +Lists>`, then the first value is the command and remaining values are its +arguments. + +This variable can be initialized via an +:envvar:`CMAKE_TEST_LAUNCHER` environment variable. + +It is also used as the default value for the +:prop_tgt:`TEST_LAUNCHER` target property of executables. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN.rst new file mode 100644 index 0000000..e0ecb12 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_TOOLSET_FORTRAN +--------------------------------- + +.. versionadded:: 3.29 + +Fortran compiler to be used by Visual Studio projects. + +:ref:`Visual Studio Generators` support selecting among Fortran compilers +whose Visual Studio Integration is installed. The compiler may be specified +by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of the form ``fortran=...``. +CMake provides the selected Fortran compiler in this variable. +The value may be empty if the field was not specified. diff --git a/Help/variable/LINKER_PREDEFINED_TYPES.txt b/Help/variable/LINKER_PREDEFINED_TYPES.txt new file mode 100644 index 0000000..e8cb19f --- /dev/null +++ b/Help/variable/LINKER_PREDEFINED_TYPES.txt @@ -0,0 +1,59 @@ +Linker types are case-sensitive and may only contain letters, numbers and +underscores. Linker types defined in all uppercase are reserved for CMake's own +built-in types. The pre-defined linker types are: + +``DEFAULT`` + This type corresponds to standard linking, essentially equivalent to + not specifying :prop_tgt:`LINKER_TYPE` target property. + +``SYSTEM`` + Use the standard linker delivered by the platform or the standard toolkit + (for example, ``SYSTEM`` imply Microsoft linker for all ``MSVC`` compatible + compilers). This type is supported for the following platforms/compilers: + + * Linux, for ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers. + * All Apple variants for ``AppleClang``, ``Clang`` and ``GNU`` compilers. + * Windows, for ``MSVC``, ``GNU``, ``Clang`` and ``NVIDIA`` compilers. + +``LLD`` + Use the ``LLVM`` linker. This type is supported for the following + platforms/compilers: + + * Linux, for ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers. + * All Apple variants for ``Clang`` and ``AppleClang`` compilers. + * Windows, for ``GNU``, ``Clang`` compilers with ``GNU`` front-end and + ``CLang``, ``MSVC`` and ``NVIDIA`` compilers with ``MSVC`` front-end. + +``BFD`` + Use the ``GNU`` linker. This type is supported for the following + platforms/compilers: + + * Linux, for ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers. + * Windows, for ``GNU``, ``Clang`` compilers with ``GNU`` front-end. + +``GOLD`` + Supported on Linux platform for ``GNU``, ``Clang``, ``LLVMFlang`` and + ``NVIDIA`` compilers. + +``MOLD`` + Use the `mold linker <https://github.com/rui314/mold>`_. This type is + supported on the following platforms: + + * Linux platform for ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` + compilers. + * All Apple variants for ``Clang`` and ``AppleClang`` compilers as an + alias to ``SOLD``. + +``SOLD`` + Use the `sold linker <https://github.com/bluewhalesystems/sold>`_. This type + is only supported on Apple platforms for ``Clang`` and ``AppleClang`` + compilers. + +``APPLE_CLASSIC`` + Use the Apple linker in the classic behavior (i.e. before ``Xcode 15.0``). + This type is only supported on Apple platforms for ``GNU``, ``Clang`` and + ``AppleClang`` compilers. + +``MSVC`` + Use the Microsoft linker. This type is only supported on Windows + platform for ``MSVC`` and ``Clang`` compiler with ``MSVC`` front-end. |