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. The MACOSX_FRAMEWORK_IDENTI‐
69 FIER sets CFBundleIdentifier key and it uniquely identifies the bundle.
70 add_library(MyFramework SHARED MyFramework.cpp)
72 set_target_properties(MyFramework PROPERTIES
73 FRAMEWORK TRUE
74 FRAMEWORK_VERSION A
75 MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
76 )
77 Object Libraries
79 The OBJECT library type defines a non-archival collection of object
80 files resulting from compiling the given source files. The object
81 files collection may be used as source inputs to other targets:
82 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
84 add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
86 add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
88 The link (or archiving) step of those other targets will use the object
90 files collection in addition to those from their own sources.
91 Alternatively, object libraries may be linked into other targets:
93 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
95 add_library(archiveExtras STATIC extras.cpp)
97 target_link_libraries(archiveExtras PUBLIC archive)
98 add_executable(test_exe test.cpp)
100 target_link_libraries(test_exe archive)
101 The link (or archiving) step of those other targets will use the object
103 files from OBJECT libraries that are directly linked. Additionally,
104 usage requirements of the OBJECT libraries will be honored when compil‐
105 ing sources in those other targets. Furthermore, those usage require‐
106 ments will propagate transitively to dependents of those other targets.
107 Object libraries may not be used as the TARGET in a use of the add_cus‐
109 tom_command(TARGET) command signature. However, the list of objects
110 can be used by add_custom_command(OUTPUT) or file(GENERATE) by using
111 $<TARGET_OBJECTS:objlib>.
112
114 The target_include_directories(), target_compile_definitions() and tar‐
115 get_compile_options() commands specify the build specifications and the
116 usage requirements of binary targets. The commands populate the
117 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS target
118 properties respectively, and/or the INTERFACE_INCLUDE_DIRECTORIES,
119 INTERFACE_COMPILE_DEFINITIONS and INTERFACE_COMPILE_OPTIONS target
120 properties.
121 Each of the commands has a PRIVATE, PUBLIC and INTERFACE mode. The
123 PRIVATE mode populates only the non-INTERFACE_ variant of the target
124 property and the INTERFACE mode populates only the INTERFACE_ variants.
125 The PUBLIC mode populates both variants of the respective target prop‐
126 erty. Each command may be invoked with multiple uses of each keyword:
127 target_compile_definitions(archive
129 PRIVATE BUILDING_WITH_LZMA
130 INTERFACE USING_ARCHIVE_LIB
131 )
132 Note that usage requirements are not designed as a way to make down‐
134 streams use particular COMPILE_OPTIONS or COMPILE_DEFINITIONS etc for
135 convenience only. The contents of the properties must be requirements,
136 not merely recommendations or convenience.
137 See the Creating Relocatable Packages section of the cmake-packages(7)
139 manual for discussion of additional care that must be taken when speci‐
140 fying usage requirements while creating packages for redistribution.
141 Target Properties
143 The contents of the INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
144 PILE_OPTIONS target properties are used appropriately when compiling
145 the source files of a binary target.
146 Entries in the INCLUDE_DIRECTORIES are added to the compile line with
148 -I or -isystem prefixes and in the order of appearance in the property
149 value.
150 Entries in the COMPILE_DEFINITIONS are prefixed with -D or /D and added
152 to the compile line in an unspecified order. The DEFINE_SYMBOL target
153 property is also added as a compile definition as a special convenience
154 case for SHARED and MODULE library targets.
155 Entries in the COMPILE_OPTIONS are escaped for the shell and added in
157 the order of appearance in the property value. Several compile options
158 have special separate handling, such as POSITION_INDEPENDENT_CODE.
159 The contents of the INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COM‐
161 PILE_DEFINITIONS and INTERFACE_COMPILE_OPTIONS target properties are
162 Usage Requirements – they specify content which consumers must use to
163 correctly compile and link with the target they appear on. For any
164 binary target, the contents of each INTERFACE_ property on each target
165 specified in a target_link_libraries() command is consumed:
166 set(srcs archive.cpp zip.cpp)
168 if (LZMA_FOUND)
169 list(APPEND srcs lzma.cpp)
170 endif()
171 add_library(archive SHARED ${srcs})
172 if (LZMA_FOUND)
173 # The archive library sources are compiled with -DBUILDING_WITH_LZMA
174 target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
175 endif()
176 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
177 add_executable(consumer)
179 # Link consumer to archive and consume its usage requirements. The consumer
180 # executable sources are compiled with -DUSING_ARCHIVE_LIB.
181 target_link_libraries(consumer archive)
182 Because it is common to require that the source directory and corre‐
184 sponding build directory are added to the INCLUDE_DIRECTORIES, the
185 CMAKE_INCLUDE_CURRENT_DIR variable can be enabled to conveniently add
186 the corresponding directories to the INCLUDE_DIRECTORIES of all tar‐
187 gets. The variable CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE can be
188 enabled to add the corresponding directories to the INTER‐
189 FACE_INCLUDE_DIRECTORIES of all targets. This makes use of targets in
190 multiple different directories convenient through use of the tar‐
191 get_link_libraries() command.
192 Transitive Usage Requirements
194 The usage requirements of a target can transitively propagate to depen‐
195 dents. The target_link_libraries() command has PRIVATE, INTERFACE and
196 PUBLIC keywords to control the propagation.
197 add_library(archive archive.cpp)
199 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
200 add_library(serialization serialization.cpp)
202 target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
203 add_library(archiveExtras extras.cpp)
205 target_link_libraries(archiveExtras PUBLIC archive)
206 target_link_libraries(archiveExtras PRIVATE serialization)
207 # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
208 # and -DUSING_SERIALIZATION_LIB
209 add_executable(consumer consumer.cpp)
211 # consumer is compiled with -DUSING_ARCHIVE_LIB
212 target_link_libraries(consumer archiveExtras)
213 Because archive is a PUBLIC dependency of archiveExtras, the usage
215 requirements of it are propagated to consumer too. Because serializa‐
216 tion is a PRIVATE dependency of archiveExtras, the usage requirements
217 of it are not propagated to consumer.
218 Generally, a dependency should be specified in a use of tar‐
220 get_link_libraries() with the PRIVATE keyword if it is used by only the
221 implementation of a library, and not in the header files. If a depen‐
222 dency is additionally used in the header files of a library (e.g. for
223 class inheritance), then it should be specified as a PUBLIC dependency.
224 A dependency which is not used by the implementation of a library, but
225 only by its headers should be specified as an INTERFACE dependency.
226 The target_link_libraries() command may be invoked with multiple uses
227 of each keyword:
228 target_link_libraries(archiveExtras
230 PUBLIC archive
231 PRIVATE serialization
232 )
233 Usage requirements are propagated by reading the INTERFACE_ variants of
235 target properties from dependencies and appending the values to the
236 non-INTERFACE_ variants of the operand. For example, the INTER‐
237 FACE_INCLUDE_DIRECTORIES of dependencies is read and appended to the
238 INCLUDE_DIRECTORIES of the operand. In cases where order is relevant
239 and maintained, and the order resulting from the tar‐
240 get_link_libraries() calls does not allow correct compilation, use of
241 an appropriate command to set the property directly may update the
242 order.
243 For example, if the linked libraries for a target must be specified in
245 the order lib1 lib2 lib3 , but the include directories must be speci‐
246 fied in the order lib3 lib1 lib2:
247 target_link_libraries(myExe lib1 lib2 lib3)
249 target_include_directories(myExe
250 PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
251 Note that care must be taken when specifying usage requirements for
253 targets which will be exported for installation using the
254 install(EXPORT) command. See Creating Packages for more.
255 Compatible Interface Properties
257 Some target properties are required to be compatible between a target
258 and the interface of each dependency. For example, the POSITION_INDE‐
259 PENDENT_CODE target property may specify a boolean value of whether a
260 target should be compiled as position-independent-code, which has plat‐
261 form-specific consequences. A target may also specify the usage
262 requirement INTERFACE_POSITION_INDEPENDENT_CODE to communicate that
263 consumers must be compiled as position-independent-code.
264 add_executable(exe1 exe1.cpp)
266 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
267 add_library(lib1 SHARED lib1.cpp)
269 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
270 add_executable(exe2 exe2.cpp)
272 target_link_libraries(exe2 lib1)
273 Here, both exe1 and exe2 will be compiled as position-independent-code.
275 lib1 will also be compiled as position-independent-code because that is
276 the default setting for SHARED libraries. If dependencies have con‐
277 flicting, non-compatible requirements cmake(1) issues a diagnostic:
278 add_library(lib1 SHARED lib1.cpp)
280 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
281 add_library(lib2 SHARED lib2.cpp)
283 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
284 add_executable(exe1 exe1.cpp)
286 target_link_libraries(exe1 lib1)
287 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
288 add_executable(exe2 exe2.cpp)
290 target_link_libraries(exe2 lib1 lib2)
291 The lib1 requirement INTERFACE_POSITION_INDEPENDENT_CODE is not “com‐
293 patible” with the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
294 get. The library requires that consumers are built as position-inde‐
295 pendent-code, while the executable specifies to not built as posi‐
296 tion-independent-code, so a diagnostic is issued.
297 The lib1 and lib2 requirements are not “compatible”. One of them
299 requires that consumers are built as position-independent-code, while
300 the other requires that consumers are not built as position-indepen‐
301 dent-code. Because exe2 links to both and they are in conflict, a
302 diagnostic is issued.
303 To be “compatible”, the POSITION_INDEPENDENT_CODE property, if set must
305 be either the same, in a boolean sense, as the INTERFACE_POSITION_INDE‐
306 PENDENT_CODE property of all transitively specified dependencies on
307 which that property is set.
308 This property of “compatible interface requirement” may be extended to
310 other properties by specifying the property in the content of the COM‐
311 PATIBLE_INTERFACE_BOOL target property. Each specified property must
312 be compatible between the consuming target and the corresponding prop‐
313 erty with an INTERFACE_ prefix from each dependency:
314 add_library(lib1Version2 SHARED lib1_v2.cpp)
316 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
317 set_property(TARGET lib1Version2 APPEND PROPERTY
318 COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
319 )
320 add_library(lib1Version3 SHARED lib1_v3.cpp)
322 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
323 add_executable(exe1 exe1.cpp)
325 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
326 add_executable(exe2 exe2.cpp)
328 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
329 Non-boolean properties may also participate in “compatible interface”
331 computations. Properties specified in the COMPATIBLE_INTERFACE_STRING
332 property must be either unspecified or compare to the same string among
333 all transitively specified dependencies. This can be useful to ensure
334 that multiple incompatible versions of a library are not linked
335 together through transitive requirements of a target:
336 add_library(lib1Version2 SHARED lib1_v2.cpp)
338 set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
339 set_property(TARGET lib1Version2 APPEND PROPERTY
340 COMPATIBLE_INTERFACE_STRING LIB_VERSION
341 )
342 add_library(lib1Version3 SHARED lib1_v3.cpp)
344 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
345 add_executable(exe1 exe1.cpp)
347 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
348 add_executable(exe2 exe2.cpp)
350 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
351 The COMPATIBLE_INTERFACE_NUMBER_MAX target property specifies that con‐
353 tent will be evaluated numerically and the maximum number among all
354 specified will be calculated:
355 add_library(lib1Version2 SHARED lib1_v2.cpp)
357 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
358 set_property(TARGET lib1Version2 APPEND PROPERTY
359 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
360 )
361 add_library(lib1Version3 SHARED lib1_v3.cpp)
363 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
364 add_executable(exe1 exe1.cpp)
366 # CONTAINER_SIZE_REQUIRED will be "200"
367 target_link_libraries(exe1 lib1Version2)
368 add_executable(exe2 exe2.cpp)
370 # CONTAINER_SIZE_REQUIRED will be "1000"
371 target_link_libraries(exe2 lib1Version2 lib1Version3)
372 Similarly, the COMPATIBLE_INTERFACE_NUMBER_MIN may be used to calculate
374 the numeric minimum value for a property from dependencies.
375 Each calculated “compatible” property value may be read in the consumer
377 at generate-time using generator expressions.
378 Note that for each dependee, the set of properties specified in each
380 compatible interface property must not intersect with the set specified
381 in any of the other properties.
382 Property Origin Debugging
384 Because build specifications can be determined by dependencies, the
385 lack of locality of code which creates a target and code which is
386 responsible for setting build specifications may make the code more
387 difficult to reason about. cmake(1) provides a debugging facility to
388 print the origin of the contents of properties which may be determined
389 by dependencies. The properties which can be debugged are listed in
390 the CMAKE_DEBUG_TARGET_PROPERTIES variable documentation:
391 set(CMAKE_DEBUG_TARGET_PROPERTIES
393 INCLUDE_DIRECTORIES
394 COMPILE_DEFINITIONS
395 POSITION_INDEPENDENT_CODE
396 CONTAINER_SIZE_REQUIRED
397 LIB_VERSION
398 )
399 add_executable(exe1 exe1.cpp)
400 In the case of properties listed in COMPATIBLE_INTERFACE_BOOL or COM‐
402 PATIBLE_INTERFACE_STRING, the debug output shows which target was
403 responsible for setting the property, and which other dependencies also
404 defined the property. In the case of COMPATIBLE_INTERFACE_NUMBER_MAX
405 and COMPATIBLE_INTERFACE_NUMBER_MIN, the debug output shows the value
406 of the property from each dependency, and whether the value determines
407 the new extreme.
408 Build Specification with Generator Expressions
410 Build specifications may use generator expressions containing content
411 which may be conditional or known only at generate-time. For example,
412 the calculated “compatible” value of a property may be read with the
413 TARGET_PROPERTY expression:
414 add_library(lib1Version2 SHARED lib1_v2.cpp)
416 set_property(TARGET lib1Version2 PROPERTY
417 INTERFACE_CONTAINER_SIZE_REQUIRED 200)
418 set_property(TARGET lib1Version2 APPEND PROPERTY
419 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
420 )
421 add_executable(exe1 exe1.cpp)
423 target_link_libraries(exe1 lib1Version2)
424 target_compile_definitions(exe1 PRIVATE
425 CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
426 )
427 In this case, the exe1 source files will be compiled with -DCON‐
429 TAINER_SIZE=200.
430 Configuration determined build specifications may be conveniently set
432 using the CONFIG generator expression.
433 target_compile_definitions(exe1 PRIVATE
435 $<$<CONFIG:Debug>:DEBUG_BUILD>
436 )
437 The CONFIG parameter is compared case-insensitively with the configura‐
439 tion being built. In the presence of IMPORTED targets, the content of
440 MAP_IMPORTED_CONFIG_DEBUG is also accounted for by this expression.
441 Some buildsystems generated by cmake(1) have a predetermined build-con‐
443 figuration set in the CMAKE_BUILD_TYPE variable. The buildsystem for
444 the IDEs such as Visual Studio and Xcode are generated independent of
445 the build-configuration, and the actual build configuration is not
446 known until build-time. Therefore, code such as
447 string(TOLOWER ${CMAKE_BUILD_TYPE} _type)
449 if (_type STREQUAL debug)
450 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
451 endif()
452 may appear to work for Makefile Generators and Ninja generators, but is
454 not portable to IDE generators. Additionally, the IMPORTED configura‐
455 tion-mappings are not accounted for with code like this, so it should
456 be avoided.
457 The unary TARGET_PROPERTY generator expression and the TARGET_POLICY
459 generator expression are evaluated with the consuming target context.
460 This means that a usage requirement specification may be evaluated dif‐
461 ferently based on the consumer:
462 add_library(lib1 lib1.cpp)
464 target_compile_definitions(lib1 INTERFACE
465 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
466 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
467 $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
468 )
469 add_executable(exe1 exe1.cpp)
471 target_link_libraries(exe1 lib1)
472 cmake_policy(SET CMP0041 NEW)
474 add_library(shared_lib shared_lib.cpp)
476 target_link_libraries(shared_lib lib1)
477 The exe1 executable will be compiled with -DLIB1_WITH_EXE, while the
479 shared_lib shared library will be compiled with -DLIB1_WITH_SHARED_LIB
480 and -DCONSUMER_CMP0041_NEW, because policy CMP0041 is NEW at the point
481 where the shared_lib target is created.
482 The BUILD_INTERFACE expression wraps requirements which are only used
484 when consumed from a target in the same buildsystem, or when consumed
485 from a target exported to the build directory using the export() com‐
486 mand. The INSTALL_INTERFACE expression wraps requirements which are
487 only used when consumed from a target which has been installed and
488 exported with the install(EXPORT) command:
489 add_library(ClimbingStats climbingstats.cpp)
491 target_compile_definitions(ClimbingStats INTERFACE
492 $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
493 $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
494 )
495 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
496 install(EXPORT libExport NAMESPACE Upstream::
497 DESTINATION lib/cmake/ClimbingStats)
498 export(EXPORT libExport NAMESPACE Upstream::)
499 add_executable(exe1 exe1.cpp)
501 target_link_libraries(exe1 ClimbingStats)
502 In this case, the exe1 executable will be compiled with -DClimb‐
504 ingStats_FROM_BUILD_LOCATION. The exporting commands generate IMPORTED
505 targets with either the INSTALL_INTERFACE or the BUILD_INTERFACE omit‐
506 ted, and the *_INTERFACE marker stripped away. A separate project con‐
507 suming the ClimbingStats package would contain:
508 find_package(ClimbingStats REQUIRED)
510 add_executable(Downstream main.cpp)
512 target_link_libraries(Downstream Upstream::ClimbingStats)
513 Depending on whether the ClimbingStats package was used from the build
515 location or the install location, the Downstream target would be com‐
516 piled with either -DClimbingStats_FROM_BUILD_LOCATION or -DClimb‐
517 ingStats_FROM_INSTALL_LOCATION. For more about packages and exporting
518 see the cmake-packages(7) manual.
519 Include Directories and Usage Requirements
521 Include directories require some special consideration when specified
522 as usage requirements and when used with generator expressions. The
523 target_include_directories() command accepts both relative and absolute
524 include directories:
525 add_library(lib1 lib1.cpp)
527 target_include_directories(lib1 PRIVATE
528 /absolute/path
529 relative/path
530 )
531 Relative paths are interpreted relative to the source directory where
533 the command appears. Relative paths are not allowed in the INTER‐
534 FACE_INCLUDE_DIRECTORIES of IMPORTED targets.
535 In cases where a non-trivial generator expression is used, the
537 INSTALL_PREFIX expression may be used within the argument of an
538 INSTALL_INTERFACE expression. It is a replacement marker which expands
539 to the installation prefix when imported by a consuming project.
540 Include directories usage requirements commonly differ between the
542 build-tree and the install-tree. The BUILD_INTERFACE and
543 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
544 rate usage requirements based on the usage location. Relative paths
545 are allowed within the INSTALL_INTERFACE expression and are interpreted
546 relative to the installation prefix. For example:
547 add_library(ClimbingStats climbingstats.cpp)
549 target_include_directories(ClimbingStats INTERFACE
550 $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
551 $<INSTALL_INTERFACE:/absolute/path>
552 $<INSTALL_INTERFACE:relative/path>
553 $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
554 )
555 Two convenience APIs are provided relating to include directories usage
557 requirements. The CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE variable may
558 be enabled, with an equivalent effect to:
559 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
561 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
562 )
563 for each target affected. The convenience for installed targets is an
565 INCLUDES DESTINATION component with the install(TARGETS) command:
566 install(TARGETS foo bar bat EXPORT tgts ${dest_args}
568 INCLUDES DESTINATION include
569 )
570 install(EXPORT tgts ${other_args})
571 install(FILES ${headers} DESTINATION include)
572 This is equivalent to appending ${CMAKE_INSTALL_PREFIX}/include to the
574 INTERFACE_INCLUDE_DIRECTORIES of each of the installed IMPORTED targets
575 when generated by install(EXPORT).
576 When the INTERFACE_INCLUDE_DIRECTORIES of an imported target is con‐
578 sumed, the entries in the property are treated as SYSTEM include direc‐
579 tories, as if they were listed in the INTERFACE_SYSTEM_INCLUDE_DIRECTO‐
580 RIES of the dependency. This can result in omission of compiler warn‐
581 ings for headers found in those directories. This behavior for
582 Imported Targets may be controlled by setting the NO_SYS‐
583 TEM_FROM_IMPORTED target property on the consumers of imported targets.
584 If a binary target is linked transitively to a macOS FRAMEWORK, the
586 Headers directory of the framework is also treated as a usage require‐
587 ment. This has the same effect as passing the framework directory as
588 an include directory.
589 Link Libraries and Generator Expressions
591 Like build specifications, link libraries may be specified with genera‐
592 tor expression conditions. However, as consumption of usage require‐
593 ments is based on collection from linked dependencies, there is an
594 additional limitation that the link dependencies must form a “directed
595 acyclic graph”. That is, if linking to a target is dependent on the
596 value of a target property, that target property may not be dependent
597 on the linked dependencies:
598 add_library(lib1 lib1.cpp)
600 add_library(lib2 lib2.cpp)
601 target_link_libraries(lib1 PUBLIC
602 $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
603 )
604 add_library(lib3 lib3.cpp)
605 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
606 add_executable(exe1 exe1.cpp)
608 target_link_libraries(exe1 lib1 lib3)
609 As the value of the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
611 get is dependent on the linked libraries (lib3), and the edge of link‐
612 ing exe1 is determined by the same POSITION_INDEPENDENT_CODE property,
613 the dependency graph above contains a cycle. cmake(1) issues a diag‐
614 nostic in this case.
615 Output Artifacts
617 The buildsystem targets created by the add_library() and add_exe‐
618 cutable() commands create rules to create binary outputs. The exact
619 output location of the binaries can only be determined at generate-time
620 because it can depend on the build-configuration and the link-language
621 of linked dependencies etc. TARGET_FILE, TARGET_LINKER_FILE and
622 related expressions can be used to access the name and location of gen‐
623 erated binaries. These expressions do not work for OBJECT libraries
624 however, as there is no single file generated by such libraries which
625 is relevant to the expressions.
626 There are three kinds of output artifacts that may be build by targets
628 as detailed in the following sections. Their classification differs
629 between DLL platforms and non-DLL platforms. All Windows-based systems
630 including Cygwin are DLL platforms.
631 Runtime Output Artifacts
633 A runtime output artifact of a buildsystem target may be:
634 · The executable file (e.g. .exe) of an executable target created by
636 the add_executable() command.
637 · On DLL platforms: the executable file (e.g. .dll) of a shared library
639 target created by the add_library() command with the SHARED option.
640 The RUNTIME_OUTPUT_DIRECTORY and RUNTIME_OUTPUT_NAME target properties
642 may be used to control runtime output artifact locations and names in
643 the build tree.
644 Library Output Artifacts
646 A library output artifact of a buildsystem target may be:
647 · The loadable module file (e.g. .dll or .so) of a module library tar‐
649 get created by the add_library() command with the MODULE option.
650 · On non-DLL platforms: the shared library file (e.g. .so or .dylib) of
652 a shared library target created by the add_library() command with the
653 SHARED option.
654 The LIBRARY_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_NAME target properties
656 may be used to control library output artifact locations and names in
657 the build tree.
658 Archive Output Artifacts
660 An archive output artifact of a buildsystem target may be:
661 · The static library file (e.g. .lib or .a) of a static library target
663 created by the add_library() command with the STATIC option.
664 · On DLL platforms: the import library file (e.g. .lib) of a shared
666 library target created by the add_library() command with the SHARED
667 option. This file is only guaranteed to exist if the library exports
668 at least one unmanaged symbol.
669 · On DLL platforms: the import library file (e.g. .lib) of an exe‐
671 cutable target created by the add_executable() command when its
672 ENABLE_EXPORTS target property is set.
673 · On AIX: the linker import file (e.g. .imp) of an executable target
675 created by the add_executable() command when its ENABLE_EXPORTS tar‐
676 get property is set.
677 The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME target properties
679 may be used to control archive output artifact locations and names in
680 the build tree.
681 Directory-Scoped Commands
683 The target_include_directories(), target_compile_definitions() and tar‐
684 get_compile_options() commands have an effect on only one target at a
685 time. The commands add_compile_definitions(), add_compile_options()
686 and include_directories() have a similar function, but operate at
687 directory scope instead of target scope for convenience.
688
690 Some target types do not represent outputs of the buildsystem, but only
691 inputs such as external dependencies, aliases or other non-build arti‐
692 facts. Pseudo targets are not represented in the generated buildsys‐
693 tem.
694 Imported Targets
696 An IMPORTED target represents a pre-existing dependency. Usually such
697 targets are defined by an upstream package and should be treated as
698 immutable. After declaring an IMPORTED target one can adjust its target
699 properties by using the customary commands such as target_compile_defi‐
700 nitions(), target_include_directories(), target_compile_options() or
701 target_link_libraries() just like with any other regular target.
702 IMPORTED targets may have the same usage requirement properties popu‐
704 lated as binary targets, such as INTERFACE_INCLUDE_DIRECTORIES, INTER‐
705 FACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
706 FACE_LINK_LIBRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.
707 The LOCATION may also be read from an IMPORTED target, though there is
709 rarely reason to do so. Commands such as add_custom_command() can
710 transparently use an IMPORTED EXECUTABLE target as a COMMAND exe‐
711 cutable.
712 The scope of the definition of an IMPORTED target is the directory
714 where it was defined. It may be accessed and used from subdirectories,
715 but not from parent directories or sibling directories. The scope is
716 similar to the scope of a cmake variable.
717 It is also possible to define a GLOBAL IMPORTED target which is acces‐
719 sible globally in the buildsystem.
720 See the cmake-packages(7) manual for more on creating packages with
722 IMPORTED targets.
723 Alias Targets
725 An ALIAS target is a name which may be used interchangeably with a
726 binary target name in read-only contexts. A primary use-case for ALIAS
727 targets is for example or unit test executables accompanying a library,
728 which may be part of the same buildsystem or built separately based on
729 user configuration.
730 add_library(lib1 lib1.cpp)
732 install(TARGETS lib1 EXPORT lib1Export ${dest_args})
733 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
734 add_library(Upstream::lib1 ALIAS lib1)
736 In another directory, we can link unconditionally to the Upstream::lib1
738 target, which may be an IMPORTED target from a package, or an ALIAS
739 target if built as part of the same buildsystem.
740 if (NOT TARGET Upstream::lib1)
742 find_package(lib1 REQUIRED)
743 endif()
744 add_executable(exe1 exe1.cpp)
745 target_link_libraries(exe1 Upstream::lib1)
746 ALIAS targets are not mutable, installable or exportable. They are
748 entirely local to the buildsystem description. A name can be tested
749 for whether it is an ALIAS name by reading the ALIASED_TARGET property
750 from it:
751 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
753 if(_aliased)
754 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
755 endif()
756 Interface Libraries
758 An INTERFACE target has no LOCATION and is mutable, but is otherwise
759 similar to an IMPORTED target.
760 It may specify usage requirements such as INTERFACE_INCLUDE_DIRECTO‐
762 RIES, INTERFACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
763 FACE_LINK_LIBRARIES, INTERFACE_SOURCES, and INTERFACE_POSITION_INDEPEN‐
764 DENT_CODE. Only the INTERFACE modes of the target_include_directo‐
765 ries(), target_compile_definitions(), target_compile_options(), tar‐
766 get_sources(), and target_link_libraries() commands may be used with
767 INTERFACE libraries.
768 A primary use-case for INTERFACE libraries is header-only libraries.
770 add_library(Eigen INTERFACE)
772 target_include_directories(Eigen INTERFACE
773 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
774 $<INSTALL_INTERFACE:include/Eigen>
775 )
776 add_executable(exe1 exe1.cpp)
778 target_link_libraries(exe1 Eigen)
779 Here, the usage requirements from the Eigen target are consumed and
781 used when compiling, but it has no effect on linking.
782 Another use-case is to employ an entirely target-focussed design for
784 usage requirements:
785 add_library(pic_on INTERFACE)
787 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
788 add_library(pic_off INTERFACE)
789 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
790 add_library(enable_rtti INTERFACE)
792 target_compile_options(enable_rtti INTERFACE
793 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
794 )
795 add_executable(exe1 exe1.cpp)
797 target_link_libraries(exe1 pic_on enable_rtti)
798 This way, the build specification of exe1 is expressed entirely as
800 linked targets, and the complexity of compiler-specific flags is encap‐
801 sulated in an INTERFACE library target.
802 The properties permitted to be set on or read from an INTERFACE library
804 are:
805 · Properties matching INTERFACE_*
807 · Built-in properties matching COMPATIBLE_INTERFACE_*
809 · EXPORT_NAME
811 · EXPORT_PROPERTIES
813 · IMPORTED
815 · MANUALLY_ADDED_DEPENDENCIES
817 · NAME
819 · Properties matching IMPORTED_LIBNAME_*
821 · Properties matching MAP_IMPORTED_CONFIG_*
823 INTERFACE libraries may be installed and exported. Any content they
825 refer to must be installed separately:
826 add_library(Eigen INTERFACE)
828 target_include_directories(Eigen INTERFACE
829 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
830 $<INSTALL_INTERFACE:include/Eigen>
831 )
832 install(TARGETS Eigen EXPORT eigenExport)
834 install(EXPORT eigenExport NAMESPACE Upstream::
835 DESTINATION lib/cmake/Eigen
836 )
837 install(FILES
838 ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h
839 ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h
840 ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h
841 DESTINATION include/Eigen
842 )
843
845 2000-2019 Kitware, Inc. and Contributors
8463.16.1 Dec 14, 2019 CMAKE-BUILDSYSTEM(7)