add_library ----------- .. only:: html .. contents:: Add a library to the project using the specified source files. Normal Libraries ^^^^^^^^^^^^^^^^ .. code-block:: cmake add_library( [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [...]) Adds a library target called ```` to be built from the source files listed in the command invocation. The ```` 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.a`` or ``.lib``). .. versionadded:: 3.1 Source arguments to ``add_library`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. .. versionadded:: 3.11 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 property is set to ``ON`` automatically. A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` target property to create an macOS Framework. .. versionadded:: 3.8 A ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK` target property to create a static Framework. If a library does not export any symbols, it must not be declared as a ``SHARED`` library. For example, a Windows resource DLL or a managed C++/CLI DLL that exports no unmanaged symbols would need to be a ``MODULE`` library. This is because CMake expects a ``SHARED`` library to always have an associated import library on Windows. By default the library file will be created in the build tree directory corresponding to the source tree directory in which the command was invoked. See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties to change this location. See documentation of the :prop_tgt:`OUTPUT_NAME` target property to change the ```` 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. 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. Object Libraries ^^^^^^^^^^^^^^^^ .. code-block:: cmake add_library( OBJECT [...]) Creates an :ref:`Object Library `. An object library compiles source files but does not archive or link their object files into a library. Instead other targets created by :command:`add_library` or :command:`add_executable` may reference the objects using an expression of the form ``$`` as a source, where ``objlib`` is the object library name. For example: .. code-block:: cmake add_library(... $ ...) add_executable(... $ ...) will include objlib's object files in a library and an executable along with those compiled from their own sources. Object libraries may contain only sources that compile, header files, and other files that would not affect linking of a normal library (e.g. ``.txt``). They may contain custom commands generating such sources, but not ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build 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 ``$``. .. versionadded:: 3.12 Object libraries can be linked to with :command:`target_link_libraries`. Interface Libraries ^^^^^^^^^^^^^^^^^^^ .. code-block:: cmake add_library( INTERFACE) Creates an :ref:`Interface Library `. 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 created with the above signature has no source files itself and is not included as a target in the generated buildsystem. .. 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: .. code-block:: cmake add_library( INTERFACE [...] [EXCLUDE_FROM_ALL]) 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` target property is set), it will appear in the generated buildsystem as a build target much like a target defined by the :command:`add_custom_target` command. It does not compile any sources, 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. .. _`add_library imported libraries`: Imported Libraries ^^^^^^^^^^^^^^^^^^ .. code-block:: cmake add_library( IMPORTED [GLOBAL]) Creates an :ref:`IMPORTED library target ` called ````. 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 ```` 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_`) 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 Windows, the :prop_tgt:`IMPORTED_IMPLIB` target property (or its per-configuration variant :prop_tgt:`IMPORTED_IMPLIB_`) 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. 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_`) 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 ^^^^^^^^^^^^^^^ .. code-block:: cmake add_library( ALIAS ) Creates an :ref:`Alias Target `, such that ```` can be used to refer to ```` in subsequent commands. The ```` does not appear in the generated buildsystem as a make target. The ```` may not be an ``ALIAS``. .. versionadded:: 3.11 An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target ` .. versionadded:: 3.18 An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is scoped to the directory in which it is created and below. The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the alias is global or not. ``ALIAS`` targets can be used as linkable targets and as targets to read properties from. They can also be tested for existence with the regular :command:`if(TARGET)` subcommand. The ```` may not be used to modify properties of ````, 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.