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 com‐
55       mands,  dependency specifications and other APIs work similarly regard‐
56       less 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.  The MACOSX_FRAMEWORK_IDENTI‐
69       FIER sets CFBundleIdentifier key and it uniquely identifies the bundle.
70
71          add_library(MyFramework SHARED MyFramework.cpp)
72          set_target_properties(MyFramework PROPERTIES
73            FRAMEWORK TRUE
74            FRAMEWORK_VERSION A
75            MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
76          )
77
78   Object Libraries
79       The OBJECT library type defines a  non-archival  collection  of  object
80       files  resulting  from  compiling  the  given source files.  The object
81       files collection may be used as source inputs to other targets:
82
83          add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
84
85          add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
86
87          add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
88
89       The link (or archiving) step of those other targets will use the object
90       files collection in addition to those from their own sources.
91
92       Alternatively, object libraries may be linked into other targets:
93
94          add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
95
96          add_library(archiveExtras STATIC extras.cpp)
97          target_link_libraries(archiveExtras PUBLIC archive)
98
99          add_executable(test_exe test.cpp)
100          target_link_libraries(test_exe archive)
101
102       The link (or archiving) step of those other targets will use the object
103       files from OBJECT libraries that are  directly  linked.   Additionally,
104       usage requirements of the OBJECT libraries will be honored when compil‐
105       ing sources in those other targets.  Furthermore, those usage  require‐
106       ments will propagate transitively to dependents of those other targets.
107
108       Object libraries may not be used as the TARGET in a use of the add_cus‐
109       tom_command(TARGET) command signature.  However, the  list  of  objects
110       can  be  used  by add_custom_command(OUTPUT) or file(GENERATE) by using
111       $<TARGET_OBJECTS:objlib>.
112

BUILD SPECIFICATION AND USAGE REQUIREMENTS

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

PSEUDO TARGETS

690       Some target types do not represent outputs of the buildsystem, but only
691       inputs such as external dependencies, aliases or other non-build  arti‐
692       facts.   Pseudo  targets are not represented in the generated buildsys‐
693       tem.
694
695   Imported Targets
696       An IMPORTED target represents a pre-existing dependency.  Usually  such
697       targets  are  defined  by  an upstream package and should be treated as
698       immutable. After declaring an IMPORTED target one can adjust its target
699       properties by using the customary commands such as target_compile_defi‐
700       nitions(),  target_include_directories(),  target_compile_options()  or
701       target_link_libraries() just like with any other regular target.
702
703       IMPORTED  targets  may have the same usage requirement properties popu‐
704       lated as binary targets, such as INTERFACE_INCLUDE_DIRECTORIES,  INTER‐
705       FACE_COMPILE_DEFINITIONS,       INTERFACE_COMPILE_OPTIONS,       INTER‐
706       FACE_LINK_LIBRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.
707
708       The LOCATION may also be read from an IMPORTED target, though there  is
709       rarely  reason  to  do  so.   Commands such as add_custom_command() can
710       transparently use an IMPORTED  EXECUTABLE  target  as  a  COMMAND  exe‐
711       cutable.
712
713       The  scope  of  the  definition  of an IMPORTED target is the directory
714       where it was defined.  It may be accessed and used from subdirectories,
715       but  not  from parent directories or sibling directories.  The scope is
716       similar to the scope of a cmake variable.
717
718       It is also possible to define a GLOBAL IMPORTED target which is  acces‐
719       sible globally in the buildsystem.
720
721       See  the  cmake-packages(7)  manual  for more on creating packages with
722       IMPORTED targets.
723
724   Alias Targets
725       An ALIAS target is a name which may  be  used  interchangeably  with  a
726       binary target name in read-only contexts.  A primary use-case for ALIAS
727       targets is for example or unit test executables accompanying a library,
728       which  may be part of the same buildsystem or built separately based on
729       user configuration.
730
731          add_library(lib1 lib1.cpp)
732          install(TARGETS lib1 EXPORT lib1Export ${dest_args})
733          install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
734
735          add_library(Upstream::lib1 ALIAS lib1)
736
737       In another directory, we can link unconditionally to the Upstream::lib1
738       target,  which  may  be  an IMPORTED target from a package, or an ALIAS
739       target if built as part of the same buildsystem.
740
741          if (NOT TARGET Upstream::lib1)
742            find_package(lib1 REQUIRED)
743          endif()
744          add_executable(exe1 exe1.cpp)
745          target_link_libraries(exe1 Upstream::lib1)
746
747       ALIAS targets are not mutable, installable  or  exportable.   They  are
748       entirely  local  to  the buildsystem description.  A name can be tested
749       for whether it is an ALIAS name by reading the ALIASED_TARGET  property
750       from it:
751
752          get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
753          if(_aliased)
754            message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
755          endif()
756
757   Interface Libraries
758       An  INTERFACE  target  has no LOCATION and is mutable, but is otherwise
759       similar to an IMPORTED target.
760
761       It may specify usage requirements  such  as  INTERFACE_INCLUDE_DIRECTO‐
762       RIES,  INTERFACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
763       FACE_LINK_LIBRARIES, INTERFACE_SOURCES, and INTERFACE_POSITION_INDEPEN‐
764       DENT_CODE.   Only  the  INTERFACE  modes of the target_include_directo‐
765       ries(),  target_compile_definitions(),  target_compile_options(),  tar‐
766       get_sources(),  and  target_link_libraries()  commands may be used with
767       INTERFACE libraries.
768
769       A primary use-case for INTERFACE libraries is header-only libraries.
770
771          add_library(Eigen INTERFACE)
772          target_include_directories(Eigen INTERFACE
773            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
774            $<INSTALL_INTERFACE:include/Eigen>
775          )
776
777          add_executable(exe1 exe1.cpp)
778          target_link_libraries(exe1 Eigen)
779
780       Here, the usage requirements from the Eigen  target  are  consumed  and
781       used when compiling, but it has no effect on linking.
782
783       Another  use-case  is  to employ an entirely target-focussed design for
784       usage requirements:
785
786          add_library(pic_on INTERFACE)
787          set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
788          add_library(pic_off INTERFACE)
789          set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
790
791          add_library(enable_rtti INTERFACE)
792          target_compile_options(enable_rtti INTERFACE
793            $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
794          )
795
796          add_executable(exe1 exe1.cpp)
797          target_link_libraries(exe1 pic_on enable_rtti)
798
799       This way, the build specification of  exe1  is  expressed  entirely  as
800       linked targets, and the complexity of compiler-specific flags is encap‐
801       sulated in an INTERFACE library target.
802
803       The properties permitted to be set on or read from an INTERFACE library
804       are:
805
806       · Properties matching INTERFACE_*
807
808       · Built-in properties matching COMPATIBLE_INTERFACE_*
809
810       · EXPORT_NAME
811
812       · EXPORT_PROPERTIES
813
814       · IMPORTED
815
816       · MANUALLY_ADDED_DEPENDENCIES
817
818       · NAME
819
820       · Properties matching IMPORTED_LIBNAME_*
821
822       · Properties matching MAP_IMPORTED_CONFIG_*
823
824       INTERFACE  libraries  may  be installed and exported.  Any content they
825       refer to must be installed separately:
826
827          add_library(Eigen INTERFACE)
828          target_include_directories(Eigen INTERFACE
829            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
830            $<INSTALL_INTERFACE:include/Eigen>
831          )
832
833          install(TARGETS Eigen EXPORT eigenExport)
834          install(EXPORT eigenExport NAMESPACE Upstream::
835            DESTINATION lib/cmake/Eigen
836          )
837          install(FILES
838              ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h
839              ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h
840              ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h
841            DESTINATION include/Eigen
842          )
843
845       2000-2019 Kitware, Inc. and Contributors
846
847
848
849
8503.16.1                           Dec 14, 2019             CMAKE-BUILDSYSTEM(7)
Impressum