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 prefixes, suffixes and extensions for the platform targeted. Dependen‐
19 cies between binary targets are expressed using the tar‐
20 get_link_libraries() 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 OS X 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 is also not linked to. It defines a
80 non-archival collection of object files resulting from compiling the
81 given source files. The object files collection can be used as source
82 inputs to other targets:
83 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
85 add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
87 add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
89 OBJECT libraries may not be used in the right hand side of tar‐
91 get_link_libraries(). They also may not be used as the TARGET in a use
92 of the add_custom_command(TARGET) command signature. They may be
93 installed, and will be exported as an INTERFACE library.
94 Although object libraries may not be named directly in calls to the
96 target_link_libraries() command, they can be “linked” indirectly by
97 using an Interface Library whose INTERFACE_SOURCES target property is
98 set to name $<TARGET_OBJECTS:objlib>.
99 Although object libraries may not be used as the TARGET in a use of the
101 add_custom_command(TARGET) command signature, the list of objects can
102 be used by add_custom_command(OUTPUT) or file(GENERATE) by using $<TAR‐
103 GET_OBJECTS:objlib>.
104
106 The target_include_directories(), target_compile_definitions() and tar‐
107 get_compile_options() commands specify the build specifications and the
108 usage requirements of binary targets. The commands populate the
109 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS target
110 properties respectively, and/or the INTERFACE_INCLUDE_DIRECTORIES,
111 INTERFACE_COMPILE_DEFINITIONS and INTERFACE_COMPILE_OPTIONS target
112 properties.
113 Each of the commands has a PRIVATE, PUBLIC and INTERFACE mode. The
115 PRIVATE mode populates only the non-INTERFACE_ variant of the target
116 property and the INTERFACE mode populates only the INTERFACE_ variants.
117 The PUBLIC mode populates both variants of the respective target prop‐
118 erty. Each command may be invoked with multiple uses of each keyword:
119 target_compile_definitions(archive
121 PRIVATE BUILDING_WITH_LZMA
122 INTERFACE USING_ARCHIVE_LIB
123 )
124 Note that usage requirements are not designed as a way to make down‐
126 streams use particular COMPILE_OPTIONS or COMPILE_DEFINITIONS etc for
127 convenience only. The contents of the properties must be requirements,
128 not merely recommendations or convenience.
129 See the Creating Relocatable Packages section of the cmake-packages(7)
131 manual for discussion of additional care that must be taken when speci‐
132 fying usage requirements while creating packages for redistribution.
133 Target Properties
135 The contents of the INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
136 PILE_OPTIONS target properties are used appropriately when compiling
137 the source files of a binary target.
138 Entries in the INCLUDE_DIRECTORIES are added to the compile line with
140 -I or -isystem prefixes and in the order of appearance in the property
141 value.
142 Entries in the COMPILE_DEFINITIONS are prefixed with -D or /D and added
144 to the compile line in an unspecified order. The DEFINE_SYMBOL target
145 property is also added as a compile definition as a special convenience
146 case for SHARED and MODULE library targets.
147 Entries in the COMPILE_OPTIONS are escaped for the shell and added in
149 the order of appearance in the property value. Several compile options
150 have special separate handling, such as POSITION_INDEPENDENT_CODE.
151 The contents of the INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COM‐
153 PILE_DEFINITIONS and INTERFACE_COMPILE_OPTIONS target properties are
154 Usage Requirements – they specify content which consumers must use to
155 correctly compile and link with the target they appear on. For any
156 binary target, the contents of each INTERFACE_ property on each target
157 specified in a target_link_libraries() command is consumed:
158 set(srcs archive.cpp zip.cpp)
160 if (LZMA_FOUND)
161 list(APPEND srcs lzma.cpp)
162 endif()
163 add_library(archive SHARED ${srcs})
164 if (LZMA_FOUND)
165 # The archive library sources are compiled with -DBUILDING_WITH_LZMA
166 target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
167 endif()
168 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
169 add_executable(consumer)
171 # Link consumer to archive and consume its usage requirements. The consumer
172 # executable sources are compiled with -DUSING_ARCHIVE_LIB.
173 target_link_libraries(consumer archive)
174 Because it is common to require that the source directory and corre‐
176 sponding build directory are added to the INCLUDE_DIRECTORIES, the
177 CMAKE_INCLUDE_CURRENT_DIR variable can be enabled to conveniently add
178 the corresponding directories to the INCLUDE_DIRECTORIES of all tar‐
179 gets. The variable CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE can be
180 enabled to add the corresponding directories to the INTER‐
181 FACE_INCLUDE_DIRECTORIES of all targets. This makes use of targets in
182 multiple different directories convenient through use of the tar‐
183 get_link_libraries() command.
184 Transitive Usage Requirements
186 The usage requirements of a target can transitively propagate to depen‐
187 dents. The target_link_libraries() command has PRIVATE, INTERFACE and
188 PUBLIC keywords to control the propagation.
189 add_library(archive archive.cpp)
191 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
192 add_library(serialization serialization.cpp)
194 target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
195 add_library(archiveExtras extras.cpp)
197 target_link_libraries(archiveExtras PUBLIC archive)
198 target_link_libraries(archiveExtras PRIVATE serialization)
199 # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
200 # and -DUSING_SERIALIZATION_LIB
201 add_executable(consumer consumer.cpp)
203 # consumer is compiled with -DUSING_ARCHIVE_LIB
204 target_link_libraries(consumer archiveExtras)
205 Because archive is a PUBLIC dependency of archiveExtras, the usage
207 requirements of it are propagated to consumer too. Because serializa‐
208 tion is a PRIVATE dependency of archiveExtras, the usage requirements
209 of it are not propagated to consumer.
210 Generally, a dependency should be specified in a use of tar‐
212 get_link_libraries() with the PRIVATE keyword if it is used by only the
213 implementation of a library, and not in the header files. If a depen‐
214 dency is additionally used in the header files of a library (e.g. for
215 class inheritance), then it should be specified as a PUBLIC dependency.
216 A dependency which is not used by the implementation of a library, but
217 only by its headers should be specified as an INTERFACE dependency.
218 The target_link_libraries() command may be invoked with multiple uses
219 of each keyword:
220 target_link_libraries(archiveExtras
222 PUBLIC archive
223 PRIVATE serialization
224 )
225 Usage requirements are propagated by reading the INTERFACE_ variants of
227 target properties from dependencies and appending the values to the
228 non-INTERFACE_ variants of the operand. For example, the INTER‐
229 FACE_INCLUDE_DIRECTORIES of dependencies is read and appended to the
230 INCLUDE_DIRECTORIES of the operand. In cases where order is relevant
231 and maintained, and the order resulting from the tar‐
232 get_link_libraries() calls does not allow correct compilation, use of
233 an appropriate command to set the property directly may update the
234 order.
235 For example, if the linked libraries for a target must be specified in
237 the order lib1 lib2 lib3 , but the include directories must be speci‐
238 fied in the order lib3 lib1 lib2:
239 target_link_libraries(myExe lib1 lib2 lib3)
241 target_include_directories(myExe
242 PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
243 Note that care must be taken when specifying usage requirements for
245 targets which will be exported for installation using the
246 install(EXPORT) command. See Creating Packages for more.
247 Compatible Interface Properties
249 Some target properties are required to be compatible between a target
250 and the interface of each dependency. For example, the POSITION_INDE‐
251 PENDENT_CODE target property may specify a boolean value of whether a
252 target should be compiled as position-independent-code, which has plat‐
253 form-specific consequences. A target may also specify the usage
254 requirement INTERFACE_POSITION_INDEPENDENT_CODE to communicate that
255 consumers must be compiled as position-independent-code.
256 add_executable(exe1 exe1.cpp)
258 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
259 add_library(lib1 SHARED lib1.cpp)
261 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
262 add_executable(exe2 exe2.cpp)
264 target_link_libraries(exe2 lib1)
265 Here, both exe1 and exe2 will be compiled as position-independent-code.
267 lib1 will also be compiled as position-independent-code because that is
268 the default setting for SHARED libraries. If dependencies have con‐
269 flicting, non-compatible requirements cmake(1) issues a diagnostic:
270 add_library(lib1 SHARED lib1.cpp)
272 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
273 add_library(lib2 SHARED lib2.cpp)
275 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
276 add_executable(exe1 exe1.cpp)
278 target_link_libraries(exe1 lib1)
279 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
280 add_executable(exe2 exe2.cpp)
282 target_link_libraries(exe2 lib1 lib2)
283 The lib1 requirement INTERFACE_POSITION_INDEPENDENT_CODE is not “com‐
285 patible” with the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
286 get. The library requires that consumers are built as position-inde‐
287 pendent-code, while the executable specifies to not built as posi‐
288 tion-independent-code, so a diagnostic is issued.
289 The lib1 and lib2 requirements are not “compatible”. One of them
291 requires that consumers are built as position-independent-code, while
292 the other requires that consumers are not built as position-indepen‐
293 dent-code. Because exe2 links to both and they are in conflict, a
294 diagnostic is issued.
295 To be “compatible”, the POSITION_INDEPENDENT_CODE property, if set must
297 be either the same, in a boolean sense, as the INTERFACE_POSITION_INDE‐
298 PENDENT_CODE property of all transitively specified dependencies on
299 which that property is set.
300 This property of “compatible interface requirement” may be extended to
302 other properties by specifying the property in the content of the COM‐
303 PATIBLE_INTERFACE_BOOL target property. Each specified property must
304 be compatible between the consuming target and the corresponding prop‐
305 erty with an INTERFACE_ prefix from each dependency:
306 add_library(lib1Version2 SHARED lib1_v2.cpp)
308 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
309 set_property(TARGET lib1Version2 APPEND PROPERTY
310 COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
311 )
312 add_library(lib1Version3 SHARED lib1_v3.cpp)
314 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
315 add_executable(exe1 exe1.cpp)
317 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
318 add_executable(exe2 exe2.cpp)
320 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
321 Non-boolean properties may also participate in “compatible interface”
323 computations. Properties specified in the COMPATIBLE_INTERFACE_STRING
324 property must be either unspecified or compare to the same string among
325 all transitively specified dependencies. This can be useful to ensure
326 that multiple incompatible versions of a library are not linked
327 together through transitive requirements of a target:
328 add_library(lib1Version2 SHARED lib1_v2.cpp)
330 set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
331 set_property(TARGET lib1Version2 APPEND PROPERTY
332 COMPATIBLE_INTERFACE_STRING LIB_VERSION
333 )
334 add_library(lib1Version3 SHARED lib1_v3.cpp)
336 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
337 add_executable(exe1 exe1.cpp)
339 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
340 add_executable(exe2 exe2.cpp)
342 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
343 The COMPATIBLE_INTERFACE_NUMBER_MAX target property specifies that con‐
345 tent will be evaluated numerically and the maximum number among all
346 specified will be calculated:
347 add_library(lib1Version2 SHARED lib1_v2.cpp)
349 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
350 set_property(TARGET lib1Version2 APPEND PROPERTY
351 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
352 )
353 add_library(lib1Version3 SHARED lib1_v3.cpp)
355 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
356 add_executable(exe1 exe1.cpp)
358 # CONTAINER_SIZE_REQUIRED will be "200"
359 target_link_libraries(exe1 lib1Version2)
360 add_executable(exe2 exe2.cpp)
362 # CONTAINER_SIZE_REQUIRED will be "1000"
363 target_link_libraries(exe2 lib1Version2 lib1Version3)
364 Similarly, the COMPATIBLE_INTERFACE_NUMBER_MIN may be used to calculate
366 the numeric minimum value for a property from dependencies.
367 Each calculated “compatible” property value may be read in the consumer
369 at generate-time using generator expressions.
370 Note that for each dependee, the set of properties specified in each
372 compatible interface property must not intersect with the set specified
373 in any of the other properties.
374 Property Origin Debugging
376 Because build specifications can be determined by dependencies, the
377 lack of locality of code which creates a target and code which is
378 responsible for setting build specifications may make the code more
379 difficult to reason about. cmake(1) provides a debugging facility to
380 print the origin of the contents of properties which may be determined
381 by dependencies. The properties which can be debugged are listed in
382 the CMAKE_DEBUG_TARGET_PROPERTIES variable documentation:
383 set(CMAKE_DEBUG_TARGET_PROPERTIES
385 INCLUDE_DIRECTORIES
386 COMPILE_DEFINITIONS
387 POSITION_INDEPENDENT_CODE
388 CONTAINER_SIZE_REQUIRED
389 LIB_VERSION
390 )
391 add_executable(exe1 exe1.cpp)
392 In the case of properties listed in COMPATIBLE_INTERFACE_BOOL or COM‐
394 PATIBLE_INTERFACE_STRING, the debug output shows which target was
395 responsible for setting the property, and which other dependencies also
396 defined the property. In the case of COMPATIBLE_INTERFACE_NUMBER_MAX
397 and COMPATIBLE_INTERFACE_NUMBER_MIN, the debug output shows the value
398 of the property from each dependency, and whether the value determines
399 the new extreme.
400 Build Specification with Generator Expressions
402 Build specifications may use generator expressions containing content
403 which may be conditional or known only at generate-time. For example,
404 the calculated “compatible” value of a property may be read with the
405 TARGET_PROPERTY expression:
406 add_library(lib1Version2 SHARED lib1_v2.cpp)
408 set_property(TARGET lib1Version2 PROPERTY
409 INTERFACE_CONTAINER_SIZE_REQUIRED 200)
410 set_property(TARGET lib1Version2 APPEND PROPERTY
411 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
412 )
413 add_executable(exe1 exe1.cpp)
415 target_link_libraries(exe1 lib1Version2)
416 target_compile_definitions(exe1 PRIVATE
417 CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
418 )
419 In this case, the exe1 source files will be compiled with -DCON‐
421 TAINER_SIZE=200.
422 Configuration determined build specifications may be conveniently set
424 using the CONFIG generator expression.
425 target_compile_definitions(exe1 PRIVATE
427 $<$<CONFIG:Debug>:DEBUG_BUILD>
428 )
429 The CONFIG parameter is compared case-insensitively with the configura‐
431 tion being built. In the presence of IMPORTED targets, the content of
432 MAP_IMPORTED_CONFIG_DEBUG is also accounted for by this expression.
433 Some buildsystems generated by cmake(1) have a predetermined build-con‐
435 figuration set in the CMAKE_BUILD_TYPE variable. The buildsystem for
436 the IDEs such as Visual Studio and Xcode are generated independent of
437 the build-configuration, and the actual build configuration is not
438 known until build-time. Therefore, code such as
439 string(TOLOWER ${CMAKE_BUILD_TYPE} _type)
441 if (_type STREQUAL debug)
442 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
443 endif()
444 may appear to work for Makefile based and Ninja generators, but is not
446 portable to IDE generators. Additionally, the IMPORTED configura‐
447 tion-mappings are not accounted for with code like this, so it should
448 be avoided.
449 The unary TARGET_PROPERTY generator expression and the TARGET_POLICY
451 generator expression are evaluated with the consuming target context.
452 This means that a usage requirement specification may be evaluated dif‐
453 ferently based on the consumer:
454 add_library(lib1 lib1.cpp)
456 target_compile_definitions(lib1 INTERFACE
457 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
458 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
459 $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
460 )
461 add_executable(exe1 exe1.cpp)
463 target_link_libraries(exe1 lib1)
464 cmake_policy(SET CMP0041 NEW)
466 add_library(shared_lib shared_lib.cpp)
468 target_link_libraries(shared_lib lib1)
469 The exe1 executable will be compiled with -DLIB1_WITH_EXE, while the
471 shared_lib shared library will be compiled with -DLIB1_WITH_SHARED_LIB
472 and -DCONSUMER_CMP0041_NEW, because policy CMP0041 is NEW at the point
473 where the shared_lib target is created.
474 The BUILD_INTERFACE expression wraps requirements which are only used
476 when consumed from a target in the same buildsystem, or when consumed
477 from a target exported to the build directory using the export() com‐
478 mand. The INSTALL_INTERFACE expression wraps requirements which are
479 only used when consumed from a target which has been installed and
480 exported with the install(EXPORT) command:
481 add_library(ClimbingStats climbingstats.cpp)
483 target_compile_definitions(ClimbingStats INTERFACE
484 $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
485 $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
486 )
487 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
488 install(EXPORT libExport NAMESPACE Upstream::
489 DESTINATION lib/cmake/ClimbingStats)
490 export(EXPORT libExport NAMESPACE Upstream::)
491 add_executable(exe1 exe1.cpp)
493 target_link_libraries(exe1 ClimbingStats)
494 In this case, the exe1 executable will be compiled with -DClimb‐
496 ingStats_FROM_BUILD_LOCATION. The exporting commands generate IMPORTED
497 targets with either the INSTALL_INTERFACE or the BUILD_INTERFACE omit‐
498 ted, and the *_INTERFACE marker stripped away. A separate project con‐
499 suming the ClimbingStats package would contain:
500 find_package(ClimbingStats REQUIRED)
502 add_executable(Downstream main.cpp)
504 target_link_libraries(Downstream Upstream::ClimbingStats)
505 Depending on whether the ClimbingStats package was used from the build
507 location or the install location, the Downstream target would be com‐
508 piled with either -DClimbingStats_FROM_BUILD_LOCATION or -DClimb‐
509 ingStats_FROM_INSTALL_LOCATION. For more about packages and exporting
510 see the cmake-packages(7) manual.
511 Include Directories and Usage Requirements
513 Include directories require some special consideration when specified
514 as usage requirements and when used with generator expressions. The
515 target_include_directories() command accepts both relative and absolute
516 include directories:
517 add_library(lib1 lib1.cpp)
519 target_include_directories(lib1 PRIVATE
520 /absolute/path
521 relative/path
522 )
523 Relative paths are interpreted relative to the source directory where
525 the command appears. Relative paths are not allowed in the INTER‐
526 FACE_INCLUDE_DIRECTORIES of IMPORTED targets.
527 In cases where a non-trivial generator expression is used, the
529 INSTALL_PREFIX expression may be used within the argument of an
530 INSTALL_INTERFACE expression. It is a replacement marker which expands
531 to the installation prefix when imported by a consuming project.
532 Include directories usage requirements commonly differ between the
534 build-tree and the install-tree. The BUILD_INTERFACE and
535 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
536 rate usage requirements based on the usage location. Relative paths
537 are allowed within the INSTALL_INTERFACE expression and are interpreted
538 relative to the installation prefix. For example:
539 add_library(ClimbingStats climbingstats.cpp)
541 target_include_directories(ClimbingStats INTERFACE
542 $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
543 $<INSTALL_INTERFACE:/absolute/path>
544 $<INSTALL_INTERFACE:relative/path>
545 $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
546 )
547 Two convenience APIs are provided relating to include directories usage
549 requirements. The CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE variable may
550 be enabled, with an equivalent effect to:
551 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
553 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
554 )
555 for each target affected. The convenience for installed targets is an
557 INCLUDES DESTINATION component with the install(TARGETS) command:
558 install(TARGETS foo bar bat EXPORT tgts ${dest_args}
560 INCLUDES DESTINATION include
561 )
562 install(EXPORT tgts ${other_args})
563 install(FILES ${headers} DESTINATION include)
564 This is equivalent to appending ${CMAKE_INSTALL_PREFIX}/include to the
566 INTERFACE_INCLUDE_DIRECTORIES of each of the installed IMPORTED targets
567 when generated by install(EXPORT).
568 When the INTERFACE_INCLUDE_DIRECTORIES of an imported target is con‐
570 sumed, the entries in the property are treated as SYSTEM include direc‐
571 tories, as if they were listed in the INTERFACE_SYSTEM_INCLUDE_DIRECTO‐
572 RIES of the dependency. This can result in omission of compiler warn‐
573 ings for headers found in those directories. This behavior for
574 Imported Targets may be controlled by setting the NO_SYS‐
575 TEM_FROM_IMPORTED target property on the consumers of imported targets.
576 If a binary target is linked transitively to a Mac OX framework, the
578 Headers directory of the framework is also treated as a usage require‐
579 ment. This has the same effect as passing the framework directory as
580 an include directory.
581 Link Libraries and Generator Expressions
583 Like build specifications, link libraries may be specified with genera‐
584 tor expression conditions. However, as consumption of usage require‐
585 ments is based on collection from linked dependencies, there is an
586 additional limitation that the link dependencies must form a “directed
587 acyclic graph”. That is, if linking to a target is dependent on the
588 value of a target property, that target property may not be dependent
589 on the linked dependencies:
590 add_library(lib1 lib1.cpp)
592 add_library(lib2 lib2.cpp)
593 target_link_libraries(lib1 PUBLIC
594 $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
595 )
596 add_library(lib3 lib3.cpp)
597 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
598 add_executable(exe1 exe1.cpp)
600 target_link_libraries(exe1 lib1 lib3)
601 As the value of the POSITION_INDEPENDENT_CODE property of the exe1 tar‐
603 get is dependent on the linked libraries (lib3), and the edge of link‐
604 ing exe1 is determined by the same POSITION_INDEPENDENT_CODE property,
605 the dependency graph above contains a cycle. cmake(1) issues a diag‐
606 nostic in this case.
607 Output Artifacts
609 The buildsystem targets created by the add_library() and add_exe‐
610 cutable() commands create rules to create binary outputs. The exact
611 output location of the binaries can only be determined at generate-time
612 because it can depend on the build-configuration and the link-language
613 of linked dependencies etc. TARGET_FILE, TARGET_LINKER_FILE and
614 related expressions can be used to access the name and location of gen‐
615 erated binaries. These expressions do not work for OBJECT libraries
616 however, as there is no single file generated by such libraries which
617 is relevant to the expressions.
618 There are three kinds of output artifacts that may be build by targets
620 as detailed in the following sections. Their classification differs
621 between DLL platforms and non-DLL platforms. All Windows-based systems
622 including Cygwin are DLL platforms.
623 Runtime Output Artifacts
625 A runtime output artifact of a buildsystem target may be:
626 · The executable file (e.g. .exe) of an executable target created by
628 the add_executable() command.
629 · On DLL platforms: the executable file (e.g. .dll) of a shared library
631 target created by the add_library() command with the SHARED option.
632 The RUNTIME_OUTPUT_DIRECTORY and RUNTIME_OUTPUT_NAME target properties
634 may be used to control runtime output artifact locations and names in
635 the build tree.
636 Library Output Artifacts
638 A library output artifact of a buildsystem target may be:
639 · The loadable module file (e.g. .dll or .so) of a module library tar‐
641 get created by the add_library() command with the MODULE option.
642 · On non-DLL platforms: the shared library file (e.g. .so or .dylib) of
644 a shared shared library target created by the add_library() command
645 with the SHARED option.
646 The LIBRARY_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_NAME target properties
648 may be used to control library output artifact locations and names in
649 the build tree.
650 Archive Output Artifacts
652 An archive output artifact of a buildsystem target may be:
653 · The static library file (e.g. .lib or .a) of a static library target
655 created by the add_library() command with the STATIC option.
656 · On DLL platforms: the import library file (e.g. .lib) of a shared
658 library target created by the add_library() command with the SHARED
659 option. This file is only guaranteed to exist if the library exports
660 at least one unmanaged symbol.
661 · On DLL platforms: the import library file (e.g. .lib) of an exe‐
663 cutable target created by the add_executable() command when its
664 ENABLE_EXPORTS target property is set.
665 The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME target properties
667 may be used to control archive output artifact locations and names in
668 the build tree.
669 Directory-Scoped Commands
671 The target_include_directories(), target_compile_definitions() and tar‐
672 get_compile_options() commands have an effect on only one target at a
673 time. The commands add_definitions(), add_compile_options() and
674 include_directories() have a similar function, but operate at directory
675 scope instead of target scope for convenience.
676
678 Some target types do not represent outputs of the buildsystem, but only
679 inputs such as external dependencies, aliases or other non-build arti‐
680 facts. Pseudo targets are not represented in the generated buildsys‐
681 tem.
682 Imported Targets
684 An IMPORTED target represents a pre-existing dependency. Usually such
685 targets are defined by an upstream package and should be treated as
686 immutable. After declaring an IMPORTED target one can adjust its target
687 properties by using the customary commands such as target_compile_defi‐
688 nitions(), target_include_directories(), target_compile_options() or
689 target_link_libraries() just like with any other regular target.
690 IMPORTED targets may have the same usage requirement properties popu‐
692 lated as binary targets, such as INTERFACE_INCLUDE_DIRECTORIES, INTER‐
693 FACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
694 FACE_LINK_LIBRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.
695 The LOCATION may also be read from an IMPORTED target, though there is
697 rarely reason to do so. Commands such as add_custom_command() can
698 transparently use an IMPORTED EXECUTABLE target as a COMMAND exe‐
699 cutable.
700 The scope of the definition of an IMPORTED target is the directory
702 where it was defined. It may be accessed and used from subdirectories,
703 but not from parent directories or sibling directories. The scope is
704 similar to the scope of a cmake variable.
705 It is also possible to define a GLOBAL IMPORTED target which is acces‐
707 sible globally in the buildsystem.
708 See the cmake-packages(7) manual for more on creating packages with
710 IMPORTED targets.
711 Alias Targets
713 An ALIAS target is a name which may be used interchangeably with a
714 binary target name in read-only contexts. A primary use-case for ALIAS
715 targets is for example or unit test executables accompanying a library,
716 which may be part of the same buildsystem or built separately based on
717 user configuration.
718 add_library(lib1 lib1.cpp)
720 install(TARGETS lib1 EXPORT lib1Export ${dest_args})
721 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
722 add_library(Upstream::lib1 ALIAS lib1)
724 In another directory, we can link unconditionally to the Upstream::lib1
726 target, which may be an IMPORTED target from a package, or an ALIAS
727 target if built as part of the same buildsystem.
728 if (NOT TARGET Upstream::lib1)
730 find_package(lib1 REQUIRED)
731 endif()
732 add_executable(exe1 exe1.cpp)
733 target_link_libraries(exe1 Upstream::lib1)
734 ALIAS targets are not mutable, installable or exportable. They are
736 entirely local to the buildsystem description. A name can be tested
737 for whether it is an ALIAS name by reading the ALIASED_TARGET property
738 from it:
739 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
741 if(_aliased)
742 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
743 endif()
744 Interface Libraries
746 An INTERFACE target has no LOCATION and is mutable, but is otherwise
747 similar to an IMPORTED target.
748 It may specify usage requirements such as INTERFACE_INCLUDE_DIRECTO‐
750 RIES, INTERFACE_COMPILE_DEFINITIONS, INTERFACE_COMPILE_OPTIONS, INTER‐
751 FACE_LINK_LIBRARIES, INTERFACE_SOURCES, and INTERFACE_POSITION_INDEPEN‐
752 DENT_CODE. Only the INTERFACE modes of the target_include_directo‐
753 ries(), target_compile_definitions(), target_compile_options(), tar‐
754 get_sources(), and target_link_libraries() commands may be used with
755 INTERFACE libraries.
756 A primary use-case for INTERFACE libraries is header-only libraries.
758 add_library(Eigen INTERFACE)
760 target_include_directories(Eigen INTERFACE
761 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
762 $<INSTALL_INTERFACE:include/Eigen>
763 )
764 add_executable(exe1 exe1.cpp)
766 target_link_libraries(exe1 Eigen)
767 Here, the usage requirements from the Eigen target are consumed and
769 used when compiling, but it has no effect on linking.
770 Another use-case is to employ an entirely target-focussed design for
772 usage requirements:
773 add_library(pic_on INTERFACE)
775 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
776 add_library(pic_off INTERFACE)
777 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
778 add_library(enable_rtti INTERFACE)
780 target_compile_options(enable_rtti INTERFACE
781 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
782 )
783 add_executable(exe1 exe1.cpp)
785 target_link_libraries(exe1 pic_on enable_rtti)
786 This way, the build specification of exe1 is expressed entirely as
788 linked targets, and the complexity of compiler-specific flags is encap‐
789 sulated in an INTERFACE library target.
790 The properties permitted to be set on or read from an INTERFACE library
792 are:
793 · Properties matching INTERFACE_*
795 · Built-in properties matching COMPATIBLE_INTERFACE_*
797 · EXPORT_NAME
799 · IMPORTED
801 · NAME
803 · Properties matching IMPORTED_LIBNAME_*
805 · Properties matching MAP_IMPORTED_CONFIG_*
807 INTERFACE libraries may be installed and exported. Any content they
809 refer to must be installed separately:
810 add_library(Eigen INTERFACE)
812 target_include_directories(Eigen INTERFACE
813 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
814 $<INSTALL_INTERFACE:include/Eigen>
815 )
816 install(TARGETS Eigen EXPORT eigenExport)
818 install(EXPORT eigenExport NAMESPACE Upstream::
819 DESTINATION lib/cmake/Eigen
820 )
821 install(FILES
822 ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h
823 ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h
824 ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h
825 DESTINATION include/Eigen
826 )
827
829 2000-2018 Kitware, Inc. and Contributors
8303.11.4 May 13, 2019 CMAKE-BUILDSYSTEM(7)