1CMAKE-BUILDSYSTEM(7) CMake CMAKE-BUILDSYSTEM(7)
2
6 cmake-buildsystem - CMake Buildsystem Reference
7
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
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 add_library(archive archive.cpp zip.cpp lzma.cpp)
23 add_executable(zipapp zipapp.cpp)
24 target_link_libraries(zipapp archive)
25 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 Binary Executables
32 The add_executable() command defines an executable target:
33 add_executable(mytool mytool.cpp)
35 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 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 add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)
47 add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
49 The BUILD_SHARED_LIBS variable may be enabled to change the behavior of
51 add_library() to build shared libraries by default.
52 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 add_library(archive MODULE 7z.cpp)
65 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 CFBundleIdentifier key and
72 it uniquely identifies the bundle.
73 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 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 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
89 add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
91 add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
93 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 Alternatively, object libraries may be linked into other targets:
98 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
100 add_library(archiveExtras STATIC extras.cpp)
102 target_link_libraries(archiveExtras PUBLIC archive)
103 add_executable(test_exe test.cpp)
105 target_link_libraries(test_exe archive)
106 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 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
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 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 target_compile_definitions(archive
134 PRIVATE BUILDING_WITH_LZMA
135 INTERFACE USING_ARCHIVE_LIB
136 )
137 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 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 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 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 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 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 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 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 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 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 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 add_library(archive archive.cpp)
205 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
206 add_library(serialization serialization.cpp)
208 target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
209 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 add_executable(consumer consumer.cpp)
217 # consumer is compiled with -DUSING_ARCHIVE_LIB
218 target_link_libraries(consumer archiveExtras)
219 Because the archive is a PUBLIC dependency of archiveExtras, the usage
221 requirements of it are propagated to consumer too.
222 Because serialization is a PRIVATE dependency of archiveExtras, the us‐
224 age requirements of it are not propagated to consumer.
225 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 target_link_libraries(archiveExtras
237 PUBLIC archive
238 PRIVATE serialization
239 )
240 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 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 target_link_libraries(myExe lib1 lib2 lib3)
256 target_include_directories(myExe
257 PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
258 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 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 add_executable(exe1 exe1.cpp)
273 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
274 add_library(lib1 SHARED lib1.cpp)
276 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
277 add_executable(exe2 exe2.cpp)
279 target_link_libraries(exe2 lib1)
280 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 add_library(lib1 SHARED lib1.cpp)
287 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
288 add_library(lib2 SHARED lib2.cpp)
290 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
291 add_executable(exe1 exe1.cpp)
293 target_link_libraries(exe1 lib1)
294 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
295 add_executable(exe2 exe2.cpp)
297 target_link_libraries(exe2 lib1 lib2)
298 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 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 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 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 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 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 add_library(lib1Version3 SHARED lib1_v3.cpp)
333 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
334 add_executable(exe1 exe1.cpp)
336 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
337 add_executable(exe2 exe2.cpp)
339 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
340 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 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 add_library(lib1Version3 SHARED lib1_v3.cpp)
355 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
356 add_executable(exe1 exe1.cpp)
358 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
359 add_executable(exe2 exe2.cpp)
361 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
362 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 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 add_library(lib1Version3 SHARED lib1_v3.cpp)
374 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
375 add_executable(exe1 exe1.cpp)
377 # CONTAINER_SIZE_REQUIRED will be "200"
378 target_link_libraries(exe1 lib1Version2)
379 add_executable(exe2 exe2.cpp)
381 # CONTAINER_SIZE_REQUIRED will be "1000"
382 target_link_libraries(exe2 lib1Version2 lib1Version3)
383 Similarly, the COMPATIBLE_INTERFACE_NUMBER_MIN may be used to calculate
385 the numeric minimum value for a property from dependencies.
386 Each calculated "compatible" property value may be read in the consumer
388 at generate-time using generator expressions.
389 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 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 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 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 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 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 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 In this case, the exe1 source files will be compiled with -DCON‐
440 TAINER_SIZE=200.
441 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 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 add_executable(exe1 exe1.cpp)
455 target_link_libraries(exe1 lib1)
456 cmake_policy(SET CMP0041 NEW)
458 add_library(shared_lib shared_lib.cpp)
460 target_link_libraries(shared_lib lib1)
461 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 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 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 add_executable(exe1 exe1.cpp)
485 target_link_libraries(exe1 ClimbingStats)
486 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 find_package(ClimbingStats REQUIRED)
494 add_executable(Downstream main.cpp)
496 target_link_libraries(Downstream Upstream::ClimbingStats)
497 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 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 add_library(lib1 lib1.cpp)
511 target_include_directories(lib1 PRIVATE
512 /absolute/path
513 relative/path
514 )
515 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 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 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 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 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 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
545 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
546 )
547 for each target affected. The convenience for installed targets is an
549 INCLUDES DESTINATION component with the install(TARGETS) command:
550 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 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 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 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 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 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 add_executable(exe1 exe1.cpp)
594 target_link_libraries(exe1 lib1 lib3)
595 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 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 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 Runtime Output Artifacts
619 A runtime output artifact of a buildsystem target may be:
620 • The executable file (e.g. .exe) of an executable target created by
622 the add_executable() command.
623 • 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 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 Library Output Artifacts
632 A library output artifact of a buildsystem target may be:
633 • 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 • 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 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 Archive Output Artifacts
646 An archive output artifact of a buildsystem target may be:
647 • 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 • 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 • 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 • 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 The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME target properties
665 may be used to control archive output artifact locations and names in
666 the build tree.
667 Directory-Scoped Commands
669 The target_include_directories(), target_compile_definitions() and
670 target_compile_options() commands have an effect on only one target at
671 a time. The commands add_compile_definitions(), add_compile_options()
672 and include_directories() have a similar function, but operate at di‐
673 rectory scope instead of target scope for convenience.
674
676 Configurations determine specifications for a certain type of build,
677 such as Release or Debug. The way this is specified depends on the
678 type of generator being used. For single configuration generators like
679 Makefile Generators and Ninja, the configuration is specified at con‐
680 figure time by the CMAKE_BUILD_TYPE variable. For multi-configuration
681 generators like Visual Studio, Xcode, and Ninja Multi-Config, the con‐
682 figuration is chosen by the user at build time and CMAKE_BUILD_TYPE is
683 ignored. In the multi-configuration case, the set of available config‐
684 urations is specified at configure time by the
685 CMAKE_CONFIGURATION_TYPES variable, but the actual configuration used
686 cannot be known until the build stage. This difference is often misun‐
687 derstood, leading to problematic code like the following:
688 # WARNING: This is wrong for multi-config generators because they don't use
690 # and typically don't even set CMAKE_BUILD_TYPE
691 string(TOLOWER ${CMAKE_BUILD_TYPE} build_type)
692 if (build_type STREQUAL debug)
693 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
694 endif()
695 Generator expressions should be used instead to handle configura‐
697 tion-specific logic correctly, regardless of the generator used. For
698 example:
699 # Works correctly for both single and multi-config generators
701 target_compile_definitions(exe1 PRIVATE
702 $<$<CONFIG:Debug>:DEBUG_BUILD>
703 )
704 In the presence of IMPORTED targets, the content of
706 MAP_IMPORTED_CONFIG_DEBUG is also accounted for by the above $<CON‐
707 FIG:Debug> expression.
708 Case Sensitivity
710 CMAKE_BUILD_TYPE and CMAKE_CONFIGURATION_TYPES are just like other
711 variables in that any string comparisons made with their values will be
712 case-sensitive. The $<CONFIG> generator expression also preserves the
713 casing of the configuration as set by the user or CMake defaults. For
714 example:
715 # NOTE: Don't use these patterns, they are for illustration purposes only.
717 set(CMAKE_BUILD_TYPE Debug)
719 if(CMAKE_BUILD_TYPE STREQUAL DEBUG)
720 # ... will never get here, "Debug" != "DEBUG"
721 endif()
722 add_custom_target(print_config ALL
723 # Prints "Config is Debug" in this single-config case
724 COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>"
725 VERBATIM
726 )
727 set(CMAKE_CONFIGURATION_TYPES Debug Release)
729 if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES)
730 # ... will never get here, "Debug" != "DEBUG"
731 endif()
732 In contrast, CMake treats the configuration type case-insensitively
734 when using it internally in places that modify behavior based on the
735 configuration. For example, the $<CONFIG:Debug> generator expression
736 will evaluate to 1 for a configuration of not only Debug, but also DE‐
737 BUG, debug or even DeBuG. Therefore, you can specify configuration
738 types in CMAKE_BUILD_TYPE and CMAKE_CONFIGURATION_TYPES with any mix‐
739 ture of upper and lowercase, although there are strong conventions (see
740 the next section). If you must test the value in string comparisons,
741 always convert the value to upper or lowercase first and adjust the
742 test accordingly.
743 Default And Custom Configurations
745 By default, CMake defines a number of standard configurations:
746 • Debug
748 • Release
750 • RelWithDebInfo
752 • MinSizeRel
754 In multi-config generators, the CMAKE_CONFIGURATION_TYPES variable will
756 be populated with (potentially a subset of) the above list by default,
757 unless overridden by the project or user. The actual configuration
758 used is selected by the user at build time.
759 For single-config generators, the configuration is specified with the
761 CMAKE_BUILD_TYPE variable at configure time and cannot be changed at
762 build time. The default value will often be none of the above standard
763 configurations and will instead be an empty string. A common misunder‐
764 standing is that this is the same as Debug, but that is not the case.
765 Users should always explicitly specify the build type instead to avoid
766 this common problem.
767 The above standard configuration types provide reasonable behavior on
769 most platforms, but they can be extended to provide other types. Each
770 configuration defines a set of compiler and linker flag variables for
771 the language in use. These variables follow the convention
772 CMAKE_<LANG>_FLAGS_<CONFIG>, where <CONFIG> is always the uppercase
773 configuration name. When defining a custom configuration type, make
774 sure these variables are set appropriately, typically as cache vari‐
775 ables.
776
778 Some target types do not represent outputs of the buildsystem, but only
779 inputs such as external dependencies, aliases or other non-build arti‐
780 facts. Pseudo targets are not represented in the generated buildsys‐
781 tem.
782 Imported Targets
784 An IMPORTED target represents a pre-existing dependency. Usually such
785 targets are defined by an upstream package and should be treated as im‐
786 mutable. After declaring an IMPORTED target one can adjust its target
787 properties by using the customary commands such as
788 target_compile_definitions(), target_include_directories(),
789 target_compile_options() or target_link_libraries() just like with any
790 other regular target.
791 IMPORTED targets may have the same usage requirement properties popu‐
793 lated as binary targets, such as INTERFACE_INCLUDE_DIRECTORIES,
794 INTERFACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS,
795 INTERFACE_LINK_LIBRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.
796 The LOCATION may also be read from an IMPORTED target, though there is
798 rarely reason to do so. Commands such as add_custom_command() can
799 transparently use an IMPORTED EXECUTABLE target as a COMMAND exe‐
800 cutable.
801 The scope of the definition of an IMPORTED target is the directory
803 where it was defined. It may be accessed and used from subdirectories,
804 but not from parent directories or sibling directories. The scope is
805 similar to the scope of a cmake variable.
806 It is also possible to define a GLOBAL IMPORTED target which is acces‐
808 sible globally in the buildsystem.
809 See the cmake-packages(7) manual for more on creating packages with
811 IMPORTED targets.
812 Alias Targets
814 An ALIAS target is a name which may be used interchangeably with a bi‐
815 nary target name in read-only contexts. A primary use-case for ALIAS
816 targets is for example or unit test executables accompanying a library,
817 which may be part of the same buildsystem or built separately based on
818 user configuration.
819 add_library(lib1 lib1.cpp)
821 install(TARGETS lib1 EXPORT lib1Export ${dest_args})
822 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
823 add_library(Upstream::lib1 ALIAS lib1)
825 In another directory, we can link unconditionally to the Upstream::lib1
827 target, which may be an IMPORTED target from a package, or an ALIAS
828 target if built as part of the same buildsystem.
829 if (NOT TARGET Upstream::lib1)
831 find_package(lib1 REQUIRED)
832 endif()
833 add_executable(exe1 exe1.cpp)
834 target_link_libraries(exe1 Upstream::lib1)
835 ALIAS targets are not mutable, installable or exportable. They are en‐
837 tirely local to the buildsystem description. A name can be tested for
838 whether it is an ALIAS name by reading the ALIASED_TARGET property from
839 it:
840 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
842 if(_aliased)
843 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
844 endif()
845 Interface Libraries
847 An INTERFACE library target does not compile sources and does not pro‐
848 duce a library artifact on disk, so it has no LOCATION.
849 It may specify usage requirements such as
851 INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COMPILE_DEFINITIONS,
852 INTERFACE_COMPILE_OPTIONS, INTERFACE_LINK_LIBRARIES, INTERFACE_SOURCES,
853 and INTERFACE_POSITION_INDEPENDENT_CODE. Only the INTERFACE modes of
854 the target_include_directories(), target_compile_definitions(),
855 target_compile_options(), target_sources(), and target_link_libraries()
856 commands may be used with INTERFACE libraries.
857 Since CMake 3.19, an INTERFACE library target may optionally contain
859 source files. An interface library that contains source files will be
860 included as a build target in the generated buildsystem. It does not
861 compile sources, but may contain custom commands to generate other
862 sources. Additionally, IDEs will show the source files as part of the
863 target for interactive reading and editing.
864 A primary use-case for INTERFACE libraries is header-only libraries.
866 Since CMake 3.23, header files may be associated with a library by
867 adding them to a header set using the target_sources() command:
868 add_library(Eigen INTERFACE)
870 target_sources(Eigen PUBLIC
872 FILE_SET HEADERS
873 BASE_DIRS src
874 FILES src/eigen.h src/vector.h src/matrix.h
875 )
876 add_executable(exe1 exe1.cpp)
878 target_link_libraries(exe1 Eigen)
879 When we specify the FILE_SET here, the BASE_DIRS we define automati‐
881 cally become include directories in the usage requirements for the tar‐
882 get Eigen. The usage requirements from the target are consumed and
883 used when compiling, but have no effect on linking.
884 Another use-case is to employ an entirely target-focussed design for
886 usage requirements:
887 add_library(pic_on INTERFACE)
889 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
890 add_library(pic_off INTERFACE)
891 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
892 add_library(enable_rtti INTERFACE)
894 target_compile_options(enable_rtti INTERFACE
895 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
896 )
897 add_executable(exe1 exe1.cpp)
899 target_link_libraries(exe1 pic_on enable_rtti)
900 This way, the build specification of exe1 is expressed entirely as
902 linked targets, and the complexity of compiler-specific flags is encap‐
903 sulated in an INTERFACE library target.
904 INTERFACE libraries may be installed and exported. We can install the
906 default header set along with the target:
907 add_library(Eigen INTERFACE)
909 target_sources(Eigen INTERFACE
911 FILE_SET HEADERS
912 BASE_DIRS src
913 FILES src/eigen.h src/vector.h src/matrix.h
914 )
915 install(TARGETS Eigen EXPORT eigenExport
917 FILE_SET HEADERS DESTINATION include/Eigen)
918 install(EXPORT eigenExport NAMESPACE Upstream::
919 DESTINATION lib/cmake/Eigen
920 )
921 Here, the headers defined in the header set are installed to in‐
923 clude/Eigen. The install destination automatically becomes an include
924 directory that is a usage requirement for consumers.
925
927 2000-2023 Kitware, Inc. and Contributors
9283.25.2 Jan 19, 2023 CMAKE-BUILDSYSTEM(7)