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
40 .. _`Binary Executables`:
45 The :command:`add_executable` command defines an executable target:
49 add_executable(mytool mytool.cpp)
51 Commands such as :command:`add_custom_command`, which generates rules to be
52 run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
53 target as a ``COMMAND`` executable. The buildsystem rules will ensure that
54 the executable is built before attempting to run the command.
59 .. _`Normal Libraries`:
64 By default, the :command:`add_library` command defines a ``STATIC`` library,
65 unless a type is specified. A type may be specified when using the command:
69 add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)
73 add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
75 The :variable:`BUILD_SHARED_LIBS` variable may be enabled to change the
76 behavior of :command:`add_library` to build shared libraries by default.
78 In the context of the buildsystem definition as a whole, it is largely
79 irrelevant whether particular libraries are ``SHARED`` or ``STATIC`` --
80 the commands, dependency specifications and other APIs work similarly
81 regardless of the library type. The ``MODULE`` library type is
82 dissimilar in that it is generally not linked to -- it is not used in
83 the right-hand-side of the :command:`target_link_libraries` command.
84 It is a type which is loaded as a plugin using runtime techniques.
85 If the library does not export any unmanaged symbols (e.g. Windows
86 resource DLL, C++/CLI DLL), it is required that the library not be a
87 ``SHARED`` library because CMake expects ``SHARED`` libraries to export
92 add_library(archive MODULE 7z.cpp)
94 .. _`Apple Frameworks`:
99 A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
100 target property to create an macOS or iOS Framework Bundle.
101 A library with the ``FRAMEWORK`` target property should also set the
102 :prop_tgt:`FRAMEWORK_VERSION` target property. This property is typically
103 set to the value of "A" by macOS conventions.
104 The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets the ``CFBundleIdentifier`` key
105 and it uniquely identifies the bundle.
107 .. code-block:: cmake
109 add_library(MyFramework SHARED MyFramework.cpp)
110 set_target_properties(MyFramework PROPERTIES
112 FRAMEWORK_VERSION A # Version "A" is macOS convention
113 MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
116 .. _`Object Libraries`:
121 The ``OBJECT`` library type defines a non-archival collection of object files
122 resulting from compiling the given source files. The object files collection
123 may be used as source inputs to other targets by using the syntax
124 :genex:`$<TARGET_OBJECTS:name>`. This is a
125 :manual:`generator expression <cmake-generator-expressions(7)>` that can be
126 used to supply the ``OBJECT`` library content to other targets:
128 .. code-block:: cmake
130 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
132 add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
134 add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
136 The link (or archiving) step of those other targets will use the object
137 files collection in addition to those from their own sources.
139 Alternatively, object libraries may be linked into other targets:
141 .. code-block:: cmake
143 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
145 add_library(archiveExtras STATIC extras.cpp)
146 target_link_libraries(archiveExtras PUBLIC archive)
148 add_executable(test_exe test.cpp)
149 target_link_libraries(test_exe archive)
151 The link (or archiving) step of those other targets will use the object
152 files from ``OBJECT`` libraries that are *directly* linked. Additionally,
153 usage requirements of the ``OBJECT`` libraries will be honored when compiling
154 sources in those other targets. Furthermore, those usage requirements
155 will propagate transitively to dependents of those other targets.
157 Object libraries may not be used as the ``TARGET`` in a use of the
158 :command:`add_custom_command(TARGET)` command signature. However,
159 the list of objects can be used by :command:`add_custom_command(OUTPUT)`
160 or :command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``.
162 Build Specification and Usage Requirements
163 ==========================================
165 Targets build according to their own
166 `build specification <Target Build Specification_>`_ in combination with
167 `usage requirements <Target Usage Requirements_>`_ propagated from their
168 link dependencies. Both may be specified using target-specific
169 `commands <Target Commands_>`_.
173 .. code-block:: cmake
175 add_library(archive SHARED archive.cpp zip.cpp)
178 # Add a source implementing support for lzma.
179 target_sources(archive PRIVATE lzma.cpp)
181 # Compile the 'archive' library sources with '-DBUILDING_WITH_LZMA'.
182 target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
185 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
187 add_executable(consumer consumer.cpp)
189 # Link 'consumer' to 'archive'. This also consumes its usage requirements,
190 # so 'consumer.cpp' is compiled with '-DUSING_ARCHIVE_LIB'.
191 target_link_libraries(consumer archive)
197 Target-specific commands populate the
198 `build specification <Target Build Specification_>`_ of `Binary Targets`_ and
199 `usage requirements <Target Usage Requirements_>`_ of `Binary Targets`_,
200 `Interface Libraries`_, and `Imported Targets`_.
202 .. _`Target Command Scope`:
204 Invocations must specify scope keywords, each affecting the visibility
205 of arguments following it. The scopes are:
208 Populates both properties for `building <Target Build Specification_>`_
209 and properties for `using <Target Usage Requirements_>`_ a target.
212 Populates only properties for `building <Target Build Specification_>`_
216 Populates only properties for `using <Target Usage Requirements_>`_
221 :command:`target_compile_definitions`
222 Populates the :prop_tgt:`COMPILE_DEFINITIONS` build specification and
223 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` usage requirement properties.
225 For example, the call
227 .. code-block:: cmake
229 target_compile_definitions(archive
230 PRIVATE BUILDING_WITH_LZMA
231 INTERFACE USING_ARCHIVE_LIB
234 appends ``BUILDING_WITH_LZMA`` to the target's ``COMPILE_DEFINITIONS``
235 property and appends ``USING_ARCHIVE_LIB`` to the target's
236 ``INTERFACE_COMPILE_DEFINITIONS`` property.
238 :command:`target_compile_options`
239 Populates the :prop_tgt:`COMPILE_OPTIONS` build specification and
240 :prop_tgt:`INTERFACE_COMPILE_OPTIONS` usage requirement properties.
242 :command:`target_compile_features`
243 .. versionadded:: 3.1
245 Populates the :prop_tgt:`COMPILE_FEATURES` build specification and
246 :prop_tgt:`INTERFACE_COMPILE_FEATURES` usage requirement properties.
248 :command:`target_include_directories`
249 Populates the :prop_tgt:`INCLUDE_DIRECTORIES` build specification
250 and :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` usage requirement
251 properties. With the ``SYSTEM`` option, it also populates the
252 :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` usage requirement.
254 For convenience, the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable
255 may be enabled to add the source directory and corresponding build
256 directory as ``INCLUDE_DIRECTORIES`` on all targets. Similarly,
257 the :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable may
258 be enabled to add them as ``INTERFACE_INCLUDE_DIRECTORIES`` on all
261 :command:`target_sources`
262 .. versionadded:: 3.1
264 Populates the :prop_tgt:`SOURCES` build specification and
265 :prop_tgt:`INTERFACE_SOURCES` usage requirement properties.
267 It also supports specifying :ref:`File Sets`, which can add C++ module
268 sources and headers not listed in the ``SOURCES`` and ``INTERFACE_SOURCES``
269 properties. File sets may also populate the :prop_tgt:`INCLUDE_DIRECTORIES`
270 build specification and :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` usage
271 requirement properties with the include directories containing the headers.
273 :command:`target_precompile_headers`
274 .. versionadded:: 3.16
276 Populates the :prop_tgt:`PRECOMPILE_HEADERS` build specification and
277 :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` usage requirement properties.
279 :command:`target_link_libraries`
280 Populates the :prop_tgt:`LINK_LIBRARIES` build specification
281 and :prop_tgt:`INTERFACE_LINK_LIBRARIES` usage requirement properties.
283 This is the primary mechanism by which link dependencies and their
284 `usage requirements <Target Usage Requirements_>`_ are transitively
285 propagated to affect compilation and linking of a target.
287 :command:`target_link_directories`
288 .. versionadded:: 3.13
290 Populates the :prop_tgt:`LINK_DIRECTORIES` build specification and
291 :prop_tgt:`INTERFACE_LINK_DIRECTORIES` usage requirement properties.
293 :command:`target_link_options`
294 .. versionadded:: 3.13
296 Populates the :prop_tgt:`LINK_OPTIONS` build specification and
297 :prop_tgt:`INTERFACE_LINK_OPTIONS` usage requirement properties.
299 .. _`Target Build Specification`:
301 Target Build Specification
302 --------------------------
304 The build specification of `Binary Targets`_ is represented by target
305 properties. For each of the following `compile <Target Compile Properties_>`_
306 and `link <Target Link Properties_>`_ properties, compilation and linking
307 of the target is affected both by its own value and by the corresponding
308 `usage requirement <Target Usage Requirements_>`_ property, named with
309 an ``INTERFACE_`` prefix, collected from the transitive closure of link
312 .. _`Target Compile Properties`:
314 Target Compile Properties
315 ^^^^^^^^^^^^^^^^^^^^^^^^^
317 These represent the `build specification <Target Build Specification_>`_
318 for compiling a target.
320 :prop_tgt:`COMPILE_DEFINITIONS`
321 List of compile definitions for compiling sources in the target.
322 These are passed to the compiler with ``-D`` flags, or equivalent,
323 in an unspecified order.
325 The :prop_tgt:`DEFINE_SYMBOL` target property is also used
326 as a compile definition as a special convenience case for
327 ``SHARED`` and ``MODULE`` library targets.
329 :prop_tgt:`COMPILE_OPTIONS`
330 List of compile options for compiling sources in the target.
331 These are passed to the compiler as flags, in the order of appearance.
333 Compile options are automatically escaped for the shell.
335 Some compile options are best specified via dedicated settings,
336 such as the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property.
338 :prop_tgt:`COMPILE_FEATURES`
339 .. versionadded:: 3.1
341 List of :manual:`compile features <cmake-compile-features(7)>` needed
342 for compiling sources in the target. Typically these ensure the
343 target's sources are compiled using a sufficient language standard level.
345 :prop_tgt:`INCLUDE_DIRECTORIES`
346 List of include directories for compiling sources in the target.
347 These are passed to the compiler with ``-I`` or ``-isystem`` flags,
348 or equivalent, in the order of appearance.
350 For convenience, the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable
351 may be enabled to add the source directory and corresponding build
352 directory as ``INCLUDE_DIRECTORIES`` on all targets.
355 List of source files associated with the target. This includes sources
356 specified when the target was created by the :command:`add_executable`,
357 :command:`add_library`, or :command:`add_custom_target` command.
358 It also includes sources added by the :command:`target_sources` command,
359 but does not include :ref:`File Sets`.
361 :prop_tgt:`PRECOMPILE_HEADERS`
362 .. versionadded:: 3.16
364 List of header files to precompile and include when compiling
365 sources in the target.
367 :prop_tgt:`AUTOMOC_MACRO_NAMES`
368 .. versionadded:: 3.10
370 List of macro names used by :prop_tgt:`AUTOMOC` to determine if a
371 C++ source in the target needs to be processed by ``moc``.
373 :prop_tgt:`AUTOUIC_OPTIONS`
374 .. versionadded:: 3.0
376 List of options used by :prop_tgt:`AUTOUIC` when invoking ``uic``
379 .. _`Target Link Properties`:
381 Target Link Properties
382 ^^^^^^^^^^^^^^^^^^^^^^
384 These represent the `build specification <Target Build Specification_>`_
385 for linking a target.
387 :prop_tgt:`LINK_LIBRARIES`
388 List of link libraries for linking the target, if it is an executable,
389 shared library, or module library. Entries for `Normal Libraries`_ are
390 passed to the linker either via paths to their link artifacts, or
391 with ``-l`` flags or equivalent. Entries for `Object Libraries`_ are
392 passed to the linker via paths to their object files.
394 Additionally, for compiling and linking the target itself,
395 `usage requirements <Target Usage Requirements_>`_ are propagated from
396 ``LINK_LIBRARIES`` entries naming `Normal Libraries`_,
397 `Interface Libraries`_, `Object Libraries`_, and `Imported Targets`_,
398 collected over the transitive closure of their
399 :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
401 :prop_tgt:`LINK_DIRECTORIES`
402 .. versionadded:: 3.13
404 List of link directories for linking the target, if it is an executable,
405 shared library, or module library. The directories are passed to the
406 linker with ``-L`` flags, or equivalent.
408 :prop_tgt:`LINK_OPTIONS`
409 .. versionadded:: 3.13
411 List of link options for linking the target, if it is an executable,
412 shared library, or module library. The options are passed to the
413 linker as flags, in the order of appearance.
415 Link options are automatically escaped for the shell.
417 :prop_tgt:`LINK_DEPENDS`
418 List of files on which linking the target depends, if it is an executable,
419 shared library, or module library. For example, linker scripts specified
420 via :prop_tgt:`LINK_OPTIONS` may be listed here such that changing them
421 causes binaries to be linked again.
423 .. _`Target Usage Requirements`:
425 Target Usage Requirements
426 -------------------------
428 The *usage requirements* of a target are settings that propagate to consumers,
429 which link to the target via :command:`target_link_libraries`, in order to
430 correctly compile and link with it. They are represented by transitive
431 `compile <Transitive Compile Properties_>`_ and
432 `link <Transitive Link Properties_>`_ properties.
434 Note that usage requirements are not designed as a way to make downstreams
435 use particular :prop_tgt:`COMPILE_OPTIONS`, :prop_tgt:`COMPILE_DEFINITIONS`,
436 etc. for convenience only. The contents of the properties must be
437 **requirements**, not merely recommendations.
439 See the :ref:`Creating Relocatable Packages` section of the
440 :manual:`cmake-packages(7)` manual for discussion of additional care
441 that must be taken when specifying usage requirements while creating
442 packages for redistribution.
444 The usage requirements of a target can transitively propagate to the dependents.
445 The :command:`target_link_libraries` command has ``PRIVATE``,
446 ``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
448 .. code-block:: cmake
450 add_library(archive archive.cpp)
451 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
453 add_library(serialization serialization.cpp)
454 target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
456 add_library(archiveExtras extras.cpp)
457 target_link_libraries(archiveExtras PUBLIC archive)
458 target_link_libraries(archiveExtras PRIVATE serialization)
459 # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
460 # and -DUSING_SERIALIZATION_LIB
462 add_executable(consumer consumer.cpp)
463 # consumer is compiled with -DUSING_ARCHIVE_LIB
464 target_link_libraries(consumer archiveExtras)
466 Because the ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the
467 usage requirements of it are propagated to ``consumer`` too.
470 ``serialization`` is a ``PRIVATE`` dependency of ``archiveExtras``, the usage
471 requirements of it are not propagated to ``consumer``.
473 Generally, a dependency should be specified in a use of
474 :command:`target_link_libraries` with the ``PRIVATE`` keyword if it is used by
475 only the implementation of a library, and not in the header files. If a
476 dependency is additionally used in the header files of a library (e.g. for
477 class inheritance), then it should be specified as a ``PUBLIC`` dependency.
478 A dependency which is not used by the implementation of a library, but only by
479 its headers should be specified as an ``INTERFACE`` dependency. The
480 :command:`target_link_libraries` command may be invoked with multiple uses of
483 .. code-block:: cmake
485 target_link_libraries(archiveExtras
487 PRIVATE serialization
490 Usage requirements are propagated by reading the ``INTERFACE_`` variants
491 of target properties from dependencies and appending the values to the
492 non-``INTERFACE_`` variants of the operand. For example, the
493 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of dependencies is read and
494 appended to the :prop_tgt:`INCLUDE_DIRECTORIES` of the operand. In cases
495 where order is relevant and maintained, and the order resulting from the
496 :command:`target_link_libraries` calls does not allow correct compilation,
497 use of an appropriate command to set the property directly may update the
500 For example, if the linked libraries for a target must be specified
501 in the order ``lib1`` ``lib2`` ``lib3`` , but the include directories must
502 be specified in the order ``lib3`` ``lib1`` ``lib2``:
504 .. code-block:: cmake
506 target_link_libraries(myExe lib1 lib2 lib3)
507 target_include_directories(myExe
508 PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
510 Note that care must be taken when specifying usage requirements for targets
511 which will be exported for installation using the :command:`install(EXPORT)`
512 command. See :ref:`Creating Packages` for more.
514 .. _`Transitive Compile Properties`:
516 Transitive Compile Properties
517 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
519 These represent `usage requirements <Target Usage Requirements_>`_ for
522 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
523 List of compile definitions for compiling sources in the target's consumers.
524 Typically these are used by the target's header files.
526 :prop_tgt:`INTERFACE_COMPILE_OPTIONS`
527 List of compile options for compiling sources in the target's consumers.
529 :prop_tgt:`INTERFACE_COMPILE_FEATURES`
530 .. versionadded:: 3.1
532 List of :manual:`compile features <cmake-compile-features(7)>` needed
533 for compiling sources in the target's consumers. Typically these
534 ensure the target's header files are processed when compiling consumers
535 using a sufficient language standard level.
537 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
538 List of include directories for compiling sources in the target's consumers.
539 Typically these are the locations of the target's header files.
541 :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`
542 List of directories that, when specified as include directories, e.g., by
543 :prop_tgt:`INCLUDE_DIRECTORIES` or :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
544 should be treated as "system" include directories when compiling sources
545 in the target's consumers.
547 :prop_tgt:`INTERFACE_SOURCES`
548 List of source files to associate with the target's consumers.
550 :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS`
551 .. versionadded:: 3.16
553 List of header files to precompile and include when compiling
554 sources in the target's consumers.
556 :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES`
557 .. versionadded:: 3.27
559 List of macro names used by :prop_tgt:`AUTOMOC` to determine if a
560 C++ source in the target's consumers needs to be processed by ``moc``.
562 :prop_tgt:`INTERFACE_AUTOUIC_OPTIONS`
563 .. versionadded:: 3.0
565 List of options used by :prop_tgt:`AUTOUIC` when invoking ``uic``
566 for the target's consumers.
568 .. _`Transitive Link Properties`:
570 Transitive Link Properties
571 ^^^^^^^^^^^^^^^^^^^^^^^^^^
573 These represent `usage requirements <Target Usage Requirements_>`_ for
576 :prop_tgt:`INTERFACE_LINK_LIBRARIES`
577 List of link libraries for linking the target's consumers, for
578 those that are executables, shared libraries, or module libraries.
579 These are the transitive dependencies of the target.
581 Additionally, for compiling and linking the target's consumers,
582 `usage requirements <Target Usage Requirements_>`_ are collected from
583 the transitive closure of ``INTERFACE_LINK_LIBRARIES`` entries naming
584 `Normal Libraries`_, `Interface Libraries`_, `Object Libraries`_,
585 and `Imported Targets`_,
587 :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
588 .. versionadded:: 3.13
590 List of link directories for linking the target's consumers, for
591 those that are executables, shared libraries, or module libraries.
593 :prop_tgt:`INTERFACE_LINK_OPTIONS`
594 .. versionadded:: 3.13
596 List of link options for linking the target's consumers, for
597 those that are executables, shared libraries, or module libraries.
599 :prop_tgt:`INTERFACE_LINK_DEPENDS`
600 .. versionadded:: 3.13
602 List of files on which linking the target's consumers depends, for
603 those that are executables, shared libraries, or module libraries.
605 .. _`Custom Transitive Properties`:
607 Custom Transitive Properties
608 ----------------------------
610 .. versionadded:: 3.30
612 The :genex:`TARGET_PROPERTY` generator expression evaluates the above
613 `build specification <Target Build Specification_>`_ and
614 `usage requirement <Target Usage Requirements_>`_ properties
615 as builtin transitive properties. It also supports custom transitive
616 properties defined by the :prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES`
617 and :prop_tgt:`TRANSITIVE_LINK_PROPERTIES` properties on the target
618 and its link dependencies.
622 .. code-block:: cmake
624 add_library(example INTERFACE)
625 set_target_properties(example PROPERTIES
626 TRANSITIVE_COMPILE_PROPERTIES "CUSTOM_C"
627 TRANSITIVE_LINK_PROPERTIES "CUSTOM_L"
629 INTERFACE_CUSTOM_C "EXAMPLE_CUSTOM_C"
630 INTERFACE_CUSTOM_L "EXAMPLE_CUSTOM_L"
633 add_library(mylib STATIC mylib.c)
634 target_link_libraries(mylib PRIVATE example)
635 set_target_properties(mylib PROPERTIES
636 CUSTOM_C "MYLIB_PRIVATE_CUSTOM_C"
637 CUSTOM_L "MYLIB_PRIVATE_CUSTOM_L"
638 INTERFACE_CUSTOM_C "MYLIB_IFACE_CUSTOM_C"
639 INTERFACE_CUSTOM_L "MYLIB_IFACE_CUSTOM_L"
642 add_executable(myexe myexe.c)
643 target_link_libraries(myexe PRIVATE mylib)
644 set_target_properties(myexe PROPERTIES
645 CUSTOM_C "MYEXE_CUSTOM_C"
646 CUSTOM_L "MYEXE_CUSTOM_L"
649 add_custom_target(print ALL VERBATIM
650 COMMAND ${CMAKE_COMMAND} -E echo
651 # Prints "MYLIB_PRIVATE_CUSTOM_C;EXAMPLE_CUSTOM_C"
652 "$<TARGET_PROPERTY:mylib,CUSTOM_C>"
654 # Prints "MYLIB_PRIVATE_CUSTOM_L;EXAMPLE_CUSTOM_L"
655 "$<TARGET_PROPERTY:mylib,CUSTOM_L>"
657 # Prints "MYEXE_CUSTOM_C"
658 "$<TARGET_PROPERTY:myexe,CUSTOM_C>"
660 # Prints "MYEXE_CUSTOM_L;MYLIB_IFACE_CUSTOM_L;EXAMPLE_CUSTOM_L"
661 "$<TARGET_PROPERTY:myexe,CUSTOM_L>"
664 .. _`Compatible Interface Properties`:
666 Compatible Interface Properties
667 -------------------------------
669 Some target properties are required to be compatible between a target and
670 the interface of each dependency. For example, the
671 :prop_tgt:`POSITION_INDEPENDENT_CODE` target property may specify a
672 boolean value of whether a target should be compiled as
673 position-independent-code, which has platform-specific consequences.
674 A target may also specify the usage requirement
675 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` to communicate that
676 consumers must be compiled as position-independent-code.
678 .. code-block:: cmake
680 add_executable(exe1 exe1.cpp)
681 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
683 add_library(lib1 SHARED lib1.cpp)
684 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
686 add_executable(exe2 exe2.cpp)
687 target_link_libraries(exe2 lib1)
689 Here, both ``exe1`` and ``exe2`` will be compiled as position-independent-code.
690 ``lib1`` will also be compiled as position-independent-code because that is the
691 default setting for ``SHARED`` libraries. If dependencies have conflicting,
692 non-compatible requirements :manual:`cmake(1)` issues a diagnostic:
694 .. code-block:: cmake
696 add_library(lib1 SHARED lib1.cpp)
697 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
699 add_library(lib2 SHARED lib2.cpp)
700 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
702 add_executable(exe1 exe1.cpp)
703 target_link_libraries(exe1 lib1)
704 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
706 add_executable(exe2 exe2.cpp)
707 target_link_libraries(exe2 lib1 lib2)
709 The ``lib1`` requirement ``INTERFACE_POSITION_INDEPENDENT_CODE`` is not
710 "compatible" with the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of
711 the ``exe1`` target. The library requires that consumers are built as
712 position-independent-code, while the executable specifies to not built as
713 position-independent-code, so a diagnostic is issued.
715 The ``lib1`` and ``lib2`` requirements are not "compatible". One of them
716 requires that consumers are built as position-independent-code, while
717 the other requires that consumers are not built as position-independent-code.
718 Because ``exe2`` links to both and they are in conflict, a CMake error message
721 CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
722 not agree with the value of POSITION_INDEPENDENT_CODE already determined
725 To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property,
726 if set must be either the same, in a boolean sense, as the
727 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` property of all transitively
728 specified dependencies on which that property is set.
730 This property of "compatible interface requirement" may be extended to other
731 properties by specifying the property in the content of the
732 :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` target property. Each specified property
733 must be compatible between the consuming target and the corresponding property
734 with an ``INTERFACE_`` prefix from each dependency:
736 .. code-block:: cmake
738 add_library(lib1Version2 SHARED lib1_v2.cpp)
739 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
740 set_property(TARGET lib1Version2 APPEND PROPERTY
741 COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
744 add_library(lib1Version3 SHARED lib1_v3.cpp)
745 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
747 add_executable(exe1 exe1.cpp)
748 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
750 add_executable(exe2 exe2.cpp)
751 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
753 Non-boolean properties may also participate in "compatible interface"
754 computations. Properties specified in the
755 :prop_tgt:`COMPATIBLE_INTERFACE_STRING`
756 property must be either unspecified or compare to the same string among
757 all transitively specified dependencies. This can be useful to ensure
758 that multiple incompatible versions of a library are not linked together
759 through transitive requirements of a target:
761 .. code-block:: cmake
763 add_library(lib1Version2 SHARED lib1_v2.cpp)
764 set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
765 set_property(TARGET lib1Version2 APPEND PROPERTY
766 COMPATIBLE_INTERFACE_STRING LIB_VERSION
769 add_library(lib1Version3 SHARED lib1_v3.cpp)
770 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
772 add_executable(exe1 exe1.cpp)
773 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
775 add_executable(exe2 exe2.cpp)
776 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
778 The :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` target property specifies
779 that content will be evaluated numerically and the maximum number among all
780 specified will be calculated:
782 .. code-block:: cmake
784 add_library(lib1Version2 SHARED lib1_v2.cpp)
785 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
786 set_property(TARGET lib1Version2 APPEND PROPERTY
787 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
790 add_library(lib1Version3 SHARED lib1_v3.cpp)
791 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
793 add_executable(exe1 exe1.cpp)
794 # CONTAINER_SIZE_REQUIRED will be "200"
795 target_link_libraries(exe1 lib1Version2)
797 add_executable(exe2 exe2.cpp)
798 # CONTAINER_SIZE_REQUIRED will be "1000"
799 target_link_libraries(exe2 lib1Version2 lib1Version3)
801 Similarly, the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` may be used to
802 calculate the numeric minimum value for a property from dependencies.
804 Each calculated "compatible" property value may be read in the consumer at
805 generate-time using generator expressions.
807 Note that for each dependee, the set of properties specified in each
808 compatible interface property must not intersect with the set specified in
809 any of the other properties.
811 Property Origin Debugging
812 -------------------------
814 Because build specifications can be determined by dependencies, the lack of
815 locality of code which creates a target and code which is responsible for
816 setting build specifications may make the code more difficult to reason about.
817 :manual:`cmake(1)` provides a debugging facility to print the origin of the
818 contents of properties which may be determined by dependencies. The properties
819 which can be debugged are listed in the
820 :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable documentation:
822 .. code-block:: cmake
824 set(CMAKE_DEBUG_TARGET_PROPERTIES
827 POSITION_INDEPENDENT_CODE
828 CONTAINER_SIZE_REQUIRED
831 add_executable(exe1 exe1.cpp)
833 In the case of properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` or
834 :prop_tgt:`COMPATIBLE_INTERFACE_STRING`, the debug output shows which target
835 was responsible for setting the property, and which other dependencies also
836 defined the property. In the case of
837 :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and
838 :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN`, the debug output shows the
839 value of the property from each dependency, and whether the value determines
842 Build Specification with Generator Expressions
843 ----------------------------------------------
845 Build specifications may use
846 :manual:`generator expressions <cmake-generator-expressions(7)>` containing
847 content which may be conditional or known only at generate-time. For example,
848 the calculated "compatible" value of a property may be read with the
849 ``TARGET_PROPERTY`` expression:
851 .. code-block:: cmake
853 add_library(lib1Version2 SHARED lib1_v2.cpp)
854 set_property(TARGET lib1Version2 PROPERTY
855 INTERFACE_CONTAINER_SIZE_REQUIRED 200)
856 set_property(TARGET lib1Version2 APPEND PROPERTY
857 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
860 add_executable(exe1 exe1.cpp)
861 target_link_libraries(exe1 lib1Version2)
862 target_compile_definitions(exe1 PRIVATE
863 CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
866 In this case, the ``exe1`` source files will be compiled with
867 ``-DCONTAINER_SIZE=200``.
869 The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY``
870 generator expression are evaluated with the consuming target context. This
871 means that a usage requirement specification may be evaluated differently based
874 .. code-block:: cmake
876 add_library(lib1 lib1.cpp)
877 target_compile_definitions(lib1 INTERFACE
878 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
879 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
880 $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
883 add_executable(exe1 exe1.cpp)
884 target_link_libraries(exe1 lib1)
886 cmake_policy(SET CMP0041 NEW)
888 add_library(shared_lib shared_lib.cpp)
889 target_link_libraries(shared_lib lib1)
891 The ``exe1`` executable will be compiled with ``-DLIB1_WITH_EXE``, while the
892 ``shared_lib`` shared library will be compiled with ``-DLIB1_WITH_SHARED_LIB``
893 and ``-DCONSUMER_CMP0041_NEW``, because policy :policy:`CMP0041` is
894 ``NEW`` at the point where the ``shared_lib`` target is created.
896 The ``BUILD_INTERFACE`` expression wraps requirements which are only used when
897 consumed from a target in the same buildsystem, or when consumed from a target
898 exported to the build directory using the :command:`export` command. The
899 ``INSTALL_INTERFACE`` expression wraps requirements which are only used when
900 consumed from a target which has been installed and exported with the
901 :command:`install(EXPORT)` command:
903 .. code-block:: cmake
905 add_library(ClimbingStats climbingstats.cpp)
906 target_compile_definitions(ClimbingStats INTERFACE
907 $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
908 $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
910 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
911 install(EXPORT libExport NAMESPACE Upstream::
912 DESTINATION lib/cmake/ClimbingStats)
913 export(EXPORT libExport NAMESPACE Upstream::)
915 add_executable(exe1 exe1.cpp)
916 target_link_libraries(exe1 ClimbingStats)
918 In this case, the ``exe1`` executable will be compiled with
919 ``-DClimbingStats_FROM_BUILD_LOCATION``. The exporting commands generate
920 :prop_tgt:`IMPORTED` targets with either the ``INSTALL_INTERFACE`` or the
921 ``BUILD_INTERFACE`` omitted, and the ``*_INTERFACE`` marker stripped away.
922 A separate project consuming the ``ClimbingStats`` package would contain:
924 .. code-block:: cmake
926 find_package(ClimbingStats REQUIRED)
928 add_executable(Downstream main.cpp)
929 target_link_libraries(Downstream Upstream::ClimbingStats)
931 Depending on whether the ``ClimbingStats`` package was used from the build
932 location or the install location, the ``Downstream`` target would be compiled
933 with either ``-DClimbingStats_FROM_BUILD_LOCATION`` or
934 ``-DClimbingStats_FROM_INSTALL_LOCATION``. For more about packages and
935 exporting see the :manual:`cmake-packages(7)` manual.
937 .. _`Include Directories and Usage Requirements`:
939 Include Directories and Usage Requirements
940 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
942 Include directories require some special consideration when specified as usage
943 requirements and when used with generator expressions. The
944 :command:`target_include_directories` command accepts both relative and
945 absolute include directories:
947 .. code-block:: cmake
949 add_library(lib1 lib1.cpp)
950 target_include_directories(lib1 PRIVATE
955 Relative paths are interpreted relative to the source directory where the
956 command appears. Relative paths are not allowed in the
957 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :prop_tgt:`IMPORTED` targets.
959 In cases where a non-trivial generator expression is used, the
960 ``INSTALL_PREFIX`` expression may be used within the argument of an
961 ``INSTALL_INTERFACE`` expression. It is a replacement marker which
962 expands to the installation prefix when imported by a consuming project.
964 Include directories usage requirements commonly differ between the build-tree
965 and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
966 generator expressions can be used to describe separate usage requirements
967 based on the usage location. Relative paths are allowed within the
968 ``INSTALL_INTERFACE`` expression and are interpreted relative to the
969 installation prefix. For example:
971 .. code-block:: cmake
973 add_library(ClimbingStats climbingstats.cpp)
974 target_include_directories(ClimbingStats INTERFACE
975 $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
976 $<INSTALL_INTERFACE:/absolute/path>
977 $<INSTALL_INTERFACE:relative/path>
978 $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
981 Two convenience APIs are provided relating to include directories usage
982 requirements. The :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable
983 may be enabled, with an equivalent effect to:
985 .. code-block:: cmake
987 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
988 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
991 for each target affected. The convenience for installed targets is
992 an ``INCLUDES DESTINATION`` component with the :command:`install(TARGETS)`
995 .. code-block:: cmake
997 install(TARGETS foo bar bat EXPORT tgts ${dest_args}
998 INCLUDES DESTINATION include
1000 install(EXPORT tgts ${other_args})
1001 install(FILES ${headers} DESTINATION include)
1003 This is equivalent to appending ``${CMAKE_INSTALL_PREFIX}/include`` to the
1004 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of each of the installed
1005 :prop_tgt:`IMPORTED` targets when generated by :command:`install(EXPORT)`.
1007 When the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an
1008 :ref:`imported target <Imported targets>` is consumed, the entries in the
1009 property may be treated as system include directories. The effects of that
1010 are toolchain-dependent, but one common effect is to omit compiler warnings
1011 for headers found in those directories. The :prop_tgt:`SYSTEM` property of
1012 the installed target determines this behavior (see the
1013 :prop_tgt:`EXPORT_NO_SYSTEM` property for how to modify the installed value
1014 for a target). It is also possible to change how consumers interpret the
1015 system behavior of consumed imported targets by setting the
1016 :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property on the *consumer*.
1018 If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the
1019 ``Headers`` directory of the framework is also treated as a usage requirement.
1020 This has the same effect as passing the framework directory as an include
1023 Link Libraries and Generator Expressions
1024 ----------------------------------------
1026 Like build specifications, :prop_tgt:`link libraries <LINK_LIBRARIES>` may be
1027 specified with generator expression conditions. However, as consumption of
1028 usage requirements is based on collection from linked dependencies, there is
1029 an additional limitation that the link dependencies must form a "directed
1030 acyclic graph". That is, if linking to a target is dependent on the value of
1031 a target property, that target property may not be dependent on the linked
1034 .. code-block:: cmake
1036 add_library(lib1 lib1.cpp)
1037 add_library(lib2 lib2.cpp)
1038 target_link_libraries(lib1 PUBLIC
1039 $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
1041 add_library(lib3 lib3.cpp)
1042 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
1044 add_executable(exe1 exe1.cpp)
1045 target_link_libraries(exe1 lib1 lib3)
1047 As the value of the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of
1048 the ``exe1`` target is dependent on the linked libraries (``lib3``), and the
1049 edge of linking ``exe1`` is determined by the same
1050 :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
1051 contains a cycle. :manual:`cmake(1)` issues an error message.
1053 .. _`Output Artifacts`:
1058 The buildsystem targets created by the :command:`add_library` and
1059 :command:`add_executable` commands create rules to create binary outputs.
1060 The exact output location of the binaries can only be determined at
1061 generate-time because it can depend on the build-configuration and the
1062 link-language of linked dependencies etc. ``TARGET_FILE``,
1063 ``TARGET_LINKER_FILE`` and related expressions can be used to access the
1064 name and location of generated binaries. These expressions do not work
1065 for ``OBJECT`` libraries however, as there is no single file generated
1066 by such libraries which is relevant to the expressions.
1068 There are three kinds of output artifacts that may be build by targets
1069 as detailed in the following sections. Their classification differs
1070 between DLL platforms and non-DLL platforms. All Windows-based
1071 systems including Cygwin are DLL platforms.
1073 .. _`Runtime Output Artifacts`:
1075 Runtime Output Artifacts
1076 ^^^^^^^^^^^^^^^^^^^^^^^^
1078 A *runtime* output artifact of a buildsystem target may be:
1080 * The executable file (e.g. ``.exe``) of an executable target
1081 created by the :command:`add_executable` command.
1083 * On DLL platforms: the executable file (e.g. ``.dll``) of a shared
1084 library target created by the :command:`add_library` command
1085 with the ``SHARED`` option.
1087 The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
1088 target properties may be used to control runtime output artifact locations
1089 and names in the build tree.
1091 .. _`Library Output Artifacts`:
1093 Library Output Artifacts
1094 ^^^^^^^^^^^^^^^^^^^^^^^^
1096 A *library* output artifact of a buildsystem target may be:
1098 * The loadable module file (e.g. ``.dll`` or ``.so``) of a module
1099 library target created by the :command:`add_library` command
1100 with the ``MODULE`` option.
1102 * On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``)
1103 of a shared library target created by the :command:`add_library`
1104 command with the ``SHARED`` option.
1106 The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME`
1107 target properties may be used to control library output artifact locations
1108 and names in the build tree.
1110 .. _`Archive Output Artifacts`:
1112 Archive Output Artifacts
1113 ^^^^^^^^^^^^^^^^^^^^^^^^
1115 An *archive* output artifact of a buildsystem target may be:
1117 * The static library file (e.g. ``.lib`` or ``.a``) of a static
1118 library target created by the :command:`add_library` command
1119 with the ``STATIC`` option.
1121 * On DLL platforms: the import library file (e.g. ``.lib``) of a shared
1122 library target created by the :command:`add_library` command
1123 with the ``SHARED`` option. This file is only guaranteed to exist if
1124 the library exports at least one unmanaged symbol.
1126 * On DLL platforms: the import library file (e.g. ``.lib``) of an
1127 executable target created by the :command:`add_executable` command
1128 when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
1130 * On AIX: the linker import file (e.g. ``.imp``) of an executable target
1131 created by the :command:`add_executable` command when its
1132 :prop_tgt:`ENABLE_EXPORTS` target property is set.
1134 * On macOS: the linker import file (e.g. ``.tbd``) of a shared library target
1135 created by the :command:`add_library` command with the ``SHARED`` option and
1136 when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
1138 The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
1139 target properties may be used to control archive output artifact locations
1140 and names in the build tree.
1142 Directory-Scoped Commands
1143 -------------------------
1145 The :command:`target_include_directories`,
1146 :command:`target_compile_definitions` and
1147 :command:`target_compile_options` commands have an effect on only one
1148 target at a time. The commands :command:`add_compile_definitions`,
1149 :command:`add_compile_options` and :command:`include_directories` have
1150 a similar function, but operate at directory scope instead of target
1151 scope for convenience.
1153 .. _`Build Configurations`:
1155 Build Configurations
1156 ====================
1158 Configurations determine specifications for a certain type of build, such
1159 as ``Release`` or ``Debug``. The way this is specified depends on the type
1160 of :manual:`generator <cmake-generators(7)>` being used. For single
1161 configuration generators like :ref:`Makefile Generators` and
1162 :generator:`Ninja`, the configuration is specified at configure time by the
1163 :variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators
1164 like :ref:`Visual Studio <Visual Studio Generators>`, :generator:`Xcode`, and
1165 :generator:`Ninja Multi-Config`, the configuration is chosen by the user at
1166 build time and :variable:`CMAKE_BUILD_TYPE` is ignored. In the
1167 multi-configuration case, the set of *available* configurations is specified
1168 at configure time by the :variable:`CMAKE_CONFIGURATION_TYPES` variable,
1169 but the actual configuration used cannot be known until the build stage.
1170 This difference is often misunderstood, leading to problematic code like the
1173 .. code-block:: cmake
1175 # WARNING: This is wrong for multi-config generators because they don't use
1176 # and typically don't even set CMAKE_BUILD_TYPE
1177 string(TOLOWER ${CMAKE_BUILD_TYPE} build_type)
1178 if (build_type STREQUAL debug)
1179 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
1182 :manual:`Generator expressions <cmake-generator-expressions(7)>` should be
1183 used instead to handle configuration-specific logic correctly, regardless of
1184 the generator used. For example:
1186 .. code-block:: cmake
1188 # Works correctly for both single and multi-config generators
1189 target_compile_definitions(exe1 PRIVATE
1190 $<$<CONFIG:Debug>:DEBUG_BUILD>
1193 In the presence of :prop_tgt:`IMPORTED` targets, the content of
1194 :prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also
1195 accounted for by the above :genex:`$<CONFIG:Debug>` expression.
1201 :variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are
1202 just like other variables in that any string comparisons made with their
1203 values will be case-sensitive. The :genex:`$<CONFIG>` generator expression also
1204 preserves the casing of the configuration as set by the user or CMake defaults.
1207 .. code-block:: cmake
1209 # NOTE: Don't use these patterns, they are for illustration purposes only.
1211 set(CMAKE_BUILD_TYPE Debug)
1212 if(CMAKE_BUILD_TYPE STREQUAL DEBUG)
1213 # ... will never get here, "Debug" != "DEBUG"
1215 add_custom_target(print_config ALL
1216 # Prints "Config is Debug" in this single-config case
1217 COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>"
1221 set(CMAKE_CONFIGURATION_TYPES Debug Release)
1222 if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES)
1223 # ... will never get here, "Debug" != "DEBUG"
1226 In contrast, CMake treats the configuration type case-insensitively when
1227 using it internally in places that modify behavior based on the configuration.
1228 For example, the :genex:`$<CONFIG:Debug>` generator expression will evaluate to 1
1229 for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or
1230 even ``DeBuG``. Therefore, you can specify configuration types in
1231 :variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with
1232 any mixture of upper and lowercase, although there are strong conventions
1233 (see the next section). If you must test the value in string comparisons,
1234 always convert the value to upper or lowercase first and adjust the test
1237 Default And Custom Configurations
1238 ---------------------------------
1240 By default, CMake defines a number of standard configurations:
1244 * ``RelWithDebInfo``
1247 In multi-config generators, the :variable:`CMAKE_CONFIGURATION_TYPES` variable
1248 will be populated with (potentially a subset of) the above list by default,
1249 unless overridden by the project or user. The actual configuration used is
1250 selected by the user at build time.
1252 For single-config generators, the configuration is specified with the
1253 :variable:`CMAKE_BUILD_TYPE` variable at configure time and cannot be changed
1254 at build time. The default value will often be none of the above standard
1255 configurations and will instead be an empty string. A common misunderstanding
1256 is that this is the same as ``Debug``, but that is not the case. Users should
1257 always explicitly specify the build type instead to avoid this common problem.
1259 The above standard configuration types provide reasonable behavior on most
1260 platforms, but they can be extended to provide other types. Each configuration
1261 defines a set of compiler and linker flag variables for the language in use.
1262 These variables follow the convention :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`,
1263 where ``<CONFIG>`` is always the uppercase configuration name. When defining
1264 a custom configuration type, make sure these variables are set appropriately,
1265 typically as cache variables.
1271 Some target types do not represent outputs of the buildsystem, but only inputs
1272 such as external dependencies, aliases or other non-build artifacts. Pseudo
1273 targets are not represented in the generated buildsystem.
1275 .. _`Imported Targets`:
1280 An :prop_tgt:`IMPORTED` target represents a pre-existing dependency. Usually
1281 such targets are defined by an upstream package and should be treated as
1282 immutable. After declaring an :prop_tgt:`IMPORTED` target one can adjust its
1283 target properties by using the customary commands such as
1284 :command:`target_compile_definitions`, :command:`target_include_directories`,
1285 :command:`target_compile_options` or :command:`target_link_libraries` just like
1286 with any other regular target.
1288 :prop_tgt:`IMPORTED` targets may have the same usage requirement properties
1289 populated as binary targets, such as
1290 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
1291 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
1292 :prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
1293 :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
1294 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
1296 The :prop_tgt:`LOCATION` may also be read from an IMPORTED target, though there
1297 is rarely reason to do so. Commands such as :command:`add_custom_command` can
1298 transparently use an :prop_tgt:`IMPORTED` :prop_tgt:`EXECUTABLE <TYPE>` target
1299 as a ``COMMAND`` executable.
1301 The scope of the definition of an :prop_tgt:`IMPORTED` target is the directory
1302 where it was defined. It may be accessed and used from subdirectories, but
1303 not from parent directories or sibling directories. The scope is similar to
1304 the scope of a cmake variable.
1306 It is also possible to define a ``GLOBAL`` :prop_tgt:`IMPORTED` target which is
1307 accessible globally in the buildsystem.
1309 See the :manual:`cmake-packages(7)` manual for more on creating packages
1310 with :prop_tgt:`IMPORTED` targets.
1312 .. _`Alias Targets`:
1317 An ``ALIAS`` target is a name which may be used interchangeably with
1318 a binary target name in read-only contexts. A primary use-case for ``ALIAS``
1319 targets is for example or unit test executables accompanying a library, which
1320 may be part of the same buildsystem or built separately based on user
1323 .. code-block:: cmake
1325 add_library(lib1 lib1.cpp)
1326 install(TARGETS lib1 EXPORT lib1Export ${dest_args})
1327 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
1329 add_library(Upstream::lib1 ALIAS lib1)
1331 In another directory, we can link unconditionally to the ``Upstream::lib1``
1332 target, which may be an :prop_tgt:`IMPORTED` target from a package, or an
1333 ``ALIAS`` target if built as part of the same buildsystem.
1335 .. code-block:: cmake
1337 if (NOT TARGET Upstream::lib1)
1338 find_package(lib1 REQUIRED)
1340 add_executable(exe1 exe1.cpp)
1341 target_link_libraries(exe1 Upstream::lib1)
1343 ``ALIAS`` targets are not mutable, installable or exportable. They are
1344 entirely local to the buildsystem description. A name can be tested for
1345 whether it is an ``ALIAS`` name by reading the :prop_tgt:`ALIASED_TARGET`
1348 .. code-block:: cmake
1350 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
1352 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
1355 .. _`Interface Libraries`:
1360 An ``INTERFACE`` library target does not compile sources and does not
1361 produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`.
1363 It may specify usage requirements such as
1364 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
1365 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
1366 :prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
1367 :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
1368 :prop_tgt:`INTERFACE_SOURCES`,
1369 and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
1370 Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
1371 :command:`target_compile_definitions`, :command:`target_compile_options`,
1372 :command:`target_sources`, and :command:`target_link_libraries` commands
1373 may be used with ``INTERFACE`` libraries.
1375 Since CMake 3.19, an ``INTERFACE`` library target may optionally contain
1376 source files. An interface library that contains source files will be
1377 included as a build target in the generated buildsystem. It does not
1378 compile sources, but may contain custom commands to generate other sources.
1379 Additionally, IDEs will show the source files as part of the target for
1380 interactive reading and editing.
1382 A primary use-case for ``INTERFACE`` libraries is header-only libraries.
1383 Since CMake 3.23, header files may be associated with a library by adding
1384 them to a header set using the :command:`target_sources` command:
1386 .. code-block:: cmake
1388 add_library(Eigen INTERFACE)
1390 target_sources(Eigen PUBLIC
1393 FILES src/eigen.h src/vector.h src/matrix.h
1396 add_executable(exe1 exe1.cpp)
1397 target_link_libraries(exe1 Eigen)
1399 When we specify the ``FILE_SET`` here, the ``BASE_DIRS`` we define automatically
1400 become include directories in the usage requirements for the target ``Eigen``.
1401 The usage requirements from the target are consumed and used when compiling, but
1402 have no effect on linking.
1404 Another use-case is to employ an entirely target-focussed design for usage
1407 .. code-block:: cmake
1409 add_library(pic_on INTERFACE)
1410 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
1411 add_library(pic_off INTERFACE)
1412 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
1414 add_library(enable_rtti INTERFACE)
1415 target_compile_options(enable_rtti INTERFACE
1416 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
1419 add_executable(exe1 exe1.cpp)
1420 target_link_libraries(exe1 pic_on enable_rtti)
1422 This way, the build specification of ``exe1`` is expressed entirely as linked
1423 targets, and the complexity of compiler-specific flags is encapsulated in an
1424 ``INTERFACE`` library target.
1426 ``INTERFACE`` libraries may be installed and exported. We can install the
1427 default header set along with the target:
1429 .. code-block:: cmake
1431 add_library(Eigen INTERFACE)
1433 target_sources(Eigen INTERFACE
1436 FILES src/eigen.h src/vector.h src/matrix.h
1439 install(TARGETS Eigen EXPORT eigenExport
1440 FILE_SET HEADERS DESTINATION include/Eigen)
1441 install(EXPORT eigenExport NAMESPACE Upstream::
1442 DESTINATION lib/cmake/Eigen
1445 Here, the headers defined in the header set are installed to ``include/Eigen``.
1446 The install destination automatically becomes an include directory that is a
1447 usage requirement for consumers.