diff options
Diffstat (limited to 'Help/variable')
| -rw-r--r-- | Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst | 19 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LANG_LINK_USING_FEATURE_SUPPORTED.rst | 13 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LINK_USING_FEATURE.rst | 23 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LINK_USING_FEATURE.txt | 111 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LINK_USING_FEATURE_SUPPORTED.rst | 14 |
5 files changed, 180 insertions, 0 deletions
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..ff8b3d9 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst @@ -0,0 +1,19 @@ +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 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..3d94461 --- /dev/null +++ b/Help/variable/CMAKE_LINK_USING_FEATURE.rst @@ -0,0 +1,23 @@ +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 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``. |