Add a library to the project using the specified source files.
add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [<source>...])
Adds a library target called
<name> 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
New in version 3.1: Source arguments to
add_library may use "generator expressions" with
$<...>. See the
manual for available expressions.
New in version 3.11: The source files can be omitted if they are added later using
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
SHARED based on whether the current value of the
MODULE libraries the
property is set to
SHARED library may be marked with the
target property to create an macOS Framework.
New in version 3.8: A
STATIC library may be marked with the
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
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
RUNTIME_OUTPUT_DIRECTORY target properties to change this
location. See documentation of the
property to change the
<name> part of the final file name.
EXCLUDE_FROM_ALL is given the corresponding property will be set on
the created target. See documentation of the
target property for details.
cmake-buildsystem(7) manual for more on defining
HEADER_FILE_ONLY on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
add_library(<name> OBJECT [<source>...])
Creates an 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
add_executable() may reference the objects using an expression of the
$<TARGET_OBJECTS:objlib> as a source, where
objlib is the
object library name. For example:
add_library(... $<TARGET_OBJECTS:objlib> ...) add_executable(... $<TARGET_OBJECTS:objlib> ...)
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.
They may contain custom commands generating such sources, but not
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
New in version 3.12: Object libraries can be linked to with
Creates an Interface Library.
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.
INTERFACE_* properties are populated on an interface
target using the commands:
and then it is used as an argument to
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.
New in version 3.15: An interface library can have
PRIVATE_HEADER properties. The headers specified by those
properties can be installed using the
New in version 3.19: An interface library target may be created with source files:
add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
Source files may be listed directly in the
add_library call or added
later by calls to
target_sources() with the
If an interface library has source files (i.e. the
target property is set), or header sets (i.e. the
target property is set), it will appear in the generated buildsystem
as a build target much like a target defined by the
add_custom_target() command. It does not compile any sources,
but does contain build rules for custom commands created by the
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
INTERFACE keyword refers
to the library type only. Sources listed after it in the
PRIVATE to the interface library and do not appear in its
INTERFACE_SOURCES target property.
add_library(<name> <type> IMPORTED [GLOBAL])
Creates an IMPORTED library target called
No rules are generated to build it, and the
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
target_link_libraries(). Details about the imported library
are specified by setting properties whose names begin in
<type> must be one of:
References a library file located outside the project. The
IMPORTED_LOCATIONtarget property (or its per-configuration variant
IMPORTED_LOCATION_<CONFIG>) specifies the location of the main library file on disk:
SHAREDlibrary on most non-Windows platforms, the main library file is the
.dylibfile used by both linkers and dynamic loaders. If the referenced library file has a
SONAME(or on macOS, has a
@rpath/), the value of that field should be set in the
IMPORTED_SONAMEtarget property. If the referenced library file does not have a
SONAME, but the platform supports it, then the
IMPORTED_NO_SONAMEtarget property should be set.
SHAREDlibrary on Windows, the
IMPORTED_IMPLIBtarget property (or its per-configuration variant
IMPORTED_IMPLIB_<CONFIG>) specifies the location of the DLL import library file (
.dll.a) on disk, and the
IMPORTED_LOCATIONis the location of the
.dllruntime library (and is optional, but needed by the
Additional usage requirements may be specified in
UNKNOWNlibrary type is typically only used in the implementation of Find Modules. It allows the path to an imported library (often found using the
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.
References a set of object files located outside the project. The
IMPORTED_OBJECTStarget property (or its per-configuration variant
IMPORTED_OBJECTS_<CONFIG>) specifies the locations of object files on disk. Additional usage requirements may be specified in
Does not reference any library or object files on disk, but may specify usage requirements in
See documentation of the
for more information.
add_library(<name> ALIAS <target>)
Creates an Alias Target, such that
<name> can be
used to refer to
<target> in subsequent commands. The
not appear in the generated buildsystem as a make target. The
may not be an
New in version 3.11: An
ALIAS can target a
GLOBAL Imported Target
New in version 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.
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
if(TARGET) subcommand. The
<name> may not be used
to modify properties of
<target>, that is, it may not be used as the
target_link_libraries() etc. An
ALIAS target may not be
installed or exported.