diff options
Diffstat (limited to 'Help')
36 files changed, 940 insertions, 68 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index 799b6ff..2769577 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 ^^^^^^^ diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index f4833e7..e482117 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -75,7 +75,8 @@ Adds a file set to a target, or adds files to an existing file set. Targets have zero or more named file sets. Each file set has a name, a type, a scope of ``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and files within those directories. The only acceptable type is ``HEADERS``. The -optional default file sets are named after their type. +optional default file sets are named after their type. The target may not be a +custom target. Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index df13dd0..403c06e 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1113,6 +1113,230 @@ Output-Related Expressions property, perhaps via the :command:`target_link_libraries` command, to specify private link dependencies without other usage requirements. +.. 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:whole_archive,lib1>") + + This specify to use the ``lib1`` target with feature ``whole_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}``. + .. genex:: $<INSTALL_INTERFACE:...> Content of ``...`` when the property is exported using :command:`install(EXPORT)`, diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 69d0543..4620984 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -19,28 +19,16 @@ supports files included with the ``include`` field. ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root directory. They both have exactly the same format, and both are optional -(though at least one must be present if ``--preset`` is specified.) -``CMakePresets.json`` is meant to save project-wide builds, while -``CMakeUserPresets.json`` is meant for developers to save their own local -builds. ``CMakePresets.json`` may be checked into a version control system, and -``CMakeUserPresets.json`` should NOT be checked in. For example, if a project -is using Git, ``CMakePresets.json`` may be tracked, and +(though at least one must be present if ``--preset`` is specified). +``CMakePresets.json`` is meant to specify project-wide build details, while +``CMakeUserPresets.json`` is meant for developers to specify their own local +build details. + +``CMakePresets.json`` may be checked into a version control system, and +``CMakeUserPresets.json`` should NOT be checked in. For example, if a +project is using Git, ``CMakePresets.json`` may be tracked, and ``CMakeUserPresets.json`` should be added to the ``.gitignore``. -``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files -with the ``include`` field in file version ``4`` and later. Files included by -these files can also include other files. If a preset file contains presets -that inherit from presets in another file, the file must include the other file -either directly or indirectly. Include cycles are not allowed among files (if -``a.json`` includes ``b.json``, ``b.json`` cannot include ``a.json``). However, -a file may be included multiple times from the same file or from different -files. If ``CMakePresets.json`` and ``CMakeUserPresets.json`` are both present, -``CMakeUserPresets.json`` implicitly includes ``CMakePresets.json``, even with -no ``include`` field, in all versions of the format. Files directly or -indirectly included from ``CMakePresets.json`` should be guaranteed to be -provided by the project. ``CMakeUserPresets.json`` may include files from -anywhere. - Format ====== @@ -73,6 +61,13 @@ The root object recognizes the following fields: An optional integer representing the patch version. +``include`` + + An optional array of strings representing files to include. If the filenames + are not absolute, they are considered relative to the current file. + This is allowed in preset files specifying version ``4`` or above. + See `Includes`_ for discussion of the constraints on included files. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -97,11 +92,25 @@ The root object recognizes the following fields: An optional array of `Test Preset`_ objects. This is allowed in preset files specifying version ``2`` or above. -``include`` +Includes +^^^^^^^^ - An optional array of strings representing files to include. If the filenames - are not absolute, they are considered relative to the current file. - This is allowed in preset files specifying version ``4`` or above. +``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files +with the ``include`` field in file version ``4`` and later. Files included +by these files can also include other files. If ``CMakePresets.json`` and +``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json`` +implicitly includes ``CMakePresets.json``, even with no ``include`` field, +in all versions of the format. + +If a preset file contains presets that inherit from presets in another file, +the file must include the other file either directly or indirectly. +Include cycles are not allowed among files. If ``a.json`` includes +``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be +included multiple times from the same file or from different files. + +Files directly or indirectly included from ``CMakePresets.json`` should be +guaranteed to be provided by the project. ``CMakeUserPresets.json`` may +include files from anywhere. Configure Preset ^^^^^^^^^^^^^^^^ @@ -129,16 +138,20 @@ that may contain the following fields: ``inherits`` An optional array of strings representing the names of presets to inherit - from. The preset will inherit all of the fields from the ``inherits`` + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list will be - preferred. Presets in ``CMakePresets.json`` may not inherit from presets - in ``CMakeUserPresets.json``. + preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. ``condition`` @@ -371,17 +384,21 @@ that may contain the following fields: ``inherits`` - An optional array of strings representing the names of presets to - inherit from. The preset will inherit all of the fields from the + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list - will be preferred. Presets in ``CMakePresets.json`` may not inherit from - presets in ``CMakeUserPresets.json``. + will be preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. ``condition`` @@ -544,17 +561,21 @@ that may contain the following fields: ``inherits`` - An optional array of strings representing the names of presets to - inherit from. The preset will inherit all of the fields from the + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list - will be preferred. Presets in ``CMakePresets.json`` may not inherit from - presets in ``CMakeUserPresets.json``. + will be preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. ``condition`` @@ -1004,7 +1025,8 @@ Recognized macros include: ``${sourceDir}`` - Path to the project source directory. + Path to the project source directory (i.e. the same as + :variable:`CMAKE_SOURCE_DIR`). ``${sourceParentDir}`` diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index f4efd3c..65f9248 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -308,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 @@ -402,6 +404,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..ffebfff 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -437,7 +437,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 +451,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 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index f7d4f6b..3c4e76a 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -299,7 +299,8 @@ Options "cmd": "add_executable", "args": ["foo", "bar"], "time": 1579512535.9687231, - "frame": 2 + "frame": 2, + "global_frame": 4 } The members are: @@ -309,7 +310,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 @@ -326,7 +333,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 @@ -338,7 +351,7 @@ Options { "version": { "major": 1, - "minor": 1 + "minor": 2 } } @@ -646,11 +659,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. @@ -719,11 +738,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. @@ -816,16 +840,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. diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index a7ec10e..873c4ad 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -2,9 +2,13 @@ "version": 4, "cmakeMinimumRequired": { "major": 3, - "minor": 21, + "minor": 23, "patch": 0 }, + "include": [ + "otherThings.json", + "moreThings.json" + ], "configurePresets": [ { "name": "default", diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst index 1e17329..99ff512 100644 --- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -18,17 +18,19 @@ order specified in the 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/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst index d7fb9b1..8b777e4 100644 --- a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst @@ -8,9 +8,10 @@ This command will be added as a prefix to :command:`add_test`, :command:`add_custom_command`, and :command:`add_custom_target` commands for built target system executables. -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. +.. versionadded:: 3.15 + 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_CROSSCOMPILING_EMULATOR` variable if it is set when a target 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/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/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/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/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/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/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/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/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_CROSSCOMPILING_EMULATOR.rst b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst index 815da00..e21b35d 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -7,9 +7,10 @@ This variable is only used when :variable:`CMAKE_CROSSCOMPILING` is on. It should point to a command on the host system that can run executable built for the target system. -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. +.. versionadded:: 3.15 + 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. The command will be used to run :command:`try_run` generated executables, which avoids manual population of the ``TryRunResults.cmake`` file. 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..b68c94a --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,20 @@ +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 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..a9fa9a7 --- /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..8aade01 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,25 @@ +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 false or not +set. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.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..249ccbc --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +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` evaluates to + ``FALSE``. 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..7aace32 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,32 @@ +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 false or not +set. + +.. 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..ad393b0 --- /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_whole_archive_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_C_LINK_LIBRARY_USING_whole_archive "-force_load <LIB_ITEM>") + elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" + AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_LIBRARY_USING_whole_archive "LINKER:--push-state,--whole-archive" + "<LINK_ITEM>" + "LINKER:--pop-state") + elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC") + set(CMAKE_C_LINK_LIBRARY_USING_whole_archive "/WHOLEARCHIVE:<LIBRARY>") + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_LIBRARY_USING_whole_archive_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + + add_library(lib2 SHARED ...) + if(CMAKE_C_LINK_LIBRARY_USING_whole_archive_SUPPORTED) + target_link_libraries(lib2 PRIVATE + "$<LINK_LIBRARY:whole_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..42b75fc --- /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` evaluates to + ``FALSE``. diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..82c406a --- /dev/null +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -0,0 +1,47 @@ +**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 in Apple environments** + +It is assumed that the linker used is the one provided by `XCode` or is +compatible with it. + +* ``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 |