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 com‐
55 mands, dependency specifications and other APIs work similarly regard‐
56 less of the library type. The MODULE library type is dissimilar in
57 that it is generally not linked to – it is not used in the
58 right-hand-side of the target_link_libraries() command. It is a type
59 which is loaded as a plugin using runtime techniques. If the library
60 does not export any unmanaged symbols (e.g. Windows resource DLL,
61 C++/CLI DLL), it is required that the library not be a SHARED library
62 because CMake expects SHARED libraries to export at least one symbol.
63 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
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 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
169 binary 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
193 enabled to add the corresponding directories to the INTER‐
194 FACE_INCLUDE_DIRECTORIES of all targets. This makes use of targets in
195 multiple different directories convenient through use of the tar‐
196 get_link_libraries() 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
220 requirements of it are propagated to consumer too. Because serializa‐
221 tion is a PRIVATE dependency of archiveExtras, the usage requirements
222 of it are not propagated to consumer.
223 Generally, a dependency should be specified in a use of tar‐
225 get_link_libraries() with the PRIVATE keyword if it is used by only the
226 implementation of a library, and not in the header files. If a depen‐
227 dency is additionally used in the header files of a library (e.g. for
228 class inheritance), then it should be specified as a PUBLIC dependency.
229 A dependency which is not used by the implementation of a library, but
230 only by its headers should be specified as an INTERFACE dependency.
231 The target_link_libraries() command may be invoked with multiple uses
232 of 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 INTER‐
242 FACE_INCLUDE_DIRECTORIES of dependencies is read and appended to the
243 INCLUDE_DIRECTORIES of the operand. In cases where order is relevant
244 and maintained, and the order resulting from the tar‐
245 get_link_libraries() calls does not allow correct compilation, use of
246 an appropriate command to set the property directly may update the
247 order.
248 For example, if the linked libraries for a target must be specified in
250 the order lib1 lib2 lib3 , but the include directories must be speci‐
251 fied in the order lib3 lib1 lib2:
252 target_link_libraries(myExe lib1 lib2 lib3)
254 target_include_directories(myExe
255 PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
256 Note that care must be taken when specifying usage requirements for
258 targets which will be exported for installation using the
259 install(EXPORT) command. See Creating Packages for more.
260 Compatible Interface Properties
262 Some target properties are required to be compatible between a target
263 and the interface of each dependency. For example, the POSITION_INDE‐
264 PENDENT_CODE target property may specify a boolean value of whether a
265 target should be compiled as position-independent-code, which has plat‐
266 form-specific consequences. A target may also specify the usage
267 requirement INTERFACE_POSITION_INDEPENDENT_CODE to communicate that
268 consumers must be compiled as position-independent-code.
269 add_executable(exe1 exe1.cpp)
271 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
272 add_library(lib1 SHARED lib1.cpp)
274 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
275 add_executable(exe2 exe2.cpp)
277 target_link_libraries(exe2 lib1)
278 Here, both exe1 and exe2 will be compiled as position-independent-code.
280 lib1 will also be compiled as position-independent-code because that is
281 the default setting for SHARED libraries. If dependencies have con‐
282 flicting, non-compatible requirements cmake(1) issues a diagnostic:
283 add_library(lib1 SHARED lib1.cpp)
285 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
286 add_library(lib2 SHARED lib2.cpp)
288 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
289 add_executable(exe1 exe1.cpp)
291 target_link_libraries(exe1 lib1)
292 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
293 add_executable(exe2 exe2.cpp)
295 target_link_libraries(exe2 lib1 lib2)
296 The lib1 requirement INTERFACE_POSITION_INDEPENDENT_CODE is not “com‐
298 patible” with the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
299 get. The library requires that consumers are built as position-inde‐
300 pendent-code, while the executable specifies to not built as posi‐
301 tion-independent-code, so a diagnostic is issued.
302 The lib1 and lib2 requirements are not “compatible”. One of them
304 requires that consumers are built as position-independent-code, while
305 the other requires that consumers are not built as position-indepen‐
306 dent-code. Because exe2 links to both and they are in conflict, a
307 CMake error message is issued:
308 CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
310 not agree with the value of POSITION_INDEPENDENT_CODE already determined
311 for "exe2".
312 To be “compatible”, the POSITION_INDEPENDENT_CODE property, if set must
314 be either the same, in a boolean sense, as the INTERFACE_POSITION_INDE‐
315 PENDENT_CODE property of all transitively specified dependencies on
316 which that property is set.
317 This property of “compatible interface requirement” may be extended to
319 other properties by specifying the property in the content of the COM‐
320 PATIBLE_INTERFACE_BOOL target property. Each specified property must
321 be compatible between the consuming target and the corresponding prop‐
322 erty with an INTERFACE_ prefix from each dependency:
323 add_library(lib1Version2 SHARED lib1_v2.cpp)
325 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
326 set_property(TARGET lib1Version2 APPEND PROPERTY
327 COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
328 )
329 add_library(lib1Version3 SHARED lib1_v3.cpp)
331 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
332 add_executable(exe1 exe1.cpp)
334 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
335 add_executable(exe2 exe2.cpp)
337 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
338 Non-boolean properties may also participate in “compatible interface”
340 computations. Properties specified in the COMPATIBLE_INTERFACE_STRING
341 property must be either unspecified or compare to the same string among
342 all transitively specified dependencies. This can be useful to ensure
343 that multiple incompatible versions of a library are not linked
344 together through transitive requirements of a target:
345 add_library(lib1Version2 SHARED lib1_v2.cpp)
347 set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
348 set_property(TARGET lib1Version2 APPEND PROPERTY
349 COMPATIBLE_INTERFACE_STRING LIB_VERSION
350 )
351 add_library(lib1Version3 SHARED lib1_v3.cpp)
353 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
354 add_executable(exe1 exe1.cpp)
356 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
357 add_executable(exe2 exe2.cpp)
359 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
360 The COMPATIBLE_INTERFACE_NUMBER_MAX target property specifies that con‐
362 tent will be evaluated numerically and the maximum number among all
363 specified will be calculated:
364 add_library(lib1Version2 SHARED lib1_v2.cpp)
366 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
367 set_property(TARGET lib1Version2 APPEND PROPERTY
368 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
369 )
370 add_library(lib1Version3 SHARED lib1_v3.cpp)
372 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
373 add_executable(exe1 exe1.cpp)
375 # CONTAINER_SIZE_REQUIRED will be "200"
376 target_link_libraries(exe1 lib1Version2)
377 add_executable(exe2 exe2.cpp)
379 # CONTAINER_SIZE_REQUIRED will be "1000"
380 target_link_libraries(exe2 lib1Version2 lib1Version3)
381 Similarly, the COMPATIBLE_INTERFACE_NUMBER_MIN may be used to calculate
383 the numeric minimum value for a property from dependencies.
384 Each calculated “compatible” property value may be read in the consumer
386 at generate-time using generator expressions.
387 Note that for each dependee, the set of properties specified in each
389 compatible interface property must not intersect with the set specified
390 in any of the other properties.
391 Property Origin Debugging
393 Because build specifications can be determined by dependencies, the
394 lack of locality of code which creates a target and code which is
395 responsible for setting build specifications may make the code more
396 difficult to reason about. cmake(1) provides a debugging facility to
397 print the origin of the contents of properties which may be determined
398 by dependencies. The properties which can be debugged are listed in
399 the CMAKE_DEBUG_TARGET_PROPERTIES variable documentation:
400 set(CMAKE_DEBUG_TARGET_PROPERTIES
402 INCLUDE_DIRECTORIES
403 COMPILE_DEFINITIONS
404 POSITION_INDEPENDENT_CODE
405 CONTAINER_SIZE_REQUIRED
406 LIB_VERSION
407 )
408 add_executable(exe1 exe1.cpp)
409 In the case of properties listed in COMPATIBLE_INTERFACE_BOOL or COM‐
411 PATIBLE_INTERFACE_STRING, the debug output shows which target was
412 responsible for setting the property, and which other dependencies also
413 defined the property. In the case of COMPATIBLE_INTERFACE_NUMBER_MAX
414 and COMPATIBLE_INTERFACE_NUMBER_MIN, the debug output shows the value
415 of the property from each dependency, and whether the value determines
416 the new extreme.
417 Build Specification with Generator Expressions
419 Build specifications may use generator expressions containing content
420 which may be conditional or known only at generate-time. For example,
421 the calculated “compatible” value of a property may be read with the
422 TARGET_PROPERTY expression:
423 add_library(lib1Version2 SHARED lib1_v2.cpp)
425 set_property(TARGET lib1Version2 PROPERTY
426 INTERFACE_CONTAINER_SIZE_REQUIRED 200)
427 set_property(TARGET lib1Version2 APPEND PROPERTY
428 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
429 )
430 add_executable(exe1 exe1.cpp)
432 target_link_libraries(exe1 lib1Version2)
433 target_compile_definitions(exe1 PRIVATE
434 CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
435 )
436 In this case, the exe1 source files will be compiled with -DCON‐
438 TAINER_SIZE=200.
439 Configuration determined build specifications may be conveniently set
441 using the CONFIG generator expression.
442 target_compile_definitions(exe1 PRIVATE
444 $<$<CONFIG:Debug>:DEBUG_BUILD>
445 )
446 The CONFIG parameter is compared case-insensitively with the configura‐
448 tion being built. In the presence of IMPORTED targets, the content of
449 MAP_IMPORTED_CONFIG_DEBUG is also accounted for by this expression.
450 Some buildsystems generated by cmake(1) have a predetermined build-con‐
452 figuration set in the CMAKE_BUILD_TYPE variable. The buildsystem for
453 the IDEs such as Visual Studio and Xcode are generated independent of
454 the build-configuration, and the actual build configuration is not
455 known until build-time. Therefore, code such as
456 string(TOLOWER ${CMAKE_BUILD_TYPE} _type)
458 if (_type STREQUAL debug)
459 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
460 endif()
461 may appear to work for Makefile Generators and Ninja generators, but is
463 not portable to IDE generators. Additionally, the IMPORTED configura‐
464 tion-mappings are not accounted for with code like this, so it should
465 be avoided.
466 The unary TARGET_PROPERTY generator expression and the TARGET_POLICY
468 generator expression are evaluated with the consuming target context.
469 This means that a usage requirement specification may be evaluated dif‐
470 ferently based on the consumer:
471 add_library(lib1 lib1.cpp)
473 target_compile_definitions(lib1 INTERFACE
474 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
475 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
476 $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
477 )
478 add_executable(exe1 exe1.cpp)
480 target_link_libraries(exe1 lib1)
481 cmake_policy(SET CMP0041 NEW)
483 add_library(shared_lib shared_lib.cpp)
485 target_link_libraries(shared_lib lib1)
486 The exe1 executable will be compiled with -DLIB1_WITH_EXE, while the
488 shared_lib shared library will be compiled with -DLIB1_WITH_SHARED_LIB
489 and -DCONSUMER_CMP0041_NEW, because policy CMP0041 is NEW at the point
490 where the shared_lib target is created.
491 The BUILD_INTERFACE expression wraps requirements which are only used
493 when consumed from a target in the same buildsystem, or when consumed
494 from a target exported to the build directory using the export() com‐
495 mand. The INSTALL_INTERFACE expression wraps requirements which are
496 only used when consumed from a target which has been installed and
497 exported with the install(EXPORT) command:
498 add_library(ClimbingStats climbingstats.cpp)
500 target_compile_definitions(ClimbingStats INTERFACE
501 $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
502 $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
503 )
504 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
505 install(EXPORT libExport NAMESPACE Upstream::
506 DESTINATION lib/cmake/ClimbingStats)
507 export(EXPORT libExport NAMESPACE Upstream::)
508 add_executable(exe1 exe1.cpp)
510 target_link_libraries(exe1 ClimbingStats)
511 In this case, the exe1 executable will be compiled with -DClimb‐
513 ingStats_FROM_BUILD_LOCATION. The exporting commands generate IMPORTED
514 targets with either the INSTALL_INTERFACE or the BUILD_INTERFACE omit‐
515 ted, and the *_INTERFACE marker stripped away. A separate project con‐
516 suming the ClimbingStats package would contain:
517 find_package(ClimbingStats REQUIRED)
519 add_executable(Downstream main.cpp)
521 target_link_libraries(Downstream Upstream::ClimbingStats)
522 Depending on whether the ClimbingStats package was used from the build
524 location or the install location, the Downstream target would be com‐
525 piled with either -DClimbingStats_FROM_BUILD_LOCATION or -DClimb‐
526 ingStats_FROM_INSTALL_LOCATION. For more about packages and exporting
527 see the cmake-packages(7) manual.
528 Include Directories and Usage Requirements
530 Include directories require some special consideration when specified
531 as usage requirements and when used with generator expressions. The
532 target_include_directories() command accepts both relative and absolute
533 include directories:
534 add_library(lib1 lib1.cpp)
536 target_include_directories(lib1 PRIVATE
537 /absolute/path
538 relative/path
539 )
540 Relative paths are interpreted relative to the source directory where
542 the command appears. Relative paths are not allowed in the INTER‐
543 FACE_INCLUDE_DIRECTORIES of IMPORTED targets.
544 In cases where a non-trivial generator expression is used, the
546 INSTALL_PREFIX expression may be used within the argument of an
547 INSTALL_INTERFACE expression. It is a replacement marker which expands
548 to the installation prefix when imported by a consuming project.
549 Include directories usage requirements commonly differ between the
551 build-tree and the install-tree. The BUILD_INTERFACE and
552 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
553 rate usage requirements based on the usage location. Relative paths
554 are allowed within the INSTALL_INTERFACE expression and are interpreted
555 relative to the installation prefix. For example:
556 add_library(ClimbingStats climbingstats.cpp)
558 target_include_directories(ClimbingStats INTERFACE
559 $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
560 $<INSTALL_INTERFACE:/absolute/path>
561 $<INSTALL_INTERFACE:relative/path>
562 $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
563 )
564 Two convenience APIs are provided relating to include directories usage
566 requirements. The CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE variable may
567 be enabled, with an equivalent effect to:
568 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
570 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
571 )
572 for each target affected. The convenience for installed targets is an
574 INCLUDES DESTINATION component with the install(TARGETS) command:
575 install(TARGETS foo bar bat EXPORT tgts ${dest_args}
577 INCLUDES DESTINATION include
578 )
579 install(EXPORT tgts ${other_args})
580 install(FILES ${headers} DESTINATION include)
581 This is equivalent to appending ${CMAKE_INSTALL_PREFIX}/include to the
583 INTERFACE_INCLUDE_DIRECTORIES of each of the installed IMPORTED targets
584 when generated by install(EXPORT).
585 When the INTERFACE_INCLUDE_DIRECTORIES of an imported target is con‐
587 sumed, the entries in the property are treated as SYSTEM include direc‐
588 tories, as if they were listed in the INTERFACE_SYSTEM_INCLUDE_DIRECTO‐
589 RIES of the dependency. This can result in omission of compiler warn‐
590 ings for headers found in those directories. This behavior for
591 Imported Targets may be controlled by setting the NO_SYS‐
592 TEM_FROM_IMPORTED target property on the consumers of imported targets.
593 If a binary target is linked transitively to a macOS FRAMEWORK, the
595 Headers directory of the framework is also treated as a usage require‐
596 ment. This has the same effect as passing the framework directory as
597 an include directory.
598 Link Libraries and Generator Expressions
600 Like build specifications, link libraries may be specified with genera‐
601 tor expression conditions. However, as consumption of usage require‐
602 ments is based on collection from linked dependencies, there is an
603 additional limitation that the link dependencies must form a “directed
604 acyclic graph”. That is, if linking to a target is dependent on the
605 value of a target property, that target property may not be dependent
606 on the linked dependencies:
607 add_library(lib1 lib1.cpp)
609 add_library(lib2 lib2.cpp)
610 target_link_libraries(lib1 PUBLIC
611 $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
612 )
613 add_library(lib3 lib3.cpp)
614 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
615 add_executable(exe1 exe1.cpp)
617 target_link_libraries(exe1 lib1 lib3)
618 As the value of the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
620 get is dependent on the linked libraries (lib3), and the edge of link‐
621 ing exe1 is determined by the same POSITION_INDEPENDENT_CODE property,
622 the dependency graph above contains a cycle. cmake(1) issues an error
623 message.
624 Output Artifacts
626 The buildsystem targets created by the add_library() and add_exe‐
627 cutable() commands create rules to create binary outputs. The exact
628 output location of the binaries can only be determined at generate-time
629 because it can depend on the build-configuration and the link-language
630 of linked dependencies etc. TARGET_FILE, TARGET_LINKER_FILE and
631 related expressions can be used to access the name and location of gen‐
632 erated binaries. These expressions do not work for OBJECT libraries
633 however, as there is no single file generated by such libraries which
634 is relevant to the expressions.
635 There are three kinds of output artifacts that may be build by targets
637 as detailed in the following sections. Their classification differs
638 between DLL platforms and non-DLL platforms. All Windows-based systems
639 including Cygwin are DLL platforms.
640 Runtime Output Artifacts
642 A runtime output artifact of a buildsystem target may be:
643 · The executable file (e.g. .exe) of an executable target created by
645 the add_executable() command.
646 · On DLL platforms: the executable file (e.g. .dll) of a shared library
648 target created by the add_library() command with the SHARED option.
649 The RUNTIME_OUTPUT_DIRECTORY and RUNTIME_OUTPUT_NAME target properties
651 may be used to control runtime output artifact locations and names in
652 the build tree.
653 Library Output Artifacts
655 A library output artifact of a buildsystem target may be:
656 · The loadable module file (e.g. .dll or .so) of a module library tar‐
658 get created by the add_library() command with the MODULE option.
659 · On non-DLL platforms: the shared library file (e.g. .so or .dylib) of
661 a shared library target created by the add_library() command with the
662 SHARED option.
663 The LIBRARY_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_NAME target properties
665 may be used to control library output artifact locations and names in
666 the build tree.
667 Archive Output Artifacts
669 An archive output artifact of a buildsystem target may be:
670 · The static library file (e.g. .lib or .a) of a static library target
672 created by the add_library() command with the STATIC option.
673 · On DLL platforms: the import library file (e.g. .lib) of a shared
675 library target created by the add_library() command with the SHARED
676 option. This file is only guaranteed to exist if the library exports
677 at least one unmanaged symbol.
678 · On DLL platforms: the import library file (e.g. .lib) of an exe‐
680 cutable target created by the add_executable() command when its
681 ENABLE_EXPORTS target property is set.
682 · On AIX: the linker import file (e.g. .imp) of an executable target
684 created by the add_executable() command when its ENABLE_EXPORTS tar‐
685 get property is set.
686 The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME target properties
688 may be used to control archive output artifact locations and names in
689 the build tree.
690 Directory-Scoped Commands
692 The target_include_directories(), target_compile_definitions() and tar‐
693 get_compile_options() commands have an effect on only one target at a
694 time. The commands add_compile_definitions(), add_compile_options()
695 and include_directories() have a similar function, but operate at
696 directory scope instead of target scope for convenience.
697
699 Some target types do not represent outputs of the buildsystem, but only
700 inputs such as external dependencies, aliases or other non-build arti‐
701 facts. Pseudo targets are not represented in the generated buildsys‐
702 tem.
703 Imported Targets
705 An IMPORTED target represents a pre-existing dependency. Usually such
706 targets are defined by an upstream package and should be treated as
707 immutable. After declaring an IMPORTED target one can adjust its target
708 properties by using the customary commands such as target_compile_defi‐
709 nitions(), target_include_directories(), target_compile_options() or
710 target_link_libraries() just like with any other regular target.
711 IMPORTED targets may have the same usage requirement properties popu‐
713 lated as binary targets, such as INTERFACE_INCLUDE_DIRECTORIES, INTER‐
714 FACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
715 FACE_LINK_LIBRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.
716 The LOCATION may also be read from an IMPORTED target, though there is
718 rarely reason to do so. Commands such as add_custom_command() can
719 transparently use an IMPORTED EXECUTABLE target as a COMMAND exe‐
720 cutable.
721 The scope of the definition of an IMPORTED target is the directory
723 where it was defined. It may be accessed and used from subdirectories,
724 but not from parent directories or sibling directories. The scope is
725 similar to the scope of a cmake variable.
726 It is also possible to define a GLOBAL IMPORTED target which is acces‐
728 sible globally in the buildsystem.
729 See the cmake-packages(7) manual for more on creating packages with
731 IMPORTED targets.
732 Alias Targets
734 An ALIAS target is a name which may be used interchangeably with a
735 binary target name in read-only contexts. A primary use-case for ALIAS
736 targets is for example or unit test executables accompanying a library,
737 which may be part of the same buildsystem or built separately based on
738 user configuration.
739 add_library(lib1 lib1.cpp)
741 install(TARGETS lib1 EXPORT lib1Export ${dest_args})
742 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
743 add_library(Upstream::lib1 ALIAS lib1)
745 In another directory, we can link unconditionally to the Upstream::lib1
747 target, which may be an IMPORTED target from a package, or an ALIAS
748 target if built as part of the same buildsystem.
749 if (NOT TARGET Upstream::lib1)
751 find_package(lib1 REQUIRED)
752 endif()
753 add_executable(exe1 exe1.cpp)
754 target_link_libraries(exe1 Upstream::lib1)
755 ALIAS targets are not mutable, installable or exportable. They are
757 entirely local to the buildsystem description. A name can be tested
758 for whether it is an ALIAS name by reading the ALIASED_TARGET property
759 from it:
760 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
762 if(_aliased)
763 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
764 endif()
765 Interface Libraries
767 An INTERFACE library target does not compile sources and does not pro‐
768 duce a library artifact on disk, so it has no LOCATION.
769 It may specify usage requirements such as INTERFACE_INCLUDE_DIRECTO‐
771 RIES, INTERFACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
772 FACE_LINK_LIBRARIES, INTERFACE_SOURCES, and INTERFACE_POSITION_INDEPEN‐
773 DENT_CODE. Only the INTERFACE modes of the target_include_directo‐
774 ries(), target_compile_definitions(), target_compile_options(), tar‐
775 get_sources(), and target_link_libraries() commands may be used with
776 INTERFACE libraries.
777 Since CMake 3.19, an INTERFACE library target may optionally contain
779 source files. An interface library that contains source files will be
780 included as a build target in the generated buildsystem. It does not
781 compile sources, but may contain custom commands to generate other
782 sources. Additionally, IDEs will show the source files as part of the
783 target for interactive reading and editing.
784 A primary use-case for INTERFACE libraries is header-only libraries.
786 add_library(Eigen INTERFACE
788 src/eigen.h
789 src/vector.h
790 src/matrix.h
791 )
792 target_include_directories(Eigen INTERFACE
793 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
794 $<INSTALL_INTERFACE:include/Eigen>
795 )
796 add_executable(exe1 exe1.cpp)
798 target_link_libraries(exe1 Eigen)
799 Here, the usage requirements from the Eigen target are consumed and
801 used when compiling, but it has no effect on linking.
802 Another use-case is to employ an entirely target-focussed design for
804 usage requirements:
805 add_library(pic_on INTERFACE)
807 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
808 add_library(pic_off INTERFACE)
809 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
810 add_library(enable_rtti INTERFACE)
812 target_compile_options(enable_rtti INTERFACE
813 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
814 )
815 add_executable(exe1 exe1.cpp)
817 target_link_libraries(exe1 pic_on enable_rtti)
818 This way, the build specification of exe1 is expressed entirely as
820 linked targets, and the complexity of compiler-specific flags is encap‐
821 sulated in an INTERFACE library target.
822 INTERFACE libraries may be installed and exported. Any content they
824 refer to must be installed separately:
825 set(Eigen_headers
827 src/eigen.h
828 src/vector.h
829 src/matrix.h
830 )
831 add_library(Eigen INTERFACE ${Eigen_headers})
832 target_include_directories(Eigen INTERFACE
833 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
834 $<INSTALL_INTERFACE:include/Eigen>
835 )
836 install(TARGETS Eigen EXPORT eigenExport)
838 install(EXPORT eigenExport NAMESPACE Upstream::
839 DESTINATION lib/cmake/Eigen
840 )
841 install(FILES ${Eigen_headers}
842 DESTINATION include/Eigen
843 )
844
846 2000-2021 Kitware, Inc. and Contributors
8473.19.7 Mar 15, 2021 CMAKE-BUILDSYSTEM(7)