1 .\" Man page generated from reStructuredText.

     2 .

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

     4 .SH NAME

     5 cmake-buildsystem \- CMake Buildsystem Reference

     6 .

     7 .nr rst2man-indent-level 0

     8 .

     9 .de1 rstReportMargin

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

    11 level \\n[rst2man-indent-level]

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

    13 -

    14 \\n[rst2man-indent0]

    15 \\n[rst2man-indent1]

    16 \\n[rst2man-indent2]

    17 ..

    18 .de1 INDENT

    19 .\" .rstReportMargin pre:

    20 . RS \\$1

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

    22 . nr rst2man-indent-level +1

    23 .\" .rstReportMargin post:

    24 ..

    25 .de UNINDENT

    26 . RE

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

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

    29 .nr rst2man-indent-level -1

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

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

    32 ..

    33 .SH INTRODUCTION

    34 .sp

    35 A CMake\-based buildsystem is organized as a set of high\-level logical

    36 targets.  Each target corresponds to an executable or library, or

    37 is a custom target containing custom commands.  Dependencies between the

    38 targets are expressed in the buildsystem to determine the build order

    39 and the rules for regeneration in response to change.

    40 .SH BINARY TARGETS

    41 .sp

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

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

    44 appropriate prefixes, suffixes and extensions for the platform targeted.

    45 Dependencies between binary targets are expressed using the

    46 \fBtarget_link_libraries()\fP command:

    47 .INDENT 0.0

    48 .INDENT 3.5

    49 .sp

    50 .nf

    51 .ft C

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

    53 add_executable(zipapp zipapp.cpp)

    54 target_link_libraries(zipapp archive)

    55 .ft P

    56 .fi

    57 .UNINDENT

    58 .UNINDENT

    59 .sp

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

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

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

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

    64 linked in.

    65 .SS Binary Executables

    66 .sp

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

    68 .INDENT 0.0

    69 .INDENT 3.5

    70 .sp

    71 .nf

    72 .ft C

    73 add_executable(mytool mytool.cpp)

    74 .ft P

    75 .fi

    76 .UNINDENT

    77 .UNINDENT

    78 .sp

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

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

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

    82 the executable is built before attempting to run the command.

    83 .SS Binary Library Types

    84 .SS Normal Libraries

    85 .sp

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

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

    88 .INDENT 0.0

    89 .INDENT 3.5

    90 .sp

    91 .nf

    92 .ft C

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

    94 .ft P

    95 .fi

    96 .UNINDENT

    97 .UNINDENT

    98 .INDENT 0.0

    99 .INDENT 3.5

   100 .sp

   101 .nf

   102 .ft C

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

   104 .ft P

   105 .fi

   106 .UNINDENT

   107 .UNINDENT

   108 .sp

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

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

   111 .sp

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

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

   114 the commands, dependency specifications and other APIs work similarly

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

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

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

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

   119 .INDENT 0.0

   120 .INDENT 3.5

   121 .sp

   122 .nf

   123 .ft C

   124 add_library(archive MODULE 7z.cpp)

   125 .ft P

   126 .fi

   127 .UNINDENT

   128 .UNINDENT

   129 .SS Object Libraries

   130 .sp

   131 The \fBOBJECT\fP library type is also not linked to. It defines a non\-archival

   132 collection of object files resulting from compiling the given source files.

   133 The object files collection can be used as source inputs to other targets:

   134 .INDENT 0.0

   135 .INDENT 3.5

   136 .sp

   137 .nf

   138 .ft C

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

   140 

   141 add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)

   142 

   143 add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)

   144 .ft P

   145 .fi

   146 .UNINDENT

   147 .UNINDENT

   148 .sp

   149 \fBOBJECT\fP libraries may only be used locally as sources in a buildsystem \-\-

   150 they may not be installed, exported, or used in the right hand side of

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

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

   153 .sp

   154 Although object libraries may not be named directly in calls to

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

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

   157 whose \fBINTERFACE_SOURCES\fP target property is set to name

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

   159 .SH BUILD SPECIFICATION AND USAGE REQUIREMENTS

   160 .sp

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

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

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

   164 \fBINCLUDE_DIRECTORIES\fP, \fBCOMPILE_DEFINITIONS\fP and

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

   166 \fBINTERFACE_INCLUDE_DIRECTORIES\fP, \fBINTERFACE_COMPILE_DEFINITIONS\fP

   167 and \fBINTERFACE_COMPILE_OPTIONS\fP target properties.

   168 .sp

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

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

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

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

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

   174 .INDENT 0.0

   175 .INDENT 3.5

   176 .sp

   177 .nf

   178 .ft C

   179 target_compile_definitions(archive

   180   PRIVATE BUILDING_WITH_LZMA

   181   INTERFACE USING_ARCHIVE_LIB

   182 )

   183 .ft P

   184 .fi

   185 .UNINDENT

   186 .UNINDENT

   187 .sp

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

   189 use particular \fBCOMPILE_OPTIONS\fP or

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

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

   192 convenience.

   193 .sp

   194 See the Creating Relocatable Packages section of the

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

   196 that must be taken when specifying usage requirements while creating

   197 packages for redistribution.

   198 .SS Target Properties

   199 .sp

   200 The contents of the \fBINCLUDE_DIRECTORIES\fP,

   201 \fBCOMPILE_DEFINITIONS\fP and \fBCOMPILE_OPTIONS\fP target

   202 properties are used appropriately when compiling the source files of a

   203 binary target.

   204 .sp

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

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

   207 property value.

   208 .sp

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

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

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

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

   213 library targets.

   214 .sp

   215 Entries in the \fBCOMPILE_OPTIONS\fP are escaped for the shell and added

   216 in the order of appearance in the property value.  Several compile options have

   217 special separate handling, such as \fBPOSITION_INDEPENDENT_CODE\fP\&.

   218 .sp

   219 The contents of the \fBINTERFACE_INCLUDE_DIRECTORIES\fP,

   220 \fBINTERFACE_COMPILE_DEFINITIONS\fP and

   221 \fBINTERFACE_COMPILE_OPTIONS\fP target properties are

   222 \fIUsage Requirements\fP \-\- they specify content which consumers

   223 must use to correctly compile and link with the target they appear on.

   224 For any binary target, the contents of each \fBINTERFACE_\fP property on

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

   226 consumed:

   227 .INDENT 0.0

   228 .INDENT 3.5

   229 .sp

   230 .nf

   231 .ft C

   232 set(srcs archive.cpp zip.cpp)

   233 if (LZMA_FOUND)

   234   list(APPEND srcs lzma.cpp)

   235 endif()

   236 add_library(archive SHARED ${srcs})

   237 if (LZMA_FOUND)

   238   # The archive library sources are compiled with \-DBUILDING_WITH_LZMA

   239   target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)

   240 endif()

   241 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)

   242 

   243 add_executable(consumer)

   244 # Link consumer to archive and consume its usage requirements. The consumer

   245 # executable sources are compiled with \-DUSING_ARCHIVE_LIB.

   246 target_link_libraries(consumer archive)

   247 .ft P

   248 .fi

   249 .UNINDENT

   250 .UNINDENT

   251 .sp

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

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

   254 \fBCMAKE_INCLUDE_CURRENT_DIR\fP variable can be enabled to conveniently

   255 add the corresponding directories to the \fBINCLUDE_DIRECTORIES\fP of

   256 all targets.  The variable \fBCMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE\fP

   257 can be enabled to add the corresponding directories to the

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

   259 targets in multiple different directories convenient through use of the

   260 \fBtarget_link_libraries()\fP command.

   261 .SS Transitive Usage Requirements

   262 .sp

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

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

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

   266 .INDENT 0.0

   267 .INDENT 3.5

   268 .sp

   269 .nf

   270 .ft C

   271 add_library(archive archive.cpp)

   272 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)

   273 

   274 add_library(serialization serialization.cpp)

   275 target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)

   276 

   277 add_library(archiveExtras extras.cpp)

   278 target_link_libraries(archiveExtras PUBLIC archive)

   279 target_link_libraries(archiveExtras PRIVATE serialization)

   280 # archiveExtras is compiled with \-DUSING_ARCHIVE_LIB

   281 # and \-DUSING_SERIALIZATION_LIB

   282 

   283 add_executable(consumer consumer.cpp)

   284 # consumer is compiled with \-DUSING_ARCHIVE_LIB

   285 target_link_libraries(consumer archiveExtras)

   286 .ft P

   287 .fi

   288 .UNINDENT

   289 .UNINDENT

   290 .sp

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

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

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

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

   295 .sp

   296 Generally, a dependency should be specified in a use of

   297 \fBtarget_link_libraries()\fP with the \fBPRIVATE\fP keyword if it is used by

   298 only the implementation of a library, and not in the header files.  If a

   299 dependency is additionally used in the header files of a library (e.g. for

   300 class inheritance), then it should be specified as a \fBPUBLIC\fP dependency.

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

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

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

   304 each keyword:

   305 .INDENT 0.0

   306 .INDENT 3.5

   307 .sp

   308 .nf

   309 .ft C

   310 target_link_libraries(archiveExtras

   311   PUBLIC archive

   312   PRIVATE serialization

   313 )

   314 .ft P

   315 .fi

   316 .UNINDENT

   317 .UNINDENT

   318 .sp

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

   320 of target properties from dependencies and appending the values to the

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

   322 \fBINTERFACE_INCLUDE_DIRECTORIES\fP of dependencies is read and

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

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

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

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

   327 order.

   328 .sp

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

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

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

   332 .INDENT 0.0

   333 .INDENT 3.5

   334 .sp

   335 .nf

   336 .ft C

   337 target_link_libraries(myExe lib1 lib2 lib3)

   338 target_include_directories(myExe

   339   PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)

   340 .ft P

   341 .fi

   342 .UNINDENT

   343 .UNINDENT

   344 .sp

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

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

   347 command.  See Creating Packages for more.

   348 .SS Compatible Interface Properties

   349 .sp

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

   351 the interface of each dependency.  For example, the

   352 \fBPOSITION_INDEPENDENT_CODE\fP target property may specify a

   353 boolean value of whether a target should be compiled as

   354 position\-independent\-code, which has platform\-specific consequences.

   355 A target may also specify the usage requirement

   356 \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP to communicate that

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

   358 .INDENT 0.0

   359 .INDENT 3.5

   360 .sp

   361 .nf

   362 .ft C

   363 add_executable(exe1 exe1.cpp)

   364 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)

   365 

   366 add_library(lib1 SHARED lib1.cpp)

   367 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

   368 

   369 add_executable(exe2 exe2.cpp)

   370 target_link_libraries(exe2 lib1)

   371 .ft P

   372 .fi

   373 .UNINDENT

   374 .UNINDENT

   375 .sp

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

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

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

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

   380 .INDENT 0.0

   381 .INDENT 3.5

   382 .sp

   383 .nf

   384 .ft C

   385 add_library(lib1 SHARED lib1.cpp)

   386 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

   387 

   388 add_library(lib2 SHARED lib2.cpp)

   389 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)

   390 

   391 add_executable(exe1 exe1.cpp)

   392 target_link_libraries(exe1 lib1)

   393 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)

   394 

   395 add_executable(exe2 exe2.cpp)

   396 target_link_libraries(exe2 lib1 lib2)

   397 .ft P

   398 .fi

   399 .UNINDENT

   400 .UNINDENT

   401 .sp

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

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

   404 target.  The library requires that consumers are built as

   405 position\-independent\-code, while the executable specifies to not built as

   406 position\-independent\-code, so a diagnostic is issued.

   407 .sp

   408 The \fBlib1\fP and \fBlib2\fP requirements are not "compatible".  One of them

   409 requires that consumers are built as position\-independent\-code, while

   410 the other requires that consumers are not built as position\-independent\-code.

   411 Because \fBexe2\fP links to both and they are in conflict, a diagnostic is

   412 issued.

   413 .sp

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

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

   416 \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP property of all transitively

   417 specified dependencies on which that property is set.

   418 .sp

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

   420 properties by specifying the property in the content of the

   421 \fBCOMPATIBLE_INTERFACE_BOOL\fP target property.  Each specified property

   422 must be compatible between the consuming target and the corresponding property

   423 with an \fBINTERFACE_\fP prefix from each dependency:

   424 .INDENT 0.0

   425 .INDENT 3.5

   426 .sp

   427 .nf

   428 .ft C

   429 add_library(lib1Version2 SHARED lib1_v2.cpp)

   430 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)

   431 set_property(TARGET lib1Version2 APPEND PROPERTY

   432   COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP

   433 )

   434 

   435 add_library(lib1Version3 SHARED lib1_v3.cpp)

   436 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)

   437 

   438 add_executable(exe1 exe1.cpp)

   439 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON

   440 

   441 add_executable(exe2 exe2.cpp)

   442 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic

   443 .ft P

   444 .fi

   445 .UNINDENT

   446 .UNINDENT

   447 .sp

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

   449 computations.  Properties specified in the

   450 \fBCOMPATIBLE_INTERFACE_STRING\fP

   451 property must be either unspecified or compare to the same string among

   452 all transitively specified dependencies. This can be useful to ensure

   453 that multiple incompatible versions of a library are not linked together

   454 through transitive requirements of a target:

   455 .INDENT 0.0

   456 .INDENT 3.5

   457 .sp

   458 .nf

   459 .ft C

   460 add_library(lib1Version2 SHARED lib1_v2.cpp)

   461 set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)

   462 set_property(TARGET lib1Version2 APPEND PROPERTY

   463   COMPATIBLE_INTERFACE_STRING LIB_VERSION

   464 )

   465 

   466 add_library(lib1Version3 SHARED lib1_v3.cpp)

   467 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)

   468 

   469 add_executable(exe1 exe1.cpp)

   470 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"

   471 

   472 add_executable(exe2 exe2.cpp)

   473 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic

   474 .ft P

   475 .fi

   476 .UNINDENT

   477 .UNINDENT

   478 .sp

   479 The \fBCOMPATIBLE_INTERFACE_NUMBER_MAX\fP target property specifies

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

   481 specified will be calculated:

   482 .INDENT 0.0

   483 .INDENT 3.5

   484 .sp

   485 .nf

   486 .ft C

   487 add_library(lib1Version2 SHARED lib1_v2.cpp)

   488 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)

   489 set_property(TARGET lib1Version2 APPEND PROPERTY

   490   COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED

   491 )

   492 

   493 add_library(lib1Version3 SHARED lib1_v3.cpp)

   494 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)

   495 

   496 add_executable(exe1 exe1.cpp)

   497 # CONTAINER_SIZE_REQUIRED will be "200"

   498 target_link_libraries(exe1 lib1Version2)

   499 

   500 add_executable(exe2 exe2.cpp)

   501 # CONTAINER_SIZE_REQUIRED will be "1000"

   502 target_link_libraries(exe2 lib1Version2 lib1Version3)

   503 .ft P

   504 .fi

   505 .UNINDENT

   506 .UNINDENT

   507 .sp

   508 Similarly, the \fBCOMPATIBLE_INTERFACE_NUMBER_MIN\fP may be used to

   509 calculate the numeric minimum value for a property from dependencies.

   510 .sp

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

   512 generate\-time using generator expressions.

   513 .sp

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

   515 compatible interface property must not intersect with the set specified in

   516 any of the other properties.

   517 .SS Property Origin Debugging

   518 .sp

   519 Because build specifications can be determined by dependencies, the lack of

   520 locality of code which creates a target and code which is responsible for

   521 setting build specifications may make the code more difficult to reason about.

   522 \fBcmake(1)\fP provides a debugging facility to print the origin of the

   523 contents of properties which may be determined by dependencies.  The properties

   524 which can be debugged are listed in the

   525 \fBCMAKE_DEBUG_TARGET_PROPERTIES\fP variable documentation:

   526 .INDENT 0.0

   527 .INDENT 3.5

   528 .sp

   529 .nf

   530 .ft C

   531 set(CMAKE_DEBUG_TARGET_PROPERTIES

   532   INCLUDE_DIRECTORIES

   533   COMPILE_DEFINITIONS

   534   POSITION_INDEPENDENT_CODE

   535   CONTAINER_SIZE_REQUIRED

   536   LIB_VERSION

   537 )

   538 add_executable(exe1 exe1.cpp)

   539 .ft P

   540 .fi

   541 .UNINDENT

   542 .UNINDENT

   543 .sp

   544 In the case of properties listed in \fBCOMPATIBLE_INTERFACE_BOOL\fP or

   545 \fBCOMPATIBLE_INTERFACE_STRING\fP, the debug output shows which target

   546 was responsible for setting the property, and which other dependencies also

   547 defined the property.  In the case of

   548 \fBCOMPATIBLE_INTERFACE_NUMBER_MAX\fP and

   549 \fBCOMPATIBLE_INTERFACE_NUMBER_MIN\fP, the debug output shows the

   550 value of the property from each dependency, and whether the value determines

   551 the new extreme.

   552 .SS Build Specification with Generator Expressions

   553 .sp

   554 Build specifications may use

   555 \fBgenerator expressions\fP containing

   556 content which may be conditional or known only at generate\-time.  For example,

   557 the calculated "compatible" value of a property may be read with the

   558 \fBTARGET_PROPERTY\fP expression:

   559 .INDENT 0.0

   560 .INDENT 3.5

   561 .sp

   562 .nf

   563 .ft C

   564 add_library(lib1Version2 SHARED lib1_v2.cpp)

   565 set_property(TARGET lib1Version2 PROPERTY

   566   INTERFACE_CONTAINER_SIZE_REQUIRED 200)

   567 set_property(TARGET lib1Version2 APPEND PROPERTY

   568   COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED

   569 )

   570 

   571 add_executable(exe1 exe1.cpp)

   572 target_link_libraries(exe1 lib1Version2)

   573 target_compile_definitions(exe1 PRIVATE

   574     CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>

   575 )

   576 .ft P

   577 .fi

   578 .UNINDENT

   579 .UNINDENT

   580 .sp

   581 In this case, the \fBexe1\fP source files will be compiled with

   582 \fB\-DCONTAINER_SIZE=200\fP\&.

   583 .sp

   584 Configuration determined build specifications may be conveniently set using

   585 the \fBCONFIG\fP generator expression.

   586 .INDENT 0.0

   587 .INDENT 3.5

   588 .sp

   589 .nf

   590 .ft C

   591 target_compile_definitions(exe1 PRIVATE

   592     $<$<CONFIG:Debug>:DEBUG_BUILD>

   593 )

   594 .ft P

   595 .fi

   596 .UNINDENT

   597 .UNINDENT

   598 .sp

   599 The \fBCONFIG\fP parameter is compared case\-insensitively with the configuration

   600 being built.  In the presence of \fBIMPORTED\fP targets, the content of

   601 \fBMAP_IMPORTED_CONFIG_DEBUG\fP is also

   602 accounted for by this expression.

   603 .sp

   604 Some buildsystems generated by \fBcmake(1)\fP have a predetermined

   605 build\-configuration set in the \fBCMAKE_BUILD_TYPE\fP variable.  The

   606 buildsystem for the IDEs such as Visual Studio and Xcode are generated

   607 independent of the build\-configuration, and the actual build configuration

   608 is not known until build\-time.  Therefore, code such as

   609 .INDENT 0.0

   610 .INDENT 3.5

   611 .sp

   612 .nf

   613 .ft C

   614 string(TOLOWER ${CMAKE_BUILD_TYPE} _type)

   615 if (_type STREQUAL debug)

   616   target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)

   617 endif()

   618 .ft P

   619 .fi

   620 .UNINDENT

   621 .UNINDENT

   622 .sp

   623 may appear to work for \fBMakefile\fP based and \fBNinja\fP generators, but is not

   624 portable to IDE generators.  Additionally, the \fBIMPORTED\fP

   625 configuration\-mappings are not accounted for with code like this, so it should

   626 be avoided.

   627 .sp

   628 The unary \fBTARGET_PROPERTY\fP generator expression and the \fBTARGET_POLICY\fP

   629 generator expression are evaluated with the consuming target context.  This

   630 means that a usage requirement specification may be evaluated differently based

   631 on the consumer:

   632 .INDENT 0.0

   633 .INDENT 3.5

   634 .sp

   635 .nf

   636 .ft C

   637 add_library(lib1 lib1.cpp)

   638 target_compile_definitions(lib1 INTERFACE

   639   $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>

   640   $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>

   641   $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>

   642 )

   643 

   644 add_executable(exe1 exe1.cpp)

   645 target_link_libraries(exe1 lib1)

   646 

   647 cmake_policy(SET CMP0041 NEW)

   648 

   649 add_library(shared_lib shared_lib.cpp)

   650 target_link_libraries(shared_lib lib1)

   651 .ft P

   652 .fi

   653 .UNINDENT

   654 .UNINDENT

   655 .sp

   656 The \fBexe1\fP executable will be compiled with \fB\-DLIB1_WITH_EXE\fP, while the

   657 \fBshared_lib\fP shared library will be compiled with \fB\-DLIB1_WITH_SHARED_LIB\fP

   658 and \fB\-DCONSUMER_CMP0041_NEW\fP, because policy \fBCMP0041\fP is

   659 \fBNEW\fP at the point where the \fBshared_lib\fP target is created.

   660 .sp

   661 The \fBBUILD_INTERFACE\fP expression wraps requirements which are only used when

   662 consumed from a target in the same buildsystem, or when consumed from a target

   663 exported to the build directory using the \fBexport()\fP command.  The

   664 \fBINSTALL_INTERFACE\fP expression wraps requirements which are only used when

   665 consumed from a target which has been installed and exported with the

   666 \fBinstall(EXPORT)\fP command:

   667 .INDENT 0.0

   668 .INDENT 3.5

   669 .sp

   670 .nf

   671 .ft C

   672 add_library(ClimbingStats climbingstats.cpp)

   673 target_compile_definitions(ClimbingStats INTERFACE

   674   $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>

   675   $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>

   676 )

   677 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})

   678 install(EXPORT libExport NAMESPACE Upstream::

   679         DESTINATION lib/cmake/ClimbingStats)

   680 export(EXPORT libExport NAMESPACE Upstream::)

   681 

   682 add_executable(exe1 exe1.cpp)

   683 target_link_libraries(exe1 ClimbingStats)

   684 .ft P

   685 .fi

   686 .UNINDENT

   687 .UNINDENT

   688 .sp

   689 In this case, the \fBexe1\fP executable will be compiled with

   690 \fB\-DClimbingStats_FROM_BUILD_LOCATION\fP\&.  The exporting commands generate

   691 \fBIMPORTED\fP targets with either the \fBINSTALL_INTERFACE\fP or the

   692 \fBBUILD_INTERFACE\fP omitted, and the \fB*_INTERFACE\fP marker stripped away.

   693 A separate project consuming the \fBClimbingStats\fP package would contain:

   694 .INDENT 0.0

   695 .INDENT 3.5

   696 .sp

   697 .nf

   698 .ft C

   699 find_package(ClimbingStats REQUIRED)

   700 

   701 add_executable(Downstream main.cpp)

   702 target_link_libraries(Downstream Upstream::ClimbingStats)

   703 .ft P

   704 .fi

   705 .UNINDENT

   706 .UNINDENT

   707 .sp

   708 Depending on whether the \fBClimbingStats\fP package was used from the build

   709 location or the install location, the \fBDownstream\fP target would be compiled

   710 with either \fB\-DClimbingStats_FROM_BUILD_LOCATION\fP or

   711 \fB\-DClimbingStats_FROM_INSTALL_LOCATION\fP\&.  For more about packages and

   712 exporting see the \fBcmake\-packages(7)\fP manual.

   713 .SS Include Directories and Usage Requirements

   714 .sp

   715 Include directories require some special consideration when specified as usage

   716 requirements and when used with generator expressions.  The

   717 \fBtarget_include_directories()\fP command accepts both relative and

   718 absolute include directories:

   719 .INDENT 0.0

   720 .INDENT 3.5

   721 .sp

   722 .nf

   723 .ft C

   724 add_library(lib1 lib1.cpp)

   725 target_include_directories(lib1 PRIVATE

   726   /absolute/path

   727   relative/path

   728 )

   729 .ft P

   730 .fi

   731 .UNINDENT

   732 .UNINDENT

   733 .sp

   734 Relative paths are interpreted relative to the source directory where the

   735 command appears.  Relative paths are not allowed in the

   736 \fBINTERFACE_INCLUDE_DIRECTORIES\fP of \fBIMPORTED\fP targets.

   737 .sp

   738 In cases where a non\-trivial generator expression is used, the

   739 \fBINSTALL_PREFIX\fP expression may be used within the argument of an

   740 \fBINSTALL_INTERFACE\fP expression.  It is a replacement marker which

   741 expands to the installation prefix when imported by a consuming project.

   742 .sp

   743 Include directories usage requirements commonly differ between the build\-tree

   744 and the install\-tree.  The \fBBUILD_INTERFACE\fP and \fBINSTALL_INTERFACE\fP

   745 generator expressions can be used to describe separate usage requirements

   746 based on the usage location.  Relative paths are allowed within the

   747 \fBINSTALL_INTERFACE\fP expression and are interpreted relative to the

   748 installation prefix.  For example:

   749 .INDENT 0.0

   750 .INDENT 3.5

   751 .sp

   752 .nf

   753 .ft C

   754 add_library(ClimbingStats climbingstats.cpp)

   755 target_include_directories(ClimbingStats INTERFACE

   756   $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>

   757   $<INSTALL_INTERFACE:/absolute/path>

   758   $<INSTALL_INTERFACE:relative/path>

   759   $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>

   760 )

   761 .ft P

   762 .fi

   763 .UNINDENT

   764 .UNINDENT

   765 .sp

   766 Two convenience APIs are provided relating to include directories usage

   767 requirements.  The \fBCMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE\fP variable

   768 may be enabled, with an equivalent effect to:

   769 .INDENT 0.0

   770 .INDENT 3.5

   771 .sp

   772 .nf

   773 .ft C

   774 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES

   775   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>

   776 )

   777 .ft P

   778 .fi

   779 .UNINDENT

   780 .UNINDENT

   781 .sp

   782 for each target affected.  The convenience for installed targets is

   783 an \fBINCLUDES DESTINATION\fP component with the \fBinstall(TARGETS)\fP

   784 command:

   785 .INDENT 0.0

   786 .INDENT 3.5

   787 .sp

   788 .nf

   789 .ft C

   790 install(TARGETS foo bar bat EXPORT tgts ${dest_args}

   791   INCLUDES DESTINATION include

   792 )

   793 install(EXPORT tgts ${other_args})

   794 install(FILES ${headers} DESTINATION include)

   795 .ft P

   796 .fi

   797 .UNINDENT

   798 .UNINDENT

   799 .sp

   800 This is equivalent to appending \fB${CMAKE_INSTALL_PREFIX}/include\fP to the

   801 \fBINTERFACE_INCLUDE_DIRECTORIES\fP of each of the installed

   802 \fBIMPORTED\fP targets when generated by \fBinstall(EXPORT)\fP\&.

   803 .sp

   804 When the \fBINTERFACE_INCLUDE_DIRECTORIES\fP of an

   805 \fI\%imported target\fP is consumed, the entries in the

   806 property are treated as \fBSYSTEM\fP include directories, as if they were

   807 listed in the \fBINTERFACE_SYSTEM_INCLUDE_DIRECTORIES\fP of the

   808 dependency. This can result in omission of compiler warnings for headers

   809 found in those directories.  This behavior for \fI\%Imported Targets\fP may

   810 be controlled with the \fBNO_SYSTEM_FROM_IMPORTED\fP target property.

   811 .sp

   812 If a binary target is linked transitively to a Mac OX framework, the

   813 \fBHeaders\fP directory of the framework is also treated as a usage requirement.

   814 This has the same effect as passing the framework directory as an include

   815 directory.

   816 .SS Link Libraries and Generator Expressions

   817 .sp

   818 Like build specifications, \fBlink libraries\fP may be

   819 specified with generator expression conditions.  However, as consumption of

   820 usage requirements is based on collection from linked dependencies, there is

   821 an additional limitation that the link dependencies must form a "directed

   822 acyclic graph".  That is, if linking to a target is dependent on the value of

   823 a target property, that target property may not be dependent on the linked

   824 dependencies:

   825 .INDENT 0.0

   826 .INDENT 3.5

   827 .sp

   828 .nf

   829 .ft C

   830 add_library(lib1 lib1.cpp)

   831 add_library(lib2 lib2.cpp)

   832 target_link_libraries(lib1 PUBLIC

   833   $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>

   834 )

   835 add_library(lib3 lib3.cpp)

   836 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

   837 

   838 add_executable(exe1 exe1.cpp)

   839 target_link_libraries(exe1 lib1 lib3)

   840 .ft P

   841 .fi

   842 .UNINDENT

   843 .UNINDENT

   844 .sp

   845 As the value of the \fBPOSITION_INDEPENDENT_CODE\fP property of

   846 the \fBexe1\fP target is dependent on the linked libraries (\fBlib3\fP), and the

   847 edge of linking \fBexe1\fP is determined by the same

   848 \fBPOSITION_INDEPENDENT_CODE\fP property, the dependency graph above

   849 contains a cycle.  \fBcmake(1)\fP issues a diagnostic in this case.

   850 .SS Output Artifacts

   851 .sp

   852 The buildsystem targets created by the \fBadd_library()\fP and

   853 \fBadd_executable()\fP commands create rules to create binary outputs.

   854 The exact output location of the binaries can only be determined at

   855 generate\-time because it can depend on the build\-configuration and the

   856 link\-language of linked dependencies etc.  \fBTARGET_FILE\fP,

   857 \fBTARGET_LINKER_FILE\fP and related expressions can be used to access the

   858 name and location of generated binaries.  These expressions do not work

   859 for \fBOBJECT\fP libraries however, as there is no single file generated

   860 by such libraries which is relevant to the expressions.

   861 .sp

   862 There are three kinds of output artifacts that may be build by targets

   863 as detailed in the following sections.  Their classification differs

   864 between DLL platforms and non\-DLL platforms.  All Windows\-based

   865 systems including Cygwin are DLL platforms.

   866 .SS Runtime Output Artifacts

   867 .sp

   868 A \fIruntime\fP output artifact of a buildsystem target may be:

   869 .INDENT 0.0

   870 .IP \(bu 2

   871 The executable file (e.g. \fB\&.exe\fP) of an executable target

   872 created by the \fBadd_executable()\fP command.

   873 .IP \(bu 2

   874 On DLL platforms: the executable file (e.g. \fB\&.dll\fP) of a shared

   875 library target created by the \fBadd_library()\fP command

   876 with the \fBSHARED\fP option.

   877 .UNINDENT

   878 .sp

   879 The \fBRUNTIME_OUTPUT_DIRECTORY\fP and \fBRUNTIME_OUTPUT_NAME\fP

   880 target properties may be used to control runtime output artifact locations

   881 and names in the build tree.

   882 .SS Library Output Artifacts

   883 .sp

   884 A \fIlibrary\fP output artifact of a buildsystem target may be:

   885 .INDENT 0.0

   886 .IP \(bu 2

   887 The loadable module file (e.g. \fB\&.dll\fP or \fB\&.so\fP) of a module

   888 library target created by the \fBadd_library()\fP command

   889 with the \fBMODULE\fP option.

   890 .IP \(bu 2

   891 On non\-DLL platforms: the shared library file (e.g. \fB\&.so\fP or \fB\&.dylib\fP)

   892 of a shared shared library target created by the \fBadd_library()\fP

   893 command with the \fBSHARED\fP option.

   894 .UNINDENT

   895 .sp

   896 The \fBLIBRARY_OUTPUT_DIRECTORY\fP and \fBLIBRARY_OUTPUT_NAME\fP

   897 target properties may be used to control library output artifact locations

   898 and names in the build tree.

   899 .SS Archive Output Artifacts

   900 .sp

   901 An \fIarchive\fP output artifact of a buildsystem target may be:

   902 .INDENT 0.0

   903 .IP \(bu 2

   904 The static library file (e.g. \fB\&.lib\fP or \fB\&.a\fP) of a static

   905 library target created by the \fBadd_library()\fP command

   906 with the \fBSTATIC\fP option.

   907 .IP \(bu 2

   908 On DLL platforms: the import library file (e.g. \fB\&.lib\fP) of a shared

   909 library target created by the \fBadd_library()\fP command

   910 with the \fBSHARED\fP option.

   911 .IP \(bu 2

   912 On DLL platforms: the import library file (e.g. \fB\&.lib\fP) of an

   913 executable target created by the \fBadd_executable()\fP command

   914 when its \fBENABLE_EXPORTS\fP target property is set.

   915 .UNINDENT

   916 .sp

   917 The \fBARCHIVE_OUTPUT_DIRECTORY\fP and \fBARCHIVE_OUTPUT_NAME\fP

   918 target properties may be used to control archive output artifact locations

   919 and names in the build tree.

   920 .SS Directory\-Scoped Commands

   921 .sp

   922 The \fBtarget_include_directories()\fP,

   923 \fBtarget_compile_definitions()\fP and

   924 \fBtarget_compile_options()\fP commands have an effect on only one

   925 target at a time.  The commands \fBadd_definitions()\fP,

   926 \fBadd_compile_options()\fP and \fBinclude_directories()\fP have

   927 a similar function, but operate at directory scope instead of target

   928 scope for convenience.

   929 .SH PSEUDO TARGETS

   930 .sp

   931 Some target types do not represent outputs of the buildsystem, but only inputs

   932 such as external dependencies, aliases or other non\-build artifacts.  Pseudo

   933 targets are not represented in the generated buildsystem.

   934 .SS Imported Targets

   935 .sp

   936 An \fBIMPORTED\fP target represents a pre\-existing dependency.  Usually

   937 such targets are defined by an upstream package and should be treated as

   938 immutable.  It is not possible to use an \fBIMPORTED\fP target in the

   939 left\-hand\-side of the \fBtarget_compile_definitions()\fP,

   940 \fBtarget_include_directories()\fP, \fBtarget_compile_options()\fP or

   941 \fBtarget_link_libraries()\fP commands, as that would be an attempt to

   942 modify it.  \fBIMPORTED\fP targets are designed to be used only in the

   943 right\-hand\-side of those commands.

   944 .sp

   945 \fBIMPORTED\fP targets may have the same usage requirement properties

   946 populated as binary targets, such as

   947 \fBINTERFACE_INCLUDE_DIRECTORIES\fP,

   948 \fBINTERFACE_COMPILE_DEFINITIONS\fP,

   949 \fBINTERFACE_COMPILE_OPTIONS\fP,

   950 \fBINTERFACE_LINK_LIBRARIES\fP, and

   951 \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP\&.

   952 .sp

   953 The \fBLOCATION\fP may also be read from an IMPORTED target, though there

   954 is rarely reason to do so.  Commands such as \fBadd_custom_command()\fP can

   955 transparently use an \fBIMPORTED\fP \fBEXECUTABLE\fP target

   956 as a \fBCOMMAND\fP executable.

   957 .sp

   958 The scope of the definition of an \fBIMPORTED\fP target is the directory

   959 where it was defined.  It may be accessed and used from subdirectories, but

   960 not from parent directories or sibling directories.  The scope is similar to

   961 the scope of a cmake variable.

   962 .sp

   963 It is also possible to define a \fBGLOBAL\fP \fBIMPORTED\fP target which is

   964 accessible globally in the buildsystem.

   965 .sp

   966 See the \fBcmake\-packages(7)\fP manual for more on creating packages

   967 with \fBIMPORTED\fP targets.

   968 .SS Alias Targets

   969 .sp

   970 An \fBALIAS\fP target is a name which may be used interchangably with

   971 a binary target name in read\-only contexts.  A primary use\-case for \fBALIAS\fP

   972 targets is for example or unit test executables accompanying a library, which

   973 may be part of the same buildsystem or built separately based on user

   974 configuration.

   975 .INDENT 0.0

   976 .INDENT 3.5

   977 .sp

   978 .nf

   979 .ft C

   980 add_library(lib1 lib1.cpp)

   981 install(TARGETS lib1 EXPORT lib1Export ${dest_args})

   982 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})

   983 

   984 add_library(Upstream::lib1 ALIAS lib1)

   985 .ft P

   986 .fi

   987 .UNINDENT

   988 .UNINDENT

   989 .sp

   990 In another directory, we can link unconditionally to the \fBUpstream::lib1\fP

   991 target, which may be an \fBIMPORTED\fP target from a package, or an

   992 \fBALIAS\fP target if built as part of the same buildsystem.

   993 .INDENT 0.0

   994 .INDENT 3.5

   995 .sp

   996 .nf

   997 .ft C

   998 if (NOT TARGET Upstream::lib1)

   999   find_package(lib1 REQUIRED)

  1000 endif()

  1001 add_executable(exe1 exe1.cpp)

  1002 target_link_libraries(exe1 Upstream::lib1)

  1003 .ft P

  1004 .fi

  1005 .UNINDENT

  1006 .UNINDENT

  1007 .sp

  1008 \fBALIAS\fP targets are not mutable, installable or exportable.  They are

  1009 entirely local to the buildsystem description.  A name can be tested for

  1010 whether it is an \fBALIAS\fP name by reading the \fBALIASED_TARGET\fP

  1011 property from it:

  1012 .INDENT 0.0

  1013 .INDENT 3.5

  1014 .sp

  1015 .nf

  1016 .ft C

  1017 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)

  1018 if(_aliased)

  1019   message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")

  1020 endif()

  1021 .ft P

  1022 .fi

  1023 .UNINDENT

  1024 .UNINDENT

  1025 .SS Interface Libraries

  1026 .sp

  1027 An \fBINTERFACE\fP target has no \fBLOCATION\fP and is mutable, but is

  1028 otherwise similar to an \fBIMPORTED\fP target.

  1029 .sp

  1030 It may specify usage requirements such as

  1031 \fBINTERFACE_INCLUDE_DIRECTORIES\fP,

  1032 \fBINTERFACE_COMPILE_DEFINITIONS\fP,

  1033 \fBINTERFACE_COMPILE_OPTIONS\fP,

  1034 \fBINTERFACE_LINK_LIBRARIES\fP,

  1035 \fBINTERFACE_SOURCES\fP,

  1036 and \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP\&.

  1037 Only the \fBINTERFACE\fP modes of the \fBtarget_include_directories()\fP,

  1038 \fBtarget_compile_definitions()\fP, \fBtarget_compile_options()\fP,

  1039 \fBtarget_sources()\fP, and \fBtarget_link_libraries()\fP commands

  1040 may be used with \fBINTERFACE\fP libraries.

  1041 .sp

  1042 A primary use\-case for \fBINTERFACE\fP libraries is header\-only libraries.

  1043 .INDENT 0.0

  1044 .INDENT 3.5

  1045 .sp

  1046 .nf

  1047 .ft C

  1048 add_library(Eigen INTERFACE)

  1049 target_include_directories(Eigen INTERFACE

  1050   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>

  1051   $<INSTALL_INTERFACE:include/Eigen>

  1052 )

  1053 

  1054 add_executable(exe1 exe1.cpp)

  1055 target_link_libraries(exe1 Eigen)

  1056 .ft P

  1057 .fi

  1058 .UNINDENT

  1059 .UNINDENT

  1060 .sp

  1061 Here, the usage requirements from the \fBEigen\fP target are consumed and used

  1062 when compiling, but it has no effect on linking.

  1063 .sp

  1064 Another use\-case is to employ an entirely target\-focussed design for usage

  1065 requirements:

  1066 .INDENT 0.0

  1067 .INDENT 3.5

  1068 .sp

  1069 .nf

  1070 .ft C

  1071 add_library(pic_on INTERFACE)

  1072 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

  1073 add_library(pic_off INTERFACE)

  1074 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)

  1075 

  1076 add_library(enable_rtti INTERFACE)

  1077 target_compile_options(enable_rtti INTERFACE

  1078   $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:\-rtti>

  1079 )

  1080 

  1081 add_executable(exe1 exe1.cpp)

  1082 target_link_libraries(exe1 pic_on enable_rtti)

  1083 .ft P

  1084 .fi

  1085 .UNINDENT

  1086 .UNINDENT

  1087 .sp

  1088 This way, the build specification of \fBexe1\fP is expressed entirely as linked

  1089 targets, and the complexity of compiler\-specific flags is encapsulated in an

  1090 \fBINTERFACE\fP library target.

  1091 .sp

  1092 The properties permitted to be set on or read from an \fBINTERFACE\fP library

  1093 are:

  1094 .INDENT 0.0

  1095 .IP \(bu 2

  1096 Properties matching \fBINTERFACE_*\fP

  1097 .IP \(bu 2

  1098 Built\-in properties matching \fBCOMPATIBLE_INTERFACE_*\fP

  1099 .IP \(bu 2

  1100 \fBEXPORT_NAME\fP

  1101 .IP \(bu 2

  1102 \fBIMPORTED\fP

  1103 .IP \(bu 2

  1104 \fBNAME\fP

  1105 .IP \(bu 2

  1106 Properties matching \fBMAP_IMPORTED_CONFIG_*\fP

  1107 .UNINDENT

  1108 .sp

  1109 \fBINTERFACE\fP libraries may be installed and exported.  Any content they refer

  1110 to must be installed separately:

  1111 .INDENT 0.0

  1112 .INDENT 3.5

  1113 .sp

  1114 .nf

  1115 .ft C

  1116 add_library(Eigen INTERFACE)

  1117 target_include_directories(Eigen INTERFACE

  1118   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>

  1119   $<INSTALL_INTERFACE:include/Eigen>

  1120 )

  1121 

  1122 install(TARGETS Eigen EXPORT eigenExport)

  1123 install(EXPORT eigenExport NAMESPACE Upstream::

  1124   DESTINATION lib/cmake/Eigen

  1125 )

  1126 install(FILES

  1127     ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h

  1128     ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h

  1129     ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h

  1130   DESTINATION include/Eigen

  1131 )

  1132 .ft P

  1133 .fi

  1134 .UNINDENT

  1135 .UNINDENT