| target_link_libraries |
| --------------------- |
| |
| .. only:: html |
| |
| .. contents:: |
| |
| Specify libraries or flags to use when linking a given target and/or |
| its dependents. :ref:`Usage requirements <Target Usage Requirements>` |
| from linked library targets will be propagated. Usage requirements |
| of a target's dependencies affect compilation of its own sources. |
| |
| Overview |
| ^^^^^^^^ |
| |
| This command has several signatures as detailed in subsections below. |
| All of them have the general form:: |
| |
| target_link_libraries(<target> ... <item>... ...) |
| |
| The named ``<target>`` must have been created in the current directory by |
| a command such as :command:`add_executable` or :command:`add_library`. |
| Repeated calls for the same ``<target>`` append items in the order called. |
| Each ``<item>`` may be: |
| |
| * **A library target name**: The generated link line will have the |
| full path to the linkable library file associated with the target. |
| The buildsystem will have a dependency to re-link ``<target>`` if |
| the library file changes. |
| |
| The named target must be created by :command:`add_library` within |
| the project or as an :ref:`IMPORTED library <Imported Targets>`. |
| If it is created within the project an ordering dependency will |
| automatically be added in the build system to make sure the named |
| library target is up-to-date before the ``<target>`` links. |
| |
| If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME` |
| target property set, CMake may ask the linker to search for |
| the library instead of using the full path |
| (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``). |
| |
| * **A full path to a library file**: The generated link line will |
| normally preserve the full path to the file. The buildsystem will |
| have a dependency to re-link ``<target>`` if the library file changes. |
| |
| There are some cases where CMake may ask the linker to search for |
| the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such |
| as when a shared library is detected to have no ``SONAME`` field. |
| See policy :policy:`CMP0060` for discussion of another case. |
| |
| If the library file is in a Mac OSX framework, the ``Headers`` directory |
| of the framework will also be processed as a |
| :ref:`usage requirement <Target Usage Requirements>`. This has the same |
| effect as passing the framework directory as an include directory. |
| |
| On :ref:`Visual Studio Generators` for VS 2010 and above, library files |
| ending in ``.targets`` will be treated as MSBuild targets files and |
| imported into generated project files. This is not supported by other |
| generators. |
| |
| * **A plain library name**: The generated link line will ask the linker |
| to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``). |
| |
| * **A link flag**: Item names starting with ``-``, but not ``-l`` or |
| ``-framework``, are treated as linker flags. Note that such flags will |
| be treated like any other library link item for purposes of transitive |
| dependencies, so they are generally safe to specify only as private link |
| items that will not propagate to dependents. |
| |
| Link flags specified here are inserted into the link command in the same |
| place as the link libraries. This might not be correct, depending on |
| the linker. Use the :prop_tgt:`LINK_FLAGS` target property to add link |
| flags explicitly. The flags will then be placed at the toolchain-defined |
| flag position in the link command. |
| |
| * A ``debug``, ``optimized``, or ``general`` keyword immediately followed |
| by another ``<item>``. The item following such a keyword will be used |
| only for the corresponding build configuration. The ``debug`` keyword |
| corresponds to the ``Debug`` configuration (or to configurations named |
| in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). |
| The ``optimized`` keyword corresponds to all other configurations. The |
| ``general`` keyword corresponds to all configurations, and is purely |
| optional. Higher granularity may be achieved for per-configuration |
| rules by creating and linking to |
| :ref:`IMPORTED library targets <Imported Targets>`. |
| |
| Items containing ``::``, such as ``Foo::Bar``, are assumed to be |
| :ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library |
| target names and will cause an error if no such target exists. |
| See policy :policy:`CMP0028`. |
| |
| Arguments to ``target_link_libraries`` may use "generator expressions" |
| with the syntax ``$<...>``. Note however, that generator expressions |
| will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. |
| See the :manual:`cmake-generator-expressions(7)` manual for available |
| expressions. See the :manual:`cmake-buildsystem(7)` manual for more on |
| defining buildsystem properties. |
| |
| Libraries for a Target and/or its Dependents |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| :: |
| |
| target_link_libraries(<target> |
| <PRIVATE|PUBLIC|INTERFACE> <item>... |
| [<PRIVATE|PUBLIC|INTERFACE> <item>...]...) |
| |
| The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to |
| specify both the link dependencies and the link interface in one command. |
| Libraries and targets following ``PUBLIC`` are linked to, and are made |
| part of the link interface. Libraries and targets following ``PRIVATE`` |
| are linked to, but are not made part of the link interface. Libraries |
| following ``INTERFACE`` are appended to the link interface and are not |
| used for linking ``<target>``. |
| |
| Libraries for both a Target and its Dependents |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| :: |
| |
| target_link_libraries(<target> <item>...) |
| |
| Library dependencies are transitive by default with this signature. |
| When this target is linked into another target then the libraries |
| linked to this target will appear on the link line for the other |
| target too. This transitive "link interface" is stored in the |
| :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property and may be overridden |
| by setting the property directly. When :policy:`CMP0022` is not set to |
| ``NEW``, transitive linking is built in but may be overridden by the |
| :prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Calls to other signatures |
| of this command may set the property making any libraries linked |
| exclusively by this signature private. |
| |
| Libraries for a Target and/or its Dependents (Legacy) |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| :: |
| |
| target_link_libraries(<target> |
| <LINK_PRIVATE|LINK_PUBLIC> <lib>... |
| [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...) |
| |
| The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both |
| the link dependencies and the link interface in one command. |
| |
| This signature is for compatibility only. Prefer the ``PUBLIC`` or |
| ``PRIVATE`` keywords instead. |
| |
| Libraries and targets following ``LINK_PUBLIC`` are linked to, and are |
| made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy |
| :policy:`CMP0022` is not ``NEW``, they are also made part of the |
| :prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following |
| ``LINK_PRIVATE`` are linked to, but are not made part of the |
| :prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`). |
| |
| Libraries for Dependents Only (Legacy) |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| :: |
| |
| target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...) |
| |
| The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the |
| :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them |
| for linking. If policy :policy:`CMP0022` is not ``NEW``, then this mode |
| also appends libraries to the :prop_tgt:`LINK_INTERFACE_LIBRARIES` and its |
| per-configuration equivalent. |
| |
| This signature is for compatibility only. Prefer the ``INTERFACE`` mode |
| instead. |
| |
| Libraries specified as ``debug`` are wrapped in a generator expression to |
| correspond to debug builds. If policy :policy:`CMP0022` is |
| not ``NEW``, the libraries are also appended to the |
| :prop_tgt:`LINK_INTERFACE_LIBRARIES_DEBUG <LINK_INTERFACE_LIBRARIES_<CONFIG>>` |
| property (or to the properties corresponding to configurations listed in |
| the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). |
| Libraries specified as ``optimized`` are appended to the |
| :prop_tgt:`INTERFACE_LINK_LIBRARIES` property. If policy :policy:`CMP0022` |
| is not ``NEW``, they are also appended to the |
| :prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Libraries specified as |
| ``general`` (or without any keyword) are treated as if specified for both |
| ``debug`` and ``optimized``. |
| |
| Cyclic Dependencies of Static Libraries |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The library dependency graph is normally acyclic (a DAG), but in the case |
| of mutually-dependent ``STATIC`` libraries CMake allows the graph to |
| contain cycles (strongly connected components). When another target links |
| to one of the libraries, CMake repeats the entire connected component. |
| For example, the code |
| |
| .. code-block:: cmake |
| |
| add_library(A STATIC a.c) |
| add_library(B STATIC b.c) |
| target_link_libraries(A B) |
| target_link_libraries(B A) |
| add_executable(main main.c) |
| target_link_libraries(main A) |
| |
| links ``main`` to ``A B A B``. While one repetition is usually |
| sufficient, pathological object file and symbol arrangements can require |
| more. One may handle such cases by using the |
| :prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually |
| repeating the component in the last ``target_link_libraries`` call. |
| However, if two archives are really so interdependent they should probably |
| be combined into a single archive, perhaps by using :ref:`Object Libraries`. |
| |
| Creating Relocatable Packages |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` |
| .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt |