diff options
Diffstat (limited to 'Help')
21 files changed, 577 insertions, 56 deletions
diff --git a/Help/command/export.rst b/Help/command/export.rst index e8a1fa7..dc69645 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -1,44 +1,62 @@ export ------ -Export targets from the build tree for use by outside projects. +Export targets or packages for outside projects to use them directly +from the current project's build tree, without installation. + +See the :command:`install(EXPORT)` command to export targets from an +install tree. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + export(`TARGETS`_ <target>... [...]) + export(`EXPORT`_ <export-name> [...]) + export(`PACKAGE`_ <PackageName>) + +Exporting Targets +^^^^^^^^^^^^^^^^^ + +.. _`export(TARGETS)`: +.. _TARGETS: .. code-block:: cmake - export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + export(TARGETS <target>... [NAMESPACE <namespace>] + [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) Creates a file ``<filename>`` that may be included by outside projects to -import targets from the current project's build tree. This is useful -during cross-compiling to build utility executables that can run on -the host platform in one project and then import them into another -project being compiled for the target platform. If the ``NAMESPACE`` -option is given the ``<namespace>`` string will be prepended to all target -names written to the file. - -Target installations are associated with the export ``<export-name>`` -using the ``EXPORT`` option of the :command:`install(TARGETS)` command. +import targets named by ``<target>...`` from the current project's build tree. +This is useful during cross-compiling to build utility executables that can +run on the host platform in one project and then import them into another +project being compiled for the target platform. The file created by this command is specific to the build tree and should never be installed. See the :command:`install(EXPORT)` command to -export targets from an installation tree. +export targets from an install tree. -The properties set on the generated IMPORTED targets will have the -same values as the final values of the input TARGETS. +The options are: -.. code-block:: cmake +``NAMESPACE <namespace>`` + Prepend the ``<namespace>`` string to all target names written to the file. - export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>] - [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) +``APPEND`` + Append to the file instead of overwriting it. This can be used to + incrementally export multiple targets to the same file. + +``EXPORT_LINK_INTERFACE_LIBRARIES`` + Include the contents of the properties named with the pattern + ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` + in the export, even when policy :policy:`CMP0022` is NEW. This is useful + to support consumers using CMake versions older than 2.8.12. -This signature is similar to the ``EXPORT`` signature, but targets are listed -explicitly rather than specified as an export-name. If the APPEND option is -given the generated code will be appended to the file instead of overwriting it. -The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the -contents of the properties matching -``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when -policy CMP0022 is NEW. If a library target is included in the export -but a target to which it links is not included the behavior is -unspecified. +This signature requires all targets to be listed explicitly. If a library +target is included in the export, but a target to which it links is not +included, the behavior is unspecified. See the `export(EXPORT)`_ signature +to automatically export the same targets from the build tree as +:command:`install(EXPORT)` would from an install tree. .. note:: @@ -49,6 +67,50 @@ unspecified. transitive usage requirements of other targets that link to the object libraries in their implementation. +Exporting Targets to Android.mk +""""""""""""""""""""""""""""""" + +.. code-block:: cmake + + export(TARGETS <target>... ANDROID_MK <filename>) + +.. versionadded:: 3.7 + +This signature exports cmake built targets to the android ndk build system +by creating an ``Android.mk`` file that references the prebuilt targets. The +Android NDK supports the use of prebuilt libraries, both static and shared. +This allows cmake to build the libraries of a project and make them available +to an ndk build system complete with transitive dependencies, include flags +and defines required to use the libraries. The signature takes a list of +targets and puts them in the ``Android.mk`` file specified by the +``<filename>`` given. This signature can only be used if policy +:policy:`CMP0022` is NEW for all targets given. A error will be issued if +that policy is set to OLD for one of the targets. + +Exporting Targets matching install(EXPORT) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`export(EXPORT)`: +.. _EXPORT: + +.. code-block:: cmake + + export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + +Creates a file ``<filename>`` that may be included by outside projects to +import targets from the current project's build tree. This is the same +as the `export(TARGETS)`_ signature, except that the targets are not +explicitly listed. Instead, it exports the targets associated with +the installation export ``<export-name>``. Target installations may be +associated with the export ``<export-name>`` using the ``EXPORT`` option +of the :command:`install(TARGETS)` command. + +Exporting Packages +^^^^^^^^^^^^^^^^^^ + +.. _`export(PACKAGE)`: +.. _PACKAGE: + .. code-block:: cmake export(PACKAGE <PackageName>) @@ -74,20 +136,3 @@ registry. outside the source and build trees. Set the :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to the CMake user package registry. - -.. code-block:: cmake - - export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>]) - -.. versionadded:: 3.7 - -This signature exports cmake built targets to the android ndk build system -by creating an Android.mk file that references the prebuilt targets. The -Android NDK supports the use of prebuilt libraries, both static and shared. -This allows cmake to build the libraries of a project and make them available -to an ndk build system complete with transitive dependencies, include flags -and defines required to use the libraries. The signature takes a list of -targets and puts them in the Android.mk file specified by the ``<filename>`` -given. This signature can only be used if policy CMP0022 is NEW for all -targets given. A error will be issued if that policy is set to OLD for one -of the targets. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index df13dd0..7c34671 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1113,6 +1113,83 @@ 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_USING_<FEATURE>` variable or, if + :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED` is false, + by :variable:`CMAKE_LINK_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_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>` + * :variable:`CMAKE_LINK_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_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, constructs like ``start-group`` and + ``end-group``, as supported by ``GNU ld``, cannot be used. + + ``CMake`` pre-defines some features of general interest: + + .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt + .. genex:: $<INSTALL_INTERFACE:...> Content of ``...`` when the property is exported using :command:`install(EXPORT)`, 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..5db622c 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -440,6 +440,8 @@ Variables that Control the Build /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG + /variable/CMAKE_LANG_LINK_USING_FEATURE + /variable/CMAKE_LANG_LINK_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY @@ -450,6 +452,8 @@ Variables that Control the Build /variable/CMAKE_LINK_INTERFACE_LIBRARIES /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG + /variable/CMAKE_LINK_USING_FEATURE + /variable/CMAKE_LINK_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 c2b4d68..a584141 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -250,16 +250,17 @@ Options See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging a more local part of the project. -``--debug-find=<pkg>[,...]`` +``--debug-find-pkg=<pkg>[,...]`` Put cmake find commands in a debug mode when running under calls - to ``find_package(<pkg>)``, where ``<pkg>`` is an entry in the given - comma-separated list of case-sensitive package names. + to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>`` + is an entry in the given comma-separated list of case-sensitive package + names. Like ``--debug-find``, but limiting scope to the specified packages. ``--debug-find-var=<var>[,...]`` Put cmake find commands in a debug mode when called with ``<var>`` - as the return variable, where ``<var>`` is an entry in the given + as the result variable, where ``<var>`` is an entry in the given comma-separated list. Like ``--debug-find``, but limiting scope to the specified variable names. @@ -298,7 +299,8 @@ Options "cmd": "add_executable", "args": ["foo", "bar"], "time": 1579512535.9687231, - "frame": 2 + "frame": 2, + "global_frame": 4 } The members are: @@ -308,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 @@ -325,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 @@ -337,7 +351,7 @@ Options { "version": { "major": 1, - "minor": 1 + "minor": 2 } } @@ -646,11 +660,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 +739,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 +841,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/prop_tgt/LINK_LIBRARY_OVERRIDE.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst new file mode 100644 index 0000000..e9c76b0 --- /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_USING_<FEATURE>` +and :variable:`CMAKE_LINK_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..58141c9 --- /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_USING_<FEATURE>` +and :variable:`CMAKE_LINK_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/Genex-LINK_LIBRARY.rst b/Help/release/dev/Genex-LINK_LIBRARY.rst new file mode 100644 index 0000000..3234acb --- /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_USING_<FEATURE>` and + :variable:`CMAKE_LINK_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/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_LANG_LINK_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst new file mode 100644 index 0000000..9d7f87a --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst @@ -0,0 +1,26 @@ +CMAKE_<LANG>_LINK_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 defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_USING_<FEATURE>` variable for the definition of features +independent from the link language. + +.. include:: CMAKE_LINK_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_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..5794b15 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED +------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>`, is supported for the linker +language ``<LANG>``. + +.. note:: + + This variable is evaluated before the more generic variable + :variable:`CMAKE_LINK_USING_<FEATURE>_SUPPORTED`. diff --git a/Help/variable/CMAKE_LINK_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_USING_FEATURE.rst new file mode 100644 index 0000000..0c9cadc --- /dev/null +++ b/Help/variable/CMAKE_LINK_USING_FEATURE.rst @@ -0,0 +1,30 @@ +CMAKE_LINK_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 defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_LINK_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_<LANG>_LINK_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_USING_<FEATURE>_SUPPORTED` is false or not set. + +.. include:: CMAKE_LINK_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_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_USING_FEATURE.txt new file mode 100644 index 0000000..92fc92d --- /dev/null +++ b/Help/variable/CMAKE_LINK_USING_FEATURE.txt @@ -0,0 +1,111 @@ + +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_USING_whole_archive_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_C_LINK_USING_whole_archive "-force_load <LIB_ITEM>") + elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" + AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_USING_whole_archive "LINKER:--push-state,--whole-archive" + "<LINK_ITEM>" + "LINKER:--pop-state") + elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC") + set(CMAKE_C_LINK_USING_whole_archive "/WHOLEARCHIVE:<LIBRARY>") + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_USING_whole_archive_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + + add_library(lib2 SHARED ...) + if(CMAKE_C_LINK_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_USING_weak_library "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}") + set(CMAKE_LINK_USING_weak_library_SUPPORTED TRUE) + endif() + + add_library(lib SHARED ...) + add_executable(main ...) + if(CMAKE_LINK_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_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..31c3108 --- /dev/null +++ b/Help/variable/CMAKE_LINK_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +CMAKE_LINK_USING_<FEATURE>_SUPPORTED +------------------------------------ + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_LINK_USING_<FEATURE>`, is supported regardless the linker +language. + +.. note:: + + This variable is evaluated if, and only if, the variable + :variable:`CMAKE_<LANG>_LINK_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..dd22e14 --- /dev/null +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -0,0 +1,5 @@ +**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. |