diff options
Diffstat (limited to 'Help')
71 files changed, 1686 insertions, 34 deletions
diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 6a9a6a0..11ebdbd 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -172,8 +172,9 @@ The options are: affected. Summary info detailing the percentage of passing tests is also unaffected by the ``QUIET`` option. -See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` -and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. +See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`, +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and +:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables. .. _`Additional Test Measurements`: diff --git a/Help/command/file.rst b/Help/command/file.rst index 799b6ff..3374d2d 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -1128,6 +1128,18 @@ Additional options to ``DOWNLOAD`` are: Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to specify this if ``DOWNLOAD`` is not given a ``<file>``. +``RANGE_START <value>`` + .. versionadded:: 3.24 + + Offset of the start of the range in file in bytes. Could be omitted to + download up to the specified ``RANGE_END``. + +``RANGE_END <value>`` + .. versionadded:: 3.24 + + Offset of the end of the range in file in bytes. Could be omitted to + download everything from the specified ``RANGE_START`` to the end of file. + Locking ^^^^^^^ @@ -1215,7 +1227,8 @@ the ``MTIME`` option. [DESTINATION <dir>] [PATTERNS <patterns>...] [LIST_ONLY] - [VERBOSE]) + [VERBOSE] + [TOUCH]) .. versionadded:: 3.18 @@ -1233,4 +1246,8 @@ extracted. ``LIST_ONLY`` will list the files in the archive rather than extract them. +.. versionadded:: 3.24 + The ``TOUCH`` option gives extracted files a current local + timestamp instead of extracting file timestamps from the archive. + With ``VERBOSE``, the command will produce verbose output. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 5acefad..e43b7bd 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -79,7 +79,8 @@ Basic Signature find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components...] - [NO_POLICY_SCOPE]) + [NO_POLICY_SCOPE] + [GLOBAL]) The basic signature is supported by both Module and Config modes. The ``MODULE`` keyword implies that only Module mode can be used to find @@ -115,6 +116,11 @@ define what occurs in such cases. Common arrangements include assuming it should find all components, no components or some well-defined subset of the available components. +Specifying the ``GLOBAL`` keyword will promote all imported targets to +a global scope in the importing project. Alternatively this functionality +can be enabled by setting the variable +:variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` + .. _FIND_PACKAGE_VERSION_FORMAT: The ``[version]`` argument requests a version with which the package found diff --git a/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst b/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst new file mode 100644 index 0000000..d3d0aa9 --- /dev/null +++ b/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst @@ -0,0 +1,9 @@ +CMAKE_COLOR_DIAGNOSTICS +----------------------- + +.. versionadded:: 3.24 + +.. include:: ENV_VAR.txt + +Specifies a default value for the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable +when there is no explicit value given on the first run. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 0799fdd..fc14262 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -31,6 +31,7 @@ Environment Variables that Control the Build /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_COLOR_DIAGNOSTICS /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index df13dd0..530a406 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1106,12 +1106,243 @@ Output-Related Expressions .. versionadded:: 3.1 - Content of ``...`` except when evaluated in a link interface while - propagating :ref:`Target Usage Requirements`, in which case it is the - empty string. - Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target - property, perhaps via the :command:`target_link_libraries` command, - to specify private link dependencies without other usage requirements. + Content of ``...``, except while collecting :ref:`Target Usage Requirements`, + in which case it is the empty string. This is intended for use in an + :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated + via the :command:`target_link_libraries` command, to specify private link + dependencies without other usage requirements. + + .. versionadded:: 3.24 + ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target + property. See policy :policy:`CMP0131`. + +.. genex:: $<LINK_LIBRARY:feature,library-list> + + .. versionadded:: 3.24 + + Manage how libraries are specified during the link step. + This expression may be used to specify how to link libraries in a target. + For example: + + .. code-block:: cmake + + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:load_archive,lib1>") + + This specify to use the ``lib1`` target with feature ``load_archive`` for + linking target ``lib2``. The feature must have be defined by + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable or, if + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is false, + by :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable. + + .. note:: + + The evaluation of this generator expression will use, for the following + variables, the values defined at the level of the creation of the target: + + * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` + * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` + + This expression can only be used to specify link libraries (i.e. part of + :command:`link_libraries` or :command:`target_link_libraries` commands and + :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + properties). + + .. note:: + + If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` + property of a target, it will be included in the imported target generated + by :command:`install(EXPORT)` command. It is the responsibility of the + environment consuming this import to define the link feature used by this + expression. + + The ``library-list`` argument can hold CMake targets or external libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` or + :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and + will be handled in the standard way. + + Each target or external library involved in the link step must have only one + kind of feature (the absence of feature is also incompatible with any + feature). For example: + + .. code-block:: cmake + + add_library(lib1 ...) + + add_library(lib2 ...) + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>") + + add_library(lib3 ...) + target_link_libraries(lib3 PRIVATE lib1 lib2) + # an error will be raised here because lib1 has two different features + + To resolve such incompatibilities, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` + and :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be + used. + + .. note:: + + This expression does not guarantee that the list of specified libraries + will be kept grouped. So, to manage constructs like ``start-group`` and + ``end-group``, as supported by ``GNU ld``, the :genex:`LINK_GROUP` + generator expression can be used. + + CMake pre-defines some features of general interest: + + .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt + +.. genex:: $<LINK_GROUP:feature,library-list> + + .. versionadded:: 3.24 + + Manage the grouping of libraries during the link step. + This expression may be used to specify how to kept groups of libraries during + the link of a target. + For example: + + .. code-block:: cmake + + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + + This specify to use the ``lib1`` target and ``external`` library with the + group feature ``cross_refs`` for linking target ``lib2``. The feature must + have be defined by :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` + variable or, if :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + is false, by :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable. + + .. note:: + + The evaluation of this generator expression will use, for the following + variables, the values defined at the level of the creation of the target: + + * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` + * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` + + This expression can only be used to specify link libraries (i.e. part of + :command:`link_libraries` or :command:`target_link_libraries` commands and + :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + properties). + + .. note:: + + If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` + property of a target, it will be included in the imported target generated + by :command:`install(EXPORT)` command. It is the responsibility of the + environment consuming this import to define the link feature used by this + expression. + + The ``library-list`` argument can hold CMake targets or external libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` or + :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and + will be handled in the standard way. + + .. note:: + + This expression is compatible with the :genex:`LINK_LIBRARY` generator + expression. The libraries involved in a group can be specified using the + :genex:`LINK_LIBRARY` generator expression. + + Each target or external library involved in the link step can be part of + different groups as far as these groups use the same feature, so mixing + different group features for the same target or library is forbidden. The + different groups will be part of the link step. + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>") + # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3} + + add_library(lib5 ...) + target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>") + # an error will be raised here because lib1 is part of two groups with + # different features + + When a target or an external library is involved in the link step as part of + a group and also as standalone, any occurrence of the standalone link item + will be replaced by the group or groups it belong to. + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC lib1) + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} + + This example will be "re-written" by CMake in the following form: + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} + + Be aware that the precedence of the group over the standalone link item can + result in some circular dependency between groups, which will raise an + error because circular dependencies are not allowed for groups. + + .. code-block:: cmake + + add_library(lib1A ...) + add_library(lib1B ...) + + add_library(lib2A ...) + add_library(lib2B ...) + + target_link_libraries(lib1A PUBLIC lib2A) + target_link_libraries(lib2B PUBLIC lib1B) + + add_library(lib ...) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>") + + This example will be "re-written" by CMake in the following form: + + .. code-block:: cmake + + add_library(lib1A ...) + add_library(lib1B ...) + + add_library(lib2A ...) + add_library(lib2B ...) + + target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>") + target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>") + + add_library(lib ...) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>") + + So, we have a circular dependency between groups ``{lib1A,lib1B}`` and + ``{lib2A,lib2B}``. + + CMake pre-defines some features of general interest: + + .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt .. genex:: $<INSTALL_INTERFACE:...> diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 0939a82..17a3764 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -52,6 +52,16 @@ to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.24 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132> + CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131> + CMP0130: while() diagnoses condition evaluation errors. </policy/CMP0130> + Policies Introduced by CMake 3.23 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 03bb5aa..c8d24f2 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -42,7 +42,7 @@ The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. - The supported versions are ``1``, ``2``, ``3``, and ``4``. + The supported versions are ``1``, ``2``, ``3``, ``4``, and ``5``. ``cmakeMinimumRequired`` @@ -715,6 +715,12 @@ that may contain the following fields: bytes. Equivalent to passing ``--test-output-size-failed`` on the command line. + ``testOutputTruncation`` + + An optional string specifying the test output truncation mode. Equivalent + to passing ``--test-output-truncation`` on the command line." + This is allowed in preset files specifying version ``5`` or above. + ``maxTestNameWidth`` An optional integer specifying the maximum width of a test name to diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index ddb917a..968a3b1 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -266,6 +266,8 @@ Properties on Targets /prop_tgt/INTERFACE_LINK_DEPENDS /prop_tgt/INTERFACE_LINK_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES + /prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT + /prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE /prop_tgt/INTERFACE_LINK_OPTIONS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_PRECOMPILE_HEADERS @@ -306,6 +308,8 @@ Properties on Targets /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_LIBRARIES /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS + /prop_tgt/LINK_LIBRARY_OVERRIDE + /prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC @@ -376,6 +380,7 @@ Properties on Targets /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/UNITY_BUILD_MODE /prop_tgt/UNITY_BUILD_UNIQUE_ID + /prop_tgt/VERIFY_HEADER_SETS /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE @@ -400,6 +405,7 @@ Properties on Targets /prop_tgt/VS_JUST_MY_CODE_DEBUGGING /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION + /prop_tgt/VS_NO_COMPILE_BATCHING /prop_tgt/VS_NO_SOLUTION_DEPLOY /prop_tgt/VS_PACKAGE_REFERENCES /prop_tgt/VS_PLATFORM_TOOLSET diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4df0237..0b81677 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -172,6 +172,7 @@ Variables that Change Behavior /variable/CMAKE_CODEBLOCKS_COMPILER_ID /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS + /variable/CMAKE_COLOR_DIAGNOSTICS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY @@ -197,6 +198,7 @@ Variables that Change Behavior /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 /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE @@ -437,7 +439,11 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE + /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINKER_LAUNCHER + /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE + /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG @@ -447,9 +453,13 @@ Variables that Control the Build /variable/CMAKE_LIBRARY_PATH_FLAG /variable/CMAKE_LINK_DEF_FILE_FLAG /variable/CMAKE_LINK_DEPENDS_NO_SHARED + /variable/CMAKE_LINK_GROUP_USING_FEATURE + /variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LINK_INTERFACE_LIBRARIES /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG + /variable/CMAKE_LINK_LIBRARY_USING_FEATURE + /variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LINK_WHAT_YOU_USE /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE @@ -493,6 +503,7 @@ Variables that Control the Build /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /variable/CMAKE_UNITY_BUILD_UNIQUE_ID /variable/CMAKE_USE_RELATIVE_PATHS + /variable/CMAKE_VERIFY_HEADER_SETS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_GLOBALS /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD @@ -633,6 +644,7 @@ Variables for CTest /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS /variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE + /variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION /variable/CTEST_CUSTOM_MEMCHECK_IGNORE /variable/CTEST_CUSTOM_POST_MEMCHECK /variable/CTEST_CUSTOM_POST_TEST diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 18bdc5f..3ef7b3f 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -197,6 +197,13 @@ Options .. include:: OPTIONS_BUILD.txt +``--fresh`` + .. versionadded:: 3.24 + + Perform a fresh configuration of the build tree. + This removes any existing ``CMakeCache.txt`` file and associated + ``CMakeFiles/`` directory, and recreates them from scratch. + ``-L[A][H]`` List non-advanced cached variables. @@ -326,7 +333,8 @@ Options "cmd": "add_executable", "args": ["foo", "bar"], "time": 1579512535.9687231, - "frame": 2 + "frame": 2, + "global_frame": 4 } The members are: @@ -336,7 +344,13 @@ Options was called. ``line`` - The line in ``file`` of the function call. + The line in ``file`` where the function call begins. + + ``line_end`` + If the function call spans multiple lines, this field will + be set to the line where the function call ends. If the function + calls spans a single line, this field will be unset. This field + was added in minor version 2 of the ``json-v1`` format. ``defer`` Optional member that is present when the function call was deferred @@ -353,7 +367,13 @@ Options Timestamp (seconds since epoch) of the function call. ``frame`` - Stack frame depth of the function that was called. + Stack frame depth of the function that was called, within the + context of the ``CMakeLists.txt`` being processed currently. + + ``global_frame`` + Stack frame depth of the function that was called, tracked globally + across all ``CMakeLists.txt`` files involved in the trace. This field + was added in minor version 2 of the ``json-v1`` format. Additionally, the first JSON document outputted contains the ``version`` key for the current major and minor version of the @@ -365,7 +385,7 @@ Options { "version": { "major": 1, - "minor": 1 + "minor": 2 } } @@ -673,11 +693,17 @@ Available commands are: ``true`` if cmake supports server-mode and ``false`` otherwise. Always false since CMake 3.20. -``cat <files>...`` +``cat [--] <files>...`` .. versionadded:: 3.18 Concatenate files and print on the standard output. + .. versionadded:: 3.24 + Added support for the double dash argument ``--``. This basic implementation + of ``cat`` does not support any options, so using a option starting with + ``-`` will result in an error. Use ``--`` to indicate the end of options, in + case a file starts with ``-``. + ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. @@ -746,11 +772,16 @@ Available commands are: ``echo_append [<string>...]`` Displays arguments as text but no new line. -``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`` +``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]`` .. versionadded:: 3.1 Run command in a modified environment. + .. versionadded:: 3.24 + Added support for the double dash argument ``--``. Use ``--`` to stop + interpreting options/environment variables and treat the next argument as + the command, even if it start with ``-`` or contains a ``=``. + ``environment`` Display the current environment variables. @@ -843,16 +874,16 @@ Available commands are: Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. -``rm [-rRf] <file> <dir>...`` +``rm [-rRf] [--] <file|dir>...`` .. versionadded:: 3.17 Remove the files ``<file>`` or directories ``<dir>``. - Use ``-r`` or ``-R`` to remove directories and their contents recursively. If any of the listed files/directories do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such - situations instead. + situations instead. Use ``--`` to stop interpreting options and treat all + remaining arguments as paths, even if they start with ``-``. ``server`` Launch :manual:`cmake-server(7)` mode. @@ -924,6 +955,12 @@ Available commands are: Specify modification time recorded in tarball entries. + ``--touch`` + .. versionadded:: 3.24 + + Use current local timestamp instead of extracting file timestamps + from the archive. + ``--`` .. versionadded:: 3.1 diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 1e7b077..82e27b8 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -362,6 +362,10 @@ Specify the directory in which to look for tests. ``--test-output-size-failed <size>`` Limit the output for failed tests to ``<size>`` bytes. +``--test-output-truncation <mode>`` + Truncate 'tail' (default), 'middle' or 'head' of test output once maximum + output size is reached. + ``--overwrite`` Overwrite CTest configuration option. diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index 873c4ad..be5c791 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,5 +1,5 @@ { - "version": 4, + "version": 5, "cmakeMinimumRequired": { "major": 3, "minor": 23, diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 12f8b5e..c96405c 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -57,6 +57,21 @@ "include": { "$ref": "#/definitions/include"} }, "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 5, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV5"}, + "include": { "$ref": "#/definitions/include"} + }, + "additionalProperties": false } ], "required": [ @@ -673,6 +688,28 @@ "additionalProperties": false } }, + "testPresetsItemsV5": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", + "items": { + "type": "object", + "properties": { + "output": { + "type": "object", + "description": "An optional object specifying output options.", + "properties": { + "testOutputTruncation": { + "type": "string", + "description": "An optional string specifying the test output truncation mode. Equivalent to passing --test-output-truncation on the command line. Must be one of the following values: \"tail\", \"middle\", or \"head\".", + "enum": [ + "tail", "middle", "head" + ] + } + } + } + } + } + }, "testPresetsItemsV3": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", @@ -821,8 +858,7 @@ "type": "integer", "description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line." } - }, - "additionalProperties": false + } }, "filter": { "type": "object", @@ -998,6 +1034,39 @@ ] } }, + "testPresetsV5": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" }, + { "$ref": "#/definitions/testPresetsItemsV5" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, "testPresetsV3": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", diff --git a/Help/policy/CMP0130.rst b/Help/policy/CMP0130.rst new file mode 100644 index 0000000..0dd5623 --- /dev/null +++ b/Help/policy/CMP0130.rst @@ -0,0 +1,32 @@ +CMP0130 +------- + +.. versionadded:: 3.24 + +:command:`while` diagnoses condition evaluation errors. + +CMake 3.23 and below accidentally tolerated errors encountered while +evaluating the condition passed to the :command:`while` command +(but not the :command:`if` command). For example, the code + +.. code-block:: cmake + + set(paren "(") + while(${paren}) + endwhile() + +creates an unbalanced parenthesis during condition evaluation. + +CMake 3.24 and above prefer to diagnose such errors. This policy +provides compatibility for projects that have not been updated to +fix their condition errors. + +The ``OLD`` behavior for this policy is to ignore errors in +:command:`while` conditions. The ``NEW`` behavior for this +policy is to diagnose errors in :command:`while` conditions. + +This policy was introduced in CMake version 3.24. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0131.rst b/Help/policy/CMP0131.rst new file mode 100644 index 0000000..e85b8ab --- /dev/null +++ b/Help/policy/CMP0131.rst @@ -0,0 +1,31 @@ +CMP0131 +------- + +.. versionadded:: 3.24 + +:prop_tgt:`LINK_LIBRARIES` supports the :genex:`$<LINK_ONLY:...>` +generator expression. + +CMake 3.23 and below documented the :genex:`$<LINK_ONLY:...>` generator +expression only for use in :prop_tgt:`INTERFACE_LINK_LIBRARIES`. +When used in :prop_tgt:`LINK_LIBRARIES`, the content guarded inside +:genex:`$<LINK_ONLY:...>` was always used, even when collecting non-linking +usage requirements such as :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`. + +CMake 3.24 and above prefer to support :genex:`$<LINK_ONLY:...>`, when +used in :prop_tgt:`LINK_LIBRARIES`, by using the guarded content only +for link dependencies and not other usage requirements. This policy +provides compatibility for projects that have not been updated to +account for this change. + +The ``OLD`` behavior for this policy is to use :prop_tgt:`LINK_LIBRARIES` +content guarded by :genex:`$<LINK_ONLY:...>` even for non-linking +usage requirements. The ``NEW`` behavior for this policy is to to use +the guarded content only for link dependencies. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set this policy 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/CMP0132.rst b/Help/policy/CMP0132.rst new file mode 100644 index 0000000..fadbbdc --- /dev/null +++ b/Help/policy/CMP0132.rst @@ -0,0 +1,26 @@ +CMP0132 +------- + +.. versionadded:: 3.24 + +Apart from when using the Xcode generator and some Visual Studio generators, +CMake 3.23 and below will set environment variables like :envvar:`CC`, +:envvar:`CXX`, etc. when the corresponding language is enabled. +This only occurs on the very first time CMake is run in a build directory, +and the environment variables are only defined at configure time, not build +time. On subsequent CMake runs, these environment variables are not set, +opening up the opportunity for different behavior between the first and +subsequent CMake runs. CMake 3.24 and above prefer to not set these +environment variables when a language is enabled, even on the first run in +a build directory. + +The ``OLD`` behavior for this policy sets the relevant environment variable +on the first run when a language is enabled. The ``NEW`` behavior for this +policy does not set any such environment variables. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst index a80651a..ad3e190 100644 --- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -19,17 +19,19 @@ property's value. The ``OP`` may be one of: to its state from the rest of the CTest execution. - ``set``: Replaces the current value of ``MYVAR`` with ``VALUE``. - ``unset``: Unsets the current value of ``MYVAR``. - - ``string_append``: Appends ``VALUE`` to the current value of ``MYVAR``. - - ``string_prepend``: Prepends ``VALUE`` to the current value of ``MYVAR``. - - ``path_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` - using the host platform's path list separator (``;`` on Windows and ``:`` - elsewhere). - - ``path_list_prepend``: Prepends ``VALUE`` to the current value of + - ``string_append``: Appends singular ``VALUE`` to the current value of + ``MYVAR``. + - ``string_prepend``: Prepends singular ``VALUE`` to the current value of + ``MYVAR``. + - ``path_list_append``: Appends singular ``VALUE`` to the current value of ``MYVAR`` using the host platform's path list separator (``;`` on Windows and ``:`` elsewhere). - - ``cmake_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` - using ``;`` as the separator. - - ``cmake_list_prepend``: Prepends ``VALUE`` to the current value of + - ``path_list_prepend``: Prepends singular ``VALUE`` to the current value of + ``MYVAR`` using the host platform's path list separator (``;`` on Windows + and ``:`` elsewhere). + - ``cmake_list_append``: Appends singular ``VALUE`` to the current value of + ``MYVAR`` using ``;`` as the separator. + - ``cmake_list_prepend``: Prepends singular ``VALUE`` to the current value of ``MYVAR`` using ``;`` as the separator. Unrecognized ``OP`` values will result in the test failing before it is diff --git a/Help/prop_tgt/CUDA_ARCHITECTURES.rst b/Help/prop_tgt/CUDA_ARCHITECTURES.rst index 191f78f..05c2599 100644 --- a/Help/prop_tgt/CUDA_ARCHITECTURES.rst +++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst @@ -34,6 +34,11 @@ The ``CUDA_ARCHITECTURES`` may be set to one of the following special values: Compile for all supported major real architectures, and the highest major virtual architecture. +``native`` + .. versionadded:: 3.24 + + Compile for the architecture(s) of the host's GPU(s). + Examples ^^^^^^^^ diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index af3d9c2..53f5838 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -26,6 +26,12 @@ manual for more on defining buildsystem properties. .. include:: LINK_LIBRARIES_INDIRECTION.txt +``INTERFACE_LINK_LIBRARIES`` adds transitive link dependencies for a +target's dependents. In advanced use cases, one may update the +direct link dependencies of a target's dependents by using the +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties. + Creating Relocatable Packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst new file mode 100644 index 0000000..b8b73df --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst @@ -0,0 +1,236 @@ +INTERFACE_LINK_LIBRARIES_DIRECT +------------------------------- + +.. versionadded:: 3.24 + +List of libraries that consumers of this library should treat +as direct link dependencies. + +This target property may be set to *include* items in a dependent +target's final set of direct link dependencies. See the +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target property +to exclude items. + +The initial set of a dependent target's direct link dependencies is +specified by its :prop_tgt:`LINK_LIBRARIES` target property. Indirect +link dependencies are specified by the transitive closure of the direct +link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties. +Any link dependency may specify additional direct link dependencies +using the ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property. +The set of direct link dependencies is then filtered to exclude items named +by any dependency's :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` +target property. + +.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT`` +.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt + +Direct Link Dependencies as Usage Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``INTERFACE_PROPERTY_LINK_DIRECT`` and +``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties +are :ref:`usage requirements <Target Usage Requirements>`. +Their effects propagate to dependent targets transitively, and can +therefore affect the direct link dependencies of every target in a +chain of dependent libraries. Whenever some library target ``X`` links +to another library target ``Y`` whose direct or transitive usage +requirements contain ``INTERFACE_PROPERTY_LINK_DIRECT`` or +``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, the properties may affect +``X``'s list of direct link dependencies: + +* If ``X`` is a shared library or executable, its dependencies are linked. + They also affect the usage requirements with which ``X``'s sources are + compiled. + +* If ``X`` is a static library or object library, it does not actually + link, so its dependencies at most affect the usage requirements with + which ``X``'s sources are compiled. + +The properties may also affect the list of direct link dependencies +on ``X``'s dependents: + +* If ``X`` links ``Y`` publicly: + + .. code-block:: cmake + + target_link_libraries(X PUBLIC Y) + + then ``Y`` is placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`, + so ``Y``'s usage requirements, including ``INTERFACE_PROPERTY_LINK_DIRECT``, + ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, and the usage requirements + declared by the direct link dependencies they add, are propagated to + ``X``'s dependents. + +* If ``X`` is a static library or object library, and links ``Y`` privately: + + .. code-block:: cmake + + target_link_libraries(X PRIVATE Y) + + then ``$<LINK_ONLY:Y>`` is placed in ``X``'s + :prop_tgt:`INTERFACE_LINK_LIBRARIES`. ``Y``'s linking requirements, + including ``INTERFACE_PROPERTY_LINK_DIRECT``, + ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, and the transitive link + dependencies declared by the direct link dependencies they add, are + propagated to ``X``'s dependents. However, ``Y``'s non-linking + usage requirements are blocked by the :genex:`LINK_ONLY` generator + expression, and are not propagated to ``X``'s dependents. + +* If ``X`` is a shared library or executable, and links ``Y`` privately: + + .. code-block:: cmake + + target_link_libraries(X PRIVATE Y) + + then ``Y`` is not placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`, + so ``Y``'s usage requirements, even ``INTERFACE_PROPERTY_LINK_DIRECT`` + and ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, are not propagated to + ``X``'s dependents. + +* In all cases, the content of ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES` + is not affected by ``Y``'s ``INTERFACE_PROPERTY_LINK_DIRECT`` or + ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``. + +One may limit the effects of ``INTERFACE_PROPERTY_LINK_DIRECT`` and +``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE`` to a subset of dependent +targets by using the :genex:`TARGET_PROPERTY` generator expression. +For example, to limit the effects to executable targets, use an +entry of the form:: + + "$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>" + +Similarly, to limit the effects to specific targets, use an entry +of the form:: + + "$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>" + +This entry will only affect targets that set their ``USE_IT`` +target property to a true value. + +Direct Link Dependency Ordering +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The list of direct link dependencies for a target is computed from an +initial ordered list in its :prop_tgt:`LINK_LIBRARIES` target property. +For each item, additional direct link dependencies are discovered from +its direct and transitive ``INTERFACE_LINK_LIBRARIES_DIRECT`` usage +requirements. Each discovered item is injected before the item that +specified it. However, a discovered item is added at most once, +and only if it did not appear anywhere in the initial list. +This gives :prop_tgt:`LINK_LIBRARIES` control over ordering of +those direct link dependencies that it explicitly specifies. + +Once all direct link dependencies have been collected, items named by +all of their :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` +usage requirements are removed from the final list. This does not +affect the order of the items that remain. + +Example: Static Plugins +^^^^^^^^^^^^^^^^^^^^^^^ + +Consider a static library ``Foo`` that provides a static plugin +``FooPlugin`` to consuming application executables, where the +implementation of the plugin depends on ``Foo`` and other things. +In this case, the application should link to ``FooPlugin`` directly, +before ``Foo``. However, the application author only knows about ``Foo``. +We can express this as follows: + +.. code-block:: cmake + + # Core library used by other components. + add_library(Core STATIC core.cpp) + + # Foo is a static library for use by applications. + # Implementation of Foo depends on Core. + add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp) + target_link_libraries(Foo PRIVATE Core) + + # Extra parts of Foo for use by its static plugins. + # Implementation of Foo's extra parts depends on both Core and Foo. + add_library(FooExtras STATIC foo_extras.cpp) + target_link_libraries(FooExtras PRIVATE Core Foo) + + # The Foo library has an associated static plugin + # that should be linked into the final executable. + # Implementation of the plugin depends on Core, Foo, and FooExtras. + add_library(FooPlugin STATIC foo_plugin.cpp) + target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras) + + # An app that links Foo should link Foo's plugin directly. + set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin) + + # An app does not need to link Foo directly because the plugin links it. + set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo) + +An application ``app`` only needs to specify that it links to ``Foo``: + +.. code-block:: cmake + + add_executable(app main.cpp) + target_link_libraries(app PRIVATE Foo) + +The ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property on ``Foo`` tells +CMake to pretend that ``app`` also links directly to ``FooPlugin``. +The ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target property on ``Foo`` +tells CMake to pretend that ``app`` did *not* link directly to ``Foo``. +Instead, ``Foo`` will be linked as a dependency of ``FooPlugin``. The +final link line for ``app`` will link the libraries in the following +order: + +* ``FooPlugin`` as a direct link dependency of ``app`` + (via ``Foo``'s usage requiremens). +* ``FooExtras`` as a dependency of ``FooPlugin``. +* ``Foo`` as a dependency of ``FooPlugin`` and ``FooExtras``. +* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``. + +Note that without the ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target +property, ``Foo`` would be linked twice: once as a direct dependency +of ``app``, and once as a dependency of ``FooPlugin``. + +Example: Opt-In Static Plugins +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the above `Example: Static Plugins`_, the ``app`` executable specifies +that it links directly to ``Foo``. In a real application, there might +be an intermediate library: + +.. code-block:: cmake + + add_library(app_impl STATIC app_impl.cpp) + target_link_libraries(app_impl PRIVATE Foo) + + add_executable(app main.cpp) + target_link_libraries(app PRIVATE app_impl) + +In this case we do not want ``Foo``'s ``INTERFACE_LINK_LIBRARIES_DIRECT`` +and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties to affect +the direct dependencies of ``app_impl``. To avoid this, we can revise +the property values to make their effects opt-in: + +.. code-block:: cmake + + # An app that links Foo should link Foo's plugin directly. + set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT + "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>" + ) + + # An app does not need to link Foo directly because the plugin links it. + set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE + "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>" + ) + +Now, the ``app`` executable can opt-in to get ``Foo``'s plugin(s): + +.. code-block:: cmake + + set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1) + +The final link line for ``app`` will now link the libraries in the following +order: + +* ``FooPlugin`` as a direct link dependency of ``app`` + (via ``Foo``'s usage requiremens). +* ``app_impl`` as a direct link dependency of ``app``. +* ``FooExtras`` as a dependency of ``FooPlugin``. +* ``Foo`` as a dependency of ``app_impl``, ``FooPlugin``, and ``FooExtras``. +* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``. diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt new file mode 100644 index 0000000..077af42 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt @@ -0,0 +1,9 @@ +The value of |INTERFACE_PROPERTY_LINK_DIRECT| may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +.. note:: + + The |INTERFACE_PROPERTY_LINK_DIRECT| target property is intended for + advanced use cases such as injection of static plugins into a consuming + executable. It should not be used as a substitute for organizing + normal calls to :command:`target_link_libraries`. diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst new file mode 100644 index 0000000..2f8f87f --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst @@ -0,0 +1,34 @@ +INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE +--------------------------------------- + +.. versionadded:: 3.24 + +List of libraries that consumers of this library should *not* treat +as direct link dependencies. + +This target property may be set to *exclude* items from a dependent +target's final set of direct link dependencies. This property is +processed after the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` +target property of all other dependencies of the dependent target, so +exclusion from direct link dependence takes priority over inclusion. + +The initial set of a dependent target's direct link dependencies is +specified by its :prop_tgt:`LINK_LIBRARIES` target property. Indirect +link dependencies are specified by the transitive closure of the direct +link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties. +Any link dependency may specify additional direct link dependencies +using the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property. +The set of direct link dependencies is then filtered to exclude items named +by any dependency's ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target +property. + +Excluding an item from a dependent target's direct link dependencies +does not mean the dependent target won't link the item. The item +may still be linked as an indirect link dependency via the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property on other dependencies. + +.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` +.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt + +See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property +documentation for more details and examples. diff --git a/Help/prop_tgt/LINK_LIBRARIES.rst b/Help/prop_tgt/LINK_LIBRARIES.rst index 29baf8c..ae5334a 100644 --- a/Help/prop_tgt/LINK_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_LIBRARIES.rst @@ -20,3 +20,8 @@ for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. .. include:: LINK_LIBRARIES_INDIRECTION.txt + +In advanced use cases, the list of direct link dependencies specified +by this property may be updated by usage requirements from dependencies. +See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties. diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst new file mode 100644 index 0000000..81a2a4a --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst @@ -0,0 +1,54 @@ +LINK_LIBRARY_OVERRIDE +--------------------- + +.. versionadded:: 3.24 + +To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator +expression, this property offers the possibility to override, per ``link-item`` +(``CMake`` target or external library) involved in the link step, any defined +features with a new one. + +This property takes a :ref:`;-list <CMake Language Lists>` of override +declarations which have the following format: + +:: + + feature[,link-item]* + +For the list of ``link-item`` (``CMake`` target or external library) specified, +the feature ``feature`` will be used in place of any declared feature. For +example: + +.. code-block:: cmake + + add_library(lib1 ...) + target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>") + + add_library(lib2 ...) + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>") + + add_library(lib3 ...) + target_link_libraries(lib3 PRIVATE lib1 lib2) + # Here, lib1 has two different features which prevents to link lib3 + # So, define LINK_LIBRARY_OVERRIDE property to ensure correct link + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external") + # The lib1 and external will be used with FEATURE2 to link lib3 + +It is also possible to override any feature with the pre-defined feature +``DEFAULT`` to get the standard behavior (i.e. no feature): + +.. code-block:: cmake + + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "DEFAULT,lib1" + "feature2,external") + # The lib1 will be used without any feature and external will use feature2 to link lib3 + +Contents of ``LINK_LIBRARY_OVERRIDE`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +See also :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target property for +a per linked target oriented approach to override features. + +For more information about features, see +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` +and :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables. diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst new file mode 100644 index 0000000..112f614 --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst @@ -0,0 +1,45 @@ +LINK_LIBRARY_OVERRIDE_<LIBRARY> +------------------------------- + +.. versionadded:: 3.24 + +To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator +expression, this property offers the possibility to override, for a +``link-item`` (``CMake`` target or external library) involved in the link step, +any defined features with a new one. + +This property takes a ``feature`` name which will be applied to the +``link-item`` specified by ``<LIBRARY>`` suffix property. For example: + +.. code-block:: cmake + + add_library(lib1 ...) + target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>") + + add_library(lib2 ...) + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>") + + add_library(lib3 ...) + target_link_libraries(lib3 PRIVATE lib1 lib2) + # Here, lib1 has two different features which prevents to link lib3 + # So, define LINK_LIBRARY_OVERRIDE_lib1 property to ensure correct link + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2) + # The lib1 will be used with feature2 to link lib3 + +It is also possible to override any feature with the pre-defined feature +``DEFAULT`` to get the standard behavior (i.e. no feature): + +.. code-block:: cmake + + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT) + # The lib1 will be used without any feature to link lib3 + +Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property takes precedence over :prop_tgt:`LINK_LIBRARY_OVERRIDE` +target property. + +For more information about features, see +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` +and :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables. diff --git a/Help/prop_tgt/VERIFY_HEADER_SETS.rst b/Help/prop_tgt/VERIFY_HEADER_SETS.rst new file mode 100644 index 0000000..cbfd51b --- /dev/null +++ b/Help/prop_tgt/VERIFY_HEADER_SETS.rst @@ -0,0 +1,24 @@ +VERIFY_HEADER_SETS +------------------ + +.. versionadded:: 3.24 + +Used to verify that all headers in a target's header sets can be included on +their own. + +When this property is set to true, and the target is an object library, static +library, shared library, or executable with exports enabled, and the target +has one or more header sets, an object library target named +``<target_name>_verify_header_sets`` is created. This verification target has +one source file per header in the header sets. Each source file only includes +its associated header file. The verification target links against the original +target to get all of its usage requirements. The verification target has its +:prop_tgt:`EXCLUDE_FROM_ALL` and :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` +properties set to true, and its :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC`, +:prop_tgt:`AUTOUIC`, and :prop_tgt:`UNITY_BUILD` properties set to false. + +If the header's :prop_sf:`LANGUAGE` property is set, the value of that property +is used to determine the language with which to compile the header file. +Otherwise, if the target has any C++ sources, the header is compiled as C++. +Otherwise, if the target has any C sources, the header is compiled as C. +Otherwise, the header file is not compiled. diff --git a/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst b/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst new file mode 100644 index 0000000..f8a9fa6 --- /dev/null +++ b/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst @@ -0,0 +1,21 @@ +VS_NO_COMPILE_BATCHING +---------------------- + +.. versionadded:: 3.24 + +Turn off compile batching for the target. Usually MSBuild calls the compiler +with multiple c/cpp files and compiler starts subprocesses for each file to +make the build parallel. If you want compiler to be invoked with one file at +a time set VS_NO_COMPILE_BATCHING to ON. If this flag is set MSBuild will call +compiler with one c/cpp file at a time. Useful when you want to use tool that +replaces the compiler, for example some build caching tool. + +Example +^^^^^^^ + +This shows setting the variable for the target foo. + +.. code-block:: cmake + + add_library(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON) 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/Apple-link-framework.rst b/Help/release/dev/Apple-link-framework.rst new file mode 100644 index 0000000..e194c15 --- /dev/null +++ b/Help/release/dev/Apple-link-framework.rst @@ -0,0 +1,11 @@ +Apple-link-framework +-------------------- + +* The :genex:`LINK_LIBRARY` generator expression gained the ability to link + frameworks in various ways when targeting ``Apple`` platforms. The following + new features were added: + + * ``FRAMEWORK`` + * ``NEEDED_FRAMEWORK`` + * ``REEXPORT_FRAMEWORK`` + * ``WEAK_FRAMEWORK`` diff --git a/Help/release/dev/Apple-link-library.rst b/Help/release/dev/Apple-link-library.rst new file mode 100644 index 0000000..ec4e3b6 --- /dev/null +++ b/Help/release/dev/Apple-link-library.rst @@ -0,0 +1,10 @@ +Apple-link-library +------------------ + +* The :genex:`LINK_LIBRARY` generator expression gained the ability to link + libraries in various ways when targeting ``Apple`` platforms. The following + new features were added: + + * ``NEEDED_LIBRARY`` + * ``REEXPORT_LIBRARY`` + * ``WEAK_LIBRARY`` diff --git a/Help/release/dev/Genex-LINK_GROUP.rst b/Help/release/dev/Genex-LINK_GROUP.rst new file mode 100644 index 0000000..aa9e318 --- /dev/null +++ b/Help/release/dev/Genex-LINK_GROUP.rst @@ -0,0 +1,8 @@ +Genex-LINK_GROUP +---------------- + +* The :genex:`LINK_GROUP` generator expression was added to manage the grouping + of libraries during the link step. The variables + :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and + :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` are used to define features + usable by the :genex:`LINK_GROUP` generator expression. diff --git a/Help/release/dev/Genex-LINK_LIBRARY.rst b/Help/release/dev/Genex-LINK_LIBRARY.rst new file mode 100644 index 0000000..fe44dbc --- /dev/null +++ b/Help/release/dev/Genex-LINK_LIBRARY.rst @@ -0,0 +1,11 @@ +Genex-LINK_LIBRARY +------------------ + +* The :genex:`LINK_LIBRARY` generator expression was added to manage how + libraries are specified during the link step. The variables + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` are used to define features + usable by the :genex:`LINK_LIBRARY` generator expression. Moreover, the + :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are available + to resolve incompatible features. diff --git a/Help/release/dev/LINK_LIBRARY-WHOLE_ARCHIVE.rst b/Help/release/dev/LINK_LIBRARY-WHOLE_ARCHIVE.rst new file mode 100644 index 0000000..abaf3a9 --- /dev/null +++ b/Help/release/dev/LINK_LIBRARY-WHOLE_ARCHIVE.rst @@ -0,0 +1,14 @@ +LINK_LIBRARY-WHOLE_ARCHIVE +-------------------------- + +* The :genex:`LINK_LIBRARY` generator expression gained the feature + ``WHOLE_ARCHIVE`` to force load of all members in a static library. This + feature is supported on the following target platforms: + + * all ``Apple`` variants + * ``Linux`` + * all ``BSD`` variants + * ``SunOS`` + * ``Windows`` + * ``CYGWIN`` + * ``MSYS`` diff --git a/Help/release/dev/cmake-E-tar-touch.rst b/Help/release/dev/cmake-E-tar-touch.rst new file mode 100644 index 0000000..6d1338d --- /dev/null +++ b/Help/release/dev/cmake-E-tar-touch.rst @@ -0,0 +1,6 @@ +cmake-E-tar-touch +----------------- + +* The :manual:`cmake(1)` ``-E tar`` command gained the ``--touch`` option + to keep the current local timestamp instead of extracting file timestamps + from the archive. diff --git a/Help/release/dev/cmake-fresh.rst b/Help/release/dev/cmake-fresh.rst new file mode 100644 index 0000000..6de5b4e --- /dev/null +++ b/Help/release/dev/cmake-fresh.rst @@ -0,0 +1,5 @@ +cmake-fresh +----------- + +* :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove + any existing ``CMakeCache.txt`` when configuring a build tree. diff --git a/Help/release/dev/cmcmd-end-of-options-delimiter.rst b/Help/release/dev/cmcmd-end-of-options-delimiter.rst new file mode 100644 index 0000000..bc9cc21 --- /dev/null +++ b/Help/release/dev/cmcmd-end-of-options-delimiter.rst @@ -0,0 +1,7 @@ +cmcmd-end-of-options-delimiter +------------------------------ + +* The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect + a double dash (``--``) argument that acts as a delimiter indicating the end of + options. Any following arguments are treated as operands/positional arguments, + even if they begin with a dash ``-`` character. diff --git a/Help/release/dev/color-diagnostics.rst b/Help/release/dev/color-diagnostics.rst new file mode 100644 index 0000000..8e0e225 --- /dev/null +++ b/Help/release/dev/color-diagnostics.rst @@ -0,0 +1,10 @@ +color-diagnostics +----------------- + +* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control + color diagnostics generated by compilers. This variable also controls + color buildsystem messages with :ref:`Makefile Generators`, replacing + :variable:`CMAKE_COLOR_MAKEFILE`. + + The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment was added to set + a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`. diff --git a/Help/release/dev/cpack-zstd-parallel.rst b/Help/release/dev/cpack-zstd-parallel.rst new file mode 100644 index 0000000..da22625 --- /dev/null +++ b/Help/release/dev/cpack-zstd-parallel.rst @@ -0,0 +1,6 @@ +cpack-zstd-parallel +------------------- + +* CPack now supports the :variable:`CPACK_THREADS` option for ``zstd`` + compression when compiled with libarchive 3.6 or higher. It is + supported by official CMake binaries available on ``cmake.org``. diff --git a/Help/release/dev/cuda-arch-native.rst b/Help/release/dev/cuda-arch-native.rst new file mode 100644 index 0000000..f44a668 --- /dev/null +++ b/Help/release/dev/cuda-arch-native.rst @@ -0,0 +1,7 @@ +cuda-arch-native +---------------- + +* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated + :prop_tgt:`CUDA_ARCHITECTURES` target property now support the + special ``native`` value to compile for the architectures(s) + of the host's GPU(s). diff --git a/Help/release/dev/file-download-range.rst b/Help/release/dev/file-download-range.rst new file mode 100644 index 0000000..194100d --- /dev/null +++ b/Help/release/dev/file-download-range.rst @@ -0,0 +1,6 @@ +file-download-range +------------------- + +* Add the fields ``RANGE_START`` and ``RANGE_END`` to ``file(DOWNLOAD)``. + Those fields provide a convenient way to specify the range, passed to the + libcurl, which can be useful for downloading parts of big binary files. diff --git a/Help/release/dev/find_package-global-imported.rst b/Help/release/dev/find_package-global-imported.rst new file mode 100644 index 0000000..b32d18d --- /dev/null +++ b/Help/release/dev/find_package-global-imported.rst @@ -0,0 +1,9 @@ +find_package-global-imported +---------------------------- + +* The :command:`find_package` command gained a `GLOBAL` option that + allows for the promotion of imported targets to global scope fur the + duration of the :command:`find_package` call. + +* Adds support for :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` to + toggle behavior of the :command:`find_package` command's new GLOBAL option diff --git a/Help/release/dev/findzlib-static.rst b/Help/release/dev/findzlib-static.rst new file mode 100644 index 0000000..35855f6 --- /dev/null +++ b/Help/release/dev/findzlib-static.rst @@ -0,0 +1,5 @@ +findzlib-static +--------------- + +* The :module:`FindZLIB` learned a new ``ZLIB_USE_STATIC_LIBS`` variable to + search only for static libraries. diff --git a/Help/release/dev/ghs_predefined_targets.rst b/Help/release/dev/ghs_predefined_targets.rst new file mode 100644 index 0000000..eeca5a9 --- /dev/null +++ b/Help/release/dev/ghs_predefined_targets.rst @@ -0,0 +1,6 @@ +ghs_predefined_targets +---------------------- + +* A new predefined target `RERUN_CMAKE` is added for + :generator:`Green Hills MULTI` generator to easily rerun + CMake if any CMake files were updated. diff --git a/Help/release/dev/link-interface-direct.rst b/Help/release/dev/link-interface-direct.rst new file mode 100644 index 0000000..8b858e2 --- /dev/null +++ b/Help/release/dev/link-interface-direct.rst @@ -0,0 +1,11 @@ +link-interface-direct +--------------------- + +* The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties + were added to express usage requirements affecting a consumer's + direct link dependencies. + +* The :prop_tgt:`LINK_LIBRARIES` target property now supports + the :genex:`$<LINK_ONLY:...>` generator expression. + See policy :policy:`CMP0131`. diff --git a/Help/release/dev/rescan-static-libraries.rst b/Help/release/dev/rescan-static-libraries.rst new file mode 100644 index 0000000..8892d70 --- /dev/null +++ b/Help/release/dev/rescan-static-libraries.rst @@ -0,0 +1,6 @@ +rescan-static-libraries +----------------------- + +* The :genex:`LINK_GROUP` generator expression gained the ability to manage, on + ``Linux`` and ``BSD`` systems, circular references between static libraries + by using ``RESCAN`` feature. diff --git a/Help/release/dev/set-env-var-first-run.rst b/Help/release/dev/set-env-var-first-run.rst new file mode 100644 index 0000000..c3f7d9f --- /dev/null +++ b/Help/release/dev/set-env-var-first-run.rst @@ -0,0 +1,6 @@ +set-env-var-first-run +--------------------- + +* CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`, + etc. when enabling the corresponding language during the first CMake run in + a build directory. See policy :policy:`CMP0132`. diff --git a/Help/release/dev/trace-global-frame.rst b/Help/release/dev/trace-global-frame.rst new file mode 100644 index 0000000..fdc4b5c --- /dev/null +++ b/Help/release/dev/trace-global-frame.rst @@ -0,0 +1,8 @@ +trace-global-frame +------------------ + +* Add the field ``global_frame`` to the json-v1 trace format. This + frame tracks the depth of the call stack globally across all + ``CMakeLists.txt`` files involved in the trace, and will let tools + reconstruct stack traces that span from the top-level ``CMakeLists.txt`` + file of the project. diff --git a/Help/release/dev/trace-line-end.rst b/Help/release/dev/trace-line-end.rst new file mode 100644 index 0000000..beade4b --- /dev/null +++ b/Help/release/dev/trace-line-end.rst @@ -0,0 +1,7 @@ +trace-line-end +-------------- + +* Add the field ``line_end`` to the json-v1 trace format. This + field tells you the line in file ``file`` at which the function + call ends. Tools can use this new field, together with ``line`` + and ``file``, to map traces to lines of CMake source code. diff --git a/Help/release/dev/verify-header-sets.rst b/Help/release/dev/verify-header-sets.rst new file mode 100644 index 0000000..7676382 --- /dev/null +++ b/Help/release/dev/verify-header-sets.rst @@ -0,0 +1,7 @@ +verify-header-sets +------------------ + +* A new :prop_tgt:`VERIFY_HEADER_SETS` target property was added, which can be + used to verify that all headers in header sets can be used on their own. +* A new :variable:`CMAKE_VERIFY_HEADER_SETS` variable was added, which is used + to initialize the :prop_tgt:`VERIFY_HEADER_SETS` target property. diff --git a/Help/release/dev/vs_buildcache_support.rst b/Help/release/dev/vs_buildcache_support.rst new file mode 100644 index 0000000..bdda675 --- /dev/null +++ b/Help/release/dev/vs_buildcache_support.rst @@ -0,0 +1,6 @@ +vs_buildcache_support +--------------------- + +* The :prop_tgt:`VS_NO_COMPILE_BATCHING` target property was added to + tell :ref:`Visual Studio Generators` whether to disable compiler parallelism + and call the compiler with one c/cpp file at a time. diff --git a/Help/release/dev/while-errors.rst b/Help/release/dev/while-errors.rst new file mode 100644 index 0000000..c39e6e8 --- /dev/null +++ b/Help/release/dev/while-errors.rst @@ -0,0 +1,5 @@ +while-errors +------------ + +* The :command:`while` command now diagnoses errors during condition + evaluation. See policy :policy:`CMP0130`. diff --git a/Help/release/index.rst b/Help/release/index.rst index ee677a3..ad33705 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_COLOR_DIAGNOSTICS.rst b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst new file mode 100644 index 0000000..a72c9e1 --- /dev/null +++ b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst @@ -0,0 +1,37 @@ +CMAKE_COLOR_DIAGNOSTICS +----------------------- + +.. versionadded:: 3.24 + +Enable color diagnostics throughout. + +This variable uses three states: ``ON``, ``OFF`` and not defined. + +When not defined: + +* :ref:`Makefile Generators` initialize the :variable:`CMAKE_COLOR_MAKEFILE` + variable to ``ON``. It controls color buildsystem messages. + +* GNU/Clang compilers are not invoked with any color diagnostics flag. + +When ``ON``: + +* :ref:`Makefile Generators` produce color buildsystem messages by default. + :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be + explicitly set to ``OFF`` to disable color buildsystem messages. + +* GNU/Clang compilers are invoked with a flag enabling color diagnostics + (``-fcolor-diagnostics``). + +When ``OFF``: + +* :ref:`Makefile Generators` do not produce color buildsystem messages by + default. :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be + explicitly set to ``ON`` to enable color buildsystem messages. + +* GNU/Clang compilers are invoked with a flag disabling color diagnostics + (``-fno-color-diagnostics``). + +If the :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable is set, its +value is used. Otherwise, ``CMAKE_COLOR_DIAGNOSTICS`` is not defined by +default. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst new file mode 100644 index 0000000..58efccf --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst @@ -0,0 +1,10 @@ +CMAKE_FIND_PACKAGE_TARGETS_GLOBAL +--------------------------------- + +Setting to ``TRUE`` promotes all :prop_tgt:`IMPORTED` targets discoverd +by :command:`find_package` to a ``GLOBAL`` scope. + + +Setting this to ``TRUE`` is akin to specifying ``GLOBAL`` +as an argument to :command:`find_package`. +Default value is ``OFF``. diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..f2ef843 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,27 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> +--------------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>`` and the linker language +``<LANG>``, the expression expected by the linker when libraries are specified +using :genex:`LINK_GROUP` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable for the definition of +features independent from the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..533eee7 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`, is supported for the +linker language ``<LANG>``. + +.. note:: + + This variable is evaluated before the more generic variable + :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED`. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst new file mode 100644 index 0000000..220ae99 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,27 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> +----------------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>`` and the linker language +``<LANG>``, the expression expected by the linker when libraries are specified +using :genex:`LINK_LIBRARY` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable for the definition of +features independent from the link language. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..e595bc7 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED +--------------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`, is supported for the +linker language ``<LANG>``. + +.. note:: + + This variable is evaluated before the more generic variable + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`. diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..692c099 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,33 @@ +CMAKE_LINK_GROUP_USING_<FEATURE> +-------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>``, the expression expected +by the linker when libraries are specified using :genex:`LINK_GROUP` generator +expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable for the definition +of features dependent from the link language. + +This variable will be used by :genex:`LINK_GROUP` generator expression if, +for the linker language, the variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is not defined +and the variable :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is +``TRUE``.. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt new file mode 100644 index 0000000..ecd9cb5 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt @@ -0,0 +1,54 @@ + +It must contain two elements. + +:: + + <PREFIX> <SUFFIX> + +``<PREFIX>`` and ``<SUFFIX>`` will be used to encapsulate the list of +libraries. + +For the elements of this variable, the ``LINKER:`` prefix can be used: + + .. include:: ../command/LINK_OPTIONS_LINKER.txt + :start-line: 3 + +Examples +^^^^^^^^ + +Solving cross-references between two static libraries +""""""""""""""""""""""""""""""""""""""""""""""""""""" + +A common need is the capability to search repeatedly in a group of static +libraries until no new undefined references are created. This capability is +offered by different environments but with a specific syntax: + +.. code-block:: cmake + + set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "GNU" + AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_GROUP_USING_cross_refs "LINKER:--start-group" + "LINKER:--end-group") + elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" + AND CMAKE_SYSTEM_NAME STREQUAL "SunOS") + set(CMAKE_C_LINK_GROUP_USING_cross_refs "LINKER:-z,rescan-start" + "LINKER:-z,rescan-end") + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + + add_library(lib3 SHARED ...) + if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + else() + target_link_libraries(lib3 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``GNU``: ``-Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group`` +* ``SunPro``: ``-Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,rescan-end`` diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..318892f --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------ + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`, is supported regardless the +linker language. + +.. note:: + + This variable is evaluated if, and only if, the variable + :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is not defined. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst new file mode 100644 index 0000000..9f1cede --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,33 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE> +---------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``FEATURE``, the expression expected +by the linker, regardless the linker language, when libraries are specified +using :genex:`LINK_LIBRARY` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable for the +definition of features dependent from the link language. + +This variable will be used by :genex:`LINK_LIBRARY` generator expression if, +for the linker language, the variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is not defined +and the variable :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is +``TRUE``. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt new file mode 100644 index 0000000..ec293d3 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt @@ -0,0 +1,112 @@ + +It can contain one or three elements. + +:: + + [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>] + +When ``<PREFIX>`` and/or ``<SUFFIX>`` are specified, they encapsulate the list +of libraries. + +.. note:: + + Even if ``<PREFIX>`` and ``<SUFFIX>`` are specified, there is not guarantee + that the list of specified libraries, as part of :genex:`LINK_LIBRARY` + generator expression, will be kept grouped. So, constructs like + ``start-group`` and ``end-group``, as supported by ``GNU ld``, cannot be + used. + +``<LIBRARY_EXPRESSION>`` is used to specify the decoration for each +library. For that purpose, the patterns ``<LIBRARY>``, ``<LINK_ITEM>``, and +``<LIB_ITEM>`` are available: + +* ``<LIBRARY>`` is expanded to the library as computed by CMake. +* ``<LINK_ITEM>`` is expanded to the same expression as if the library was + specified in the standard way. +* ``<LIB_ITEM>`` is equivalent to ``<LIBRARY>`` for CMake targets and is + expanded to the item specified by the user for external libraries. + +Moreover, it is possible to have different decorations for paths (CMake targets +and external libraries specified with absolute paths) and other items specified +by name. For that purpose, ``PATH{}`` and ``NAME{}`` wrappers can be used. + +For all three elements of this variable, the ``LINKER:`` prefix can be used: + + .. include:: ../command/LINK_OPTIONS_LINKER.txt + :start-line: 3 + +Examples +^^^^^^^^ + +Loading a whole static library +"""""""""""""""""""""""""""""" + +A common need is the capability to load a whole static library. This capability +is offered by various environments but with a specific syntax: + +.. code-block:: cmake + + set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>") + elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" + AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "LINKER:--push-state,--whole-archive" + "<LINK_ITEM>" + "LINKER:--pop-state") + elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>") + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + + add_library(lib2 SHARED ...) + if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED) + target_link_libraries(lib2 PRIVATE + "$<LINK_LIBRARY:load_archive,lib1,$<IF:$<LINK_LANG_AND_ID:C,Clang>,libexternal.a,external>>") + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``Clang``: ``-force_load /path/to/lib1.a -force_load libexternal.a`` +* ``GNU``: ``-Wl,--whole-archive /path/to/lib1.a -lexternal -Wl,--no-whole-archive`` +* ``MSVC``: ``/WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib`` + +CMake will ensure, when possible, that ``<PREFIX>`` and ``<SUFFIX>`` are +not repeated for each library. + +In case of ``Clang``, the pattern ``<LIB_ITEM>`` is used because we need to +specify the library as defined by the user, not the name computed by CMake +(in that case ``external``). + +Linking a library as weak +""""""""""""""""""""""""" + +On MacOS, it is possible to link a library in weak mode (the library and all +references are marked as weak imports), but different flags must be used for a +library specified by path and by name. This constraint by be solved by using +``PATH{}`` and ``NAME{}`` wrappers: + +.. code-block:: cmake + + if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_LINK_LIBRARY_USING_weak_library + "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}") + set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE) + endif() + + add_library(lib SHARED ...) + add_executable(main ...) + if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED) + target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>") + else() + target_link_libraries(main PRIVATE lib external) + endif() + +CMake will generate the following link expression: +``-weak_library /path/to/lib -Xlinker -weak-lexternal`` diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..417724b --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED +-------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>`, is supported regardless the +linker language. + +.. note:: + + This variable is evaluated if, and only if, the variable + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is not + defined. diff --git a/Help/variable/CMAKE_VERIFY_HEADER_SETS.rst b/Help/variable/CMAKE_VERIFY_HEADER_SETS.rst new file mode 100644 index 0000000..8bd618a --- /dev/null +++ b/Help/variable/CMAKE_VERIFY_HEADER_SETS.rst @@ -0,0 +1,17 @@ +CMAKE_VERIFY_HEADER_SETS +------------------------ + +.. versionadded:: 3.24 + +This variable is used to initialize the :prop_tgt:`VERIFY_HEADER_SETS` +property of targets when they are created. Setting it to true +enables header set verification. + +Projects should not set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable header set verification according to the capabilities of their own +machine and compiler. + +By default, this variable is not set, which will result in header set +verification being disabled. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst index 7e7d431..007cfe0 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst @@ -3,7 +3,8 @@ CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE When saving a failing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 307200 -(300 KiB). +(300 KiB). See :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` for possible +truncation modes. If a test's output contains the literal string "CTEST_FULL_OUTPUT", the output will not be truncated and may exceed the maximum size. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst index 64367f9..8545fc4 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst @@ -3,7 +3,8 @@ CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE When saving a passing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 1024 -(1 KiB). +(1 KiB). See :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` for possible +truncation modes. If a test's output contains the literal string "CTEST_FULL_OUTPUT", the output will not be truncated and may exceed the maximum size. diff --git a/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst b/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst new file mode 100644 index 0000000..2d4219e --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst @@ -0,0 +1,12 @@ +CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION +----------------------------------- + +.. versionadded:: 3.24 + +Set the test output truncation mode in case a maximum size is configured +via the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` or +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. +By default the ``tail`` of the output will be truncated. Other possible +values are ``middle`` and ``head``. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..5f1a11b --- /dev/null +++ b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt @@ -0,0 +1,22 @@ +**Circular references with static libraries** + +Some linkers are one-pass only so to handle circular references between +static libraries, the following feature can be used: + +``RESCAN`` + The specified static libraries are searched repeatedly until no + new undefined references are created. Normally, an static library is searched + only once in the order that it is specified on the command line. If a symbol + in that library is needed to resolve an undefined symbol referred to by an + object in an library that appears later on the command line, the linker would + not be able to resolve that reference. By grouping the static libraries, they + all be searched repeatedly until all possible references are resolved (use + linker options ``--start-group`` and ``--end-group`` or, on ``SunOS``, + ``-z rescan-start`` and ``-z rescan-end``). + + Using this feature has a significant performance cost. It is best to use it + only when there are unavoidable circular references between two or more + static libraries. + + This feature is available on ``Linux``, ``BSD``, and ``SunOS`` target + platforms as well as ``Windows`` when ``GNU`` toolchain is used. diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..e4fa0ed8 --- /dev/null +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -0,0 +1,88 @@ +**Features available in all environments** + +``DEFAULT`` + This feature enables default link expression. This is mainly + useful with :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties. + +**Features available for a subset of environments** + +``WHOLE_ARCHIVE`` + Force load of all members in a static library. + + Target platforms supported: all ``Apple`` variants, ``Linux``, all ``BSD`` + variants, ``SunOS``, ``Windows``, ``CYGWIN``, and ``MSYS``. + + Platform-specific notes: + + * On Apple platforms, the library must be specified as a CMake target name, a + library file name (such as ``libfoo.a``), or a library file path (such as + ``/path/to/libfoo.a``). It cannot be specified as a plain library name + (such as ``foo``, where ``foo`` is not CMake target), due to a limitation + in the Apple linker. + * On Windows platforms, for ``MSVC`` or MSVC-like toolchains, the version + must be greater than ``1900``. + +**Features available in Apple environments** + +It is assumed that the linker used is the one provided by `XCode` or is +compatible with it. + +Framework support + +``FRAMEWORK`` + This option tells the linker to search for the specified + framework (use linker option ``-framework``). +``NEEDED_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but means + to really link with the framework even if no symbols are used from it (use + linker option ``-needed_framework``). +``REEXPORT_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but + also specifies that all symbols in that framework should be available to + clients linking to the library being created (use linker option + ``-reexport_framework``). +``WEAK_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but forces + the framework and all references to it to be marked as weak imports (use + linker option ``-weak_framework``). + +Features for framework linking have a special handling in CMake: the +framework can be specified as a CMake framework target or file path. In the +first case, the target must have the :prop_tgt:`FRAMEWORK` target property set +as ``TRUE`` to enable framework handling. In the later case, if the path +includes a directory part, this one will be specified as framework search path +at link step. + +.. code-block:: cmake + + add_library(lib SHARED ...) + target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:NEEDED_FRAMEWORK,/path/to/my_framework>") + + # at link step we will have: + # -F/path/to -needed_framework my_framework + +.. note:: + + The expected formats for the file path, with optional parts specified as + ``()?``, are: + + * (/path/to/)?FwName(.framework)? + * (/path/to/)?FwName.framework/FwName + * (/path/to/)?FwName.framework/Versions/\*/FwName + +Library support + +``NEEDED_LIBRARY`` + This is the same as specifying a link item (target or + library) but means to really link with the item even if no symbols are used + from it (use linker option ``-needed_library`` or ``-needed-l``). +``REEXPORT_LIBRARY`` + This is the same as specifying a link item (target or + library) but also specifies that all symbols in that item should be available + to clients linking to the library being created (use linker option + ``-reexport_library`` or ``-reexport-l``). +``WEAK_LIBRARY`` + This is the same as specifying a link item (target or + library) but forces the item and all references to it to be marked as weak + imports (use linker option ``-weak_library`` or ``-weak-l``). |