mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-04-24 23:28:32 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'doc-add_library-updates'

Browse Source 
ee5b58f491 Help: State in add_library that INTERFACE libraries have no build targets
99b1e85f07 Help: Consolidate add_library documentation on IMPORTED libraries
716e76be3e Help: Re-order add_library sections
1b0adeea81 Help: Clarify target_sources PRIVATE/PUBLIC/INTERFACE scopes

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5086
This commit is contained in:
Craig Scott
2020-08-01 23:59:48 +00:00
committed by Kitware Robot
parent 03d3cc1136 ee5b58f491
commit bda967bcb9
2 changed files with 82 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/command/add_library.rst
+74 -68
View File
@@ -64,42 +64,6 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.
Imported Libraries
^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
[GLOBAL])
An :ref:`IMPORTED library target <Imported Targets>` references a library
file located outside the project. No rules are generated to build it, and
the :prop_tgt:`IMPORTED` target property is ``True``. 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`. Details
about the imported library are specified by setting properties whose names
begin in ``IMPORTED_`` and ``INTERFACE_``.
The most important properties are:
* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
location of the main library file on disk.
* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
for object libraries, specifies the locations of object files on disk.
* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation
See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
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.
Object Libraries
^^^^^^^^^^^^^^^^
@@ -129,6 +93,80 @@ systems (such as Xcode) may not like targets that have only object files, so
consider adding at least one real source file to any target that references
``$<TARGET_OBJECTS:objlib>``.
Interface Libraries
^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> INTERFACE)
Creates an :ref:`Interface Library <Interface Libraries>`.
An ``INTERFACE`` library target does not compile sources and does
not produce a library artifact on disk. However, it may have
properties set on it and it may be installed and exported.
Typically, ``INTERFACE_*`` properties are populated on an interface
target using the commands:
* :command:`set_property`,
* :command:`target_link_libraries(INTERFACE)`,
* :command:`target_link_options(INTERFACE)`,
* :command:`target_include_directories(INTERFACE)`,
* :command:`target_compile_options(INTERFACE)`,
* :command:`target_compile_definitions(INTERFACE)`, and
* :command:`target_sources(INTERFACE)`,
and then it is used as an argument to :command:`target_link_libraries`
like any other target.
An interface library has no source files itself and is not included
as a target in the generated buildsystem.
Imported Libraries
^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> <type> IMPORTED [GLOBAL])
Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
No rules are generated to build it, and the :prop_tgt:`IMPORTED` target
property is ``True``. 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`. Details about the imported library
are specified by setting properties whose names begin in ``IMPORTED_`` and
``INTERFACE_``.
The ``<type>`` must be one of:
``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
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.
Additional usage requirements may be specified in ``INTERFACE_*`` properties.
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
for more information.
Alias Libraries
^^^^^^^^^^^^^^^
@@ -153,35 +191,3 @@ to modify properties of ``<target>``, that is, it may not be used as the
operand of :command:`set_property`, :command:`set_target_properties`,
:command:`target_link_libraries` etc. An ``ALIAS`` target may not be
installed or exported.
Interface Libraries
^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE``
library target does not directly create build output, though it may
have properties set on it and it may be installed, exported and
imported. Typically the ``INTERFACE_*`` properties are populated on
the interface target using the commands:
* :command:`set_property`,
* :command:`target_link_libraries(INTERFACE)`,
* :command:`target_link_options(INTERFACE)`,
* :command:`target_include_directories(INTERFACE)`,
* :command:`target_compile_options(INTERFACE)`,
* :command:`target_compile_definitions(INTERFACE)`, and
* :command:`target_sources(INTERFACE)`,
and then it is used as an argument to :command:`target_link_libraries`
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`.
Help/command/target_sources.rst
+8 -6
View File
@@ -11,19 +11,21 @@ Add sources to a target.
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies sources to use when compiling a given target. Relative
source file paths are interpreted as being relative to the current
Specifies sources to use when building a target and/or its dependents.
Relative source file paths are interpreted as being relative to the current
source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). The
named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
specify the scope of the items following them. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`SOURCES` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``.
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
``<target>``, which are used when building the target itself.
``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
when building dependents. (:ref:`IMPORTED targets <Imported Targets>`
only support ``INTERFACE`` items because they are not build targets.)
The following arguments specify sources. Repeated calls for the same
``<target>`` append items in the order called.