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 Configuration determined build specifications may be conveniently set
440 using the CONFIG generator expression.
441 target_compile_definitions(exe1 PRIVATE
443 $<$<CONFIG:Debug>:DEBUG_BUILD>
444 )
445 The CONFIG parameter is compared case-insensitively with the configura‐
447 tion being built. In the presence of IMPORTED targets, the content of
448 MAP_IMPORTED_CONFIG_DEBUG is also accounted for by this expression.
449 Some buildsystems generated by cmake(1) have a predetermined build-con‐
451 figuration set in the CMAKE_BUILD_TYPE variable. The buildsystem for
452 the IDEs such as Visual Studio and Xcode are generated independent of
453 the build-configuration, and the actual build configuration is not
454 known until build-time. Therefore, code such as
455 string(TOLOWER ${CMAKE_BUILD_TYPE} _type)
457 if (_type STREQUAL debug)
458 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
459 endif()
460 may appear to work for Makefile Generators and Ninja generators, but is
462 not portable to IDE generators. Additionally, the IMPORTED configura‐
463 tion-mappings are not accounted for with code like this, so it should
464 be avoided.
465 The unary TARGET_PROPERTY generator expression and the TARGET_POLICY
467 generator expression are evaluated with the consuming target context.
468 This means that a usage requirement specification may be evaluated dif‐
469 ferently based on the consumer:
470 add_library(lib1 lib1.cpp)
472 target_compile_definitions(lib1 INTERFACE
473 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
474 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
475 $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
476 )
477 add_executable(exe1 exe1.cpp)
479 target_link_libraries(exe1 lib1)
480 cmake_policy(SET CMP0041 NEW)
482 add_library(shared_lib shared_lib.cpp)
484 target_link_libraries(shared_lib lib1)
485 The exe1 executable will be compiled with -DLIB1_WITH_EXE, while the
487 shared_lib shared library will be compiled with -DLIB1_WITH_SHARED_LIB
488 and -DCONSUMER_CMP0041_NEW, because policy CMP0041 is NEW at the point
489 where the shared_lib target is created.
490 The BUILD_INTERFACE expression wraps requirements which are only used
492 when consumed from a target in the same buildsystem, or when consumed
493 from a target exported to the build directory using the export() com‐
494 mand. The INSTALL_INTERFACE expression wraps requirements which are
495 only used when consumed from a target which has been installed and ex‐
496 ported with the install(EXPORT) command:
497 add_library(ClimbingStats climbingstats.cpp)
499 target_compile_definitions(ClimbingStats INTERFACE
500 $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
501 $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
502 )
503 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
504 install(EXPORT libExport NAMESPACE Upstream::
505 DESTINATION lib/cmake/ClimbingStats)
506 export(EXPORT libExport NAMESPACE Upstream::)
507 add_executable(exe1 exe1.cpp)
509 target_link_libraries(exe1 ClimbingStats)
510 In this case, the exe1 executable will be compiled with -DClimb‐
512 ingStats_FROM_BUILD_LOCATION. The exporting commands generate IMPORTED
513 targets with either the INSTALL_INTERFACE or the BUILD_INTERFACE omit‐
514 ted, and the *_INTERFACE marker stripped away. A separate project con‐
515 suming the ClimbingStats package would contain:
516 find_package(ClimbingStats REQUIRED)
518 add_executable(Downstream main.cpp)
520 target_link_libraries(Downstream Upstream::ClimbingStats)
521 Depending on whether the ClimbingStats package was used from the build
523 location or the install location, the Downstream target would be com‐
524 piled with either -DClimbingStats_FROM_BUILD_LOCATION or -DClimb‐
525 ingStats_FROM_INSTALL_LOCATION. For more about packages and exporting
526 see the cmake-packages(7) manual.
527 Include Directories and Usage Requirements
529 Include directories require some special consideration when specified
530 as usage requirements and when used with generator expressions. The
531 target_include_directories() command accepts both relative and absolute
532 include directories:
533 add_library(lib1 lib1.cpp)
535 target_include_directories(lib1 PRIVATE
536 /absolute/path
537 relative/path
538 )
539 Relative paths are interpreted relative to the source directory where
541 the command appears. Relative paths are not allowed in the INTER‐
542 FACE_INCLUDE_DIRECTORIES of IMPORTED targets.
543 In cases where a non-trivial generator expression is used, the IN‐
545 STALL_PREFIX expression may be used within the argument of an IN‐
546 STALL_INTERFACE expression. It is a replacement marker which expands
547 to the installation prefix when imported by a consuming project.
548 Include directories usage requirements commonly differ between the
550 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
551 TERFACE generator expressions can be used to describe separate usage
552 requirements based on the usage location. Relative paths are allowed
553 within the INSTALL_INTERFACE expression and are interpreted relative to
554 the installation prefix. For example:
555 add_library(ClimbingStats climbingstats.cpp)
557 target_include_directories(ClimbingStats INTERFACE
558 $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
559 $<INSTALL_INTERFACE:/absolute/path>
560 $<INSTALL_INTERFACE:relative/path>
561 $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
562 )
563 Two convenience APIs are provided relating to include directories usage
565 requirements. The CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE variable may
566 be enabled, with an equivalent effect to:
567 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
569 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
570 )
571 for each target affected. The convenience for installed targets is an
573 INCLUDES DESTINATION component with the install(TARGETS) command:
574 install(TARGETS foo bar bat EXPORT tgts ${dest_args}
576 INCLUDES DESTINATION include
577 )
578 install(EXPORT tgts ${other_args})
579 install(FILES ${headers} DESTINATION include)
580 This is equivalent to appending ${CMAKE_INSTALL_PREFIX}/include to the
582 INTERFACE_INCLUDE_DIRECTORIES of each of the installed IMPORTED targets
583 when generated by install(EXPORT).
584 When the INTERFACE_INCLUDE_DIRECTORIES of an imported target is con‐
586 sumed, the entries in the property are treated as SYSTEM include direc‐
587 tories, as if they were listed in the INTERFACE_SYSTEM_INCLUDE_DIRECTO‐
588 RIES of the dependency. This can result in omission of compiler warn‐
589 ings for headers found in those directories. This behavior for
590 Imported Targets may be controlled by setting the NO_SYSTEM_FROM_IM‐
591 PORTED target property on the consumers of imported targets.
592 If a binary target is linked transitively to a macOS FRAMEWORK, the
594 Headers directory of the framework is also treated as a usage require‐
595 ment. This has the same effect as passing the framework directory as
596 an include directory.
597 Link Libraries and Generator Expressions
599 Like build specifications, link libraries may be specified with genera‐
600 tor expression conditions. However, as consumption of usage require‐
601 ments is based on collection from linked dependencies, there is an ad‐
602 ditional limitation that the link dependencies must form a "directed
603 acyclic graph". That is, if linking to a target is dependent on the
604 value of a target property, that target property may not be dependent
605 on the linked dependencies:
606 add_library(lib1 lib1.cpp)
608 add_library(lib2 lib2.cpp)
609 target_link_libraries(lib1 PUBLIC
610 $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
611 )
612 add_library(lib3 lib3.cpp)
613 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
614 add_executable(exe1 exe1.cpp)
616 target_link_libraries(exe1 lib1 lib3)
617 As the value of the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
619 get is dependent on the linked libraries (lib3), and the edge of link‐
620 ing exe1 is determined by the same POSITION_INDEPENDENT_CODE property,
621 the dependency graph above contains a cycle. cmake(1) issues an error
622 message.
623 Output Artifacts
625 The buildsystem targets created by the add_library() and add_exe‐
626 cutable() commands create rules to create binary outputs. The exact
627 output location of the binaries can only be determined at generate-time
628 because it can depend on the build-configuration and the link-language
629 of linked dependencies etc. TARGET_FILE, TARGET_LINKER_FILE and re‐
630 lated expressions can be used to access the name and location of gener‐
631 ated binaries. These expressions do not work for OBJECT libraries how‐
632 ever, as there is no single file generated by such libraries which is
633 relevant to the expressions.
634 There are three kinds of output artifacts that may be build by targets
636 as detailed in the following sections. Their classification differs
637 between DLL platforms and non-DLL platforms. All Windows-based systems
638 including Cygwin are DLL platforms.
639 Runtime Output Artifacts
641 A runtime output artifact of a buildsystem target may be:
642 • The executable file (e.g. .exe) of an executable target created by
644 the add_executable() command.
645 • On DLL platforms: the executable file (e.g. .dll) of a shared library
647 target created by the add_library() command with the SHARED option.
648 The RUNTIME_OUTPUT_DIRECTORY and RUNTIME_OUTPUT_NAME target properties
650 may be used to control runtime output artifact locations and names in
651 the build tree.
652 Library Output Artifacts
654 A library output artifact of a buildsystem target may be:
655 • The loadable module file (e.g. .dll or .so) of a module library tar‐
657 get created by the add_library() command with the MODULE option.
658 • On non-DLL platforms: the shared library file (e.g. .so or .dylib) of
660 a shared library target created by the add_library() command with the
661 SHARED option.
662 The LIBRARY_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_NAME target properties
664 may be used to control library output artifact locations and names in
665 the build tree.
666 Archive Output Artifacts
668 An archive output artifact of a buildsystem target may be:
669 • The static library file (e.g. .lib or .a) of a static library target
671 created by the add_library() command with the STATIC option.
672 • On DLL platforms: the import library file (e.g. .lib) of a shared li‐
674 brary target created by the add_library() command with the SHARED op‐
675 tion. This file is only guaranteed to exist if the library exports
676 at least one unmanaged symbol.
677 • On DLL platforms: the import library file (e.g. .lib) of an exe‐
679 cutable target created by the add_executable() command when its EN‐
680 ABLE_EXPORTS target property is set.
681 • On AIX: the linker import file (e.g. .imp) of an executable target
683 created by the add_executable() command when its ENABLE_EXPORTS tar‐
684 get property is set.
685 The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME target properties
687 may be used to control archive output artifact locations and names in
688 the build tree.
689 Directory-Scoped Commands
691 The target_include_directories(), target_compile_definitions() and tar‐
692 get_compile_options() commands have an effect on only one target at a
693 time. The commands add_compile_definitions(), add_compile_options()
694 and include_directories() have a similar function, but operate at di‐
695 rectory scope instead of target scope for convenience.
696
698 Some target types do not represent outputs of the buildsystem, but only
699 inputs such as external dependencies, aliases or other non-build arti‐
700 facts. Pseudo targets are not represented in the generated buildsys‐
701 tem.
702 Imported Targets
704 An IMPORTED target represents a pre-existing dependency. Usually such
705 targets are defined by an upstream package and should be treated as im‐
706 mutable. After declaring an IMPORTED target one can adjust its target
707 properties by using the customary commands such as target_compile_defi‐
708 nitions(), target_include_directories(), target_compile_options() or
709 target_link_libraries() just like with any other regular target.
710 IMPORTED targets may have the same usage requirement properties popu‐
712 lated as binary targets, such as INTERFACE_INCLUDE_DIRECTORIES, INTER‐
713 FACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTERFACE_LINK_LI‐
714 BRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.
715 The LOCATION may also be read from an IMPORTED target, though there is
717 rarely reason to do so. Commands such as add_custom_command() can
718 transparently use an IMPORTED EXECUTABLE target as a COMMAND exe‐
719 cutable.
720 The scope of the definition of an IMPORTED target is the directory
722 where it was defined. It may be accessed and used from subdirectories,
723 but not from parent directories or sibling directories. The scope is
724 similar to the scope of a cmake variable.
725 It is also possible to define a GLOBAL IMPORTED target which is acces‐
727 sible globally in the buildsystem.
728 See the cmake-packages(7) manual for more on creating packages with IM‐
730 PORTED targets.
731 Alias Targets
733 An ALIAS target is a name which may be used interchangeably with a bi‐
734 nary target name in read-only contexts. A primary use-case for ALIAS
735 targets is for example or unit test executables accompanying a library,
736 which may be part of the same buildsystem or built separately based on
737 user configuration.
738 add_library(lib1 lib1.cpp)
740 install(TARGETS lib1 EXPORT lib1Export ${dest_args})
741 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
742 add_library(Upstream::lib1 ALIAS lib1)
744 In another directory, we can link unconditionally to the Upstream::lib1
746 target, which may be an IMPORTED target from a package, or an ALIAS
747 target if built as part of the same buildsystem.
748 if (NOT TARGET Upstream::lib1)
750 find_package(lib1 REQUIRED)
751 endif()
752 add_executable(exe1 exe1.cpp)
753 target_link_libraries(exe1 Upstream::lib1)
754 ALIAS targets are not mutable, installable or exportable. They are en‐
756 tirely local to the buildsystem description. A name can be tested for
757 whether it is an ALIAS name by reading the ALIASED_TARGET property from
758 it:
759 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
761 if(_aliased)
762 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
763 endif()
764 Interface Libraries
766 An INTERFACE library target does not compile sources and does not pro‐
767 duce a library artifact on disk, so it has no LOCATION.
768 It may specify usage requirements such as INTERFACE_INCLUDE_DIRECTO‐
770 RIES, INTERFACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
771 FACE_LINK_LIBRARIES, INTERFACE_SOURCES, and INTERFACE_POSITION_INDEPEN‐
772 DENT_CODE. Only the INTERFACE modes of the target_include_directo‐
773 ries(), target_compile_definitions(), target_compile_options(), tar‐
774 get_sources(), and target_link_libraries() commands may be used with
775 INTERFACE libraries.
776 Since CMake 3.19, an INTERFACE library target may optionally contain
778 source files. An interface library that contains source files will be
779 included as a build target in the generated buildsystem. It does not
780 compile sources, but may contain custom commands to generate other
781 sources. Additionally, IDEs will show the source files as part of the
782 target for interactive reading and editing.
783 A primary use-case for INTERFACE libraries is header-only libraries.
785 add_library(Eigen INTERFACE
787 src/eigen.h
788 src/vector.h
789 src/matrix.h
790 )
791 target_include_directories(Eigen INTERFACE
792 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
793 $<INSTALL_INTERFACE:include/Eigen>
794 )
795 add_executable(exe1 exe1.cpp)
797 target_link_libraries(exe1 Eigen)
798 Here, the usage requirements from the Eigen target are consumed and
800 used when compiling, but it has no effect on linking.
801 Another use-case is to employ an entirely target-focussed design for
803 usage requirements:
804 add_library(pic_on INTERFACE)
806 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
807 add_library(pic_off INTERFACE)
808 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
809 add_library(enable_rtti INTERFACE)
811 target_compile_options(enable_rtti INTERFACE
812 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
813 )
814 add_executable(exe1 exe1.cpp)
816 target_link_libraries(exe1 pic_on enable_rtti)
817 This way, the build specification of exe1 is expressed entirely as
819 linked targets, and the complexity of compiler-specific flags is encap‐
820 sulated in an INTERFACE library target.
821 INTERFACE libraries may be installed and exported. Any content they
823 refer to must be installed separately:
824 set(Eigen_headers
826 src/eigen.h
827 src/vector.h
828 src/matrix.h
829 )
830 add_library(Eigen INTERFACE ${Eigen_headers})
831 target_include_directories(Eigen INTERFACE
832 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
833 $<INSTALL_INTERFACE:include/Eigen>
834 )
835 install(TARGETS Eigen EXPORT eigenExport)
837 install(EXPORT eigenExport NAMESPACE Upstream::
838 DESTINATION lib/cmake/Eigen
839 )
840 install(FILES ${Eigen_headers}
841 DESTINATION include/Eigen
842 )
843
845 2000-2021 Kitware, Inc. and Contributors
8463.20.3 May 30, 2021 CMAKE-BUILDSYSTEM(7)