diff options
| author | Craig Scott <craig.scott@crascit.com> | 2022-06-27 10:36:58 (GMT) |
|---|---|---|
| committer | Craig Scott <craig.scott@crascit.com> | 2022-07-03 04:34:41 (GMT) |
| commit | d185f7c0a8cac19edaea8d54c2a12b51a622731b (patch) | |
| tree | 96ab4b102d1d8a94536b0e09915d2911d3c505d5 /Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt | |
| parent | 8c562ece28b7a13ddb734b8c51710ebafe9ac570 (diff) | |
| download | CMake-d185f7c0a8cac19edaea8d54c2a12b51a622731b.zip CMake-d185f7c0a8cac19edaea8d54c2a12b51a622731b.tar.gz CMake-d185f7c0a8cac19edaea8d54c2a12b51a622731b.tar.bz2 | |
Help: Rework $<LINK_LIBRARY>, $<LINK_GROUP> and related docs
These changes restructure the docs to improve readability and flow,
correct grammar and typos, and fix errors and inconsistencies in
some of the examples.
Fixes: #23684
Diffstat (limited to 'Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt')
| -rw-r--r-- | Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt | 158 |
1 files changed, 83 insertions, 75 deletions
diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt index e4fa0ed8..8ae6c57 100644 --- a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -1,88 +1,96 @@ -**Features available in all environments** - ``DEFAULT`` - This feature enables default link expression. This is mainly - useful with :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + This feature corresponds to standard linking, essentially equivalent to + using no feature at all. It is typically only used with the + :prop_tgt:`LINK_LIBRARY_OVERRIDE` and :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties. -**Features available for a subset of environments** - ``WHOLE_ARCHIVE`` - Force load of all members in a static library. - - Target platforms supported: all ``Apple`` variants, ``Linux``, all ``BSD`` - variants, ``SunOS``, ``Windows``, ``CYGWIN``, and ``MSYS``. - - Platform-specific notes: - - * On Apple platforms, the library must be specified as a CMake target name, a - library file name (such as ``libfoo.a``), or a library file path (such as - ``/path/to/libfoo.a``). It cannot be specified as a plain library name - (such as ``foo``, where ``foo`` is not CMake target), due to a limitation - in the Apple linker. - * On Windows platforms, for ``MSVC`` or MSVC-like toolchains, the version - must be greater than ``1900``. - -**Features available in Apple environments** - -It is assumed that the linker used is the one provided by `XCode` or is -compatible with it. - -Framework support + Force inclusion of all members of a static library. This feature is only + supported for the following platforms, with limitations as noted: + + * Linux. + * All BSD variants. + * SunOS. + * All Apple variants. The library must be specified as a CMake target name, + a library file name (such as ``libfoo.a``), or a library file path (such as + ``/path/to/libfoo.a``). Due to a limitation of the Apple linker, it + cannot be specified as a plain library name like ``foo``, where ``foo`` + is not a CMake target. + * Windows. When using a MSVC or MSVC-like toolchain, the MSVC version must + be greater than 1900. + * Cygwin. + * MSYS. ``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``). + This option tells the linker to search for the specified framework using + the ``-framework`` linker option. It can only be used on Apple platforms, + and only with a linker that understands the option used (i.e. the linker + provided with Xcode, or one compatible with it). + + The framework can be specified as a CMake framework target, a bare framework + name, or a file path. If a target is given, that target must have the + :prop_tgt:`FRAMEWORK` target property set to true. For a file path, if it + contains a directory part, that directory will be added as a framework + search path. + + .. code-block:: cmake + + add_library(lib SHARED ...) + target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>") + + # The constructed linker command line will contain: + # -F/path/to -framework my_framework + + File paths must conform to one of the following patterns (``*`` is a + wildcard, and optional parts are shown as ``[...]``): + + * ``[/path/to/]FwName[.framework]`` + * ``[/path/to/]FwName.framework/FwName`` + * ``[/path/to/]FwName.framework/Versions/*/FwName`` + + Note that CMake recognizes and automatically handles framework targets, + even without using the ``$<LINK_LIBRARY:FRAMEWORK,...>`` expression. + The generator expression can still be used with a CMake target if the + project wants to be explicit about it, but it is not required to do so. + The linker command line may have some differences between using the + generator expression or not, but the final result should be the same. + On the other hand, if a file path is given, CMake will recognize some paths + automatically, but not all cases. The project may want to use + ``$<LINK_LIBRARY:FRAMEWORK,...>`` for file paths so that the expected + behavior is clear. -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: +``NEEDED_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it forces the linker + to link with the framework even if no symbols are used from it. It uses + the ``-needed_framework`` option and has the same linker constraints as + ``FRAMEWORK``. - * (/path/to/)?FwName(.framework)? - * (/path/to/)?FwName.framework/FwName - * (/path/to/)?FwName.framework/Versions/\*/FwName +``REEXPORT_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it tells the linker + that the framework should be available to clients linking to the library + being created. It uses the ``-reexport_framework`` option and has the + same linker constraints as ``FRAMEWORK``. -Library support +``WEAK_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it forces the linker + to mark the framework and all references to it as weak imports. It uses + the ``-weak_framework`` option and has the same linker constraints as + ``FRAMEWORK``. ``NEEDED_LIBRARY`` - This is the same as specifying a link item (target or - library) but means to really link with the item even if no symbols are used - from it (use linker option ``-needed_library`` or ``-needed-l``). + This is similar to the ``NEEDED_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-needed_library`` or ``-needed-l`` option as appropriate, + and has the same linker constraints as ``NEEDED_FRAMEWORK``. + ``REEXPORT_LIBRARY`` - This is the same as specifying a link item (target or - library) but also specifies that all symbols in that item should be available - to clients linking to the library being created (use linker option - ``-reexport_library`` or ``-reexport-l``). + This is similar to the ``REEXPORT_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-reexport_library`` or ``-reexport-l`` option as appropriate, + and has the same linker constraints as ``REEXPORT_FRAMEWORK``. + ``WEAK_LIBRARY`` - This is the same as specifying a link item (target or - library) but forces the item and all references to it to be marked as weak - imports (use linker option ``-weak_library`` or ``-weak-l``). + This is similar to the ``WEAK_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-weak_library`` or ``-weak-l`` option as appropriate, + and has the same linker constraints as ``WEAK_FRAMEWORK``. |