130 lines
5.4 KiB
ReStructuredText
130 lines
5.4 KiB
ReStructuredText
add_library
|
|
-----------
|
|
|
|
Add a library to the project using the specified source files.
|
|
|
|
::
|
|
|
|
add_library(<name> [STATIC | SHARED | MODULE]
|
|
[EXCLUDE_FROM_ALL]
|
|
source1 source2 ... sourceN)
|
|
|
|
Adds a library target called <name> to be built from the source files
|
|
listed in the command invocation. 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).
|
|
|
|
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 BUILD_SHARED_LIBS is true. For SHARED and MODULE libraries
|
|
the POSITION_INDEPENDENT_CODE target property is set to TRUE
|
|
automatically.
|
|
|
|
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
|
|
ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and
|
|
RUNTIME_OUTPUT_DIRECTORY target properties to change this location.
|
|
See documentation of the OUTPUT_NAME target 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 EXCLUDE_FROM_ALL target
|
|
property for details.
|
|
|
|
The add_library command can also create IMPORTED library targets using
|
|
this signature:
|
|
|
|
::
|
|
|
|
add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
|
|
[GLOBAL])
|
|
|
|
An IMPORTED library target references a library file located outside
|
|
the project. No rules are generated to build it. 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 target_link_libraries.
|
|
Details about the imported library are specified by setting properties
|
|
whose names begin in ``IMPORTED_``. The most important such property is
|
|
IMPORTED_LOCATION (and its per-configuration version
|
|
IMPORTED_LOCATION_<CONFIG>) which specifies the location of the main
|
|
library file on disk. See documentation of the IMPORTED_* properties
|
|
for more information.
|
|
|
|
The signature
|
|
|
|
::
|
|
|
|
add_library(<name> OBJECT <src>...)
|
|
|
|
creates a special "object library" target. An object library compiles
|
|
source files but does not archive or link their object files into a
|
|
library. Instead other targets created by add_library or
|
|
add_executable may reference the objects using an expression of the
|
|
form $<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 (and headers) that compile to object files.
|
|
They may contain custom commands generating such sources, but not
|
|
PRE_BUILD, PRE_LINK, or POST_BUILD commands. Object libraries cannot
|
|
be imported, exported, installed, or linked. Some native build
|
|
systems may not like targets that have only object files, so consider
|
|
adding at least one real source file to any target that references
|
|
$<TARGET_OBJECTS:objlib>.
|
|
|
|
The signature
|
|
|
|
::
|
|
|
|
add_library(<name> ALIAS <target>)
|
|
|
|
creates an alias, such that <name> can be used to refer to <target> in
|
|
subsequent commands. The <name> does not appear in the generated
|
|
buildsystem as a make target. The <target> may not be an IMPORTED
|
|
target or an ALIAS. Alias targets can be used as linkable targets,
|
|
targets to read properties from. They can also be tested for
|
|
existance with the regular if(TARGET) subcommand. The <name> may not
|
|
be used to modify properties of <target>, that is, it may not be used
|
|
as the operand of set_property, set_target_properties,
|
|
target_link_libraries etc. An ALIAS target may not be installed of
|
|
exported.
|
|
|
|
The signature
|
|
|
|
::
|
|
|
|
add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
|
|
|
|
creates an interface target. An interface target does not directly
|
|
create build output, though it may have properties set on it and it
|
|
may be installed, exported and imported. Typically the INTERFACE_*
|
|
properties are populated on the interface target using the
|
|
:command:`set_property`, :command:`target_link_libraries`,
|
|
:command:`target_include_directories`
|
|
and :command:`target_compile_defintions` commands, and then it is used as an
|
|
argument to :command:`target_link_libraries` like any other target.
|
|
|
|
An ``INTERFACE`` :prop_tgt:`IMPORTED` target may also be created with this
|
|
signature. An :prop_tgt:`IMPORTED` library target references a library defined
|
|
outside the project. 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. :prop_tgt:`IMPORTED`
|
|
libraries are useful for convenient reference from commands like
|
|
:command:`target_link_libraries`.
|