Merge topic 'cmake-buildsystem-manual'
0d9cdab Help: Add cmake-buildsystem.7 manualThis commit is contained in:
Brad King
CMake Topic Stage
commit
1377542db5
|
|
@ -25,6 +25,7 @@ Reference Manuals
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
/manual/cmake-buildsystem.7
|
||||
/manual/cmake-commands.7
|
||||
/manual/cmake-developer.7
|
||||
/manual/cmake-generator-expressions.7
|
||||
|
|
|
|||
|
|
@ -0,0 +1,794 @@
|
|||
.. 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
|
||||
-------------------------------
|
||||
|
||||
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
|
||||
)
|
||||
Loading…
Reference in New Issue