Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt

   1 ``DEFAULT``
   2   This feature corresponds to standard linking, essentially equivalent to
   3   using no feature at all.  It is typically only used with the
   4   :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
   5   :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties.
   6
   7 ``WHOLE_ARCHIVE``
   8   Force inclusion of all members of a static library.  This feature is only
   9   supported for the following platforms, with limitations as noted:
  10
  11   * Linux.
  12   * All BSD variants.
  13   * SunOS.
  14   * All Apple variants.  The library must be specified as a CMake target name,
  15     a library file name (such as ``libfoo.a``), or a library file path (such as
  16     ``/path/to/libfoo.a``).  Due to a limitation of the Apple linker, it
  17     cannot be specified as a plain library name like ``foo``, where ``foo``
  18     is not a CMake target.
  19   * Windows.  When using a MSVC or MSVC-like toolchain, the MSVC version must
  20     be greater than 1900.
  21   * Cygwin.
  22   * MSYS.
  23
  24 ``FRAMEWORK``
  25   This option tells the linker to search for the specified framework using
  26   the ``-framework`` linker option.  It can only be used on Apple platforms,
  27   and only with a linker that understands the option used (i.e. the linker
  28   provided with Xcode, or one compatible with it).
  29
  30   The framework can be specified as a CMake framework target, a bare framework
  31   name, or a file path.  If a target is given, that target must have the
  32   :prop_tgt:`FRAMEWORK` target property set to true.  For a file path, if it
  33   contains a directory part, that directory will be added as a framework
  34   search path.
  35
  36   .. code-block:: cmake
  37
  38     add_library(lib SHARED ...)
  39     target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
  40
  41     # The constructed linker command line will contain:
  42     #   -F/path/to -framework my_framework
  43
  44   File paths must conform to one of the following patterns (``*`` is a
  45   wildcard, and optional parts are shown as ``[...]``):
  46
  47      * ``[/path/to/]FwName[.framework]``
  48      * ``[/path/to/]FwName.framework/FwName[suffix]``
  49      * ``[/path/to/]FwName.framework/Versions/*/FwName[suffix]``
  50
  51   Note that CMake recognizes and automatically handles framework targets,
  52   even without using the ``$<LINK_LIBRARY:FRAMEWORK,...>`` expression.
  53   The generator expression can still be used with a CMake target if the
  54   project wants to be explicit about it, but it is not required to do so.
  55   The linker command line may have some differences between using the
  56   generator expression or not, but the final result should be the same.
  57   On the other hand, if a file path is given, CMake will recognize some paths
  58   automatically, but not all cases.  The project may want to use
  59   ``$<LINK_LIBRARY:FRAMEWORK,...>`` for file paths so that the expected
  60   behavior is clear.
  61
  62   .. versionadded:: 3.25
  63     The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property as
  64     well as the ``suffix`` of the framework library name are now supported by
  65     the ``FRAMEWORK`` features.
  66
  67 ``NEEDED_FRAMEWORK``
  68   This is similar to the ``FRAMEWORK`` feature, except it forces the linker
  69   to link with the framework even if no symbols are used from it.  It uses
  70   the ``-needed_framework`` option and has the same linker constraints as
  71   ``FRAMEWORK``.
  72
  73 ``REEXPORT_FRAMEWORK``
  74   This is similar to the ``FRAMEWORK`` feature, except it tells the linker
  75   that the framework should be available to clients linking to the library
  76   being created.  It uses the ``-reexport_framework`` option and has the
  77   same linker constraints as ``FRAMEWORK``.
  78
  79 ``WEAK_FRAMEWORK``
  80   This is similar to the ``FRAMEWORK`` feature, except it forces the linker
  81   to mark the framework and all references to it as weak imports.  It uses
  82   the ``-weak_framework`` option and has the same linker constraints as
  83   ``FRAMEWORK``.
  84
  85 ``NEEDED_LIBRARY``
  86   This is similar to the ``NEEDED_FRAMEWORK`` feature, except it is for use
  87   with non-framework targets or libraries (Apple platforms only).
  88   It uses the ``-needed_library`` or ``-needed-l`` option as appropriate,
  89   and has the same linker constraints as ``NEEDED_FRAMEWORK``.
  90
  91 ``REEXPORT_LIBRARY``
  92   This is similar to the ``REEXPORT_FRAMEWORK`` feature,  except it is for use
  93   with non-framework targets or libraries (Apple platforms only).
  94   It uses the ``-reexport_library`` or ``-reexport-l`` option as appropriate,
  95   and has the same linker constraints as ``REEXPORT_FRAMEWORK``.
  96
  97 ``WEAK_LIBRARY``
  98   This is similar to the ``WEAK_FRAMEWORK`` feature, except it is for use
  99   with non-framework targets or libraries (Apple platforms only).
 100   It uses the ``-weak_library`` or ``-weak-l`` option as appropriate,
 101   and has the same linker constraints as ``WEAK_FRAMEWORK``.