1add_library
2-----------
3
4.. only:: html
5
6   .. contents::
7
8Add a library to the project using the specified source files.
9
10Normal Libraries
11^^^^^^^^^^^^^^^^
12
13.. code-block:: cmake
14
15  add_library(<name> [STATIC | SHARED | MODULE]
16              [EXCLUDE_FROM_ALL]
17              [<source>...])
18
19Adds a library target called ``<name>`` to be built from the source files
20listed in the command invocation.  The ``<name>``
21corresponds to the logical target name and must be globally unique within
22a project.  The actual file name of the library built is constructed based
23on conventions of the native platform (such as ``lib<name>.a`` or
24``<name>.lib``).
25
26.. versionadded:: 3.1
27  Source arguments to ``add_library`` may use "generator expressions" with
28  the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
29  manual for available expressions.
30
31.. versionadded:: 3.11
32  The source files can be omitted if they are added later using
33  :command:`target_sources`.
34
35``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
36library to be created.  ``STATIC`` libraries are archives of object files
37for use when linking other targets.  ``SHARED`` libraries are linked
38dynamically and loaded at runtime.  ``MODULE`` libraries are plugins that
39are not linked into other targets but may be loaded dynamically at runtime
40using dlopen-like functionality.  If no type is given explicitly the
41type is ``STATIC`` or ``SHARED`` based on whether the current value of the
42variable :variable:`BUILD_SHARED_LIBS` is ``ON``.  For ``SHARED`` and
43``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
44property is set to ``ON`` automatically.
45A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
46target property to create an macOS Framework.
47
48.. versionadded:: 3.8
49  A ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK`
50  target property to create a static Framework.
51
52If a library does not export any symbols, it must not be declared as a
53``SHARED`` library.  For example, a Windows resource DLL or a managed C++/CLI
54DLL that exports no unmanaged symbols would need to be a ``MODULE`` library.
55This is because CMake expects a ``SHARED`` library to always have an
56associated import library on Windows.
57
58By default the library file will be created in the build tree directory
59corresponding to the source tree directory in which the command was
60invoked.  See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
61:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
62:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties to change this
63location.  See documentation of the :prop_tgt:`OUTPUT_NAME` target
64property to change the ``<name>`` part of the final file name.
65
66If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
67the created target.  See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
68target property for details.
69
70See the :manual:`cmake-buildsystem(7)` manual for more on defining
71buildsystem properties.
72
73See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
74pre-processed, and you want to have the original sources reachable from
75within IDE.
76
77Object Libraries
78^^^^^^^^^^^^^^^^
79
80.. code-block:: cmake
81
82  add_library(<name> OBJECT [<source>...])
83
84Creates an :ref:`Object Library <Object Libraries>`.  An object library
85compiles source files but does not archive or link their object files into a
86library.  Instead other targets created by :command:`add_library` or
87:command:`add_executable` may reference the objects using an expression of the
88form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the
89object library name.  For example:
90
91.. code-block:: cmake
92
93  add_library(... $<TARGET_OBJECTS:objlib> ...)
94  add_executable(... $<TARGET_OBJECTS:objlib> ...)
95
96will include objlib's object files in a library and an executable
97along with those compiled from their own sources.  Object libraries
98may contain only sources that compile, header files, and other files
99that would not affect linking of a normal library (e.g. ``.txt``).
100They may contain custom commands generating such sources, but not
101``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands.  Some native build
102systems (such as Xcode) may not like targets that have only object files, so
103consider adding at least one real source file to any target that references
104``$<TARGET_OBJECTS:objlib>``.
105
106.. versionadded:: 3.12
107  Object libraries can be linked to with :command:`target_link_libraries`.
108
109Interface Libraries
110^^^^^^^^^^^^^^^^^^^
111
112.. code-block:: cmake
113
114  add_library(<name> INTERFACE)
115
116Creates an :ref:`Interface Library <Interface Libraries>`.
117An ``INTERFACE`` library target does not compile sources and does
118not produce a library artifact on disk.  However, it may have
119properties set on it and it may be installed and exported.
120Typically, ``INTERFACE_*`` properties are populated on an interface
121target using the commands:
122
123* :command:`set_property`,
124* :command:`target_link_libraries(INTERFACE)`,
125* :command:`target_link_options(INTERFACE)`,
126* :command:`target_include_directories(INTERFACE)`,
127* :command:`target_compile_options(INTERFACE)`,
128* :command:`target_compile_definitions(INTERFACE)`, and
129* :command:`target_sources(INTERFACE)`,
130
131and then it is used as an argument to :command:`target_link_libraries`
132like any other target.
133
134An interface library created with the above signature has no source files
135itself and is not included as a target in the generated buildsystem.
136
137.. versionadded:: 3.15
138  An interface library can have :prop_tgt:`PUBLIC_HEADER` and
139  :prop_tgt:`PRIVATE_HEADER` properties.  The headers specified by those
140  properties can be installed using the :command:`install(TARGETS)` command.
141
142.. versionadded:: 3.19
143  An interface library target may be created with source files:
144
145  .. code-block:: cmake
146
147    add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
148
149  Source files may be listed directly in the ``add_library`` call or added
150  later by calls to :command:`target_sources` with the ``PRIVATE`` or
151  ``PUBLIC`` keywords.
152
153  If an interface library has source files (i.e. the :prop_tgt:`SOURCES`
154  target property is set), it will appear in the generated buildsystem
155  as a build target much like a target defined by the
156  :command:`add_custom_target` command.  It does not compile any sources,
157  but does contain build rules for custom commands created by the
158  :command:`add_custom_command` command.
159
160.. note::
161  In most command signatures where the ``INTERFACE`` keyword appears,
162  the items listed after it only become part of that target's usage
163  requirements and are not part of the target's own settings.  However,
164  in this signature of ``add_library``, the ``INTERFACE`` keyword refers
165  to the library type only.  Sources listed after it in the ``add_library``
166  call are ``PRIVATE`` to the interface library and do not appear in its
167  :prop_tgt:`INTERFACE_SOURCES` target property.
168
169.. _`add_library imported libraries`:
170
171Imported Libraries
172^^^^^^^^^^^^^^^^^^
173
174.. code-block:: cmake
175
176  add_library(<name> <type> IMPORTED [GLOBAL])
177
178Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
179No rules are generated to build it, and the :prop_tgt:`IMPORTED` target
180property is ``True``.  The target name has scope in the directory in which
181it is created and below, but the ``GLOBAL`` option extends visibility.
182It may be referenced like any target built within the project.
183``IMPORTED`` libraries are useful for convenient reference from commands
184like :command:`target_link_libraries`.  Details about the imported library
185are specified by setting properties whose names begin in ``IMPORTED_`` and
186``INTERFACE_``.
187
188The ``<type>`` must be one of:
189
190``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
191  References a library file located outside the project.  The
192  :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
193  variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
194  location of the main library file on disk:
195
196  * For a ``SHARED`` library on most non-Windows platforms, the main library
197    file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
198    loaders.  If the referenced library file has a ``SONAME`` (or on macOS,
199    has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
200    should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
201    If the referenced library file does not have a ``SONAME``, but the
202    platform supports it, then  the :prop_tgt:`IMPORTED_NO_SONAME` target
203    property should be set.
204
205  * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
206    target property (or its per-configuration variant
207    :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
208    DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
209    ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
210    library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
211    generator expression).
212
213  Additional usage requirements may be specified in ``INTERFACE_*`` properties.
214
215  An ``UNKNOWN`` library type is typically only used in the implementation of
216  :ref:`Find Modules`.  It allows the path to an imported library (often found
217  using the :command:`find_library` command) to be used without having to know
218  what type of library it is.  This is especially useful on Windows where a
219  static library and a DLL's import library both have the same file extension.
220
221``OBJECT``
222  References a set of object files located outside the project.
223  The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
224  variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
225  object files on disk.
226  Additional usage requirements may be specified in ``INTERFACE_*`` properties.
227
228``INTERFACE``
229  Does not reference any library or object files on disk, but may
230  specify usage requirements in ``INTERFACE_*`` properties.
231
232See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
233for more information.
234
235Alias Libraries
236^^^^^^^^^^^^^^^
237
238.. code-block:: cmake
239
240  add_library(<name> ALIAS <target>)
241
242Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
243used to refer to ``<target>`` in subsequent commands.  The ``<name>`` does
244not appear in the generated buildsystem as a make target.  The ``<target>``
245may not be an ``ALIAS``.
246
247.. versionadded:: 3.11
248  An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`
249
250.. versionadded:: 3.18
251  An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is
252  scoped to the directory in which it is created and below.
253  The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
254  alias is global or not.
255
256``ALIAS`` targets can be used as linkable targets and as targets to
257read properties from.  They can also be tested for existence with the
258regular :command:`if(TARGET)` subcommand.  The ``<name>`` may not be used
259to modify properties of ``<target>``, that is, it may not be used as the
260operand of :command:`set_property`, :command:`set_target_properties`,
261:command:`target_link_libraries` etc.  An ``ALIAS`` target may not be
262installed or exported.
263