Help/command/add_library.rst

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