mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-05 13:20:47 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Use signature directive for the 'add_library' command

Browse Source 
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
2023-12-06 12:29:17 -05:00
parent bfc9e71d1f
commit e1519edd91
2 changed files with 151 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Help/command/add_executable.rst
View File

@@ -63,7 +63,7 @@ Imported Executables
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
.. signature:: .. signature::
add_executable(<name> IMPORTED <options>...) add_executable(<name> IMPORTED [GLOBAL])
:target: IMPORTED :target: IMPORTED
Add an :ref:`IMPORTED executable target <Imported Targets>` to reference Add an :ref:`IMPORTED executable target <Imported Targets>` to reference

273
Help/command/add_library.rst
View File

@@ -10,18 +10,39 @@ Add a library to the project using the specified source files.
Normal Libraries Normal Libraries
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
.. code-block:: cmake .. signature::
add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)
:target: normal
add_library(<name> [STATIC | SHARED | MODULE] Add a library target called ``<name>`` to be built from the source files
[EXCLUDE_FROM_ALL] listed in the command invocation.
[<source>...])
Adds a library target called ``<name>`` to be built from the source files The optional ``<type>`` specifies the type of library to be created:
listed in the command invocation. The ``<name>``
corresponds to the logical target name and must be globally unique within ``STATIC``
a project. The actual file name of the library built is constructed based An archive of object files for use when linking other targets.
on conventions of the native platform (such as ``lib<name>.a`` or
``<name>.lib``). ``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 .. versionadded:: 3.1
Source arguments to ``add_library`` may use "generator expressions" with 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 The source files can be omitted if they are added later using
:command:`target_sources`. :command:`target_sources`.
``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of For ``SHARED`` and ``MODULE`` libraries the
library to be created. ``STATIC`` libraries are archives of object files :prop_tgt:`POSITION_INDEPENDENT_CODE` target
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
property is set to ``ON`` automatically. property is set to ``ON`` automatically.
A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create an macOS 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 location. See documentation of the :prop_tgt:`OUTPUT_NAME` target
property to change the ``<name>`` part of the final file name. 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 See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties. buildsystem properties.
@@ -77,14 +87,15 @@ within IDE.
Object Libraries 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 Other targets created by ``add_library`` or :command:`add_executable`
compiles source files but does not archive or link their object files into a may reference the objects using an expression of the
library. Instead 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 form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where
``objlib`` is the object library name. For example: ``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 Interface Libraries
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake .. signature::
add_library(<name> INTERFACE) add_library(<name> INTERFACE)
:target: INTERFACE
Creates an :ref:`Interface Library <Interface Libraries>`. Add an :ref:`Interface Library <Interface Libraries>` target that may
An ``INTERFACE`` library target does not compile sources and does specify usage requirements for dependents but does not compile sources
not produce a library artifact on disk. However, it may have and does not produce a library artifact on disk.
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`, An interface library with no source files is not included as a target
* :command:`target_link_libraries(INTERFACE)`, in the generated buildsystem. However, it may have
* :command:`target_link_options(INTERFACE)`, properties set on it and it may be installed and exported.
* :command:`target_include_directories(INTERFACE)`, Typically, ``INTERFACE_*`` properties are populated on an interface
* :command:`target_compile_options(INTERFACE)`, target using the commands:
* :command:`target_compile_definitions(INTERFACE)`, and
* :command:`target_sources(INTERFACE)`,
and then it is used as an argument to :command:`target_link_libraries` * :command:`set_property`,
like any other target. * :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 and then it is used as an argument to :command:`target_link_libraries`
itself and is not included as a target in the generated buildsystem. like any other target.
.. versionadded:: 3.15 .. versionadded:: 3.15
An interface library can have :prop_tgt:`PUBLIC_HEADER` and An interface library can have :prop_tgt:`PUBLIC_HEADER` and
:prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those :prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those
properties can be installed using the :command:`install(TARGETS)` command. properties can be installed using the :command:`install(TARGETS)` command.
.. versionadded:: 3.19 .. signature::
An interface library target may be created with source files: 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>...]) Add an :ref:`Interface Library <Interface Libraries>` target with
source files (in addition to usage requirements and properties as
Source files may be listed directly in the ``add_library`` call or added documented by the :command:`above signature <add_library(INTERFACE)>`).
later by calls to :command:`target_sources` with the ``PRIVATE`` or Source files may be listed directly in the ``add_library`` call
``PUBLIC`` keywords. 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` 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` 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 but does contain build rules for custom commands created by the
:command:`add_custom_command` command. :command:`add_custom_command` command.
.. note:: The options are:
In most command signatures where the ``INTERFACE`` keyword appears,
the items listed after it only become part of that target's usage ``EXCLUDE_FROM_ALL``
requirements and are not part of the target's own settings. However, Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
in this signature of ``add_library``, the ``INTERFACE`` keyword refers See documentation of that target property for details.
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 .. note::
:prop_tgt:`INTERFACE_SOURCES` target property. 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`: .. _`add_library imported libraries`:
Imported Libraries Imported Libraries
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
.. code-block:: cmake .. signature::
add_library(<name> <type> IMPORTED [GLOBAL]) add_library(<name> <type> IMPORTED [GLOBAL])
:target: IMPORTED
Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``. Add an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
No rules are generated to build it, and the :prop_tgt:`IMPORTED` target The target name may be referenced like any target built within the project,
property is ``True``. The target name has scope in the directory in which except that by default it is visible only in the directory in which it is
it is created and below, but the ``GLOBAL`` option extends visibility. created, and below.
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: The ``<type>`` must be one of:
``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN`` ``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
References a library file located outside the project. The References a library file located outside the project. The
:prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
location of the main library file on disk: location of the main library file on disk:
* For a ``SHARED`` library on most non-Windows platforms, the main library * 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 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, 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 has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
should be set in the :prop_tgt:`IMPORTED_SONAME` target property. should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
If the referenced library file does not have a ``SONAME``, but the If the referenced library file does not have a ``SONAME``, but the
platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target
property should be set. property should be set.
* For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB` * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
target property (or its per-configuration variant target property (or its per-configuration variant
:prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
DLL import library file (``.lib`` or ``.dll.a``) on disk, and the DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS` library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
generator expression). 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 An ``UNKNOWN`` library type is typically only used in the implementation
:ref:`Find Modules`. It allows the path to an imported library (often found of :ref:`Find Modules`. It allows the path to an imported library
using the :command:`find_library` command) to be used without having to know (often found using the :command:`find_library` command) to be used
what type of library it is. This is especially useful on Windows where a without having to know what type of library it is. This is especially
static library and a DLL's import library both have the same file extension. useful on Windows where a static library and a DLL's import library
both have the same file extension.
``OBJECT`` ``OBJECT``
References a set of object files located outside the project. References a set of object files located outside the project.
The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
object files on disk. object files on disk.
Additional usage requirements may be specified in ``INTERFACE_*`` properties. Additional usage requirements may be specified in ``INTERFACE_*``
properties.
``INTERFACE`` ``INTERFACE``
Does not reference any library or object files on disk, but may Does not reference any library or object files on disk, but may
specify usage requirements in ``INTERFACE_*`` properties. specify usage requirements in ``INTERFACE_*`` properties.
See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties The options are:
for more information.
``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 Alias Libraries
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
.. code-block:: cmake .. signature::
add_library(<name> ALIAS <target>) add_library(<name> ALIAS <target>)
:target: ALIAS
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
not appear in the generated buildsystem as a make target. The ``<target>`` not appear in the generated buildsystem as a make target. The ``<target>``
may not be an ``ALIAS``. may not be an ``ALIAS``.
.. versionadded:: 3.11 .. versionadded:: 3.11
An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>` An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`