.\" Man page generated from reStructuredText.

.

.TH "CMAKE-BUILDSYSTEM" "7" "October 14, 2015" "3.3.2" "CMake"

.SH NAME

cmake-buildsystem \- CMake Buildsystem Reference

.

.nr rst2man-indent-level 0

.

.de1 rstReportMargin

\\$1 \\n[an-margin]

level \\n[rst2man-indent-level]

level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

-

\\n[rst2man-indent0]

\\n[rst2man-indent1]

\\n[rst2man-indent2]

..

.de1 INDENT

.\" .rstReportMargin pre:

. RS \\$1

. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]

. nr rst2man-indent-level +1

.\" .rstReportMargin post:

..

.de UNINDENT

. RE

.\" indent \\n[an-margin]

.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]

.nr rst2man-indent-level -1

.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]

.in \\n[rst2man-indent\\n[rst2man-indent-level]]u

..

.SH INTRODUCTION

.sp

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.

.SH BINARY TARGETS

.sp

Executables and libraries are defined using the \fBadd_executable()\fP

and \fBadd_library()\fP commands.  The resulting binary files have

appropriate prefixes, suffixes and extensions for the platform targeted.

Dependencies between binary targets are expressed using the

\fBtarget_link_libraries()\fP command:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_library(archive archive.cpp zip.cpp lzma.cpp)

add_executable(zipapp zipapp.cpp)

target_link_libraries(zipapp archive)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

\fBarchive\fP is defined as a static library \-\- an archive containing objects

compiled from \fBarchive.cpp\fP, \fBzip.cpp\fP, and \fBlzma.cpp\fP\&.  \fBzipapp\fP

is defined as an executable formed by compiling and linking \fBzipapp.cpp\fP\&.

When linking the \fBzipapp\fP executable, the \fBarchive\fP static library is

linked in.

.SS Binary Executables

.sp

The \fBadd_executable()\fP command defines an executable target:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_executable(mytool mytool.cpp)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Commands such as \fBadd_custom_command()\fP, which generates rules to be

run at build time can transparently use an \fBEXECUTABLE\fP

target as a \fBCOMMAND\fP executable.  The buildsystem rules will ensure that

the executable is built before attempting to run the command.

.SS Binary Library Types

.SS Normal Libraries

.sp

By default, the \fBadd_library()\fP command defines a static library,

unless a type is specified.  A type may be specified when using the command:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)

.ft P

.fi

.UNINDENT

.UNINDENT

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

The \fBBUILD_SHARED_LIBS\fP variable may be enabled to change the

behavior of \fBadd_library()\fP to build shared libraries by default.

.sp

In the context of the buildsystem definition as a whole, it is largely

irrelevant whether particular libraries are \fBSHARED\fP or \fBSTATIC\fP \-\-

the commands, dependency specifications and other APIs work similarly

regardless of the library type.  The \fBMODULE\fP library type is

dissimilar in that it is generally not linked to \-\- it is not used in

the right\-hand\-side of the \fBtarget_link_libraries()\fP command.

It is a type which is loaded as a plugin using runtime techniques.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_library(archive MODULE 7z.cpp)

.ft P

.fi

.UNINDENT

.UNINDENT

.SS Object Libraries

.sp

The \fBOBJECT\fP 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:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

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)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

\fBOBJECT\fP 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

\fBtarget_link_libraries()\fP\&.  They also may not be used as the \fBTARGET\fP

in a use of the \fBadd_custom_command(TARGET)\fP command signature.

.sp

Although object libraries may not be named directly in calls to

the \fBtarget_link_libraries()\fP command, they can be "linked"

indirectly by using an \fI\%Interface Library\fP

whose \fBINTERFACE_SOURCES\fP target property is set to name

\fB$<TARGET_OBJECTS:objlib>\fP\&.

.SH BUILD SPECIFICATION AND USAGE REQUIREMENTS

.sp

The \fBtarget_include_directories()\fP, \fBtarget_compile_definitions()\fP

and \fBtarget_compile_options()\fP commands specify the build specifications

and the usage requirements of binary targets.  The commands populate the

\fBINCLUDE_DIRECTORIES\fP, \fBCOMPILE_DEFINITIONS\fP and

\fBCOMPILE_OPTIONS\fP target properties respectively, and/or the

\fBINTERFACE_INCLUDE_DIRECTORIES\fP, \fBINTERFACE_COMPILE_DEFINITIONS\fP

and \fBINTERFACE_COMPILE_OPTIONS\fP target properties.

.sp

Each of the commands has a \fBPRIVATE\fP, \fBPUBLIC\fP and \fBINTERFACE\fP mode.  The

\fBPRIVATE\fP mode populates only the non\-\fBINTERFACE_\fP variant of the target

property and the \fBINTERFACE\fP mode populates only the \fBINTERFACE_\fP variants.

The \fBPUBLIC\fP mode populates both variants of the repective target property.

Each command may be invoked with multiple uses of each keyword:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

target_compile_definitions(archive

  PRIVATE BUILDING_WITH_LZMA

  INTERFACE USING_ARCHIVE_LIB

)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Note that usage requirements are not designed as a way to make downstreams

use particular \fBCOMPILE_OPTIONS\fP or

\fBCOMPILE_DEFINITIONS\fP etc for convenience only.  The contents of

the properties must be \fBrequirements\fP, not merely recommendations or

convenience.

.sp

See the Creating Relocatable Packages section of the

\fBcmake\-packages(7)\fP manual for discussion of additional care

that must be taken when specifying usage requirements while creating

packages for redistribution.

.SS Target Properties

.sp

The contents of the \fBINCLUDE_DIRECTORIES\fP,

\fBCOMPILE_DEFINITIONS\fP and \fBCOMPILE_OPTIONS\fP target

properties are used appropriately when compiling the source files of a

binary target.

.sp

Entries in the \fBINCLUDE_DIRECTORIES\fP are added to the compile line

with \fB\-I\fP or \fB\-isystem\fP prefixes and in the order of appearance in the

property value.

.sp

Entries in the \fBCOMPILE_DEFINITIONS\fP are prefixed with \fB\-D\fP or

\fB/D\fP and added to the compile line in an unspecified order.  The

\fBDEFINE_SYMBOL\fP target property is also added as a compile

definition as a special convenience case for \fBSHARED\fP and \fBMODULE\fP

library targets.

.sp

Entries in the \fBCOMPILE_OPTIONS\fP 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 \fBPOSITION_INDEPENDENT_CODE\fP\&.

.sp

The contents of the \fBINTERFACE_INCLUDE_DIRECTORIES\fP,

\fBINTERFACE_COMPILE_DEFINITIONS\fP and

\fBINTERFACE_COMPILE_OPTIONS\fP target properties are

\fIUsage Requirements\fP \-\- 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 \fBINTERFACE_\fP property on

each target specified in a \fBtarget_link_libraries()\fP command is

consumed:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

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)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Because it is common to require that the source directory and corresponding

build directory are added to the \fBINCLUDE_DIRECTORIES\fP, the

\fBCMAKE_INCLUDE_CURRENT_DIR\fP variable can be enabled to conveniently

add the corresponding directories to the \fBINCLUDE_DIRECTORIES\fP of

all targets.  The variable \fBCMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE\fP

can be enabled to add the corresponding directories to the

\fBINTERFACE_INCLUDE_DIRECTORIES\fP of all targets.  This makes use of

targets in multiple different directories convenient through use of the

\fBtarget_link_libraries()\fP command.

.SS Transitive Usage Requirements

.sp

The usage requirements of a target can transitively propagate to dependents.

The \fBtarget_link_libraries()\fP command has \fBPRIVATE\fP,

\fBINTERFACE\fP and \fBPUBLIC\fP keywords to control the propagation.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

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)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Because \fBarchive\fP is a \fBPUBLIC\fP dependency of \fBarchiveExtras\fP, the

usage requirements of it are propagated to \fBconsumer\fP too.  Because

\fBserialization\fP is a \fBPRIVATE\fP dependency of \fBarchive\fP, the usage

requirements of it are not propagated to \fBconsumer\fP\&.

.sp

Generally, a dependency should be specified in a use of

\fBtarget_link_libraries()\fP with the \fBPRIVATE\fP 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 \fBPUBLIC\fP dependency.

A dependency which is not used by the implementation of a library, but only by

its headers should be specified as an \fBINTERFACE\fP dependency.  The

\fBtarget_link_libraries()\fP command may be invoked with multiple uses of

each keyword:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

target_link_libraries(archiveExtras

  PUBLIC archive

  PRIVATE serialization

)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Usage requirements are propagated by reading the \fBINTERFACE_\fP variants

of target properties from dependencies and appending the values to the

non\-\fBINTERFACE_\fP variants of the operand.  For example, the

\fBINTERFACE_INCLUDE_DIRECTORIES\fP of dependencies is read and

appended to the \fBINCLUDE_DIRECTORIES\fP of the operand.  In cases

where order is relevant and maintained, and the order resulting from the

\fBtarget_link_libraries()\fP calls does not allow correct compilation,

use of an appropriate command to set the property directly may update the

order.

.sp

For example, if the linked libraries for a target must be specified

in the order \fBlib1\fP \fBlib2\fP \fBlib3\fP , but the include directories must

be specified in the order \fBlib3\fP \fBlib1\fP \fBlib2\fP:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

target_link_libraries(myExe lib1 lib2 lib3)

target_include_directories(myExe

  PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Note that care must be taken when specifying usage requirements for targets

which will be exported for installation using the \fBinstall(EXPORT)\fP

command.  See Creating Packages for more.

.SS Compatible Interface Properties

.sp

Some target properties are required to be compatible between a target and

the interface of each dependency.  For example, the

\fBPOSITION_INDEPENDENT_CODE\fP 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

\fBINTERFACE_POSITION_INDEPENDENT_CODE\fP to communicate that

consumers must be compiled as position\-independent\-code.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

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)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Here, both \fBexe1\fP and \fBexe2\fP will be compiled as position\-independent\-code.

\fBlib1\fP will also be compiled as position\-independent\-code because that is the

default setting for \fBSHARED\fP libraries.  If dependencies have conflicting,

non\-compatible requirements \fBcmake(1)\fP issues a diagnostic:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

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)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

The \fBlib1\fP requirement \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP is not

"compatible" with the \fBPOSITION_INDEPENDENT_CODE\fP property of the \fBexe1\fP

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.

.sp

The \fBlib1\fP and \fBlib2\fP 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 \fBexe2\fP links to both and they are in conflict, a diagnostic is

issued.

.sp

To be "compatible", the \fBPOSITION_INDEPENDENT_CODE\fP property,

if set must be either the same, in a boolean sense, as the

\fBINTERFACE_POSITION_INDEPENDENT_CODE\fP property of all transitively

specified dependencies on which that property is set.

.sp

This property of "compatible interface requirement" may be extended to other

properties by specifying the property in the content of the

\fBCOMPATIBLE_INTERFACE_BOOL\fP target property.  Each specified property

must be compatible between the consuming target and the corresponding property

with an \fBINTERFACE_\fP prefix from each dependency:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

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

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Non\-boolean properties may also participate in "compatible interface"

computations.  Properties specified in the

\fBCOMPATIBLE_INTERFACE_STRING\fP

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:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

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

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

The \fBCOMPATIBLE_INTERFACE_NUMBER_MAX\fP target property specifies

that content will be evaluated numerically and the maximum number among all

specified will be calculated:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

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)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Similarly, the \fBCOMPATIBLE_INTERFACE_NUMBER_MIN\fP may be used to

calculate the numeric minimum value for a property from dependencies.

.sp

Each calculated "compatible" property value may be read in the consumer at

generate\-time using generator expressions.

.sp

Note that for each dependee, the set of properties specified in each

compatible interface property must not intersect with the set specified in

any of the other properties.

.SS Property Origin Debugging

.sp

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.

\fBcmake(1)\fP 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 listed in the

\fBCMAKE_DEBUG_TARGET_PROPERTIES\fP variable documentation:

.INDENT 0.0

.INDENT 3.5

.sp

.nf