1 .. cmake-manual-description: CMake Buildsystem Reference
13 A CMake-based buildsystem is organized as a set of high-level logical
14 targets. Each target corresponds to an executable or library, or
15 is a custom target containing custom commands. Dependencies between the
16 targets are expressed in the buildsystem to determine the build order
17 and the rules for regeneration in response to change.
22 Executables and libraries are defined using the :command:`add_executable`
23 and :command:`add_library` commands. The resulting binary files have
24 appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the
25 platform targeted. Dependencies between binary targets are expressed using
26 the :command:`target_link_libraries` command:
30 add_library(archive archive.cpp zip.cpp lzma.cpp)
31 add_executable(zipapp zipapp.cpp)
32 target_link_libraries(zipapp archive)
34 ``archive`` is defined as a ``STATIC`` library -- an archive containing objects
35 compiled from ``archive.cpp``, ``zip.cpp``, and ``lzma.cpp``. ``zipapp``
36 is defined as an executable formed by compiling and linking ``zipapp.cpp``.
37 When linking the ``zipapp`` executable, the ``archive`` static library is
43 The :command:`add_executable` command defines an executable target:
47 add_executable(mytool mytool.cpp)
49 Commands such as :command:`add_custom_command`, which generates rules to be
50 run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
51 target as a ``COMMAND`` executable. The buildsystem rules will ensure that
52 the executable is built before attempting to run the command.
57 .. _`Normal Libraries`:
62 By default, the :command:`add_library` command defines a ``STATIC`` library,
63 unless a type is specified. A type may be specified when using the command:
67 add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)
71 add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
73 The :variable:`BUILD_SHARED_LIBS` variable may be enabled to change the
74 behavior of :command:`add_library` to build shared libraries by default.
76 In the context of the buildsystem definition as a whole, it is largely
77 irrelevant whether particular libraries are ``SHARED`` or ``STATIC`` --
78 the commands, dependency specifications and other APIs work similarly
79 regardless of the library type. The ``MODULE`` library type is
80 dissimilar in that it is generally not linked to -- it is not used in
81 the right-hand-side of the :command:`target_link_libraries` command.
82 It is a type which is loaded as a plugin using runtime techniques.
83 If the library does not export any unmanaged symbols (e.g. Windows
84 resource DLL, C++/CLI DLL), it is required that the library not be a
85 ``SHARED`` library because CMake expects ``SHARED`` libraries to export
90 add_library(archive MODULE 7z.cpp)
92 .. _`Apple Frameworks`:
97 A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
98 target property to create an macOS or iOS Framework Bundle.
99 A library with the ``FRAMEWORK`` target property should also set the
100 :prop_tgt:`FRAMEWORK_VERSION` target property. This property is typically
101 set to the value of "A" by macOS conventions.
102 The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key
103 and it uniquely identifies the bundle.
105 .. code-block:: cmake
107 add_library(MyFramework SHARED MyFramework.cpp)
108 set_target_properties(MyFramework PROPERTIES
110 FRAMEWORK_VERSION A # Version "A" is macOS convention
111 MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
114 .. _`Object Libraries`:
119 The ``OBJECT`` library type defines a non-archival collection of object files
120 resulting from compiling the given source files. The object files collection
121 may be used as source inputs to other targets by using the syntax
122 ``$<TARGET_OBJECTS:name>``. This is a
123 :manual:`generator expression <cmake-generator-expressions(7)>` that can be
124 used to supply the ``OBJECT`` library content to other targets:
126 .. code-block:: cmake
128 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
130 add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
132 add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
134 The link (or archiving) step of those other targets will use the object
135 files collection in addition to those from their own sources.
137 Alternatively, object libraries may be linked into other targets:
139 .. code-block:: cmake
141 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
143 add_library(archiveExtras STATIC extras.cpp)
144 target_link_libraries(archiveExtras PUBLIC archive)
146 add_executable(test_exe test.cpp)
147 target_link_libraries(test_exe archive)
149 The link (or archiving) step of those other targets will use the object
150 files from ``OBJECT`` libraries that are *directly* linked. Additionally,
151 usage requirements of the ``OBJECT`` libraries will be honored when compiling
152 sources in those other targets. Furthermore, those usage requirements
153 will propagate transitively to dependents of those other targets.
155 Object libraries may not be used as the ``TARGET`` in a use of the
156 :command:`add_custom_command(TARGET)` command signature. However,
157 the list of objects can be used by :command:`add_custom_command(OUTPUT)`
158 or :command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``.
160 Build Specification and Usage Requirements
161 ==========================================
163 The :command:`target_include_directories`, :command:`target_compile_definitions`
164 and :command:`target_compile_options` commands specify the build specifications
165 and the usage requirements of binary targets. The commands populate the
166 :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and
167 :prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the
168 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
169 and :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.
171 Each of the commands has a ``PRIVATE``, ``PUBLIC`` and ``INTERFACE`` mode. The
172 ``PRIVATE`` mode populates only the non-``INTERFACE_`` variant of the target
173 property and the ``INTERFACE`` mode populates only the ``INTERFACE_`` variants.
174 The ``PUBLIC`` mode populates both variants of the respective target property.
175 Each command may be invoked with multiple uses of each keyword:
177 .. code-block:: cmake
179 target_compile_definitions(archive
180 PRIVATE BUILDING_WITH_LZMA
181 INTERFACE USING_ARCHIVE_LIB
184 Note that usage requirements are not designed as a way to make downstreams
185 use particular :prop_tgt:`COMPILE_OPTIONS` or
186 :prop_tgt:`COMPILE_DEFINITIONS` etc for convenience only. The contents of
187 the properties must be **requirements**, not merely recommendations or
190 See the :ref:`Creating Relocatable Packages` section of the
191 :manual:`cmake-packages(7)` manual for discussion of additional care
192 that must be taken when specifying usage requirements while creating
193 packages for redistribution.
198 The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`,
199 :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target
200 properties are used appropriately when compiling the source files of a
203 Entries in the :prop_tgt:`INCLUDE_DIRECTORIES` are added to the compile line
204 with ``-I`` or ``-isystem`` prefixes and in the order of appearance in the
207 Entries in the :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or
208 ``/D`` and added to the compile line in an unspecified order. The
209 :prop_tgt:`DEFINE_SYMBOL` target property is also added as a compile
210 definition as a special convenience case for ``SHARED`` and ``MODULE``
213 Entries in the :prop_tgt:`COMPILE_OPTIONS` are escaped for the shell and added
214 in the order of appearance in the property value. Several compile options have
215 special separate handling, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`.
217 The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
218 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and
219 :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties are
220 *Usage Requirements* -- they specify content which consumers
221 must use to correctly compile and link with the target they appear on.
222 For any binary target, the contents of each ``INTERFACE_`` property on
223 each target specified in a :command:`target_link_libraries` command is
226 .. code-block:: cmake
228 set(srcs archive.cpp zip.cpp)
230 list(APPEND srcs lzma.cpp)
232 add_library(archive SHARED ${srcs})
234 # The archive library sources are compiled with -DBUILDING_WITH_LZMA
235 target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
237 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
239 add_executable(consumer)
240 # Link consumer to archive and consume its usage requirements. The consumer
241 # executable sources are compiled with -DUSING_ARCHIVE_LIB.
242 target_link_libraries(consumer archive)
244 Because it is common to require that the source directory and corresponding
245 build directory are added to the :prop_tgt:`INCLUDE_DIRECTORIES`, the
246 :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently
247 add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of
248 all targets. The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`
249 can be enabled to add the corresponding directories to the
250 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets. This makes use of
251 targets in multiple different directories convenient through use of the
252 :command:`target_link_libraries` command.
255 .. _`Target Usage Requirements`:
257 Transitive Usage Requirements
258 -----------------------------
260 The usage requirements of a target can transitively propagate to dependents.
261 The :command:`target_link_libraries` command has ``PRIVATE``,
262 ``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
264 .. code-block:: cmake
266 add_library(archive archive.cpp)
267 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
269 add_library(serialization serialization.cpp)
270 target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
272 add_library(archiveExtras extras.cpp)
273 target_link_libraries(archiveExtras PUBLIC archive)
274 target_link_libraries(archiveExtras PRIVATE serialization)
275 # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
276 # and -DUSING_SERIALIZATION_LIB
278 add_executable(consumer consumer.cpp)
279 # consumer is compiled with -DUSING_ARCHIVE_LIB
280 target_link_libraries(consumer archiveExtras)
282 Because ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the
283 usage requirements of it are propagated to ``consumer`` too. Because
284 ``serialization`` is a ``PRIVATE`` dependency of ``archiveExtras``, the usage
285 requirements of it are not propagated to ``consumer``.
287 Generally, a dependency should be specified in a use of
288 :command:`target_link_libraries` with the ``PRIVATE`` keyword if it is used by
289 only the implementation of a library, and not in the header files. If a
290 dependency is additionally used in the header files of a library (e.g. for
291 class inheritance), then it should be specified as a ``PUBLIC`` dependency.
292 A dependency which is not used by the implementation of a library, but only by
293 its headers should be specified as an ``INTERFACE`` dependency. The
294 :command:`target_link_libraries` command may be invoked with multiple uses of
297 .. code-block:: cmake
299 target_link_libraries(archiveExtras
301 PRIVATE serialization
304 Usage requirements are propagated by reading the ``INTERFACE_`` variants
305 of target properties from dependencies and appending the values to the
306 non-``INTERFACE_`` variants of the operand. For example, the
307 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of dependencies is read and
308 appended to the :prop_tgt:`INCLUDE_DIRECTORIES` of the operand. In cases
309 where order is relevant and maintained, and the order resulting from the
310 :command:`target_link_libraries` calls does not allow correct compilation,
311 use of an appropriate command to set the property directly may update the
314 For example, if the linked libraries for a target must be specified
315 in the order ``lib1`` ``lib2`` ``lib3`` , but the include directories must
316 be specified in the order ``lib3`` ``lib1`` ``lib2``:
318 .. code-block:: cmake
320 target_link_libraries(myExe lib1 lib2 lib3)
321 target_include_directories(myExe
322 PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
324 Note that care must be taken when specifying usage requirements for targets
325 which will be exported for installation using the :command:`install(EXPORT)`
326 command. See :ref:`Creating Packages` for more.
328 .. _`Compatible Interface Properties`:
330 Compatible Interface Properties
331 -------------------------------
333 Some target properties are required to be compatible between a target and
334 the interface of each dependency. For example, the
335 :prop_tgt:`POSITION_INDEPENDENT_CODE` target property may specify a
336 boolean value of whether a target should be compiled as
337 position-independent-code, which has platform-specific consequences.
338 A target may also specify the usage requirement
339 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` to communicate that
340 consumers must be compiled as position-independent-code.
342 .. code-block:: cmake
344 add_executable(exe1 exe1.cpp)
345 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
347 add_library(lib1 SHARED lib1.cpp)
348 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
350 add_executable(exe2 exe2.cpp)
351 target_link_libraries(exe2 lib1)
353 Here, both ``exe1`` and ``exe2`` will be compiled as position-independent-code.
354 ``lib1`` will also be compiled as position-independent-code because that is the
355 default setting for ``SHARED`` libraries. If dependencies have conflicting,
356 non-compatible requirements :manual:`cmake(1)` issues a diagnostic:
358 .. code-block:: cmake
360 add_library(lib1 SHARED lib1.cpp)
361 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
363 add_library(lib2 SHARED lib2.cpp)
364 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
366 add_executable(exe1 exe1.cpp)
367 target_link_libraries(exe1 lib1)
368 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
370 add_executable(exe2 exe2.cpp)
371 target_link_libraries(exe2 lib1 lib2)
373 The ``lib1`` requirement ``INTERFACE_POSITION_INDEPENDENT_CODE`` is not
374 "compatible" with the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of
375 the ``exe1`` target. The library requires that consumers are built as
376 position-independent-code, while the executable specifies to not built as
377 position-independent-code, so a diagnostic is issued.
379 The ``lib1`` and ``lib2`` requirements are not "compatible". One of them
380 requires that consumers are built as position-independent-code, while
381 the other requires that consumers are not built as position-independent-code.
382 Because ``exe2`` links to both and they are in conflict, a CMake error message
385 CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
386 not agree with the value of POSITION_INDEPENDENT_CODE already determined
389 To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property,
390 if set must be either the same, in a boolean sense, as the
391 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` property of all transitively
392 specified dependencies on which that property is set.
394 This property of "compatible interface requirement" may be extended to other
395 properties by specifying the property in the content of the
396 :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` target property. Each specified property
397 must be compatible between the consuming target and the corresponding property
398 with an ``INTERFACE_`` prefix from each dependency:
400 .. code-block:: cmake
402 add_library(lib1Version2 SHARED lib1_v2.cpp)
403 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
404 set_property(TARGET lib1Version2 APPEND PROPERTY
405 COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
408 add_library(lib1Version3 SHARED lib1_v3.cpp)
409 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
411 add_executable(exe1 exe1.cpp)
412 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
414 add_executable(exe2 exe2.cpp)
415 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
417 Non-boolean properties may also participate in "compatible interface"
418 computations. Properties specified in the
419 :prop_tgt:`COMPATIBLE_INTERFACE_STRING`
420 property must be either unspecified or compare to the same string among
421 all transitively specified dependencies. This can be useful to ensure
422 that multiple incompatible versions of a library are not linked together
423 through transitive requirements of a target:
425 .. code-block:: cmake
427 add_library(lib1Version2 SHARED lib1_v2.cpp)
428 set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
429 set_property(TARGET lib1Version2 APPEND PROPERTY
430 COMPATIBLE_INTERFACE_STRING LIB_VERSION
433 add_library(lib1Version3 SHARED lib1_v3.cpp)
434 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
436 add_executable(exe1 exe1.cpp)
437 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
439 add_executable(exe2 exe2.cpp)
440 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
442 The :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` target property specifies
443 that content will be evaluated numerically and the maximum number among all
444 specified will be calculated:
446 .. code-block:: cmake
448 add_library(lib1Version2 SHARED lib1_v2.cpp)
449 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
450 set_property(TARGET lib1Version2 APPEND PROPERTY
451 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
454 add_library(lib1Version3 SHARED lib1_v3.cpp)
455 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
457 add_executable(exe1 exe1.cpp)
458 # CONTAINER_SIZE_REQUIRED will be "200"
459 target_link_libraries(exe1 lib1Version2)
461 add_executable(exe2 exe2.cpp)
462 # CONTAINER_SIZE_REQUIRED will be "1000"
463 target_link_libraries(exe2 lib1Version2 lib1Version3)
465 Similarly, the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` may be used to
466 calculate the numeric minimum value for a property from dependencies.
468 Each calculated "compatible" property value may be read in the consumer at
469 generate-time using generator expressions.
471 Note that for each dependee, the set of properties specified in each
472 compatible interface property must not intersect with the set specified in
473 any of the other properties.
475 Property Origin Debugging
476 -------------------------
478 Because build specifications can be determined by dependencies, the lack of
479 locality of code which creates a target and code which is responsible for
480 setting build specifications may make the code more difficult to reason about.
481 :manual:`cmake(1)` provides a debugging facility to print the origin of the
482 contents of properties which may be determined by dependencies. The properties
483 which can be debugged are listed in the
484 :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable documentation:
486 .. code-block:: cmake
488 set(CMAKE_DEBUG_TARGET_PROPERTIES
491 POSITION_INDEPENDENT_CODE
492 CONTAINER_SIZE_REQUIRED
495 add_executable(exe1 exe1.cpp)
497 In the case of properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` or
498 :prop_tgt:`COMPATIBLE_INTERFACE_STRING`, the debug output shows which target
499 was responsible for setting the property, and which other dependencies also
500 defined the property. In the case of
501 :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and
502 :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN`, the debug output shows the
503 value of the property from each dependency, and whether the value determines
506 Build Specification with Generator Expressions
507 ----------------------------------------------
509 Build specifications may use
510 :manual:`generator expressions <cmake-generator-expressions(7)>` containing
511 content which may be conditional or known only at generate-time. For example,
512 the calculated "compatible" value of a property may be read with the
513 ``TARGET_PROPERTY`` expression:
515 .. code-block:: cmake
517 add_library(lib1Version2 SHARED lib1_v2.cpp)
518 set_property(TARGET lib1Version2 PROPERTY
519 INTERFACE_CONTAINER_SIZE_REQUIRED 200)
520 set_property(TARGET lib1Version2 APPEND PROPERTY
521 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
524 add_executable(exe1 exe1.cpp)
525 target_link_libraries(exe1 lib1Version2)
526 target_compile_definitions(exe1 PRIVATE
527 CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
530 In this case, the ``exe1`` source files will be compiled with
531 ``-DCONTAINER_SIZE=200``.
533 The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY``
534 generator expression are evaluated with the consuming target context. This
535 means that a usage requirement specification may be evaluated differently based
538 .. code-block:: cmake
540 add_library(lib1 lib1.cpp)
541 target_compile_definitions(lib1 INTERFACE
542 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
543 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
544 $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
547 add_executable(exe1 exe1.cpp)
548 target_link_libraries(exe1 lib1)
550 cmake_policy(SET CMP0041 NEW)
552 add_library(shared_lib shared_lib.cpp)
553 target_link_libraries(shared_lib lib1)
555 The ``exe1`` executable will be compiled with ``-DLIB1_WITH_EXE``, while the
556 ``shared_lib`` shared library will be compiled with ``-DLIB1_WITH_SHARED_LIB``
557 and ``-DCONSUMER_CMP0041_NEW``, because policy :policy:`CMP0041` is
558 ``NEW`` at the point where the ``shared_lib`` target is created.
560 The ``BUILD_INTERFACE`` expression wraps requirements which are only used when
561 consumed from a target in the same buildsystem, or when consumed from a target
562 exported to the build directory using the :command:`export` command. The
563 ``INSTALL_INTERFACE`` expression wraps requirements which are only used when
564 consumed from a target which has been installed and exported with the
565 :command:`install(EXPORT)` command:
567 .. code-block:: cmake
569 add_library(ClimbingStats climbingstats.cpp)
570 target_compile_definitions(ClimbingStats INTERFACE
571 $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
572 $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
574 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
575 install(EXPORT libExport NAMESPACE Upstream::
576 DESTINATION lib/cmake/ClimbingStats)
577 export(EXPORT libExport NAMESPACE Upstream::)
579 add_executable(exe1 exe1.cpp)
580 target_link_libraries(exe1 ClimbingStats)
582 In this case, the ``exe1`` executable will be compiled with
583 ``-DClimbingStats_FROM_BUILD_LOCATION``. The exporting commands generate
584 :prop_tgt:`IMPORTED` targets with either the ``INSTALL_INTERFACE`` or the
585 ``BUILD_INTERFACE`` omitted, and the ``*_INTERFACE`` marker stripped away.
586 A separate project consuming the ``ClimbingStats`` package would contain:
588 .. code-block:: cmake
590 find_package(ClimbingStats REQUIRED)
592 add_executable(Downstream main.cpp)
593 target_link_libraries(Downstream Upstream::ClimbingStats)
595 Depending on whether the ``ClimbingStats`` package was used from the build
596 location or the install location, the ``Downstream`` target would be compiled
597 with either ``-DClimbingStats_FROM_BUILD_LOCATION`` or
598 ``-DClimbingStats_FROM_INSTALL_LOCATION``. For more about packages and
599 exporting see the :manual:`cmake-packages(7)` manual.
601 .. _`Include Directories and Usage Requirements`:
603 Include Directories and Usage Requirements
604 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
606 Include directories require some special consideration when specified as usage
607 requirements and when used with generator expressions. The
608 :command:`target_include_directories` command accepts both relative and
609 absolute include directories:
611 .. code-block:: cmake
613 add_library(lib1 lib1.cpp)
614 target_include_directories(lib1 PRIVATE
619 Relative paths are interpreted relative to the source directory where the
620 command appears. Relative paths are not allowed in the
621 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :prop_tgt:`IMPORTED` targets.
623 In cases where a non-trivial generator expression is used, the
624 ``INSTALL_PREFIX`` expression may be used within the argument of an
625 ``INSTALL_INTERFACE`` expression. It is a replacement marker which
626 expands to the installation prefix when imported by a consuming project.
628 Include directories usage requirements commonly differ between the build-tree
629 and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
630 generator expressions can be used to describe separate usage requirements
631 based on the usage location. Relative paths are allowed within the
632 ``INSTALL_INTERFACE`` expression and are interpreted relative to the
633 installation prefix. For example:
635 .. code-block:: cmake
637 add_library(ClimbingStats climbingstats.cpp)
638 target_include_directories(ClimbingStats INTERFACE
639 $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
640 $<INSTALL_INTERFACE:/absolute/path>
641 $<INSTALL_INTERFACE:relative/path>
642 $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
645 Two convenience APIs are provided relating to include directories usage
646 requirements. The :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable
647 may be enabled, with an equivalent effect to:
649 .. code-block:: cmake
651 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
652 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
655 for each target affected. The convenience for installed targets is
656 an ``INCLUDES DESTINATION`` component with the :command:`install(TARGETS)`
659 .. code-block:: cmake
661 install(TARGETS foo bar bat EXPORT tgts ${dest_args}
662 INCLUDES DESTINATION include
664 install(EXPORT tgts ${other_args})
665 install(FILES ${headers} DESTINATION include)
667 This is equivalent to appending ``${CMAKE_INSTALL_PREFIX}/include`` to the
668 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of each of the installed
669 :prop_tgt:`IMPORTED` targets when generated by :command:`install(EXPORT)`.
671 When the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an
672 :ref:`imported target <Imported targets>` is consumed, the entries in the
673 property are treated as ``SYSTEM`` include directories, as if they were
674 listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the
675 dependency. This can result in omission of compiler warnings for headers
676 found in those directories. This behavior for :ref:`imported targets` may
677 be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target
678 property on the *consumers* of imported targets, or by setting the
679 :prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets
682 If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the
683 ``Headers`` directory of the framework is also treated as a usage requirement.
684 This has the same effect as passing the framework directory as an include
687 Link Libraries and Generator Expressions
688 ----------------------------------------
690 Like build specifications, :prop_tgt:`link libraries <LINK_LIBRARIES>` may be
691 specified with generator expression conditions. However, as consumption of
692 usage requirements is based on collection from linked dependencies, there is
693 an additional limitation that the link dependencies must form a "directed
694 acyclic graph". That is, if linking to a target is dependent on the value of
695 a target property, that target property may not be dependent on the linked
698 .. code-block:: cmake
700 add_library(lib1 lib1.cpp)
701 add_library(lib2 lib2.cpp)
702 target_link_libraries(lib1 PUBLIC
703 $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
705 add_library(lib3 lib3.cpp)
706 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
708 add_executable(exe1 exe1.cpp)
709 target_link_libraries(exe1 lib1 lib3)
711 As the value of the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of
712 the ``exe1`` target is dependent on the linked libraries (``lib3``), and the
713 edge of linking ``exe1`` is determined by the same
714 :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
715 contains a cycle. :manual:`cmake(1)` issues an error message.
717 .. _`Output Artifacts`:
722 The buildsystem targets created by the :command:`add_library` and
723 :command:`add_executable` commands create rules to create binary outputs.
724 The exact output location of the binaries can only be determined at
725 generate-time because it can depend on the build-configuration and the
726 link-language of linked dependencies etc. ``TARGET_FILE``,
727 ``TARGET_LINKER_FILE`` and related expressions can be used to access the
728 name and location of generated binaries. These expressions do not work
729 for ``OBJECT`` libraries however, as there is no single file generated
730 by such libraries which is relevant to the expressions.
732 There are three kinds of output artifacts that may be build by targets
733 as detailed in the following sections. Their classification differs
734 between DLL platforms and non-DLL platforms. All Windows-based
735 systems including Cygwin are DLL platforms.
737 .. _`Runtime Output Artifacts`:
739 Runtime Output Artifacts
740 ^^^^^^^^^^^^^^^^^^^^^^^^
742 A *runtime* output artifact of a buildsystem target may be:
744 * The executable file (e.g. ``.exe``) of an executable target
745 created by the :command:`add_executable` command.
747 * On DLL platforms: the executable file (e.g. ``.dll``) of a shared
748 library target created by the :command:`add_library` command
749 with the ``SHARED`` option.
751 The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
752 target properties may be used to control runtime output artifact locations
753 and names in the build tree.
755 .. _`Library Output Artifacts`:
757 Library Output Artifacts
758 ^^^^^^^^^^^^^^^^^^^^^^^^
760 A *library* output artifact of a buildsystem target may be:
762 * The loadable module file (e.g. ``.dll`` or ``.so``) of a module
763 library target created by the :command:`add_library` command
764 with the ``MODULE`` option.
766 * On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``)
767 of a shared library target created by the :command:`add_library`
768 command with the ``SHARED`` option.
770 The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME`
771 target properties may be used to control library output artifact locations
772 and names in the build tree.
774 .. _`Archive Output Artifacts`:
776 Archive Output Artifacts
777 ^^^^^^^^^^^^^^^^^^^^^^^^
779 An *archive* output artifact of a buildsystem target may be:
781 * The static library file (e.g. ``.lib`` or ``.a``) of a static
782 library target created by the :command:`add_library` command
783 with the ``STATIC`` option.
785 * On DLL platforms: the import library file (e.g. ``.lib``) of a shared
786 library target created by the :command:`add_library` command
787 with the ``SHARED`` option. This file is only guaranteed to exist if
788 the library exports at least one unmanaged symbol.
790 * On DLL platforms: the import library file (e.g. ``.lib``) of an
791 executable target created by the :command:`add_executable` command
792 when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
794 * On AIX: the linker import file (e.g. ``.imp``) of an executable target
795 created by the :command:`add_executable` command when its
796 :prop_tgt:`ENABLE_EXPORTS` target property is set.
798 The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
799 target properties may be used to control archive output artifact locations
800 and names in the build tree.
802 Directory-Scoped Commands
803 -------------------------
805 The :command:`target_include_directories`,
806 :command:`target_compile_definitions` and
807 :command:`target_compile_options` commands have an effect on only one
808 target at a time. The commands :command:`add_compile_definitions`,
809 :command:`add_compile_options` and :command:`include_directories` have
810 a similar function, but operate at directory scope instead of target
811 scope for convenience.
813 .. _`Build Configurations`:
818 Configurations determine specifications for a certain type of build, such
819 as ``Release`` or ``Debug``. The way this is specified depends on the type
820 of :manual:`generator <cmake-generators(7)>` being used. For single
821 configuration generators like :ref:`Makefile Generators` and
822 :generator:`Ninja`, the configuration is specified at configure time by the
823 :variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators
824 like :ref:`Visual Studio <Visual Studio Generators>`, :generator:`Xcode`, and
825 :generator:`Ninja Multi-Config`, the configuration is chosen by the user at
826 build time and :variable:`CMAKE_BUILD_TYPE` is ignored. In the
827 multi-configuration case, the set of *available* configurations is specified
828 at configure time by the :variable:`CMAKE_CONFIGURATION_TYPES` variable,
829 but the actual configuration used cannot be known until the build stage.
830 This difference is often misunderstood, leading to problematic code like the
833 .. code-block:: cmake
835 # WARNING: This is wrong for multi-config generators because they don't use
836 # and typically don't even set CMAKE_BUILD_TYPE
837 string(TOLOWER ${CMAKE_BUILD_TYPE} build_type)
838 if (build_type STREQUAL debug)
839 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
842 :manual:`Generator expressions <cmake-generator-expressions(7)>` should be
843 used instead to handle configuration-specific logic correctly, regardless of
844 the generator used. For example:
846 .. code-block:: cmake
848 # Works correctly for both single and multi-config generators
849 target_compile_definitions(exe1 PRIVATE
850 $<$<CONFIG:Debug>:DEBUG_BUILD>
853 In the presence of :prop_tgt:`IMPORTED` targets, the content of
854 :prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also
855 accounted for by the above ``$<CONFIG:Debug>`` expression.
861 :variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are
862 just like other variables in that any string comparisons made with their
863 values will be case-sensitive. The ``$<CONFIG>`` generator expression also
864 preserves the casing of the configuration as set by the user or CMake defaults.
867 .. code-block:: cmake
869 # NOTE: Don't use these patterns, they are for illustration purposes only.
871 set(CMAKE_BUILD_TYPE Debug)
872 if(CMAKE_BUILD_TYPE STREQUAL DEBUG)
873 # ... will never get here, "Debug" != "DEBUG"
875 add_custom_target(print_config ALL
876 # Prints "Config is Debug" in this single-config case
877 COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>"
881 set(CMAKE_CONFIGURATION_TYPES Debug Release)
882 if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES)
883 # ... will never get here, "Debug" != "DEBUG"
886 In contrast, CMake treats the configuration type case-insensitively when
887 using it internally in places that modify behavior based on the configuration.
888 For example, the ``$<CONFIG:Debug>`` generator expression will evaluate to 1
889 for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or
890 even ``DeBuG``. Therefore, you can specify configuration types in
891 :variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with
892 any mixture of upper and lowercase, although there are strong conventions
893 (see the next section). If you must test the value in string comparisons,
894 always convert the value to upper or lowercase first and adjust the test
897 Default And Custom Configurations
898 ---------------------------------
900 By default, CMake defines a number of standard configurations:
907 In multi-config generators, the :variable:`CMAKE_CONFIGURATION_TYPES` variable
908 will be populated with (potentially a subset of) the above list by default,
909 unless overridden by the project or user. The actual configuration used is
910 selected by the user at build time.
912 For single-config generators, the configuration is specified with the
913 :variable:`CMAKE_BUILD_TYPE` variable at configure time and cannot be changed
914 at build time. The default value will often be none of the above standard
915 configurations and will instead be an empty string. A common misunderstanding
916 is that this is the same as ``Debug``, but that is not the case. Users should
917 always explicitly specify the build type instead to avoid this common problem.
919 The above standard configuration types provide reasonable behavior on most
920 platforms, but they can be extended to provide other types. Each configuration
921 defines a set of compiler and linker flag variables for the language in use.
922 These variables follow the convention :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`,
923 where ``<CONFIG>`` is always the uppercase configuration name. When defining
924 a custom configuration type, make sure these variables are set appropriately,
925 typically as cache variables.
931 Some target types do not represent outputs of the buildsystem, but only inputs
932 such as external dependencies, aliases or other non-build artifacts. Pseudo
933 targets are not represented in the generated buildsystem.
935 .. _`Imported Targets`:
940 An :prop_tgt:`IMPORTED` target represents a pre-existing dependency. Usually
941 such targets are defined by an upstream package and should be treated as
942 immutable. After declaring an :prop_tgt:`IMPORTED` target one can adjust its
943 target properties by using the customary commands such as
944 :command:`target_compile_definitions`, :command:`target_include_directories`,
945 :command:`target_compile_options` or :command:`target_link_libraries` just like
946 with any other regular target.
948 :prop_tgt:`IMPORTED` targets may have the same usage requirement properties
949 populated as binary targets, such as
950 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
951 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
952 :prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
953 :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
954 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
956 The :prop_tgt:`LOCATION` may also be read from an IMPORTED target, though there
957 is rarely reason to do so. Commands such as :command:`add_custom_command` can
958 transparently use an :prop_tgt:`IMPORTED` :prop_tgt:`EXECUTABLE <TYPE>` target
959 as a ``COMMAND`` executable.
961 The scope of the definition of an :prop_tgt:`IMPORTED` target is the directory
962 where it was defined. It may be accessed and used from subdirectories, but
963 not from parent directories or sibling directories. The scope is similar to
964 the scope of a cmake variable.
966 It is also possible to define a ``GLOBAL`` :prop_tgt:`IMPORTED` target which is
967 accessible globally in the buildsystem.
969 See the :manual:`cmake-packages(7)` manual for more on creating packages
970 with :prop_tgt:`IMPORTED` targets.
977 An ``ALIAS`` target is a name which may be used interchangeably with
978 a binary target name in read-only contexts. A primary use-case for ``ALIAS``
979 targets is for example or unit test executables accompanying a library, which
980 may be part of the same buildsystem or built separately based on user
983 .. code-block:: cmake
985 add_library(lib1 lib1.cpp)
986 install(TARGETS lib1 EXPORT lib1Export ${dest_args})
987 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
989 add_library(Upstream::lib1 ALIAS lib1)
991 In another directory, we can link unconditionally to the ``Upstream::lib1``
992 target, which may be an :prop_tgt:`IMPORTED` target from a package, or an
993 ``ALIAS`` target if built as part of the same buildsystem.
995 .. code-block:: cmake
997 if (NOT TARGET Upstream::lib1)
998 find_package(lib1 REQUIRED)
1000 add_executable(exe1 exe1.cpp)
1001 target_link_libraries(exe1 Upstream::lib1)
1003 ``ALIAS`` targets are not mutable, installable or exportable. They are
1004 entirely local to the buildsystem description. A name can be tested for
1005 whether it is an ``ALIAS`` name by reading the :prop_tgt:`ALIASED_TARGET`
1008 .. code-block:: cmake
1010 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
1012 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
1015 .. _`Interface Libraries`:
1020 An ``INTERFACE`` library target does not compile sources and does not
1021 produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`.
1023 It may specify usage requirements such as
1024 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
1025 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
1026 :prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
1027 :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
1028 :prop_tgt:`INTERFACE_SOURCES`,
1029 and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
1030 Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
1031 :command:`target_compile_definitions`, :command:`target_compile_options`,
1032 :command:`target_sources`, and :command:`target_link_libraries` commands
1033 may be used with ``INTERFACE`` libraries.
1035 Since CMake 3.19, an ``INTERFACE`` library target may optionally contain
1036 source files. An interface library that contains source files will be
1037 included as a build target in the generated buildsystem. It does not
1038 compile sources, but may contain custom commands to generate other sources.
1039 Additionally, IDEs will show the source files as part of the target for
1040 interactive reading and editing.
1042 A primary use-case for ``INTERFACE`` libraries is header-only libraries.
1043 Since CMake 3.23, header files may be associated with a library by adding
1044 them to a header set using the :command:`target_sources` command:
1046 .. code-block:: cmake
1048 add_library(Eigen INTERFACE)
1050 target_sources(Eigen INTERFACE
1053 FILES src/eigen.h src/vector.h src/matrix.h
1056 add_executable(exe1 exe1.cpp)
1057 target_link_libraries(exe1 Eigen)
1059 When we specify the ``FILE_SET`` here, the ``BASE_DIRS`` we define automatically
1060 become include directories in the usage requirements for the target ``Eigen``.
1061 The usage requirements from the target are consumed and used when compiling, but
1062 have no effect on linking.
1064 Another use-case is to employ an entirely target-focussed design for usage
1067 .. code-block:: cmake
1069 add_library(pic_on INTERFACE)
1070 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
1071 add_library(pic_off INTERFACE)
1072 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
1074 add_library(enable_rtti INTERFACE)
1075 target_compile_options(enable_rtti INTERFACE
1076 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
1079 add_executable(exe1 exe1.cpp)
1080 target_link_libraries(exe1 pic_on enable_rtti)
1082 This way, the build specification of ``exe1`` is expressed entirely as linked
1083 targets, and the complexity of compiler-specific flags is encapsulated in an
1084 ``INTERFACE`` library target.
1086 ``INTERFACE`` libraries may be installed and exported. We can install the
1087 default header set along with the target:
1089 .. code-block:: cmake
1091 add_library(Eigen INTERFACE)
1093 target_sources(Eigen INTERFACE
1096 FILES src/eigen.h src/vector.h src/matrix.h
1099 install(TARGETS Eigen EXPORT eigenExport
1100 FILE_SET HEADERS DESTINATION include/Eigen)
1101 install(EXPORT eigenExport NAMESPACE Upstream::
1102 DESTINATION lib/cmake/Eigen
1105 Here, the headers defined in the header set are installed to ``include/Eigen``.
1106 The install destination automatically becomes an include directory that is a
1107 usage requirement for consumers.