| **Features available in all environments** |
| |
| ``DEFAULT`` |
| This feature enables default link expression. This is mainly |
| useful with :prop_tgt:`LINK_LIBRARY_OVERRIDE` and |
| :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties. |
| |
| **Features available for a subset of environments** |
| |
| ``WHOLE_ARCHIVE`` |
| Force load of all members in a static library. |
| |
| Target platforms supported: all ``Apple`` variants, ``Linux``, all ``BSD`` |
| variants, ``SunOS``, ``Windows``, ``CYGWIN``, and ``MSYS``. |
| |
| Platform-specific notes: |
| |
| * On Apple platforms, the library must be specified as a CMake target name, a |
| library file name (such as ``libfoo.a``), or a library file path (such as |
| ``/path/to/libfoo.a``). It cannot be specified as a plain library name |
| (such as ``foo``, where ``foo`` is not CMake target), due to a limitation |
| in the Apple linker. |
| * On Windows platforms, for ``MSVC`` or MSVC-like toolchains, the version |
| must be greater than ``1900``. |
| |
| **Features available in Apple environments** |
| |
| It is assumed that the linker used is the one provided by `XCode` or is |
| compatible with it. |
| |
| Framework support |
| |
| ``FRAMEWORK`` |
| This option tells the linker to search for the specified |
| framework (use linker option ``-framework``). |
| ``NEEDED_FRAMEWORK`` |
| This is the same as the ``FRAMEWORK`` feature but means |
| to really link with the framework even if no symbols are used from it (use |
| linker option ``-needed_framework``). |
| ``REEXPORT_FRAMEWORK`` |
| This is the same as the ``FRAMEWORK`` feature but |
| also specifies that all symbols in that framework should be available to |
| clients linking to the library being created (use linker option |
| ``-reexport_framework``). |
| ``WEAK_FRAMEWORK`` |
| This is the same as the ``FRAMEWORK`` feature but forces |
| the framework and all references to it to be marked as weak imports (use |
| linker option ``-weak_framework``). |
| |
| Features for framework linking have a special handling in CMake: the |
| framework can be specified as a CMake framework target or file path. In the |
| first case, the target must have the :prop_tgt:`FRAMEWORK` target property set |
| as ``TRUE`` to enable framework handling. In the later case, if the path |
| includes a directory part, this one will be specified as framework search path |
| at link step. |
| |
| .. code-block:: cmake |
| |
| add_library(lib SHARED ...) |
| target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:NEEDED_FRAMEWORK,/path/to/my_framework>") |
| |
| # at link step we will have: |
| # -F/path/to -needed_framework my_framework |
| |
| .. note:: |
| |
| The expected formats for the file path, with optional parts specified as |
| ``()?``, are: |
| |
| * (/path/to/)?FwName(.framework)? |
| * (/path/to/)?FwName.framework/FwName |
| * (/path/to/)?FwName.framework/Versions/\*/FwName |
| |
| Library support |
| |
| ``NEEDED_LIBRARY`` |
| This is the same as specifying a link item (target or |
| library) but means to really link with the item even if no symbols are used |
| from it (use linker option ``-needed_library`` or ``-needed-l``). |
| ``REEXPORT_LIBRARY`` |
| This is the same as specifying a link item (target or |
| library) but also specifies that all symbols in that item should be available |
| to clients linking to the library being created (use linker option |
| ``-reexport_library`` or ``-reexport-l``). |
| ``WEAK_LIBRARY`` |
| This is the same as specifying a link item (target or |
| library) but forces the item and all references to it to be marked as weak |
| imports (use linker option ``-weak_library`` or ``-weak-l``). |