Help/command/target_link_directories.rst

   1 target_link_directories
   2 -----------------------
   3
   4 .. versionadded:: 3.13
   5
   6 Add link directories to a target.
   7
   8 .. code-block:: cmake
   9
  10   target_link_directories(<target> [BEFORE]
  11     <INTERFACE|PUBLIC|PRIVATE> [items1...]
  12     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
  13
  14 Specifies the paths in which the linker should search for libraries when
  15 linking a given target.  Each item can be an absolute or relative path,
  16 with the latter being interpreted as relative to the current source
  17 directory.  These items will be added to the link command.
  18
  19 The named ``<target>`` must have been created by a command such as
  20 :command:`add_executable` or :command:`add_library` and must not be an
  21 :ref:`ALIAS target <Alias Targets>`.
  22
  23 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
  24 specify the :ref:`scope <Target Usage Requirements>` of the items that follow
  25 them. ``PRIVATE`` and ``PUBLIC`` items will populate the
  26 :prop_tgt:`LINK_DIRECTORIES` property of ``<target>``.  ``PUBLIC`` and
  27 ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
  28 property of ``<target>`` (:ref:`IMPORTED targets <Imported Targets>` only
  29 support ``INTERFACE`` items).
  30 Each item specifies a link directory and will be converted to an absolute
  31 path if necessary before adding it to the relevant property.  Repeated
  32 calls for the same ``<target>`` append items in the order called.
  33
  34 If ``BEFORE`` is specified, the content will be prepended to the relevant
  35 property instead of being appended.
  36
  37 Arguments to ``target_link_directories`` may use "generator expressions"
  38 with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
  39 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
  40 manual for more on defining buildsystem properties.
  41
  42 .. note::
  43
  44   This command is rarely necessary and should be avoided where there are
  45   other choices.  Prefer to pass full absolute paths to libraries where
  46   possible, since this ensures the correct library will always be linked.
  47   The :command:`find_library` command provides the full path, which can
  48   generally be used directly in calls to :command:`target_link_libraries`.
  49   Situations where a library search path may be needed include:
  50
  51   - Project generators like Xcode where the user can switch target
  52     architecture at build time, but a full path to a library cannot
  53     be used because it only provides one architecture (i.e. it is not
  54     a universal binary).
  55   - Libraries may themselves have other private library dependencies
  56     that expect to be found via ``RPATH`` mechanisms, but some linkers
  57     are not able to fully decode those paths (e.g. due to the presence
  58     of things like ``$ORIGIN``).