mirror of
https://github.com/reactos/CMake.git
synced 2024-12-05 02:06:34 +00:00
6556481eb8
CMake assumes that a SHARED library compiled on Windows will export a LIB file. This is not actually the case on Visual C++ if the library does not export any symbols, and causes incremental builds to break if the user specifies SHARED anyway. (Users should use MODULE libraries instead.)
163 lines
6.9 KiB
ReStructuredText
163 lines
6.9 KiB
ReStructuredText
add_library
|
|
-----------
|
|
|
|
.. only:: html
|
|
|
|
.. contents::
|
|
|
|
Add a library to the project using the specified source files.
|
|
|
|
Normal Libraries
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
add_library(<name> [STATIC | SHARED | MODULE]
|
|
[EXCLUDE_FROM_ALL]
|
|
source1 [source2 ...])
|
|
|
|
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 :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 OS X 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 ``<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 :prop_tgt:`EXCLUDE_FROM_ALL`
|
|
target property for details.
|
|
|
|
Source arguments to ``add_library`` may use "generator expressions" with
|
|
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
|
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
|
|
manual for more on defining buildsystem properties.
|
|
|
|
Imported Libraries
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
|
|
[GLOBAL])
|
|
|
|
An :ref:`IMPORTED library target <Imported Targets>` references a library
|
|
file located outside the project. 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 most important such
|
|
property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
|
|
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
|
|
location of the main library file on disk. See documentation of the
|
|
``IMPORTED_*`` and ``INTERFACE_*`` properties for more information.
|
|
|
|
Object Libraries
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
add_library(<name> OBJECT <src>...)
|
|
|
|
Creates an :ref:`Object Library <Object Libraries>`. 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 ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the
|
|
object library name. For example:
|
|
|
|
.. code-block:: cmake
|
|
|
|
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. ``.txt``).
|
|
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>``.
|
|
|
|
Alias Libraries
|
|
^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
add_library(<name> ALIAS <target>)
|
|
|
|
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
|
|
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
|
|
not appear in the generatedbuildsystem as a make target. The ``<target>``
|
|
may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
|
|
``ALIAS`` targets can be used as linkable targets and as targets to
|
|
read properties from. They can also be tested for existance with the
|
|
regular :command:`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 :command:`set_property`, :command:`set_target_properties`,
|
|
:command:`target_link_libraries` etc. An ``ALIAS`` target may not be
|
|
installed or exported.
|
|
|
|
Interface Libraries
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
|
|
|
|
Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE``
|
|
library 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 commands:
|
|
|
|
* :command:`set_property`,
|
|
* :command:`target_link_libraries(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`` :ref:`Imported Target <Imported Targets>` may also be
|
|
created with this signature. An ``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. ``IMPORTED`` libraries are useful for convenient reference
|
|
from commands like :command:`target_link_libraries`.
|