797 lines
31 KiB
ReStructuredText
797 lines
31 KiB
ReStructuredText
.. cmake-manual-description: CMake Buildsystem Reference
|
|
|
|
cmake-buildsystem(7)
|
|
********************
|
|
|
|
.. only:: html or latex
|
|
|
|
.. contents::
|
|
|
|
Introduction
|
|
============
|
|
|
|
A CMake-based buildsystem is organized as a set of high-level logical
|
|
targets. Each target corresponds to an executable or library, or
|
|
is a custom target containing custom commands. Dependencies between the
|
|
targets are expressed in the buildsystem to determine the build order
|
|
and the rules for regeneration in response to change.
|
|
|
|
Binary Targets
|
|
==============
|
|
|
|
Executables and libraries are defined using the :command:`add_library`
|
|
and :command:`add_executable` commands. The resulting binary files have
|
|
appropriate prefixes, suffixes and extensions for the platform targeted.
|
|
Dependencies between binary targets are expressed using the
|
|
:command:`target_link_libraries` command:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(archive archive.cpp zip.cpp lzma.cpp)
|
|
add_executable(zipapp zipapp.cpp)
|
|
target_link_libraries(zipapp archive)
|
|
|
|
``archive`` is defined as a static library -- an archive containing objects
|
|
compiled from ``archive.cpp``, ``zip.cpp``, and ``lzma.cpp``. ``zipapp``
|
|
is defined as an executable formed by compiling and linking ``zipapp.cpp``.
|
|
When linking the ``zipapp`` executable, the ``archive`` static library is
|
|
linked in.
|
|
|
|
Binary Library Types
|
|
--------------------
|
|
|
|
By default, the :command:`add_library` command defines a static library,
|
|
unless a type is specified. A type may be specified when using the command:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
|
|
|
|
The :variable:`BUILD_SHARED_LIBS` variable may be enabled to change the
|
|
behavior of :command:`add_library` to build shared libraries by default.
|
|
|
|
In the context of the buildsystem definition as a whole, it is largely
|
|
irrelevant whether particular libraries are ``SHARED`` or ``STATIC`` --
|
|
the commands, dependency specifications and other APIs work similarly
|
|
regardless of the library type. The ``MODULE`` library type is
|
|
dissimilar in that it is generally not linked to -- it is not used in
|
|
the right-hand-side of the :command:`target_link_libraries` command.
|
|
It is a type which is loaded as a plugin using runtime techniques.
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(archive MODULE 7z.cpp)
|
|
|
|
The ``OBJECT`` library type is also not linked to. It defines a non-archival
|
|
collection of object files resulting from compiling the given source files.
|
|
The object files collection can be used as source inputs to other targets:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
|
|
|
|
add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
|
|
|
|
add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
|
|
|
|
``OBJECT`` libraries may only be used locally as sources in a buildsystem --
|
|
they may not be installed, exported, or used in the right hand side of
|
|
:command:`target_link_libraries`. They also may not be used as the ``TARGET``
|
|
in a use of the :command:`add_custom_command(TARGET)` command signature.
|
|
|
|
Commands such as :command:`add_custom_command`, which generates rules to be
|
|
run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
|
|
target as a ``COMMAND`` executable. The buildsystem rules will ensure that
|
|
the executable is built before attempting to run the command.
|
|
|
|
Build Specification and Usage Requirements
|
|
==========================================
|
|
|
|
The :command:`target_include_directories`, :command:`target_compile_definitions`
|
|
and :command:`target_compile_options` commands specify the build specifications
|
|
and the usage requirements of binary targets. The commands populate the
|
|
:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and
|
|
:prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the
|
|
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
|
|
and :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.
|
|
|
|
Each of the commands has a ``PRIVATE``, ``PUBLIC`` and ``INTERFACE`` mode. The
|
|
``PRIVATE`` mode populates only the non-``INTERFACE_`` variant of the target
|
|
property and the ``INTERFACE`` mode populates only the ``INTERFACE_`` variants.
|
|
The ``PUBLIC`` mode populates both variants of the repective target property.
|
|
Each command may be invoked with multiple uses of each keyword:
|
|
|
|
.. code-block:: cmake
|
|
|
|
target_compile_definitions(archive
|
|
PRIVATE BUILDING_WITH_LZMA
|
|
INTERFACE USING_ARCHIVE_LIB
|
|
)
|
|
|
|
Target Properties
|
|
-----------------
|
|
|
|
The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`,
|
|
:prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target
|
|
properties are used appropriately when compiling the source files of a
|
|
binary target.
|
|
|
|
Entries in the :prop_tgt:`INCLUDE_DIRECTORIES` are added to the compile line
|
|
with ``-I`` or ``-isystem`` prefixes and in the order of appearance in the
|
|
property value.
|
|
|
|
Entries in the :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or
|
|
``/D`` and added to the compile line in an unspecified order. The
|
|
:prop_tgt:`DEFINE_SYMBOL` target property is also added as a compile
|
|
definition as a special convenience case for ``SHARED`` and ``MODULE``
|
|
library targets.
|
|
|
|
Entries in the :prop_tgt:`COMPILE_OPTIONS` are escaped for the shell and added
|
|
in the order of appearance in the property value. Several compile options have
|
|
special separate handling, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`.
|
|
|
|
The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
|
|
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and
|
|
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties are
|
|
*Usage Requirements* -- they specify content which consumers
|
|
must use to correctly compile and link with the target they appear on.
|
|
For any binary target, the contents of each ``INTERFACE_`` property on
|
|
each target specified in a :command:`target_link_libraries` command is
|
|
consumed:
|
|
|
|
.. code-block:: cmake
|
|
|
|
set(srcs archive.cpp zip.cpp)
|
|
if (LZMA_FOUND)
|
|
list(APPEND srcs lzma.cpp)
|
|
endif()
|
|
add_library(archive SHARED ${srcs})
|
|
if (LZMA_FOUND)
|
|
# The archive library sources are compiled with -DBUILDING_WITH_LZMA
|
|
target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
|
|
endif()
|
|
target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
|
|
|
|
add_executable(consumer)
|
|
# Link consumer to archive and consume its usage requirements. The consumer
|
|
# executable sources are compiled with -DUSING_ARCHIVE_LIB.
|
|
target_link_libraries(consumer archive)
|
|
|
|
Because it is common to require that the source directory and corresponding
|
|
build directory are added to the :prop_tgt:`INCLUDE_DIRECTORIES`, the
|
|
:variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently
|
|
add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of
|
|
all targets. The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`
|
|
can be enabled to add the corresponding directories to the
|
|
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets. This makes use of
|
|
targets in multiple different directories convenient through use of the
|
|
:command:`target_link_libraries` command.
|
|
|
|
Transitive Usage Requirements
|
|
-----------------------------
|
|
|
|
The usage requirements of a target can transitively propagate to dependents.
|
|
The :command:`target_link_libraries` command also has ``PRIVATE``,
|
|
``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(archive archive.cpp)
|
|
target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
|
|
|
|
add_library(serialization serialization.cpp)
|
|
target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
|
|
|
|
add_library(archiveExtras extras.cpp)
|
|
target_link_libraries(archiveExtras PUBLIC archive)
|
|
target_link_libraries(archiveExtras PRIVATE serialization)
|
|
# archiveExtras is compiled with -DUSING_ARCHIVE_LIB
|
|
# and -DUSING_SERIALIZATION_LIB
|
|
|
|
add_executable(consumer consumer.cpp)
|
|
# consumer is compiled with -DUSING_ARCHIVE_LIB
|
|
target_link_libraries(consumer archiveExtras)
|
|
|
|
Because ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the
|
|
usage requirements of it are propagated to ``consumer`` too. Because
|
|
``serialization`` is a ``PRIVATE`` dependency of ``archive``, the usage
|
|
requirements of it are not propagated to ``consumer``.
|
|
|
|
Generally, a dependency should be specified in a use of
|
|
:command:`target_link_libraries` with the ``PRIVATE`` keyword if it is used by
|
|
only the implementation of a library, and not in the header files. If a
|
|
dependency is additionally used in the header files of a library (e.g. for
|
|
class inheritance), then it should be specified as a ``PUBLIC`` dependency.
|
|
A dependency which is not used by the implementation of a library, but only by
|
|
its headers should be specified as an ``INTERFACE`` dependency. The
|
|
:command:`target_link_libraries` command may be invoked with multiple uses of
|
|
each keyword:
|
|
|
|
.. code-block:: cmake
|
|
|
|
target_link_libraries(archiveExtras
|
|
PUBLIC archive
|
|
PRIVATE serialization
|
|
)
|
|
|
|
.. _`Compatible Interface Properties`:
|
|
|
|
Compatible Interface Properties
|
|
-------------------------------
|
|
|
|
Some target properties are required to be compatible between a target and
|
|
the interface of each dependency. For example, the
|
|
:prop_tgt:`POSITION_INDEPENDENT_CODE` target property may specify a
|
|
boolean value of whether a target should be compiled as
|
|
position-independent-code, which has platform-specific consequences.
|
|
A target may also specify the usage requirement
|
|
:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` to communicate that
|
|
consumers must be compiled as position-independent-code.
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
|
|
|
|
add_library(lib1 SHARED lib1.cpp)
|
|
set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
|
|
|
|
add_executable(exe2 exe2.cpp)
|
|
target_link_libraries(exe2 lib1)
|
|
|
|
Here, both ``exe1`` and ``exe2`` will be compiled as position-independent-code.
|
|
``lib1`` will also be compiled as position-independent-code because that is the
|
|
default setting for ``SHARED`` libraries. If dependencies have conflicting,
|
|
non-compatible requirements :manual:`cmake(1)` issues a diagnostic:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1 SHARED lib1.cpp)
|
|
set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
|
|
|
|
add_library(lib2 SHARED lib2.cpp)
|
|
set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 lib1)
|
|
set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
|
|
|
|
add_executable(exe2 exe2.cpp)
|
|
target_link_libraries(exe2 lib1 lib2)
|
|
|
|
The ``lib1`` requirement ``INTERFACE_POSITION_INDEPENDENT_CODE`` is not
|
|
"compatible" with the ``POSITION_INDEPENDENT_CODE`` property of the ``exe1``
|
|
target. The library requires that consumers are built as
|
|
position-independent-code, while the executable specifies to not built as
|
|
position-independent-code, so a diagnostic is issued.
|
|
|
|
The ``lib1`` and ``lib2`` requirements are not "compatible". One of them
|
|
requires that consumers are built as position-independent-code, while
|
|
the other requires that consumers are not built as position-independent-code.
|
|
Because ``exe2`` links to both and they are in conflict, a diagnostic is
|
|
issued.
|
|
|
|
To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property,
|
|
if set must be either the same, in a boolean sense, as the
|
|
:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` property of all transitively
|
|
specified dependencies on which that property is set.
|
|
|
|
This property of "compatible interface requirement" may be extended to other
|
|
properties by specifying the property in the content of the
|
|
:prop_tgt:`COMPATIBLE_INTERFACE_BOOL` target property. Each specified property
|
|
must be compatible between the consuming target and the corresponding property
|
|
with an ``INTERFACE_`` prefix from each dependency:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1Version2 SHARED lib1_v2.cpp)
|
|
set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
|
|
set_property(TARGET lib1Version2 APPEND PROPERTY
|
|
COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
|
|
)
|
|
|
|
add_library(lib1Version3 SHARED lib1_v3.cpp)
|
|
set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
|
|
|
|
add_executable(exe2 exe2.cpp)
|
|
target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
|
|
|
|
Non-boolean properties may also participate in "compatible interface"
|
|
computations. Properties specified in the
|
|
:prop_tgt:`COMPATIBLE_INTERFACE_STRING`
|
|
property must be either unspecified or compare to the same string among
|
|
all transitively specified dependencies. This can be useful to ensure
|
|
that multiple incompatible versions of a library are not linked together
|
|
through transitive requirements of a target:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1Version2 SHARED lib1_v2.cpp)
|
|
set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
|
|
set_property(TARGET lib1Version2 APPEND PROPERTY
|
|
COMPATIBLE_INTERFACE_STRING LIB_VERSION
|
|
)
|
|
|
|
add_library(lib1Version3 SHARED lib1_v3.cpp)
|
|
set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
|
|
|
|
add_executable(exe2 exe2.cpp)
|
|
target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
|
|
|
|
The :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` target property specifies
|
|
that content will be evaluated numerically and the maximum number among all
|
|
specified will be calculated:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1Version2 SHARED lib1_v2.cpp)
|
|
set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
|
|
set_property(TARGET lib1Version2 APPEND PROPERTY
|
|
COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
|
|
)
|
|
|
|
add_library(lib1Version3 SHARED lib1_v3.cpp)
|
|
set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
# CONTAINER_SIZE_REQUIRED will be "200"
|
|
target_link_libraries(exe1 lib1Version2)
|
|
|
|
add_executable(exe2 exe2.cpp)
|
|
# CONTAINER_SIZE_REQUIRED will be "1000"
|
|
target_link_libraries(exe2 lib1Version2 lib1Version3)
|
|
|
|
Similarly, the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` may be used to
|
|
calculate the numeric minimum value for a property from dependencies.
|
|
|
|
Each calculated "compatible" property value may be read in the consumer at
|
|
generate-time using generator expressions.
|
|
|
|
Property Origin Debugging
|
|
-------------------------
|
|
|
|
Because build specifications can be determined by dependencies, the lack of
|
|
locality of code which creates a target and code which is responsible for
|
|
setting build specifications may make the code more difficult to reason about.
|
|
:manual:`cmake(1)` provides a debugging facility to print the origin of the
|
|
contents of properties which may be determined by dependencies. The properties
|
|
which can be debugged are :prop_tgt:`INCLUDE_DIRECTORIES`,
|
|
:prop_tgt:`COMPILE_DEFINITIONS`, :prop_tgt:`COMPILE_OPTIONS`,
|
|
:prop_tgt:`AUTOUIC_OPTIONS`, and all properties listed in a
|
|
``COMPATIBLE_INTERFACE_*`` target property:
|
|
|
|
.. code-block:: cmake
|
|
|
|
set(CMAKE_DEBUG_TARGET_PROPERTIES
|
|
INCLUDE_DIRECTORIES
|
|
COMPILE_DEFINITIONS
|
|
POSITION_INDEPENDENT_CODE
|
|
CONTAINER_SIZE_REQUIRED
|
|
LIB_VERSION
|
|
)
|
|
add_executable(exe1 exe1.cpp)
|
|
|
|
In the case of properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` or
|
|
:prop_tgt:`COMPATIBLE_INTERFACE_STRING`, the debug output shows which target
|
|
was responsible for setting the property, and which other dependencies also
|
|
defined the property. In the case of
|
|
:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and
|
|
:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN`, the debug output shows the
|
|
value of the property from each dependency, and whether the value determines
|
|
the new extreme.
|
|
|
|
Build Specification with Generator Expressions
|
|
----------------------------------------------
|
|
|
|
Build specifications may use
|
|
:manual:`generator expressions <cmake-generator-expressions(7)>` containing
|
|
content which may be conditional or known only at generate-time. For example,
|
|
the calculated "compatible" value of a property may be read with the
|
|
``TARGET_PROPERTY`` expression:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1Version2 SHARED lib1_v2.cpp)
|
|
set_property(TARGET lib1Version2 PROPERTY
|
|
INTERFACE_CONTAINER_SIZE_REQUIRED 200)
|
|
set_property(TARGET lib1Version2 APPEND PROPERTY
|
|
COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
|
|
)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 lib1Version2)
|
|
target_compile_definitions(exe1 PRIVATE
|
|
CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
|
|
)
|
|
|
|
In this case, the ``exe1`` source files will be compiled with
|
|
``-DCONTAINER_SIZE=200``.
|
|
|
|
Configuration determined build specifications may be conveniently set using
|
|
the ``CONFIG`` generator expression.
|
|
|
|
.. code-block:: cmake
|
|
|
|
target_compile_definitions(exe1 PRIVATE
|
|
$<$<CONFIG:Debug>:DEBUG_BUILD>
|
|
)
|
|
|
|
The ``CONFIG`` parameter is compared case-insensitively with the configuration
|
|
being built. In the presence of :prop_tgt:`IMPORTED` targets, the content of
|
|
:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_CONFIG>` is also
|
|
accounted for by this expression.
|
|
|
|
Some buildsystems generated by :manual:`cmake(1)` have a predetermined
|
|
build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable. The
|
|
buildsystem for the IDEs such as Visual Studio and Xcode are generated
|
|
independent of the build-configuration, and the actual build configuration
|
|
is not known until build-time. Therefore, code such as
|
|
|
|
.. code-block:: cmake
|
|
|
|
string(TOLOWER ${CMAKE_BUILD_TYPE} _type)
|
|
if (_type STREQUAL debug)
|
|
target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
|
|
endif()
|
|
|
|
may appear to work for ``Makefile`` based and ``Ninja`` generators, but is not
|
|
portable to IDE generators. Additionally, the :prop_tgt:`IMPORTED`
|
|
configuration-mappings are not accounted for with code like this, so it should
|
|
be avoided.
|
|
|
|
The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY``
|
|
generator expression are evaluated with the consuming target context. This
|
|
means that a usage requirement specification may be evaluated differently based
|
|
on the consumer:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1 lib1.cpp)
|
|
target_compile_definitions(lib1 INTERFACE
|
|
$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
|
|
$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
|
|
$<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
|
|
)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 lib1)
|
|
|
|
cmake_policy(SET CMP0041 NEW)
|
|
|
|
add_library(shared_lib shared_lib.cpp)
|
|
target_link_libraries(shared_lib lib1)
|
|
|
|
The ``exe1`` executable will be compiled with ``-DLIB1_WITH_EXE``, while the
|
|
``shared_lib`` shared library will be compiled with ``-DLIB1_WITH_SHARED_LIB``
|
|
and ``-DCONSUMER_CMP0041_NEW``, because policy :policy:`CMP0041` is
|
|
``NEW`` at the point where the ``shared_lib`` target is created.
|
|
|
|
The ``BUILD_INTERFACE`` expression wraps requirements which are only used when
|
|
consumed from a target in the same buildsystem, or when consumed from a target
|
|
exported to the build directory using the :command:`export` command. The
|
|
``INSTALL_INTERFACE`` expression wraps requirements which are only used when
|
|
consumed from a target which has been installed and exported with the
|
|
:command:`install(EXPORT)` command:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(ClimbingStats climbingstats.cpp)
|
|
target_compile_definitions(ClimbingStats INTERFACE
|
|
$<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
|
|
$<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
|
|
)
|
|
install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
|
|
install(EXPORT libExport NAMESPACE Upstream::
|
|
DESTINATION lib/cmake/ClimbingStats)
|
|
export(EXPORT libExport NAMESPACE Upstream::)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 ClimbingStats)
|
|
|
|
In this case, the ``exe1`` executable will be compiled with
|
|
``-DClimbingStats_FROM_BUILD_LOCATION``. The exporting commands generate
|
|
:prop_tgt:`IMPORTED` targets with either the ``INSTALL_INTERFACE`` or the
|
|
``BUILD_INTERFACE`` omitted, and the ``*_INTERFACE`` marker stripped away.
|
|
A separate project consuming the ``ClimbingStats`` package would contain:
|
|
|
|
.. code-block:: cmake
|
|
|
|
find_package(ClimbingStats REQUIRED)
|
|
|
|
add_executable(Downstream main.cpp)
|
|
target_link_libraries(Downstream Upstream::ClimbingStats)
|
|
|
|
Depending on whether the ``ClimbingStats`` package was used from the build
|
|
location or the install location, the ``Downstream`` target would be compiled
|
|
with either ``-DClimbingStats_FROM_BUILD_LOCATION`` or
|
|
``-DClimbingStats_FROM_INSTALL_LOCATION``. For more about packages and
|
|
exporting see the :manual:`cmake-packages(7)` manual.
|
|
|
|
Include Directories and Usage Requirements
|
|
''''''''''''''''''''''''''''''''''''''''''
|
|
|
|
Include directories require some special consideration when specified as usage
|
|
requirements and when used with generator expressions. The
|
|
:command:`target_include_directories` command accepts both relative and
|
|
absolute include directories:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1 lib1.cpp)
|
|
target_include_directories(lib1 PRIVATE
|
|
/absolute/path
|
|
relative/path
|
|
)
|
|
|
|
Relative paths are interpreted relative to the source directory where the
|
|
command appears. Relative paths are not allowed in the
|
|
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :prop_tgt:`IMPORTED` targets.
|
|
|
|
In cases where a non-trivial generator expression is used, the
|
|
``INSTALL_PREFIX`` expression may be used within the argument of an
|
|
``INSTALL_INTERFACE`` expression. It is a replacement marker which
|
|
expands to the installation prefix when imported by a consuming project.
|
|
|
|
Include directories usage requirements commonly differ between the build-tree
|
|
and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
|
|
generator expressions can be used to describe separate usage requirements
|
|
based on the usage location. Relative paths are allowed within these
|
|
expressions, and are interpreted relative to the current source directory
|
|
or the installation prefix, as appropriate.
|
|
|
|
Two convenience APIs are provided relating to include directories usage
|
|
requirements. The :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable
|
|
may be enabled, with an equivalent effect to:
|
|
|
|
.. code-block:: cmake
|
|
|
|
set_property(TARGET tgt APPEND PROPERTY
|
|
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
|
|
)
|
|
|
|
for each target affected. The convenience for installed targets is
|
|
an ``INCLUDES DESTINATION`` component with the :command:`install(TARGETS)`
|
|
command:
|
|
|
|
.. code-block:: cmake
|
|
|
|
install(TARGETS foo bar bat EXPORT tgts ${dest_args}
|
|
INCLUDES DESTINATION include
|
|
)
|
|
install(EXPORT tgts ${other_args})
|
|
install(FILES ${headers} DESTINATION include)
|
|
|
|
This is equivalent to appending ``${CMAKE_INSTALL_PREFIX}/include`` to the
|
|
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of each of the installed
|
|
:prop_tgt:`IMPORTED` targets when generated by :command:`install(EXPORT)`.
|
|
|
|
If a binary target is linked transitively to a Mac OX framework, the
|
|
``Headers`` directory of the framework is also treated as a usage requirement.
|
|
This has the same effect as passing the framework directory as an include
|
|
directory.
|
|
|
|
Link Libraries and Generator Expressions
|
|
----------------------------------------
|
|
|
|
Like build specifications, :prop_tgt:`link libraries <LINK_LIBRARIES>` may be
|
|
specified with generator expression conditions. However, as consumption of
|
|
usage requirements is based on collection from linked dependencies, there is
|
|
an additional limitation that the link dependencies must form a "directed
|
|
acyclic graph". That is, if linking to a target is dependent on the value of
|
|
a target property, that target property may not be dependent on the linked
|
|
dependencies:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1 lib1.cpp)
|
|
add_library(lib2 lib2.cpp)
|
|
target_link_libraries(lib1 PUBLIC
|
|
$<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
|
|
)
|
|
add_library(lib3 lib3.cpp)
|
|
set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 lib1 lib3)
|
|
|
|
As the value of the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of
|
|
the ``exe1`` target is dependent on the linked libraries (``lib3``), and the
|
|
edge of linking ``exe1`` is determined by the same
|
|
:prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
|
|
contains a cycle. :manual:`cmake(1)` issues a diagnostic in this case.
|
|
|
|
Output Files
|
|
------------
|
|
|
|
The buildsystem targets created by the :command:`add_library` and
|
|
:command:`add_executable` commands create rules to create binary outputs.
|
|
The exact output location of the binaries can only be determined at
|
|
generate-time because it can depend on the build-configuration and the
|
|
link-language of linked dependencies etc. ``TARGET_FILE``,
|
|
``TARGET_LINKER_FILE`` and related expressions can be used to access the
|
|
name and location of generated binaries. These expressions do not work
|
|
for ``OBJECT`` libraries however, as there is no single file generated
|
|
by such libraries which is relevant to the expressions.
|
|
|
|
Directory-Scoped Commands
|
|
-------------------------
|
|
|
|
The :command:`target_include_directories`,
|
|
:command:`target_compile_definitions` and
|
|
:command:`target_compile_options` commands have an effect on only one
|
|
target at a time. The commands :command:`add_definitions`,
|
|
:command:`add_compile_options` and :command:`include_directories` have
|
|
a similar function, but operate at directory scope instead of target
|
|
scope for convenience.
|
|
|
|
Psuedo Targets
|
|
==============
|
|
|
|
Some target types do not represent outputs of the buildsystem, but only inputs
|
|
such as external dependencies, aliases or other non-build artifacts. Pseudo
|
|
targets are not represented in the generated buildsystem.
|
|
|
|
Imported Targets
|
|
----------------
|
|
|
|
An :prop_tgt:`IMPORTED` target represents a pre-existing dependency. Usually
|
|
such targets are defined by an upstream package and should be treated as
|
|
immutable. It is not possible to use an :prop_tgt:`IMPORTED` target in the
|
|
left-hand-side of the :command:`target_compile_definitions`,
|
|
:command:`target_include_directories`, :command:`target_compile_options` or
|
|
:command:`target_link_libraries` commands, as that would be an attempt to
|
|
modify it. :prop_tgt:`IMPORTED` targets are designed to be used only in the
|
|
right-hand-side of those commands.
|
|
|
|
:prop_tgt:`IMPORTED` targets may have the same usage requirement properties
|
|
populated as binary targets, such as
|
|
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
|
|
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
|
|
:prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
|
|
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
|
|
:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
|
|
|
|
The :prop_tgt:`LOCATION` may also be read from an IMPORTED target, though there
|
|
is rarely reason to do so. Commands such as :command:`add_custom_command` can
|
|
transparently use an :prop_tgt:`IMPORTED` :prop_tgt:`EXECUTABLE <TYPE>` target
|
|
as a ``COMMAND`` executable.
|
|
|
|
The scope of the definition of an :prop_tgt:`IMPORTED` target is the directory
|
|
where it was defined. It may be accessed and used from subdirectories, but
|
|
not from parent directories or sibling directories. The scope is similar to
|
|
the scope of a cmake variable.
|
|
|
|
It is also possible to define a ``GLOBAL`` :prop_tgt:`IMPORTED` target which is
|
|
accessible globally in the buildsystem.
|
|
|
|
See the :manual:`cmake-packages(7)` manual for more on creating packages
|
|
with :prop_tgt:`IMPORTED` targets.
|
|
|
|
Alias Targets
|
|
-------------
|
|
|
|
An ``ALIAS`` target is a name which may be used interchangably with
|
|
a binary target name in read-only contexts. A primary use-case for ``ALIAS``
|
|
targets is for example or unit test executables accompanying a library, which
|
|
may be part of the same buildsystem or built separately based on user
|
|
configuration.
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(lib1 lib1.cpp)
|
|
install(TARGETS lib1 EXPORT lib1Export ${dest_args})
|
|
install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
|
|
|
|
add_library(Upstream::lib1 ALIAS lib1)
|
|
|
|
In another directory, we can link unconditionally to the ``Upstream::lib1``
|
|
target, which may be an :prop_tgt:`IMPORTED` target from a package, or an
|
|
``ALIAS`` target if built as part of the same buildsystem.
|
|
|
|
.. code-block:: cmake
|
|
|
|
if (NOT TARGET Upstream::lib1)
|
|
find_package(lib1 REQUIRED)
|
|
endif()
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 Upstream::lib1)
|
|
|
|
``ALIAS`` targets are not mutable, installable or exportable. They are
|
|
entirely local to the buildsystem description. A name can be tested for
|
|
whether it is an ``ALIAS`` name by reading the :prop_tgt:`ALIASED_TARGET`
|
|
property from it:
|
|
|
|
.. code-block:: cmake
|
|
|
|
get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
|
|
if(_aliased)
|
|
message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
|
|
endif()
|
|
|
|
Interface Libraries
|
|
-------------------
|
|
|
|
An ``INTERFACE`` target has no :prop_tgt:`LOCATION` and is mutable, but is
|
|
otherwise similar to an :prop_tgt:`IMPORTED` target.
|
|
|
|
It may specify usage requirements such as
|
|
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
|
|
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
|
|
:prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
|
|
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
|
|
:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
|
|
Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
|
|
:command:`target_compile_definitions`, :command:`target_compile_options`,
|
|
and :command:`target_link_libraries` commands may be used with ``INTERFACE``
|
|
libraries.
|
|
|
|
A primary use-case for ``INTERFACE`` libraries is header-only libraries.
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(Eigen INTERFACE)
|
|
target_include_directories(Eigen INTERFACE
|
|
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
|
|
$<INSTALL_INTERFACE:include/Eigen>
|
|
)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 Eigen)
|
|
|
|
Here, the usage requirements from the ``Eigen`` target are consumed and used
|
|
when compiling, but it has no effect on linking.
|
|
|
|
Another use-case is to employ an entirely target-focussed design for usage
|
|
requirements:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(pic_on INTERFACE)
|
|
set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
|
|
add_library(pic_off INTERFACE)
|
|
set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
|
|
|
|
add_library(enable_rtti INTERFACE)
|
|
target_compile_options(enable_rtti INTERFACE
|
|
$<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
|
|
)
|
|
|
|
add_executable(exe1 exe1.cpp)
|
|
target_link_libraries(exe1 pic_on enable_rtti)
|
|
|
|
This way, the build specification of ``exe1`` is expressed entirely as linked
|
|
targets, and the complexity of compiler-specific flags is encapsulated in an
|
|
``INTERFACE`` library target.
|
|
|
|
``INTERFACE`` libraries may be installed and exported. Any content they refer
|
|
to must be installed separately:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_library(Eigen INTERFACE)
|
|
target_include_directories(Eigen INTERFACE
|
|
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
|
|
$<INSTALL_INTERFACE:include/Eigen>
|
|
)
|
|
|
|
install(TARGETS Eigen EXPORT eigenExport)
|
|
install(EXPORT eigenExport NAMESPACE Upstream::
|
|
DESTINATION lib/cmake/Eigen
|
|
)
|
|
install(FILES
|
|
${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h
|
|
${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h
|
|
${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h
|
|
DESTINATION include/Eigen
|
|
)
|