mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-02-18 21:20:40 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Consolidate add_library documentation on IMPORTED libraries

Browse Source 
Move documentation on IMPORTED INTERFACE libraries to the main section
on Imported Libraries.  Revise the section to clarify the different
kinds of imported libraries that can be created and what properties they
need.

Issue: #18975
This commit is contained in:
Brad King
2020-07-31 11:35:46 -04:00
parent 716e76be3e
commit 99b1e85f07
1 changed files with 34 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
Help/command/add_library.rst
View File

@@ -98,7 +98,7 @@ Interface Libraries
.. code-block:: cmake .. code-block:: cmake
add_library(<name> INTERFACE [IMPORTED [GLOBAL]]) add_library(<name> INTERFACE)
Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE`` Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE``
library target does not directly create build output, though it may library target does not directly create build output, though it may
@@ -117,50 +117,52 @@ the interface target using the commands:
and then it is used as an argument to :command:`target_link_libraries` and then it is used as an argument to :command:`target_link_libraries`
like any other target. like any other target.
An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` may also be
created with this signature. An ``IMPORTED`` library target references a
library defined outside the project. The target name has scope in the
directory in which it is created and below, but the ``GLOBAL`` option
extends visibility. It may be referenced like any target built within
the project. ``IMPORTED`` libraries are useful for convenient reference
from commands like :command:`target_link_libraries`.
Imported Libraries Imported Libraries
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
.. code-block:: cmake .. code-block:: cmake
add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED add_library(<name> <type> IMPORTED [GLOBAL])
[GLOBAL])
An :ref:`IMPORTED library target <Imported Targets>` references a library Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
file located outside the project. No rules are generated to build it, and No rules are generated to build it, and the :prop_tgt:`IMPORTED` target
the :prop_tgt:`IMPORTED` target property is ``True``. The target name has property is ``True``. The target name has scope in the directory in which
scope in the directory in which it is created and below, but the ``GLOBAL`` it is created and below, but the ``GLOBAL`` option extends visibility.
option extends visibility. It may be referenced like any target built It may be referenced like any target built within the project.
within the project. ``IMPORTED`` libraries are useful for convenient ``IMPORTED`` libraries are useful for convenient reference from commands
reference from commands like :command:`target_link_libraries`. Details like :command:`target_link_libraries`. Details about the imported library
about the imported library are specified by setting properties whose names are specified by setting properties whose names begin in ``IMPORTED_`` and
begin in ``IMPORTED_`` and ``INTERFACE_``. ``INTERFACE_``.
The most important properties are: The ``<type>`` must be one of:
* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration ``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the References a library file located outside the project. The
:prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
location of the main library file on disk. location of the main library file on disk.
* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) Additional usage requirements may be specified in ``INTERFACE_*`` properties.
for object libraries, specifies the locations of object files on disk.
* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation An ``UNKNOWN`` library type is typically only used in the implementation of
:ref:`Find Modules`. It allows the path to an imported library (often found
using the :command:`find_library` command) to be used without having to know
what type of library it is. This is especially useful on Windows where a
static library and a DLL's import library both have the same file extension.
``OBJECT``
References a set of object files located outside the project.
The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
object files on disk.
Additional usage requirements may be specified in ``INTERFACE_*`` properties.
``INTERFACE``
Does not reference any library or object files on disk, but may
specify usage requirements in ``INTERFACE_*`` properties.
See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
for more information. for more information.
An ``UNKNOWN`` library type is typically only used in the implementation of
:ref:`Find Modules`. It allows the path to an imported library (often found
using the :command:`find_library` command) to be used without having to know
what type of library it is. This is especially useful on Windows where a
static library and a DLL's import library both have the same file extension.
Alias Libraries Alias Libraries
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^