mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-02 03:39:43 -06:00
Help: Use signature directive for the 'add_library' command
This allows individual signatures to be cross-referenced from elsewhere. It also associates with each signature its main documentation via indentation.
This commit is contained in:
Brad King
@@ -63,7 +63,7 @@ Imported Executables
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. signature::
|
||||
add_executable(<name> IMPORTED <options>...)
|
||||
add_executable(<name> IMPORTED [GLOBAL])
|
||||
:target: IMPORTED
|
||||
|
||||
Add an :ref:`IMPORTED executable target <Imported Targets>` to reference
|
||||
|
||||
@@ -10,18 +10,39 @@ Add a library to the project using the specified source files.
|
||||
Normal Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
.. signature::
|
||||
add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)
|
||||
:target: normal
|
||||
|
||||
add_library(<name> [STATIC | SHARED | MODULE]
|
||||
[EXCLUDE_FROM_ALL]
|
||||
[<source>...])
|
||||
Add a library target called ``<name>`` to be built from the source files
|
||||
listed in the command invocation.
|
||||
|
||||
Adds a library target called ``<name>`` to be built from the source files
|
||||
listed in the command invocation. The ``<name>``
|
||||
corresponds to the logical target name and must be globally unique within
|
||||
a project. The actual file name of the library built is constructed based
|
||||
on conventions of the native platform (such as ``lib<name>.a`` or
|
||||
``<name>.lib``).
|
||||
The optional ``<type>`` specifies the type of library to be created:
|
||||
|
||||
``STATIC``
|
||||
An archive of object files for use when linking other targets.
|
||||
|
||||
``SHARED``
|
||||
A dynamic library that may be linked by other targets and loaded
|
||||
at runtime.
|
||||
|
||||
``MODULE``
|
||||
A plugin that may not be linked by other targets, but may be
|
||||
dynamically loaded at runtime using dlopen-like functionality.
|
||||
|
||||
If no ``<type>`` is given the default is ``STATIC`` or ``SHARED``
|
||||
based on the value of the :variable:`BUILD_SHARED_LIBS` variable.
|
||||
|
||||
The options are:
|
||||
|
||||
``EXCLUDE_FROM_ALL``
|
||||
Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
|
||||
See documentation of that target property for details.
|
||||
|
||||
The ``<name>`` corresponds to the logical target name and must be globally
|
||||
unique within a project. The actual file name of the library built is
|
||||
constructed based on conventions of the native platform (such as
|
||||
``lib<name>.a`` or ``<name>.lib``).
|
||||
|
||||
.. versionadded:: 3.1
|
||||
Source arguments to ``add_library`` may use "generator expressions" with
|
||||
@@ -32,15 +53,8 @@ on conventions of the native platform (such as ``lib<name>.a`` or
|
||||
The source files can be omitted if they are added later using
|
||||
:command:`target_sources`.
|
||||
|
||||
``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
|
||||
library to be created. ``STATIC`` libraries are archives of object files
|
||||
for use when linking other targets. ``SHARED`` libraries are linked
|
||||
dynamically and loaded at runtime. ``MODULE`` libraries are plugins that
|
||||
are not linked into other targets but may be loaded dynamically at runtime
|
||||
using dlopen-like functionality. If no type is given explicitly the
|
||||
type is ``STATIC`` or ``SHARED`` based on whether the current value of the
|
||||
variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and
|
||||
``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
|
||||
For ``SHARED`` and ``MODULE`` libraries the
|
||||
:prop_tgt:`POSITION_INDEPENDENT_CODE` target
|
||||
property is set to ``ON`` automatically.
|
||||
A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
|
||||
target property to create an macOS Framework.
|
||||
@@ -63,10 +77,6 @@ invoked. See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
|
||||
location. See documentation of the :prop_tgt:`OUTPUT_NAME` target
|
||||
property to change the ``<name>`` part of the final file name.
|
||||
|
||||
If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
|
||||
the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
|
||||
target property for details.
|
||||
|
||||
See the :manual:`cmake-buildsystem(7)` manual for more on defining
|
||||
buildsystem properties.
|
||||
|
||||
@@ -77,14 +87,15 @@ within IDE.
|
||||
Object Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
.. signature::
|
||||
add_library(<name> OBJECT <sources>...)
|
||||
:target: OBJECT
|
||||
|
||||
add_library(<name> OBJECT [<source>...])
|
||||
Add an :ref:`Object Library <Object Libraries>` to compile source files
|
||||
without archiving or linking their object files into a library.
|
||||
|
||||
Creates an :ref:`Object Library <Object Libraries>`. An object library
|
||||
compiles source files but does not archive or link their object files into a
|
||||
library. Instead other targets created by ``add_library`` or
|
||||
:command:`add_executable` may reference the objects using an expression of the
|
||||
Other targets created by ``add_library`` or :command:`add_executable`
|
||||
may reference the objects using an expression of the
|
||||
form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where
|
||||
``objlib`` is the object library name. For example:
|
||||
|
||||
@@ -109,46 +120,48 @@ consider adding at least one real source file to any target that references
|
||||
Interface Libraries
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
add_library(<name> INTERFACE)
|
||||
:target: 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:
|
||||
Add an :ref:`Interface Library <Interface Libraries>` target that may
|
||||
specify usage requirements for dependents but does not compile sources
|
||||
and does not produce a library artifact on disk.
|
||||
|
||||
* :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)`,
|
||||
An interface library with no source files is not included as a target
|
||||
in the generated buildsystem. 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:
|
||||
|
||||
and then it is used as an argument to :command:`target_link_libraries`
|
||||
like any other target.
|
||||
* :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)`,
|
||||
|
||||
An interface library created with the above signature has no source files
|
||||
itself and is not included as a target in the generated buildsystem.
|
||||
and then it is used as an argument to :command:`target_link_libraries`
|
||||
like any other target.
|
||||
|
||||
.. versionadded:: 3.15
|
||||
An interface library can have :prop_tgt:`PUBLIC_HEADER` and
|
||||
:prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those
|
||||
properties can be installed using the :command:`install(TARGETS)` command.
|
||||
.. versionadded:: 3.15
|
||||
An interface library can have :prop_tgt:`PUBLIC_HEADER` and
|
||||
:prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those
|
||||
properties can be installed using the :command:`install(TARGETS)` command.
|
||||
|
||||
.. versionadded:: 3.19
|
||||
An interface library target may be created with source files:
|
||||
.. signature::
|
||||
add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...)
|
||||
:target: INTERFACE-with-sources
|
||||
|
||||
.. code-block:: cmake
|
||||
.. versionadded:: 3.19
|
||||
|
||||
add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] [<source>...])
|
||||
|
||||
Source files may be listed directly in the ``add_library`` call or added
|
||||
later by calls to :command:`target_sources` with the ``PRIVATE`` or
|
||||
``PUBLIC`` keywords.
|
||||
Add an :ref:`Interface Library <Interface Libraries>` target with
|
||||
source files (in addition to usage requirements and properties as
|
||||
documented by the :command:`above signature <add_library(INTERFACE)>`).
|
||||
Source files may be listed directly in the ``add_library`` call
|
||||
or added later by calls to :command:`target_sources` with the
|
||||
``PRIVATE`` or ``PUBLIC`` keywords.
|
||||
|
||||
If an interface library has source files (i.e. the :prop_tgt:`SOURCES`
|
||||
target property is set), or header sets (i.e. the :prop_tgt:`HEADER_SETS`
|
||||
@@ -158,92 +171,106 @@ itself and is not included as a target in the generated buildsystem.
|
||||
but does contain build rules for custom commands created by the
|
||||
:command:`add_custom_command` command.
|
||||
|
||||
.. note::
|
||||
In most command signatures where the ``INTERFACE`` keyword appears,
|
||||
the items listed after it only become part of that target's usage
|
||||
requirements and are not part of the target's own settings. However,
|
||||
in this signature of ``add_library``, the ``INTERFACE`` keyword refers
|
||||
to the library type only. Sources listed after it in the ``add_library``
|
||||
call are ``PRIVATE`` to the interface library and do not appear in its
|
||||
:prop_tgt:`INTERFACE_SOURCES` target property.
|
||||
The options are:
|
||||
|
||||
``EXCLUDE_FROM_ALL``
|
||||
Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
|
||||
See documentation of that target property for details.
|
||||
|
||||
.. note::
|
||||
In most command signatures where the ``INTERFACE`` keyword appears,
|
||||
the items listed after it only become part of that target's usage
|
||||
requirements and are not part of the target's own settings. However,
|
||||
in this signature of ``add_library``, the ``INTERFACE`` keyword refers
|
||||
to the library type only. Sources listed after it in the ``add_library``
|
||||
call are ``PRIVATE`` to the interface library and do not appear in its
|
||||
:prop_tgt:`INTERFACE_SOURCES` target property.
|
||||
|
||||
.. _`add_library imported libraries`:
|
||||
|
||||
Imported Libraries
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
add_library(<name> <type> IMPORTED [GLOBAL])
|
||||
:target: IMPORTED
|
||||
|
||||
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_``.
|
||||
Add an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
|
||||
The target name may be referenced like any target built within the project,
|
||||
except that by default it is visible only in the directory in which it is
|
||||
created, and below.
|
||||
|
||||
The ``<type>`` must be one of:
|
||||
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:
|
||||
``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:
|
||||
|
||||
* For a ``SHARED`` library on most non-Windows platforms, the main library
|
||||
file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
|
||||
loaders. If the referenced library file has a ``SONAME`` (or on macOS,
|
||||
has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
|
||||
should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
|
||||
If the referenced library file does not have a ``SONAME``, but the
|
||||
platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target
|
||||
property should be set.
|
||||
* For a ``SHARED`` library on most non-Windows platforms, the main library
|
||||
file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
|
||||
loaders. If the referenced library file has a ``SONAME`` (or on macOS,
|
||||
has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
|
||||
should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
|
||||
If the referenced library file does not have a ``SONAME``, but the
|
||||
platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target
|
||||
property should be set.
|
||||
|
||||
* For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
|
||||
target property (or its per-configuration variant
|
||||
:prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
|
||||
DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
|
||||
``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
|
||||
library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
|
||||
generator expression).
|
||||
* For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
|
||||
target property (or its per-configuration variant
|
||||
:prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
|
||||
DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
|
||||
``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
|
||||
library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
|
||||
generator expression).
|
||||
|
||||
Additional usage requirements may be specified in ``INTERFACE_*`` properties.
|
||||
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.
|
||||
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.
|
||||
``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.
|
||||
``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.
|
||||
The options are:
|
||||
|
||||
``GLOBAL``
|
||||
Make the target name globally visible.
|
||||
|
||||
No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
|
||||
target property is ``True``. 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_``. See documentation of
|
||||
such properties for more information.
|
||||
|
||||
Alias Libraries
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
add_library(<name> ALIAS <target>)
|
||||
:target: ALIAS
|
||||
|
||||
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
|
||||
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
|
||||
not appear in the generated buildsystem as a make target. The ``<target>``
|
||||
may not be an ``ALIAS``.
|
||||
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
|
||||
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
|
||||
not appear in the generated buildsystem as a make target. The ``<target>``
|
||||
may not be an ``ALIAS``.
|
||||
|
||||
.. versionadded:: 3.11
|
||||
An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`
|
||||
|
||||
Reference in New Issue
Block a user