1CMAKE-BUILDSYSTEM(7)                 CMake                CMAKE-BUILDSYSTEM(7)
2
3
4

NAME

6       cmake-buildsystem - CMake Buildsystem Reference
7

INTRODUCTION

9       A  CMake-based  buildsystem is organized as a set of high-level logical
10       targets.  Each target corresponds to an executable or library, or is  a
11       custom  target  containing  custom  commands.  Dependencies between the
12       targets are expressed in the buildsystem to determine the  build  order
13       and the rules for regeneration in response to change.
14

BINARY TARGETS

16       Executables  and  libraries  are defined using the add_executable() and
17       add_library() commands.  The resulting binary  files  have  appropriate
18       PREFIX,  SUFFIX  and extensions for the platform targeted. Dependencies
19       between binary targets are expressed using the  target_link_libraries()
20       command:
21
22          add_library(archive archive.cpp zip.cpp lzma.cpp)
23          add_executable(zipapp zipapp.cpp)
24          target_link_libraries(zipapp archive)
25
26       archive is defined as a STATIC library -- an archive containing objects
27       compiled from archive.cpp, zip.cpp, and lzma.cpp.  zipapp is defined as
28       an executable formed by compiling and linking zipapp.cpp.  When linking
29       the zipapp executable, the archive static library is linked in.
30
31   Binary Executables
32       The add_executable() command defines an executable target:
33
34          add_executable(mytool mytool.cpp)
35
36       Commands such as add_custom_command(), which generates rules to be  run
37       at  build  time can transparently use an EXECUTABLE target as a COMMAND
38       executable.  The buildsystem rules will ensure that the  executable  is
39       built before attempting to run the command.
40
41   Binary Library Types
42   Normal Libraries
43       By  default, the add_library() command defines a STATIC library, unless
44       a type is specified.  A type may be specified when using the command:
45
46          add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)
47
48          add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
49
50       The BUILD_SHARED_LIBS variable may be enabled to change the behavior of
51       add_library() to build shared libraries by default.
52
53       In  the context of the buildsystem definition as a whole, it is largely
54       irrelevant whether particular libraries are SHARED  or  STATIC  --  the
55       commands,  dependency  specifications and other APIs work similarly re‐
56       gardless of the library type.  The MODULE library type is dissimilar in
57       that  it  is  generally  not  linked  to  --  it  is  not  used  in the
58       right-hand-side of the target_link_libraries() command.  It is  a  type
59       which  is  loaded as a plugin using runtime techniques.  If the library
60       does not export any  unmanaged  symbols  (e.g.  Windows  resource  DLL,
61       C++/CLI  DLL),  it is required that the library not be a SHARED library
62       because CMake expects SHARED libraries to export at least one symbol.
63
64          add_library(archive MODULE 7z.cpp)
65
66   Apple Frameworks
67       A SHARED library may be marked with the FRAMEWORK  target  property  to
68       create  an macOS or iOS Framework Bundle.  A library with the FRAMEWORK
69       target property should also set the FRAMEWORK_VERSION target  property.
70       This  property  is  typically  set to the value of "A" by macOS conven‐
71       tions.  The MACOSX_FRAMEWORK_IDENTIFIER sets the CFBundleIdentifier key
72       and it uniquely identifies the bundle.
73
74          add_library(MyFramework SHARED MyFramework.cpp)
75          set_target_properties(MyFramework PROPERTIES
76            FRAMEWORK TRUE
77            FRAMEWORK_VERSION A # Version "A" is macOS convention
78            MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
79          )
80
81   Object Libraries
82       The  OBJECT  library  type  defines a non-archival collection of object
83       files resulting from compiling the  given  source  files.   The  object
84       files collection may be used as source inputs to other targets by using
85       the syntax $<TARGET_OBJECTS:name>.  This is a generator expression that
86       can be used to supply the OBJECT library content to other targets:
87
88          add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
89
90          add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
91
92          add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
93
94       The link (or archiving) step of those other targets will use the object
95       files collection in addition to those from their own sources.
96
97       Alternatively, object libraries may be linked into other targets:
98
99          add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
100
101          add_library(archiveExtras STATIC extras.cpp)
102          target_link_libraries(archiveExtras PUBLIC archive)
103
104          add_executable(test_exe test.cpp)
105          target_link_libraries(test_exe archive)
106
107       The link (or archiving) step of those other targets will use the object
108       files  from  OBJECT  libraries that are directly linked.  Additionally,
109       usage requirements of the OBJECT libraries will be honored when compil‐
110       ing  sources in those other targets.  Furthermore, those usage require‐
111       ments will propagate transitively to dependents of those other targets.
112
113       Object libraries may not be  used  as  the  TARGET  in  a  use  of  the
114       add_custom_command(TARGET) command signature.  However, the list of ob‐
115       jects can be used by add_custom_command(OUTPUT)  or  file(GENERATE)  by
116       using $<TARGET_OBJECTS:objlib>.
117

BUILD SPECIFICATION AND USAGE REQUIREMENTS

119       The   target_include_directories(),   target_compile_definitions()  and
120       target_compile_options() commands specify the build specifications  and
121       the  usage  requirements  of binary targets.  The commands populate the
122       INCLUDE_DIRECTORIES,  COMPILE_DEFINITIONS  and  COMPILE_OPTIONS  target
123       properties   respectively,  and/or  the  INTERFACE_INCLUDE_DIRECTORIES,
124       INTERFACE_COMPILE_DEFINITIONS  and   INTERFACE_COMPILE_OPTIONS   target
125       properties.
126
127       Each  of  the  commands  has a PRIVATE, PUBLIC and INTERFACE mode.  The
128       PRIVATE mode populates only the non-INTERFACE_ variant  of  the  target
129       property and the INTERFACE mode populates only the INTERFACE_ variants.
130       The PUBLIC mode populates both variants of the respective target  prop‐
131       erty.  Each command may be invoked with multiple uses of each keyword:
132
133          target_compile_definitions(archive
134            PRIVATE BUILDING_WITH_LZMA
135            INTERFACE USING_ARCHIVE_LIB
136          )
137
138       Note  that  usage  requirements are not designed as a way to make down‐
139       streams use particular COMPILE_OPTIONS or COMPILE_DEFINITIONS  etc  for
140       convenience only.  The contents of the properties must be requirements,
141       not merely recommendations or convenience.
142
143       See the Creating Relocatable Packages section of the  cmake-packages(7)
144       manual for discussion of additional care that must be taken when speci‐
145       fying usage requirements while creating packages for redistribution.
146
147   Target Properties
148       The  contents  of  the  INCLUDE_DIRECTORIES,  COMPILE_DEFINITIONS   and
149       COMPILE_OPTIONS target properties are used appropriately when compiling
150       the source files of a binary target.
151
152       Entries in the INCLUDE_DIRECTORIES are added to the compile  line  with
153       -I  or -isystem prefixes and in the order of appearance in the property
154       value.
155
156       Entries in the COMPILE_DEFINITIONS are prefixed with -D or /D and added
157       to  the compile line in an unspecified order.  The DEFINE_SYMBOL target
158       property is also added as a compile definition as a special convenience
159       case for SHARED and MODULE library targets.
160
161       Entries  in  the COMPILE_OPTIONS are escaped for the shell and added in
162       the order of appearance in the property value.  Several compile options
163       have special separate handling, such as POSITION_INDEPENDENT_CODE.
164
165       The       contents      of      the      INTERFACE_INCLUDE_DIRECTORIES,
166       INTERFACE_COMPILE_DEFINITIONS  and   INTERFACE_COMPILE_OPTIONS   target
167       properties  are  Usage  Requirements -- they specify content which con‐
168       sumers must use to correctly compile and link with the target they  ap‐
169       pear  on.  For any binary target, the contents of each INTERFACE_ prop‐
170       erty on each target specified in a target_link_libraries()  command  is
171       consumed:
172
173          set(srcs archive.cpp zip.cpp)
174          if (LZMA_FOUND)
175            list(APPEND srcs lzma.cpp)
176          endif()
177          add_library(archive SHARED ${srcs})
178          if (LZMA_FOUND)
179            # The archive library sources are compiled with -DBUILDING_WITH_LZMA
180            target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
181          endif()
182          target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
183
184          add_executable(consumer)
185          # Link consumer to archive and consume its usage requirements. The consumer
186          # executable sources are compiled with -DUSING_ARCHIVE_LIB.
187          target_link_libraries(consumer archive)
188
189       Because  it  is  common to require that the source directory and corre‐
190       sponding build directory are  added  to  the  INCLUDE_DIRECTORIES,  the
191       CMAKE_INCLUDE_CURRENT_DIR  variable  can be enabled to conveniently add
192       the corresponding directories to the INCLUDE_DIRECTORIES  of  all  tar‐
193       gets.   The  variable CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE can be en‐
194       abled    to    add    the    corresponding    directories    to     the
195       INTERFACE_INCLUDE_DIRECTORIES  of  all targets.  This makes use of tar‐
196       gets in multiple different directories convenient through  use  of  the
197       target_link_libraries() command.
198
199   Transitive Usage Requirements
200       The  usage  requirements  of a target can transitively propagate to the
201       dependents.  The target_link_libraries() command has PRIVATE, INTERFACE
202       and PUBLIC keywords to control the propagation.
203
204          add_library(archive archive.cpp)
205          target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
206
207          add_library(serialization serialization.cpp)
208          target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
209
210          add_library(archiveExtras extras.cpp)
211          target_link_libraries(archiveExtras PUBLIC archive)
212          target_link_libraries(archiveExtras PRIVATE serialization)
213          # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
214          # and -DUSING_SERIALIZATION_LIB
215
216          add_executable(consumer consumer.cpp)
217          # consumer is compiled with -DUSING_ARCHIVE_LIB
218          target_link_libraries(consumer archiveExtras)
219
220       Because  the archive is a PUBLIC dependency of archiveExtras, the usage
221       requirements of it are propagated to consumer too.
222
223       Because serialization is a PRIVATE dependency of archiveExtras, the us‐
224       age requirements of it are not propagated to consumer.
225
226       Generally,   a   dependency   should   be   specified   in   a  use  of
227       target_link_libraries() with the PRIVATE keyword if it is used by  only
228       the implementation of a library, and not in the header files.  If a de‐
229       pendency is additionally used in the header files of  a  library  (e.g.
230       for  class inheritance), then it should be specified as a PUBLIC depen‐
231       dency.  A dependency which is not used by the implementation of  a  li‐
232       brary,  but only by its headers should be specified as an INTERFACE de‐
233       pendency.  The target_link_libraries() command may be invoked with mul‐
234       tiple uses of each keyword:
235
236          target_link_libraries(archiveExtras
237            PUBLIC archive
238            PRIVATE serialization
239          )
240
241       Usage requirements are propagated by reading the INTERFACE_ variants of
242       target properties from dependencies and appending  the  values  to  the
243       non-INTERFACE_   variants   of   the   operand.    For   example,   the
244       INTERFACE_INCLUDE_DIRECTORIES of dependencies is read and  appended  to
245       the  INCLUDE_DIRECTORIES of the operand.  In cases where order is rele‐
246       vant   and   maintained,   and   the   order   resulting    from    the
247       target_link_libraries()  calls  does not allow correct compilation, use
248       of an appropriate command to set the property directly may  update  the
249       order.
250
251       For  example, if the linked libraries for a target must be specified in
252       the order lib1 lib2 lib3 , but the include directories must  be  speci‐
253       fied in the order lib3 lib1 lib2:
254
255          target_link_libraries(myExe lib1 lib2 lib3)
256          target_include_directories(myExe
257            PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
258
259       Note  that  care  must  be taken when specifying usage requirements for
260       targets  which  will   be   exported   for   installation   using   the
261       install(EXPORT) command.  See Creating Packages for more.
262
263   Compatible Interface Properties
264       Some  target  properties are required to be compatible between a target
265       and   the   interface   of   each   dependency.    For   example,   the
266       POSITION_INDEPENDENT_CODE  target  property may specify a boolean value
267       of whether a target should be  compiled  as  position-independent-code,
268       which  has  platform-specific  consequences.  A target may also specify
269       the usage requirement INTERFACE_POSITION_INDEPENDENT_CODE  to  communi‐
270       cate that consumers must be compiled as position-independent-code.
271
272          add_executable(exe1 exe1.cpp)
273          set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
274
275          add_library(lib1 SHARED lib1.cpp)
276          set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
277
278          add_executable(exe2 exe2.cpp)
279          target_link_libraries(exe2 lib1)
280
281       Here, both exe1 and exe2 will be compiled as position-independent-code.
282       lib1 will also be compiled as position-independent-code because that is
283       the  default  setting  for SHARED libraries.  If dependencies have con‐
284       flicting, non-compatible requirements cmake(1) issues a diagnostic:
285
286          add_library(lib1 SHARED lib1.cpp)
287          set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
288
289          add_library(lib2 SHARED lib2.cpp)
290          set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
291
292          add_executable(exe1 exe1.cpp)
293          target_link_libraries(exe1 lib1)
294          set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
295
296          add_executable(exe2 exe2.cpp)
297          target_link_libraries(exe2 lib1 lib2)
298
299       The lib1 requirement INTERFACE_POSITION_INDEPENDENT_CODE is  not  "com‐
300       patible"  with  the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
301       get.  The library requires that consumers are built  as  position-inde‐
302       pendent-code,  while  the  executable  specifies  to not built as posi‐
303       tion-independent-code, so a diagnostic is issued.
304
305       The lib1 and lib2 requirements are not "compatible".  One of  them  re‐
306       quires that consumers are built as position-independent-code, while the
307       other requires  that  consumers  are  not  built  as  position-indepen‐
308       dent-code.   Because  exe2  links  to  both and they are in conflict, a
309       CMake error message is issued:
310
311          CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
312          not agree with the value of POSITION_INDEPENDENT_CODE already determined
313          for "exe2".
314
315       To be "compatible", the POSITION_INDEPENDENT_CODE property, if set must
316       be    either    the    same,    in    a    boolean    sense,   as   the
317       INTERFACE_POSITION_INDEPENDENT_CODE property of all transitively speci‐
318       fied dependencies on which that property is set.
319
320       This  property of "compatible interface requirement" may be extended to
321       other properties by specifying the  property  in  the  content  of  the
322       COMPATIBLE_INTERFACE_BOOL  target  property.   Each  specified property
323       must be compatible between the consuming target and  the  corresponding
324       property with an INTERFACE_ prefix from each dependency:
325
326          add_library(lib1Version2 SHARED lib1_v2.cpp)
327          set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
328          set_property(TARGET lib1Version2 APPEND PROPERTY
329            COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
330          )
331
332          add_library(lib1Version3 SHARED lib1_v3.cpp)
333          set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
334
335          add_executable(exe1 exe1.cpp)
336          target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
337
338          add_executable(exe2 exe2.cpp)
339          target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
340
341       Non-boolean  properties  may also participate in "compatible interface"
342       computations.  Properties specified in the  COMPATIBLE_INTERFACE_STRING
343       property must be either unspecified or compare to the same string among
344       all transitively specified dependencies. This can be useful  to  ensure
345       that  multiple  incompatible  versions  of a library are not linked to‐
346       gether through transitive requirements of a target:
347
348          add_library(lib1Version2 SHARED lib1_v2.cpp)
349          set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
350          set_property(TARGET lib1Version2 APPEND PROPERTY
351            COMPATIBLE_INTERFACE_STRING LIB_VERSION
352          )
353
354          add_library(lib1Version3 SHARED lib1_v3.cpp)
355          set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
356
357          add_executable(exe1 exe1.cpp)
358          target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
359
360          add_executable(exe2 exe2.cpp)
361          target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
362
363       The COMPATIBLE_INTERFACE_NUMBER_MAX target property specifies that con‐
364       tent  will  be  evaluated  numerically and the maximum number among all
365       specified will be calculated:
366
367          add_library(lib1Version2 SHARED lib1_v2.cpp)
368          set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
369          set_property(TARGET lib1Version2 APPEND PROPERTY
370            COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
371          )
372
373          add_library(lib1Version3 SHARED lib1_v3.cpp)
374          set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
375
376          add_executable(exe1 exe1.cpp)
377          # CONTAINER_SIZE_REQUIRED will be "200"
378          target_link_libraries(exe1 lib1Version2)
379
380          add_executable(exe2 exe2.cpp)
381          # CONTAINER_SIZE_REQUIRED will be "1000"
382          target_link_libraries(exe2 lib1Version2 lib1Version3)
383
384       Similarly, the COMPATIBLE_INTERFACE_NUMBER_MIN may be used to calculate
385       the numeric minimum value for a property from dependencies.
386
387       Each calculated "compatible" property value may be read in the consumer
388       at generate-time using generator expressions.
389
390       Note that for each dependee, the set of properties  specified  in  each
391       compatible interface property must not intersect with the set specified
392       in any of the other properties.
393
394   Property Origin Debugging
395       Because build specifications can be  determined  by  dependencies,  the
396       lack  of  locality of code which creates a target and code which is re‐
397       sponsible for setting build specifications may make the code more  dif‐
398       ficult  to  reason  about.   cmake(1)  provides a debugging facility to
399       print the origin of the contents of properties which may be  determined
400       by  dependencies.   The  properties which can be debugged are listed in
401       the CMAKE_DEBUG_TARGET_PROPERTIES variable documentation:
402
403          set(CMAKE_DEBUG_TARGET_PROPERTIES
404            INCLUDE_DIRECTORIES
405            COMPILE_DEFINITIONS
406            POSITION_INDEPENDENT_CODE
407            CONTAINER_SIZE_REQUIRED
408            LIB_VERSION
409          )
410          add_executable(exe1 exe1.cpp)
411
412       In the  case  of  properties  listed  in  COMPATIBLE_INTERFACE_BOOL  or
413       COMPATIBLE_INTERFACE_STRING,  the  debug  output shows which target was
414       responsible for setting the property, and which other dependencies also
415       defined  the  property.  In the case of COMPATIBLE_INTERFACE_NUMBER_MAX
416       and COMPATIBLE_INTERFACE_NUMBER_MIN, the debug output shows  the  value
417       of  the property from each dependency, and whether the value determines
418       the new extreme.
419
420   Build Specification with Generator Expressions
421       Build specifications may use generator expressions  containing  content
422       which  may be conditional or known only at generate-time.  For example,
423       the calculated "compatible" value of a property may be  read  with  the
424       TARGET_PROPERTY expression:
425
426          add_library(lib1Version2 SHARED lib1_v2.cpp)
427          set_property(TARGET lib1Version2 PROPERTY
428            INTERFACE_CONTAINER_SIZE_REQUIRED 200)
429          set_property(TARGET lib1Version2 APPEND PROPERTY
430            COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
431          )
432
433          add_executable(exe1 exe1.cpp)
434          target_link_libraries(exe1 lib1Version2)
435          target_compile_definitions(exe1 PRIVATE
436              CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
437          )
438
439       In  this  case,  the  exe1  source  files  will be compiled with -DCON‐
440       TAINER_SIZE=200.
441
442       The unary TARGET_PROPERTY generator expression  and  the  TARGET_POLICY
443       generator  expression  are evaluated with the consuming target context.
444       This means that a usage requirement specification may be evaluated dif‐
445       ferently based on the consumer:
446
447          add_library(lib1 lib1.cpp)
448          target_compile_definitions(lib1 INTERFACE
449            $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
450            $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
451            $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
452          )
453
454          add_executable(exe1 exe1.cpp)
455          target_link_libraries(exe1 lib1)
456
457          cmake_policy(SET CMP0041 NEW)
458
459          add_library(shared_lib shared_lib.cpp)
460          target_link_libraries(shared_lib lib1)
461
462       The  exe1  executable  will be compiled with -DLIB1_WITH_EXE, while the
463       shared_lib shared library will be compiled with  -DLIB1_WITH_SHARED_LIB
464       and  -DCONSUMER_CMP0041_NEW, because policy CMP0041 is NEW at the point
465       where the shared_lib target is created.
466
467       The BUILD_INTERFACE expression wraps requirements which are  only  used
468       when  consumed  from a target in the same buildsystem, or when consumed
469       from a target exported to the build directory using the  export()  com‐
470       mand.   The  INSTALL_INTERFACE  expression wraps requirements which are
471       only used when consumed from a target which has been installed and  ex‐
472       ported with the install(EXPORT) command:
473
474          add_library(ClimbingStats climbingstats.cpp)
475          target_compile_definitions(ClimbingStats INTERFACE
476            $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
477            $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
478          )
479          install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
480          install(EXPORT libExport NAMESPACE Upstream::
481                  DESTINATION lib/cmake/ClimbingStats)
482          export(EXPORT libExport NAMESPACE Upstream::)
483
484          add_executable(exe1 exe1.cpp)
485          target_link_libraries(exe1 ClimbingStats)
486
487       In  this  case,  the  exe1  executable  will  be compiled with -DClimb‐
488       ingStats_FROM_BUILD_LOCATION.  The exporting commands generate IMPORTED
489       targets  with either the INSTALL_INTERFACE or the BUILD_INTERFACE omit‐
490       ted, and the *_INTERFACE marker stripped away.  A separate project con‐
491       suming the ClimbingStats package would contain:
492
493          find_package(ClimbingStats REQUIRED)
494
495          add_executable(Downstream main.cpp)
496          target_link_libraries(Downstream Upstream::ClimbingStats)
497
498       Depending  on whether the ClimbingStats package was used from the build
499       location or the install location, the Downstream target would  be  com‐
500       piled   with  either  -DClimbingStats_FROM_BUILD_LOCATION  or  -DClimb‐
501       ingStats_FROM_INSTALL_LOCATION.  For more about packages and  exporting
502       see the cmake-packages(7) manual.
503
504   Include Directories and Usage Requirements
505       Include  directories  require some special consideration when specified
506       as usage requirements and when used with  generator  expressions.   The
507       target_include_directories() command accepts both relative and absolute
508       include directories:
509
510          add_library(lib1 lib1.cpp)
511          target_include_directories(lib1 PRIVATE
512            /absolute/path
513            relative/path
514          )
515
516       Relative paths are interpreted relative to the source  directory  where
517       the   command   appears.    Relative  paths  are  not  allowed  in  the
518       INTERFACE_INCLUDE_DIRECTORIES of IMPORTED targets.
519
520       In cases where a non-trivial generator  expression  is  used,  the  IN‐
521       STALL_PREFIX  expression  may  be  used  within  the argument of an IN‐
522       STALL_INTERFACE expression.  It is a replacement marker  which  expands
523       to the installation prefix when imported by a consuming project.
524
525       Include  directories  usage  requirements  commonly  differ between the
526       build-tree and the install-tree.  The BUILD_INTERFACE  and  INSTALL_IN‐
527       TERFACE  generator  expressions  can be used to describe separate usage
528       requirements based on the usage location.  Relative paths  are  allowed
529       within the INSTALL_INTERFACE expression and are interpreted relative to
530       the installation prefix.  For example:
531
532          add_library(ClimbingStats climbingstats.cpp)
533          target_include_directories(ClimbingStats INTERFACE
534            $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
535            $<INSTALL_INTERFACE:/absolute/path>
536            $<INSTALL_INTERFACE:relative/path>
537            $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
538          )
539
540       Two convenience APIs are provided relating to include directories usage
541       requirements.   The CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE variable may
542       be enabled, with an equivalent effect to:
543
544          set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
545            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
546          )
547
548       for each target affected.  The convenience for installed targets is  an
549       INCLUDES DESTINATION component with the install(TARGETS) command:
550
551          install(TARGETS foo bar bat EXPORT tgts ${dest_args}
552            INCLUDES DESTINATION include
553          )
554          install(EXPORT tgts ${other_args})
555          install(FILES ${headers} DESTINATION include)
556
557       This  is equivalent to appending ${CMAKE_INSTALL_PREFIX}/include to the
558       INTERFACE_INCLUDE_DIRECTORIES of each of the installed IMPORTED targets
559       when generated by install(EXPORT).
560
561       When  the  INTERFACE_INCLUDE_DIRECTORIES  of an imported target is con‐
562       sumed, the entries in the property may be treated as system include di‐
563       rectories.  The effects of that are toolchain-dependent, but one common
564       effect is to omit compiler warnings for headers found in those directo‐
565       ries.   The SYSTEM property of the installed target determines this be‐
566       havior (see the EXPORT_NO_SYSTEM property for how  to  modify  the  in‐
567       stalled  value  for  a target).  It is also possible to change how con‐
568       sumers interpret the system behavior of consumed  imported  targets  by
569       setting the NO_SYSTEM_FROM_IMPORTED target property on the consumer.
570
571       If  a  binary  target  is linked transitively to a macOS FRAMEWORK, the
572       Headers directory of the framework is also treated as a usage  require‐
573       ment.   This  has the same effect as passing the framework directory as
574       an include directory.
575
576   Link Libraries and Generator Expressions
577       Like build specifications, link libraries may be specified with genera‐
578       tor  expression  conditions.  However, as consumption of usage require‐
579       ments is based on collection from linked dependencies, there is an  ad‐
580       ditional  limitation  that  the link dependencies must form a "directed
581       acyclic graph".  That is, if linking to a target is  dependent  on  the
582       value  of  a target property, that target property may not be dependent
583       on the linked dependencies:
584
585          add_library(lib1 lib1.cpp)
586          add_library(lib2 lib2.cpp)
587          target_link_libraries(lib1 PUBLIC
588            $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
589          )
590          add_library(lib3 lib3.cpp)
591          set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
592
593          add_executable(exe1 exe1.cpp)
594          target_link_libraries(exe1 lib1 lib3)
595
596       As the value of the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
597       get  is dependent on the linked libraries (lib3), and the edge of link‐
598       ing exe1 is determined by the same POSITION_INDEPENDENT_CODE  property,
599       the  dependency graph above contains a cycle.  cmake(1) issues an error
600       message.
601
602   Output Artifacts
603       The   buildsystem   targets   created   by   the   add_library()    and
604       add_executable()  commands  create rules to create binary outputs.  The
605       exact output location of the binaries can only be determined at  gener‐
606       ate-time  because  it  can  depend  on  the build-configuration and the
607       link-language  of   linked   dependencies   etc.    TARGET_FILE,   TAR‐
608       GET_LINKER_FILE  and related expressions can be used to access the name
609       and location of generated binaries.  These expressions do not work  for
610       OBJECT  libraries however, as there is no single file generated by such
611       libraries which is relevant to the expressions.
612
613       There are three kinds of output artifacts that may be build by  targets
614       as  detailed  in  the following sections.  Their classification differs
615       between DLL platforms and non-DLL platforms.  All Windows-based systems
616       including Cygwin are DLL platforms.
617
618   Runtime Output Artifacts
619       A runtime output artifact of a buildsystem target may be:
620
621       • The  executable  file  (e.g. .exe) of an executable target created by
622         the add_executable() command.
623
624       • On DLL platforms: the executable file (e.g. .dll) of a shared library
625         target created by the add_library() command with the SHARED option.
626
627       The  RUNTIME_OUTPUT_DIRECTORY and RUNTIME_OUTPUT_NAME target properties
628       may be used to control runtime output artifact locations and  names  in
629       the build tree.
630
631   Library Output Artifacts
632       A library output artifact of a buildsystem target may be:
633
634       • The  loadable module file (e.g. .dll or .so) of a module library tar‐
635         get created by the add_library() command with the MODULE option.
636
637       • On non-DLL platforms: the shared library file (e.g. .so or .dylib) of
638         a shared library target created by the add_library() command with the
639         SHARED option.
640
641       The LIBRARY_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_NAME target  properties
642       may  be  used to control library output artifact locations and names in
643       the build tree.
644
645   Archive Output Artifacts
646       An archive output artifact of a buildsystem target may be:
647
648       • The static library file (e.g. .lib or .a) of a static library  target
649         created by the add_library() command with the STATIC option.
650
651       • On DLL platforms: the import library file (e.g. .lib) of a shared li‐
652         brary target created by the add_library() command with the SHARED op‐
653         tion.   This  file is only guaranteed to exist if the library exports
654         at least one unmanaged symbol.
655
656       • On DLL platforms: the import library file  (e.g.  .lib)  of  an  exe‐
657         cutable  target  created  by  the  add_executable()  command when its
658         ENABLE_EXPORTS target property is set.
659
660       • On AIX: the linker import file (e.g. .imp) of  an  executable  target
661         created  by the add_executable() command when its ENABLE_EXPORTS tar‐
662         get property is set.
663
664       • On macOS: the linker import file (e.g. .tbd) of a shared library tar‐
665         get  created  by the add_library() command with the SHARED option and
666         when its ENABLE_EXPORTS target property is set.
667
668       The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME target  properties
669       may  be  used to control archive output artifact locations and names in
670       the build tree.
671
672   Directory-Scoped Commands
673       The  target_include_directories(),   target_compile_definitions()   and
674       target_compile_options()  commands have an effect on only one target at
675       a time.  The commands add_compile_definitions(),  add_compile_options()
676       and  include_directories()  have a similar function, but operate at di‐
677       rectory scope instead of target scope for convenience.
678

BUILD CONFIGURATIONS

680       Configurations determine specifications for a certain  type  of  build,
681       such  as  Release  or  Debug.  The way this is specified depends on the
682       type of generator being used.  For single configuration generators like
683       Makefile  Generators  and Ninja, the configuration is specified at con‐
684       figure time by the CMAKE_BUILD_TYPE variable.  For  multi-configuration
685       generators  like Visual Studio, Xcode, and Ninja Multi-Config, the con‐
686       figuration is chosen by the user at build time and CMAKE_BUILD_TYPE  is
687       ignored.  In the multi-configuration case, the set of available config‐
688       urations    is    specified    at     configure     time     by     the
689       CMAKE_CONFIGURATION_TYPES  variable,  but the actual configuration used
690       cannot be known until the build stage.  This difference is often misun‐
691       derstood, leading to problematic code like the following:
692
693          # WARNING: This is wrong for multi-config generators because they don't use
694          #          and typically don't even set CMAKE_BUILD_TYPE
695          string(TOLOWER ${CMAKE_BUILD_TYPE} build_type)
696          if (build_type STREQUAL debug)
697            target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
698          endif()
699
700       Generator  expressions  should  be  used  instead  to handle configura‐
701       tion-specific logic correctly, regardless of the generator  used.   For
702       example:
703
704          # Works correctly for both single and multi-config generators
705          target_compile_definitions(exe1 PRIVATE
706            $<$<CONFIG:Debug>:DEBUG_BUILD>
707          )
708
709       In    the    presence    of    IMPORTED   targets,   the   content   of
710       MAP_IMPORTED_CONFIG_DEBUG  is  also  accounted   for   by   the   above
711       $<CONFIG:Debug> expression.
712
713   Case Sensitivity
714       CMAKE_BUILD_TYPE  and  CMAKE_CONFIGURATION_TYPES  are  just  like other
715       variables in that any string comparisons made with their values will be
716       case-sensitive.   The $<CONFIG> generator expression also preserves the
717       casing of the configuration as set by the user or CMake defaults.   For
718       example:
719
720          # NOTE: Don't use these patterns, they are for illustration purposes only.
721
722          set(CMAKE_BUILD_TYPE Debug)
723          if(CMAKE_BUILD_TYPE STREQUAL DEBUG)
724            # ... will never get here, "Debug" != "DEBUG"
725          endif()
726          add_custom_target(print_config ALL
727            # Prints "Config is Debug" in this single-config case
728            COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>"
729            VERBATIM
730          )
731
732          set(CMAKE_CONFIGURATION_TYPES Debug Release)
733          if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES)
734            # ... will never get here, "Debug" != "DEBUG"
735          endif()
736
737       In  contrast,  CMake  treats  the configuration type case-insensitively
738       when using it internally in places that modify behavior  based  on  the
739       configuration.   For  example, the $<CONFIG:Debug> generator expression
740       will evaluate to 1 for a configuration of not only Debug, but also  DE‐
741       BUG,  debug  or  even  DeBuG.  Therefore, you can specify configuration
742       types in CMAKE_BUILD_TYPE and CMAKE_CONFIGURATION_TYPES with  any  mix‐
743       ture of upper and lowercase, although there are strong conventions (see
744       the next section).  If you must test the value in  string  comparisons,
745       always  convert  the  value  to upper or lowercase first and adjust the
746       test accordingly.
747
748   Default And Custom Configurations
749       By default, CMake defines a number of standard configurations:
750
751Debug
752
753Release
754
755RelWithDebInfo
756
757MinSizeRel
758
759       In multi-config generators, the CMAKE_CONFIGURATION_TYPES variable will
760       be  populated with (potentially a subset of) the above list by default,
761       unless overridden by the project or  user.   The  actual  configuration
762       used is selected by the user at build time.
763
764       For  single-config  generators, the configuration is specified with the
765       CMAKE_BUILD_TYPE variable at configure time and cannot  be  changed  at
766       build time.  The default value will often be none of the above standard
767       configurations and will instead be an empty string.  A common misunder‐
768       standing  is  that this is the same as Debug, but that is not the case.
769       Users should always explicitly specify the build type instead to  avoid
770       this common problem.
771
772       The  above  standard configuration types provide reasonable behavior on
773       most platforms, but they can be extended to provide other types.   Each
774       configuration  defines  a set of compiler and linker flag variables for
775       the  language  in  use.   These   variables   follow   the   convention
776       CMAKE_<LANG>_FLAGS_<CONFIG>,  where  <CONFIG>  is  always the uppercase
777       configuration name.  When defining a custom  configuration  type,  make
778       sure  these  variables  are set appropriately, typically as cache vari‐
779       ables.
780

PSEUDO TARGETS

782       Some target types do not represent outputs of the buildsystem, but only
783       inputs  such as external dependencies, aliases or other non-build arti‐
784       facts.  Pseudo targets are not represented in the  generated  buildsys‐
785       tem.
786
787   Imported Targets
788       An  IMPORTED target represents a pre-existing dependency.  Usually such
789       targets are defined by an upstream package and should be treated as im‐
790       mutable.  After  declaring an IMPORTED target one can adjust its target
791       properties    by    using    the    customary    commands    such    as
792       target_compile_definitions(),             target_include_directories(),
793       target_compile_options() or target_link_libraries() just like with  any
794       other regular target.
795
796       IMPORTED  targets  may have the same usage requirement properties popu‐
797       lated  as  binary  targets,  such   as   INTERFACE_INCLUDE_DIRECTORIES,
798       INTERFACE_COMPILE_DEFINITIONS,               INTERFACE_COMPILE_OPTIONS,
799       INTERFACE_LINK_LIBRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.
800
801       The LOCATION may also be read from an IMPORTED target, though there  is
802       rarely  reason  to  do  so.   Commands such as add_custom_command() can
803       transparently use an IMPORTED  EXECUTABLE  target  as  a  COMMAND  exe‐
804       cutable.
805
806       The  scope  of  the  definition  of an IMPORTED target is the directory
807       where it was defined.  It may be accessed and used from subdirectories,
808       but  not  from parent directories or sibling directories.  The scope is
809       similar to the scope of a cmake variable.
810
811       It is also possible to define a GLOBAL IMPORTED target which is  acces‐
812       sible globally in the buildsystem.
813
814       See  the  cmake-packages(7)  manual  for more on creating packages with
815       IMPORTED targets.
816
817   Alias Targets
818       An ALIAS target is a name which may be used interchangeably with a  bi‐
819       nary  target  name in read-only contexts.  A primary use-case for ALIAS
820       targets is for example or unit test executables accompanying a library,
821       which  may be part of the same buildsystem or built separately based on
822       user configuration.
823
824          add_library(lib1 lib1.cpp)
825          install(TARGETS lib1 EXPORT lib1Export ${dest_args})
826          install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
827
828          add_library(Upstream::lib1 ALIAS lib1)
829
830       In another directory, we can link unconditionally to the Upstream::lib1
831       target,  which  may  be  an IMPORTED target from a package, or an ALIAS
832       target if built as part of the same buildsystem.
833
834          if (NOT TARGET Upstream::lib1)
835            find_package(lib1 REQUIRED)
836          endif()
837          add_executable(exe1 exe1.cpp)
838          target_link_libraries(exe1 Upstream::lib1)
839
840       ALIAS targets are not mutable, installable or exportable.  They are en‐
841       tirely  local to the buildsystem description.  A name can be tested for
842       whether it is an ALIAS name by reading the ALIASED_TARGET property from
843       it:
844
845          get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
846          if(_aliased)
847            message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
848          endif()
849
850   Interface Libraries
851       An  INTERFACE library target does not compile sources and does not pro‐
852       duce a library artifact on disk, so it has no LOCATION.
853
854       It      may      specify      usage      requirements      such      as
855       INTERFACE_INCLUDE_DIRECTORIES,           INTERFACE_COMPILE_DEFINITIONS,
856       INTERFACE_COMPILE_OPTIONS, INTERFACE_LINK_LIBRARIES, INTERFACE_SOURCES,
857       and  INTERFACE_POSITION_INDEPENDENT_CODE.   Only the INTERFACE modes of
858       the     target_include_directories(),     target_compile_definitions(),
859       target_compile_options(), target_sources(), and target_link_libraries()
860       commands may be used with INTERFACE libraries.
861
862       Since CMake 3.19, an INTERFACE library target  may  optionally  contain
863       source  files.  An interface library that contains source files will be
864       included as a build target in the generated buildsystem.  It  does  not
865       compile  sources,  but  may  contain  custom commands to generate other
866       sources.  Additionally, IDEs will show the source files as part of  the
867       target for interactive reading and editing.
868
869       A  primary  use-case  for INTERFACE libraries is header-only libraries.
870       Since CMake 3.23, header files may be  associated  with  a  library  by
871       adding them to a header set using the target_sources() command:
872
873          add_library(Eigen INTERFACE)
874
875          target_sources(Eigen PUBLIC
876            FILE_SET HEADERS
877              BASE_DIRS src
878              FILES src/eigen.h src/vector.h src/matrix.h
879          )
880
881          add_executable(exe1 exe1.cpp)
882          target_link_libraries(exe1 Eigen)
883
884       When  we  specify  the FILE_SET here, the BASE_DIRS we define automati‐
885       cally become include directories in the usage requirements for the tar‐
886       get  Eigen.   The  usage  requirements from the target are consumed and
887       used when compiling, but have no effect on linking.
888
889       Another use-case is to employ an entirely  target-focussed  design  for
890       usage requirements:
891
892          add_library(pic_on INTERFACE)
893          set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
894          add_library(pic_off INTERFACE)
895          set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
896
897          add_library(enable_rtti INTERFACE)
898          target_compile_options(enable_rtti INTERFACE
899            $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
900          )
901
902          add_executable(exe1 exe1.cpp)
903          target_link_libraries(exe1 pic_on enable_rtti)
904
905       This  way,  the  build  specification  of exe1 is expressed entirely as
906       linked targets, and the complexity of compiler-specific flags is encap‐
907       sulated in an INTERFACE library target.
908
909       INTERFACE  libraries  may be installed and exported. We can install the
910       default header set along with the target:
911
912          add_library(Eigen INTERFACE)
913
914          target_sources(Eigen INTERFACE
915            FILE_SET HEADERS
916              BASE_DIRS src
917              FILES src/eigen.h src/vector.h src/matrix.h
918          )
919
920          install(TARGETS Eigen EXPORT eigenExport
921            FILE_SET HEADERS DESTINATION include/Eigen)
922          install(EXPORT eigenExport NAMESPACE Upstream::
923            DESTINATION lib/cmake/Eigen
924          )
925
926       Here, the headers defined in  the  header  set  are  installed  to  in‐
927       clude/Eigen.   The install destination automatically becomes an include
928       directory that is a usage requirement for consumers.
929
931       2000-2023 Kitware, Inc. and Contributors
932
933
934
935
9363.27.7                           Oct 07, 2023             CMAKE-BUILDSYSTEM(7)
Impressum