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 add_cus‐
114 tom_command(TARGET) command signature. However, the list of objects
115 can be used by add_custom_command(OUTPUT) or file(GENERATE) by using
116 $<TARGET_OBJECTS:objlib>.
117
119 The target_include_directories(), target_compile_definitions() and tar‐
120 get_compile_options() commands specify the build specifications and the
121 usage requirements of binary targets. The commands populate the IN‐
122 CLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS target prop‐
123 erties respectively, and/or the INTERFACE_INCLUDE_DIRECTORIES, INTER‐
124 FACE_COMPILE_DEFINITIONS and INTERFACE_COMPILE_OPTIONS target proper‐
125 ties.
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 COM‐
149 PILE_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, INTERFACE_COM‐
166 PILE_DEFINITIONS and INTERFACE_COMPILE_OPTIONS target properties are
167 Usage Requirements -- they specify content which consumers must use to
168 correctly compile and link with the target they appear on. For any bi‐
169 nary target, the contents of each INTERFACE_ property on each target
170 specified in a target_link_libraries() command is consumed:
171 set(srcs archive.cpp zip.cpp)
173 if (LZMA_FOUND)
174 list(APPEND srcs lzma.cpp)
175 endif()
176 add_library(archive SHARED ${srcs})
177 if (LZMA_FOUND)
178 # The archive library sources are compiled with -DBUILDING_WITH_LZMA
179 target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
180 endif()
181 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
182 add_executable(consumer)
184 # Link consumer to archive and consume its usage requirements. The consumer
185 # executable sources are compiled with -DUSING_ARCHIVE_LIB.
186 target_link_libraries(consumer archive)
187 Because it is common to require that the source directory and corre‐
189 sponding build directory are added to the INCLUDE_DIRECTORIES, the
190 CMAKE_INCLUDE_CURRENT_DIR variable can be enabled to conveniently add
191 the corresponding directories to the INCLUDE_DIRECTORIES of all tar‐
192 gets. The variable CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE can be en‐
193 abled to add the corresponding directories to the INTERFACE_INCLUDE_DI‐
194 RECTORIES of all targets. This makes use of targets in multiple dif‐
195 ferent directories convenient through use of the target_link_li‐
196 braries() command.
197 Transitive Usage Requirements
199 The usage requirements of a target can transitively propagate to depen‐
200 dents. The target_link_libraries() command has PRIVATE, INTERFACE and
201 PUBLIC keywords to control the propagation.
202 add_library(archive archive.cpp)
204 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
205 add_library(serialization serialization.cpp)
207 target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
208 add_library(archiveExtras extras.cpp)
210 target_link_libraries(archiveExtras PUBLIC archive)
211 target_link_libraries(archiveExtras PRIVATE serialization)
212 # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
213 # and -DUSING_SERIALIZATION_LIB
214 add_executable(consumer consumer.cpp)
216 # consumer is compiled with -DUSING_ARCHIVE_LIB
217 target_link_libraries(consumer archiveExtras)
218 Because archive is a PUBLIC dependency of archiveExtras, the usage re‐
220 quirements of it are propagated to consumer too. Because serialization
221 is a PRIVATE dependency of archiveExtras, the usage requirements of it
222 are not propagated to consumer.
223 Generally, a dependency should be specified in a use of target_link_li‐
225 braries() with the PRIVATE keyword if it is used by only the implemen‐
226 tation of a library, and not in the header files. If a dependency is
227 additionally used in the header files of a library (e.g. for class in‐
228 heritance), then it should be specified as a PUBLIC dependency. A de‐
229 pendency which is not used by the implementation of a library, but only
230 by its headers should be specified as an INTERFACE dependency. The
231 target_link_libraries() command may be invoked with multiple uses of
232 each keyword:
233 target_link_libraries(archiveExtras
235 PUBLIC archive
236 PRIVATE serialization
237 )
238 Usage requirements are propagated by reading the INTERFACE_ variants of
240 target properties from dependencies and appending the values to the
241 non-INTERFACE_ variants of the operand. For example, the INTERFACE_IN‐
242 CLUDE_DIRECTORIES of dependencies is read and appended to the IN‐
243 CLUDE_DIRECTORIES of the operand. In cases where order is relevant and
244 maintained, and the order resulting from the target_link_libraries()
245 calls does not allow correct compilation, use of an appropriate command
246 to set the property directly may update the order.
247 For example, if the linked libraries for a target must be specified in
249 the order lib1 lib2 lib3 , but the include directories must be speci‐
250 fied in the order lib3 lib1 lib2:
251 target_link_libraries(myExe lib1 lib2 lib3)
253 target_include_directories(myExe
254 PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
255 Note that care must be taken when specifying usage requirements for
257 targets which will be exported for installation using the install(EX‐
258 PORT) command. See Creating Packages for more.
259 Compatible Interface Properties
261 Some target properties are required to be compatible between a target
262 and the interface of each dependency. For example, the POSITION_INDE‐
263 PENDENT_CODE target property may specify a boolean value of whether a
264 target should be compiled as position-independent-code, which has plat‐
265 form-specific consequences. A target may also specify the usage re‐
266 quirement INTERFACE_POSITION_INDEPENDENT_CODE to communicate that con‐
267 sumers must be compiled as position-independent-code.
268 add_executable(exe1 exe1.cpp)
270 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
271 add_library(lib1 SHARED lib1.cpp)
273 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
274 add_executable(exe2 exe2.cpp)
276 target_link_libraries(exe2 lib1)
277 Here, both exe1 and exe2 will be compiled as position-independent-code.
279 lib1 will also be compiled as position-independent-code because that is
280 the default setting for SHARED libraries. If dependencies have con‐
281 flicting, non-compatible requirements cmake(1) issues a diagnostic:
282 add_library(lib1 SHARED lib1.cpp)
284 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
285 add_library(lib2 SHARED lib2.cpp)
287 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
288 add_executable(exe1 exe1.cpp)
290 target_link_libraries(exe1 lib1)
291 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
292 add_executable(exe2 exe2.cpp)
294 target_link_libraries(exe2 lib1 lib2)
295 The lib1 requirement INTERFACE_POSITION_INDEPENDENT_CODE is not "com‐
297 patible" with the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
298 get. The library requires that consumers are built as position-inde‐
299 pendent-code, while the executable specifies to not built as posi‐
300 tion-independent-code, so a diagnostic is issued.
301 The lib1 and lib2 requirements are not "compatible". One of them re‐
303 quires that consumers are built as position-independent-code, while the
304 other requires that consumers are not built as position-indepen‐
305 dent-code. Because exe2 links to both and they are in conflict, a
306 CMake error message is issued:
307 CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
309 not agree with the value of POSITION_INDEPENDENT_CODE already determined
310 for "exe2".
311 To be "compatible", the POSITION_INDEPENDENT_CODE property, if set must
313 be either the same, in a boolean sense, as the INTERFACE_POSITION_INDE‐
314 PENDENT_CODE property of all transitively specified dependencies on
315 which that property is set.
316 This property of "compatible interface requirement" may be extended to
318 other properties by specifying the property in the content of the COM‐
319 PATIBLE_INTERFACE_BOOL target property. Each specified property must
320 be compatible between the consuming target and the corresponding prop‐
321 erty with an INTERFACE_ prefix from each dependency:
322 add_library(lib1Version2 SHARED lib1_v2.cpp)
324 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
325 set_property(TARGET lib1Version2 APPEND PROPERTY
326 COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
327 )
328 add_library(lib1Version3 SHARED lib1_v3.cpp)
330 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
331 add_executable(exe1 exe1.cpp)
333 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
334 add_executable(exe2 exe2.cpp)
336 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
337 Non-boolean properties may also participate in "compatible interface"
339 computations. Properties specified in the COMPATIBLE_INTERFACE_STRING
340 property must be either unspecified or compare to the same string among
341 all transitively specified dependencies. This can be useful to ensure
342 that multiple incompatible versions of a library are not linked to‐
343 gether through transitive requirements of a target:
344 add_library(lib1Version2 SHARED lib1_v2.cpp)
346 set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
347 set_property(TARGET lib1Version2 APPEND PROPERTY
348 COMPATIBLE_INTERFACE_STRING LIB_VERSION
349 )
350 add_library(lib1Version3 SHARED lib1_v3.cpp)
352 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
353 add_executable(exe1 exe1.cpp)
355 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
356 add_executable(exe2 exe2.cpp)
358 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
359 The COMPATIBLE_INTERFACE_NUMBER_MAX target property specifies that con‐
361 tent will be evaluated numerically and the maximum number among all
362 specified will be calculated:
363 add_library(lib1Version2 SHARED lib1_v2.cpp)
365 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
366 set_property(TARGET lib1Version2 APPEND PROPERTY
367 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
368 )
369 add_library(lib1Version3 SHARED lib1_v3.cpp)
371 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
372 add_executable(exe1 exe1.cpp)
374 # CONTAINER_SIZE_REQUIRED will be "200"
375 target_link_libraries(exe1 lib1Version2)
376 add_executable(exe2 exe2.cpp)
378 # CONTAINER_SIZE_REQUIRED will be "1000"
379 target_link_libraries(exe2 lib1Version2 lib1Version3)
380 Similarly, the COMPATIBLE_INTERFACE_NUMBER_MIN may be used to calculate
382 the numeric minimum value for a property from dependencies.
383 Each calculated "compatible" property value may be read in the consumer
385 at generate-time using generator expressions.
386 Note that for each dependee, the set of properties specified in each
388 compatible interface property must not intersect with the set specified
389 in any of the other properties.
390 Property Origin Debugging
392 Because build specifications can be determined by dependencies, the
393 lack of locality of code which creates a target and code which is re‐
394 sponsible for setting build specifications may make the code more dif‐
395 ficult to reason about. cmake(1) provides a debugging facility to
396 print the origin of the contents of properties which may be determined
397 by dependencies. The properties which can be debugged are listed in
398 the CMAKE_DEBUG_TARGET_PROPERTIES variable documentation:
399 set(CMAKE_DEBUG_TARGET_PROPERTIES
401 INCLUDE_DIRECTORIES
402 COMPILE_DEFINITIONS
403 POSITION_INDEPENDENT_CODE
404 CONTAINER_SIZE_REQUIRED
405 LIB_VERSION
406 )
407 add_executable(exe1 exe1.cpp)
408 In the case of properties listed in COMPATIBLE_INTERFACE_BOOL or COM‐
410 PATIBLE_INTERFACE_STRING, the debug output shows which target was re‐
411 sponsible for setting the property, and which other dependencies also
412 defined the property. In the case of COMPATIBLE_INTERFACE_NUMBER_MAX
413 and COMPATIBLE_INTERFACE_NUMBER_MIN, the debug output shows the value
414 of the property from each dependency, and whether the value determines
415 the new extreme.
416 Build Specification with Generator Expressions
418 Build specifications may use generator expressions containing content
419 which may be conditional or known only at generate-time. For example,
420 the calculated "compatible" value of a property may be read with the
421 TARGET_PROPERTY expression:
422 add_library(lib1Version2 SHARED lib1_v2.cpp)
424 set_property(TARGET lib1Version2 PROPERTY
425 INTERFACE_CONTAINER_SIZE_REQUIRED 200)
426 set_property(TARGET lib1Version2 APPEND PROPERTY
427 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
428 )
429 add_executable(exe1 exe1.cpp)
431 target_link_libraries(exe1 lib1Version2)
432 target_compile_definitions(exe1 PRIVATE
433 CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
434 )
435 In this case, the exe1 source files will be compiled with -DCON‐
437 TAINER_SIZE=200.
438 The unary TARGET_PROPERTY generator expression and the TARGET_POLICY
440 generator expression are evaluated with the consuming target context.
441 This means that a usage requirement specification may be evaluated dif‐
442 ferently based on the consumer:
443 add_library(lib1 lib1.cpp)
445 target_compile_definitions(lib1 INTERFACE
446 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
447 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
448 $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
449 )
450 add_executable(exe1 exe1.cpp)
452 target_link_libraries(exe1 lib1)
453 cmake_policy(SET CMP0041 NEW)
455 add_library(shared_lib shared_lib.cpp)
457 target_link_libraries(shared_lib lib1)
458 The exe1 executable will be compiled with -DLIB1_WITH_EXE, while the
460 shared_lib shared library will be compiled with -DLIB1_WITH_SHARED_LIB
461 and -DCONSUMER_CMP0041_NEW, because policy CMP0041 is NEW at the point
462 where the shared_lib target is created.
463 The BUILD_INTERFACE expression wraps requirements which are only used
465 when consumed from a target in the same buildsystem, or when consumed
466 from a target exported to the build directory using the export() com‐
467 mand. The INSTALL_INTERFACE expression wraps requirements which are
468 only used when consumed from a target which has been installed and ex‐
469 ported with the install(EXPORT) command:
470 add_library(ClimbingStats climbingstats.cpp)
472 target_compile_definitions(ClimbingStats INTERFACE
473 $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
474 $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
475 )
476 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
477 install(EXPORT libExport NAMESPACE Upstream::
478 DESTINATION lib/cmake/ClimbingStats)
479 export(EXPORT libExport NAMESPACE Upstream::)
480 add_executable(exe1 exe1.cpp)
482 target_link_libraries(exe1 ClimbingStats)
483 In this case, the exe1 executable will be compiled with -DClimb‐
485 ingStats_FROM_BUILD_LOCATION. The exporting commands generate IMPORTED
486 targets with either the INSTALL_INTERFACE or the BUILD_INTERFACE omit‐
487 ted, and the *_INTERFACE marker stripped away. A separate project con‐
488 suming the ClimbingStats package would contain:
489 find_package(ClimbingStats REQUIRED)
491 add_executable(Downstream main.cpp)
493 target_link_libraries(Downstream Upstream::ClimbingStats)
494 Depending on whether the ClimbingStats package was used from the build
496 location or the install location, the Downstream target would be com‐
497 piled with either -DClimbingStats_FROM_BUILD_LOCATION or -DClimb‐
498 ingStats_FROM_INSTALL_LOCATION. For more about packages and exporting
499 see the cmake-packages(7) manual.
500 Include Directories and Usage Requirements
502 Include directories require some special consideration when specified
503 as usage requirements and when used with generator expressions. The
504 target_include_directories() command accepts both relative and absolute
505 include directories:
506 add_library(lib1 lib1.cpp)
508 target_include_directories(lib1 PRIVATE
509 /absolute/path
510 relative/path
511 )
512 Relative paths are interpreted relative to the source directory where
514 the command appears. Relative paths are not allowed in the INTER‐
515 FACE_INCLUDE_DIRECTORIES of IMPORTED targets.
516 In cases where a non-trivial generator expression is used, the IN‐
518 STALL_PREFIX expression may be used within the argument of an IN‐
519 STALL_INTERFACE expression. It is a replacement marker which expands
520 to the installation prefix when imported by a consuming project.
521 Include directories usage requirements commonly differ between the
523 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
524 TERFACE generator expressions can be used to describe separate usage
525 requirements based on the usage location. Relative paths are allowed
526 within the INSTALL_INTERFACE expression and are interpreted relative to
527 the installation prefix. For example:
528 add_library(ClimbingStats climbingstats.cpp)
530 target_include_directories(ClimbingStats INTERFACE
531 $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
532 $<INSTALL_INTERFACE:/absolute/path>
533 $<INSTALL_INTERFACE:relative/path>
534 $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
535 )
536 Two convenience APIs are provided relating to include directories usage
538 requirements. The CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE variable may
539 be enabled, with an equivalent effect to:
540 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
542 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
543 )
544 for each target affected. The convenience for installed targets is an
546 INCLUDES DESTINATION component with the install(TARGETS) command:
547 install(TARGETS foo bar bat EXPORT tgts ${dest_args}
549 INCLUDES DESTINATION include
550 )
551 install(EXPORT tgts ${other_args})
552 install(FILES ${headers} DESTINATION include)
553 This is equivalent to appending ${CMAKE_INSTALL_PREFIX}/include to the
555 INTERFACE_INCLUDE_DIRECTORIES of each of the installed IMPORTED targets
556 when generated by install(EXPORT).
557 When the INTERFACE_INCLUDE_DIRECTORIES of an imported target is con‐
559 sumed, the entries in the property are treated as SYSTEM include direc‐
560 tories, as if they were listed in the INTERFACE_SYSTEM_INCLUDE_DIRECTO‐
561 RIES of the dependency. This can result in omission of compiler warn‐
562 ings for headers found in those directories. This behavior for
563 Imported Targets may be controlled by setting the NO_SYSTEM_FROM_IM‐
564 PORTED target property on the consumers of imported targets.
565 If a binary target is linked transitively to a macOS FRAMEWORK, the
567 Headers directory of the framework is also treated as a usage require‐
568 ment. This has the same effect as passing the framework directory as
569 an include directory.
570 Link Libraries and Generator Expressions
572 Like build specifications, link libraries may be specified with genera‐
573 tor expression conditions. However, as consumption of usage require‐
574 ments is based on collection from linked dependencies, there is an ad‐
575 ditional limitation that the link dependencies must form a "directed
576 acyclic graph". That is, if linking to a target is dependent on the
577 value of a target property, that target property may not be dependent
578 on the linked dependencies:
579 add_library(lib1 lib1.cpp)
581 add_library(lib2 lib2.cpp)
582 target_link_libraries(lib1 PUBLIC
583 $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
584 )
585 add_library(lib3 lib3.cpp)
586 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
587 add_executable(exe1 exe1.cpp)
589 target_link_libraries(exe1 lib1 lib3)
590 As the value of the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
592 get is dependent on the linked libraries (lib3), and the edge of link‐
593 ing exe1 is determined by the same POSITION_INDEPENDENT_CODE property,
594 the dependency graph above contains a cycle. cmake(1) issues an error
595 message.
596 Output Artifacts
598 The buildsystem targets created by the add_library() and add_exe‐
599 cutable() commands create rules to create binary outputs. The exact
600 output location of the binaries can only be determined at generate-time
601 because it can depend on the build-configuration and the link-language
602 of linked dependencies etc. TARGET_FILE, TARGET_LINKER_FILE and re‐
603 lated expressions can be used to access the name and location of gener‐
604 ated binaries. These expressions do not work for OBJECT libraries how‐
605 ever, as there is no single file generated by such libraries which is
606 relevant to the expressions.
607 There are three kinds of output artifacts that may be build by targets
609 as detailed in the following sections. Their classification differs
610 between DLL platforms and non-DLL platforms. All Windows-based systems
611 including Cygwin are DLL platforms.
612 Runtime Output Artifacts
614 A runtime output artifact of a buildsystem target may be:
615 • The executable file (e.g. .exe) of an executable target created by
617 the add_executable() command.
618 • On DLL platforms: the executable file (e.g. .dll) of a shared library
620 target created by the add_library() command with the SHARED option.
621 The RUNTIME_OUTPUT_DIRECTORY and RUNTIME_OUTPUT_NAME target properties
623 may be used to control runtime output artifact locations and names in
624 the build tree.
625 Library Output Artifacts
627 A library output artifact of a buildsystem target may be:
628 • The loadable module file (e.g. .dll or .so) of a module library tar‐
630 get created by the add_library() command with the MODULE option.
631 • On non-DLL platforms: the shared library file (e.g. .so or .dylib) of
633 a shared library target created by the add_library() command with the
634 SHARED option.
635 The LIBRARY_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_NAME target properties
637 may be used to control library output artifact locations and names in
638 the build tree.
639 Archive Output Artifacts
641 An archive output artifact of a buildsystem target may be:
642 • The static library file (e.g. .lib or .a) of a static library target
644 created by the add_library() command with the STATIC option.
645 • On DLL platforms: the import library file (e.g. .lib) of a shared li‐
647 brary target created by the add_library() command with the SHARED op‐
648 tion. This file is only guaranteed to exist if the library exports
649 at least one unmanaged symbol.
650 • On DLL platforms: the import library file (e.g. .lib) of an exe‐
652 cutable target created by the add_executable() command when its EN‐
653 ABLE_EXPORTS target property is set.
654 • On AIX: the linker import file (e.g. .imp) of an executable target
656 created by the add_executable() command when its ENABLE_EXPORTS tar‐
657 get property is set.
658 The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME target properties
660 may be used to control archive output artifact locations and names in
661 the build tree.
662 Directory-Scoped Commands
664 The target_include_directories(), target_compile_definitions() and tar‐
665 get_compile_options() commands have an effect on only one target at a
666 time. The commands add_compile_definitions(), add_compile_options()
667 and include_directories() have a similar function, but operate at di‐
668 rectory scope instead of target scope for convenience.
669
671 Configurations determine specifications for a certain type of build,
672 such as Release or Debug. The way this is specified depends on the
673 type of generator being used. For single configuration generators like
674 Makefile Generators and Ninja, the configuration is specified at con‐
675 figure time by the CMAKE_BUILD_TYPE variable. For multi-configuration
676 generators like Visual Studio, Xcode, and Ninja Multi-Config, the con‐
677 figuration is chosen by the user at build time and CMAKE_BUILD_TYPE is
678 ignored. In the multi-configuration case, the set of available config‐
679 urations is specified at configure time by the CMAKE_CONFIGURA‐
680 TION_TYPES variable, but the actual configuration used cannot be known
681 until the build stage. This difference is often misunderstood, leading
682 to problematic code like the following:
683 # WARNING: This is wrong for multi-config generators because they don't use
685 # and typically don't even set CMAKE_BUILD_TYPE
686 string(TOLOWER ${CMAKE_BUILD_TYPE} build_type)
687 if (build_type STREQUAL debug)
688 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
689 endif()
690 Generator expressions should be used instead to handle configura‐
692 tion-specific logic correctly, regardless of the generator used. For
693 example:
694 # Works correctly for both single and multi-config generators
696 target_compile_definitions(exe1 PRIVATE
697 $<$<CONFIG:Debug>:DEBUG_BUILD>
698 )
699 In the presence of IMPORTED targets, the content of MAP_IMPORTED_CON‐
701 FIG_DEBUG is also accounted for by the above $<CONFIG:Debug> expres‐
702 sion.
703 Case Sensitivity
705 CMAKE_BUILD_TYPE and CMAKE_CONFIGURATION_TYPES are just like other
706 variables in that any string comparisons made with their values will be
707 case-sensitive. The $<CONFIG> generator expression also preserves the
708 casing of the configuration as set by the user or CMake defaults. For
709 example:
710 # NOTE: Don't use these patterns, they are for illustration purposes only.
712 set(CMAKE_BUILD_TYPE Debug)
714 if(CMAKE_BUILD_TYPE STREQUAL DEBUG)
715 # ... will never get here, "Debug" != "DEBUG"
716 endif()
717 add_custom_target(print_config ALL
718 # Prints "Config is Debug" in this single-config case
719 COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>"
720 VERBATIM
721 )
722 set(CMAKE_CONFIGURATION_TYPES Debug Release)
724 if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES)
725 # ... will never get here, "Debug" != "DEBUG"
726 endif()
727 In contrast, CMake treats the configuration type case-insensitively
729 when using it internally in places that modify behavior based on the
730 configuration. For example, the $<CONFIG:Debug> generator expression
731 will evaluate to 1 for a configuration of not only Debug, but also DE‐
732 BUG, debug or even DeBuG. Therefore, you can specify configuration
733 types in CMAKE_BUILD_TYPE and CMAKE_CONFIGURATION_TYPES with any mix‐
734 ture of upper and lowercase, although there are strong conventions (see
735 the next section). If you must test the value in string comparisons,
736 always convert the value to upper or lowercase first and adjust the
737 test accordingly.
738 Default And Custom Configurations
740 By default, CMake defines a number of standard configurations:
741 • Debug
743 • Release
745 • RelWithDebInfo
747 • MinSizeRel
749 In multi-config generators, the CMAKE_CONFIGURATION_TYPES variable will
751 be populated with (potentially a subset of) the above list by default,
752 unless overridden by the project or user. The actual configuration
753 used is selected by the user at build time.
754 For single-config generators, the configuration is specified with the
756 CMAKE_BUILD_TYPE variable at configure time and cannot be changed at
757 build time. The default value will often be none of the above standard
758 configurations and will instead be an empty string. A common misunder‐
759 standing is that this is the same as Debug, but that is not the case.
760 Users should always explicitly specify the build type instead to avoid
761 this common problem.
762 The above standard configuration types provide reasonable behavior on
764 most platforms, but they can be extended to provide other types. Each
765 configuration defines a set of compiler and linker flag variables for
766 the language in use. These variables follow the convention
767 CMAKE_<LANG>_FLAGS_<CONFIG>, where <CONFIG> is always the uppercase
768 configuration name. When defining a custom configuration type, make
769 sure these variables are set appropriately, typically as cache vari‐
770 ables.
771
773 Some target types do not represent outputs of the buildsystem, but only
774 inputs such as external dependencies, aliases or other non-build arti‐
775 facts. Pseudo targets are not represented in the generated buildsys‐
776 tem.
777 Imported Targets
779 An IMPORTED target represents a pre-existing dependency. Usually such
780 targets are defined by an upstream package and should be treated as im‐
781 mutable. After declaring an IMPORTED target one can adjust its target
782 properties by using the customary commands such as target_compile_defi‐
783 nitions(), target_include_directories(), target_compile_options() or
784 target_link_libraries() just like with any other regular target.
785 IMPORTED targets may have the same usage requirement properties popu‐
787 lated as binary targets, such as INTERFACE_INCLUDE_DIRECTORIES, INTER‐
788 FACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTERFACE_LINK_LI‐
789 BRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.
790 The LOCATION may also be read from an IMPORTED target, though there is
792 rarely reason to do so. Commands such as add_custom_command() can
793 transparently use an IMPORTED EXECUTABLE target as a COMMAND exe‐
794 cutable.
795 The scope of the definition of an IMPORTED target is the directory
797 where it was defined. It may be accessed and used from subdirectories,
798 but not from parent directories or sibling directories. The scope is
799 similar to the scope of a cmake variable.
800 It is also possible to define a GLOBAL IMPORTED target which is acces‐
802 sible globally in the buildsystem.
803 See the cmake-packages(7) manual for more on creating packages with IM‐
805 PORTED targets.
806 Alias Targets
808 An ALIAS target is a name which may be used interchangeably with a bi‐
809 nary target name in read-only contexts. A primary use-case for ALIAS
810 targets is for example or unit test executables accompanying a library,
811 which may be part of the same buildsystem or built separately based on
812 user configuration.
813 add_library(lib1 lib1.cpp)
815 install(TARGETS lib1 EXPORT lib1Export ${dest_args})
816 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
817 add_library(Upstream::lib1 ALIAS lib1)
819 In another directory, we can link unconditionally to the Upstream::lib1
821 target, which may be an IMPORTED target from a package, or an ALIAS
822 target if built as part of the same buildsystem.
823 if (NOT TARGET Upstream::lib1)
825 find_package(lib1 REQUIRED)
826 endif()
827 add_executable(exe1 exe1.cpp)
828 target_link_libraries(exe1 Upstream::lib1)
829 ALIAS targets are not mutable, installable or exportable. They are en‐
831 tirely local to the buildsystem description. A name can be tested for
832 whether it is an ALIAS name by reading the ALIASED_TARGET property from
833 it:
834 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
836 if(_aliased)
837 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
838 endif()
839 Interface Libraries
841 An INTERFACE library target does not compile sources and does not pro‐
842 duce a library artifact on disk, so it has no LOCATION.
843 It may specify usage requirements such as INTERFACE_INCLUDE_DIRECTO‐
845 RIES, INTERFACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
846 FACE_LINK_LIBRARIES, INTERFACE_SOURCES, and INTERFACE_POSITION_INDEPEN‐
847 DENT_CODE. Only the INTERFACE modes of the target_include_directo‐
848 ries(), target_compile_definitions(), target_compile_options(), tar‐
849 get_sources(), and target_link_libraries() commands may be used with
850 INTERFACE libraries.
851 Since CMake 3.19, an INTERFACE library target may optionally contain
853 source files. An interface library that contains source files will be
854 included as a build target in the generated buildsystem. It does not
855 compile sources, but may contain custom commands to generate other
856 sources. Additionally, IDEs will show the source files as part of the
857 target for interactive reading and editing.
858 A primary use-case for INTERFACE libraries is header-only libraries.
860 add_library(Eigen INTERFACE
862 src/eigen.h
863 src/vector.h
864 src/matrix.h
865 )
866 target_include_directories(Eigen INTERFACE
867 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
868 $<INSTALL_INTERFACE:include/Eigen>
869 )
870 add_executable(exe1 exe1.cpp)
872 target_link_libraries(exe1 Eigen)
873 Here, the usage requirements from the Eigen target are consumed and
875 used when compiling, but it has no effect on linking.
876 Another use-case is to employ an entirely target-focussed design for
878 usage requirements:
879 add_library(pic_on INTERFACE)
881 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
882 add_library(pic_off INTERFACE)
883 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
884 add_library(enable_rtti INTERFACE)
886 target_compile_options(enable_rtti INTERFACE
887 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
888 )
889 add_executable(exe1 exe1.cpp)
891 target_link_libraries(exe1 pic_on enable_rtti)
892 This way, the build specification of exe1 is expressed entirely as
894 linked targets, and the complexity of compiler-specific flags is encap‐
895 sulated in an INTERFACE library target.
896 INTERFACE libraries may be installed and exported. Any content they
898 refer to must be installed separately:
899 set(Eigen_headers
901 src/eigen.h
902 src/vector.h
903 src/matrix.h
904 )
905 add_library(Eigen INTERFACE ${Eigen_headers})
906 target_include_directories(Eigen INTERFACE
907 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
908 $<INSTALL_INTERFACE:include/Eigen>
909 )
910 install(TARGETS Eigen EXPORT eigenExport)
912 install(EXPORT eigenExport NAMESPACE Upstream::
913 DESTINATION lib/cmake/Eigen
914 )
915 install(FILES ${Eigen_headers}
916 DESTINATION include/Eigen
917 )
918
920 2000-2021 Kitware, Inc. and Contributors
9213.22.0 Dec 02, 2021 CMAKE-BUILDSYSTEM(7)