diff options
Diffstat (limited to 'Help/command/target_link_libraries.rst')
| -rw-r--r-- | Help/command/target_link_libraries.rst | 208 |
1 files changed, 124 insertions, 84 deletions
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 88a555aa4b..393c8b454e 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -1,38 +1,107 @@ target_link_libraries --------------------- -Link a target to given 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. + +* **A full path to a library file**: The generated link line will + normally preserve the full path to the file. However, there are + some cases where CMake must ask the linker to search for the library + (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such as when it + appears in a system library directory that the compiler front-end + may replace with an alternative. Either way, the buildsystem will + have a dependency to re-link ``<target>`` if the library file changes. + + 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. + +* **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. + +* 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> [item1 [item2 [...]]] - [[debug|optimized|general] <item>] ...) - -Specify libraries or flags to use when linking a given target. The -named ``<target>`` must have been created in the current directory by a -command such as :command:`add_executable` or :command:`add_library`. The -remaining arguments specify library names or flags. Repeated calls for -the same ``<target>`` append items in the order called. - -If a library name matches that of another target in the project a -dependency will automatically be added in the build system to make sure -the library being linked is up-to-date before the target links. 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 of ``<target>``. - -A ``debug``, ``optimized``, or ``general`` keyword indicates that the -library immediately following it is to 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 (assumed if omitted). Higher granularity may be achieved for -per-configuration rules by creating and linking to -:ref:`IMPORTED library targets <Imported Targets>`. + 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 @@ -45,37 +114,34 @@ by setting the property directly. When :policy:`CMP0022` is not set to of this command may set the property making any libraries linked exclusively by this signature private. -CMake will also propagate :ref:`usage requirements <Target Usage Requirements>` -from linked library targets. Usage requirements of dependencies affect -compilation of sources in the ``<target>``. - -If an ``<item>`` is a library in a Mac OX 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. - --------------------------------------------------------------------------- +Libraries for a Target and/or its Dependents (Legacy) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: target_link_libraries(<target> - <PRIVATE|PUBLIC|INTERFACE> <lib> ... - [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...]) + <LINK_PRIVATE|LINK_PUBLIC> <lib>... + [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...) -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>``. +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 - [[debug|optimized|general] <lib>] ...) + 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 @@ -99,28 +165,8 @@ is not ``NEW``, they are also appended to the ``general`` (or without any keyword) are treated as if specified for both ``debug`` and ``optimized``. --------------------------------------------------------------------------- - -:: - - target_link_libraries(<target> - <LINK_PRIVATE|LINK_PUBLIC> - [[debug|optimized|general] <lib>] ... - [<LINK_PRIVATE|LINK_PUBLIC> - [[debug|optimized|general] <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`). +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 @@ -139,17 +185,11 @@ For example, the code 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 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. - -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. +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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |