noble (7) cmake-buildsystem.7.gz

Provided by: cmake-data_3.28.3-1build7_all bug

NAME

       cmake-buildsystem - CMake Buildsystem Reference

INTRODUCTION

       A  CMake-based  buildsystem is organized as a set of high-level logical targets.  Each target corresponds
       to an executable or library, or is a custom target containing custom commands.  Dependencies between  the
       targets  are  expressed in the buildsystem to determine the build order and the rules for regeneration in
       response to change.

BINARY TARGETS

       Executables and libraries are  defined  using  the  add_executable()  and  add_library()  commands.   The
       resulting  binary  files  have  appropriate  PREFIX,  SUFFIX  and  extensions  for the platform targeted.
       Dependencies between binary targets are expressed using the target_link_libraries() command:

          add_library(archive archive.cpp zip.cpp lzma.cpp)
          add_executable(zipapp zipapp.cpp)
          target_link_libraries(zipapp archive)

       archive is defined as a STATIC library --  an  archive  containing  objects  compiled  from  archive.cpp,
       zip.cpp,  and  lzma.cpp.   zipapp is defined as an executable formed by compiling and linking zipapp.cpp.
       When linking the zipapp executable, the archive static library is linked in.

   Binary Executables
       The add_executable() command defines an executable target:

          add_executable(mytool mytool.cpp)

       Commands such as add_custom_command(), which generates rules to be run at build  time  can  transparently
       use  an EXECUTABLE target as a COMMAND executable.  The buildsystem rules will ensure that the executable
       is built before attempting to run the command.

   Binary Library Types
   Normal Libraries
       By default, the add_library() command defines a STATIC library, unless a type is specified.  A  type  may
       be specified when using the command:

          add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)

          add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)

       The  BUILD_SHARED_LIBS  variable  may  be enabled to change the behavior of add_library() to build shared
       libraries by default.

       In the context of the buildsystem definition as a whole, it  is  largely  irrelevant  whether  particular
       libraries  are  SHARED or STATIC -- the commands, dependency specifications and other APIs work similarly
       regardless of the library type.  The MODULE library type is dissimilar in that it is generally not linked
       to  --  it is not used in the right-hand-side of the target_link_libraries() command.  It is a type which
       is loaded as a plugin using runtime techniques.  If the library does not  export  any  unmanaged  symbols
       (e.g. Windows resource DLL, C++/CLI DLL), it is required that the library not be a SHARED library because
       CMake expects SHARED libraries to export at least one symbol.

          add_library(archive MODULE 7z.cpp)

   Apple Frameworks
       A SHARED library may be marked with the FRAMEWORK target property to create an  macOS  or  iOS  Framework
       Bundle.   A  library  with  the  FRAMEWORK  target  property should also set the FRAMEWORK_VERSION target
       property.   This  property  is  typically  set  to  the  value  of  "A"  by   macOS   conventions.    The
       MACOSX_FRAMEWORK_IDENTIFIER sets the CFBundleIdentifier key and it uniquely identifies the bundle.

          add_library(MyFramework SHARED MyFramework.cpp)
          set_target_properties(MyFramework PROPERTIES
            FRAMEWORK TRUE
            FRAMEWORK_VERSION A # Version "A" is macOS convention
            MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
          )

   Object Libraries
       The  OBJECT  library  type defines a non-archival collection of object files resulting from compiling the
       given source files.  The object files collection may be used as source inputs to other targets  by  using
       the  syntax $<TARGET_OBJECTS:name>.  This is a generator expression that can be used to supply the OBJECT
       library content to other targets:

          add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)

          add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)

          add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)

       The link (or archiving) step of those other targets will use the object files collection in  addition  to
       those from their own sources.

       Alternatively, object libraries may be linked into other targets:

          add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)

          add_library(archiveExtras STATIC extras.cpp)
          target_link_libraries(archiveExtras PUBLIC archive)

          add_executable(test_exe test.cpp)
          target_link_libraries(test_exe archive)

       The  link (or archiving) step of those other targets will use the object files from OBJECT libraries that
       are directly linked.  Additionally, usage requirements of the  OBJECT  libraries  will  be  honored  when
       compiling  sources  in  those  other  targets.   Furthermore,  those  usage  requirements  will propagate
       transitively to dependents of those other targets.

       Object libraries may not be used as the  TARGET  in  a  use  of  the  add_custom_command(TARGET)  command
       signature.   However,  the list of objects can be used by add_custom_command(OUTPUT) or file(GENERATE) by
       using $<TARGET_OBJECTS:objlib>.

BUILD SPECIFICATION AND USAGE REQUIREMENTS

       The  target_include_directories(),  target_compile_definitions()  and  target_compile_options()  commands
       specify the build specifications and the usage requirements of binary targets.  The commands populate the
       INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS target properties respectively,  and/or  the
       INTERFACE_INCLUDE_DIRECTORIES,   INTERFACE_COMPILE_DEFINITIONS   and   INTERFACE_COMPILE_OPTIONS   target
       properties.

       Each of the commands has a PRIVATE, PUBLIC and INTERFACE mode.   The  PRIVATE  mode  populates  only  the
       non-INTERFACE_  variant  of  the  target  property  and  the INTERFACE mode populates only the INTERFACE_
       variants.  The PUBLIC mode populates both variants of the respective target property.  Each  command  may
       be invoked with multiple uses of each keyword:

          target_compile_definitions(archive
            PRIVATE BUILDING_WITH_LZMA
            INTERFACE USING_ARCHIVE_LIB
          )

       Note that usage requirements are not designed as a way to make downstreams use particular COMPILE_OPTIONS
       or COMPILE_DEFINITIONS etc for convenience only.  The contents of the properties  must  be  requirements,
       not merely recommendations or convenience.

       See  the  Creating  Relocatable  Packages  section  of  the  cmake-packages(7)  manual  for discussion of
       additional care that must be taken  when  specifying  usage  requirements  while  creating  packages  for
       redistribution.

   Target Properties
       The  contents  of  the INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS target properties are
       used appropriately when compiling the source files of a binary target.

       Entries in the INCLUDE_DIRECTORIES are added to the compile line with -I or -isystem prefixes and in  the
       order of appearance in the property value.

       Entries  in  the  COMPILE_DEFINITIONS  are  prefixed  with  -D  or /D and added to the compile line in an
       unspecified order.  The DEFINE_SYMBOL target property is also added as a compile definition as a  special
       convenience case for SHARED and MODULE library targets.

       Entries  in  the  COMPILE_OPTIONS  are  escaped for the shell and added in the order of appearance in the
       property   value.    Several   compile   options   have    special    separate    handling,    such    as
       POSITION_INDEPENDENT_CODE.

       The     contents     of     the    INTERFACE_INCLUDE_DIRECTORIES,    INTERFACE_COMPILE_DEFINITIONS    and
       INTERFACE_COMPILE_OPTIONS target  properties  are  Usage  Requirements  --  they  specify  content  which
       consumers  must use to correctly compile and link with the target they appear on.  For any binary target,
       the contents of each INTERFACE_ property on each target specified in a target_link_libraries() command is
       consumed:

          set(srcs archive.cpp zip.cpp)
          if (LZMA_FOUND)
            list(APPEND srcs lzma.cpp)
          endif()
          add_library(archive SHARED ${srcs})
          if (LZMA_FOUND)
            # The archive library sources are compiled with -DBUILDING_WITH_LZMA
            target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
          endif()
          target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)

          add_executable(consumer)
          # Link consumer to archive and consume its usage requirements. The consumer
          # executable sources are compiled with -DUSING_ARCHIVE_LIB.
          target_link_libraries(consumer archive)

       Because  it is common to require that the source directory and corresponding build directory are added to
       the INCLUDE_DIRECTORIES, the CMAKE_INCLUDE_CURRENT_DIR variable can be enabled to  conveniently  add  the
       corresponding    directories    to    the    INCLUDE_DIRECTORIES    of   all   targets.    The   variable
       CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE can be  enabled  to  add  the  corresponding  directories  to  the
       INTERFACE_INCLUDE_DIRECTORIES  of  all  targets.   This  makes  use  of  targets  in  multiple  different
       directories convenient through use of the target_link_libraries() command.

   Transitive Usage Requirements
       The  usage  requirements  of  a   target   can   transitively   propagate   to   the   dependents.    The
       target_link_libraries() command has PRIVATE, INTERFACE and PUBLIC keywords to control the propagation.

          add_library(archive archive.cpp)
          target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)

          add_library(serialization serialization.cpp)
          target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)

          add_library(archiveExtras extras.cpp)
          target_link_libraries(archiveExtras PUBLIC archive)
          target_link_libraries(archiveExtras PRIVATE serialization)
          # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
          # and -DUSING_SERIALIZATION_LIB

          add_executable(consumer consumer.cpp)
          # consumer is compiled with -DUSING_ARCHIVE_LIB
          target_link_libraries(consumer archiveExtras)

       Because  the archive is a PUBLIC dependency of archiveExtras, the usage requirements of it are propagated
       to consumer too.

       Because serialization is a PRIVATE dependency of archiveExtras, the usage  requirements  of  it  are  not
       propagated to consumer.

       Generally,  a dependency should be specified in a use of target_link_libraries() with the PRIVATE keyword
       if it is used by only the implementation of a library, and not in the header files.  If a  dependency  is
       additionally  used  in  the  header  files  of  a library (e.g. for class inheritance), then it should be
       specified as a PUBLIC dependency.  A dependency which is not used by the implementation of a library, but
       only  by its headers should be specified as an INTERFACE dependency.  The target_link_libraries() command
       may be invoked with multiple uses of each keyword:

          target_link_libraries(archiveExtras
            PUBLIC archive
            PRIVATE serialization
          )

       Usage requirements  are  propagated  by  reading  the  INTERFACE_  variants  of  target  properties  from
       dependencies  and  appending  the values to the non-INTERFACE_ variants of the operand.  For example, the
       INTERFACE_INCLUDE_DIRECTORIES of dependencies is read and appended  to  the  INCLUDE_DIRECTORIES  of  the
       operand.   In  cases  where  order  is  relevant  and  maintained,  and  the  order  resulting  from  the
       target_link_libraries() calls does not allow correct compilation, use of an appropriate  command  to  set
       the property directly may update the order.

       For example, if the linked libraries for a target must be specified in the order lib1 lib2 lib3 , but the
       include directories must be specified in the order lib3 lib1 lib2:

          target_link_libraries(myExe lib1 lib2 lib3)
          target_include_directories(myExe
            PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)

       Note that care must be taken when specifying usage requirements for targets which will  be  exported  for
       installation using the install(EXPORT) command.  See Creating Packages for more.

   Compatible Interface Properties
       Some  target  properties  are  required  to  be  compatible  between  a  target and the interface of each
       dependency.  For example, the POSITION_INDEPENDENT_CODE target property may specify a  boolean  value  of
       whether   a   target  should  be  compiled  as  position-independent-code,  which  has  platform-specific
       consequences.  A target may also specify the  usage  requirement  INTERFACE_POSITION_INDEPENDENT_CODE  to
       communicate that consumers must be compiled as position-independent-code.

          add_executable(exe1 exe1.cpp)
          set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)

          add_library(lib1 SHARED lib1.cpp)
          set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

          add_executable(exe2 exe2.cpp)
          target_link_libraries(exe2 lib1)

       Here,  both  exe1  and exe2 will be compiled as position-independent-code.  lib1 will also be compiled as
       position-independent-code because that is the default setting for SHARED libraries.  If dependencies have
       conflicting, non-compatible requirements cmake(1) issues a diagnostic:

          add_library(lib1 SHARED lib1.cpp)
          set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

          add_library(lib2 SHARED lib2.cpp)
          set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 lib1)
          set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)

          add_executable(exe2 exe2.cpp)
          target_link_libraries(exe2 lib1 lib2)

       The    lib1    requirement    INTERFACE_POSITION_INDEPENDENT_CODE    is   not   "compatible"   with   the
       POSITION_INDEPENDENT_CODE property of the exe1 target.  The library requires that consumers are built  as
       position-independent-code, while the executable specifies to not built as position-independent-code, so a
       diagnostic is issued.

       The lib1 and lib2 requirements are not "compatible".  One of them requires that consumers  are  built  as
       position-independent-code,    while    the   other   requires   that   consumers   are   not   built   as
       position-independent-code.  Because exe2 links to both and they are in conflict, a CMake error message is
       issued:

          CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
          not agree with the value of POSITION_INDEPENDENT_CODE already determined
          for "exe2".

       To  be "compatible", the POSITION_INDEPENDENT_CODE property, if set must be either the same, in a boolean
       sense, as the INTERFACE_POSITION_INDEPENDENT_CODE property of all transitively specified dependencies  on
       which that property is set.

       This property of "compatible interface requirement" may be extended to other properties by specifying the
       property in the content of the COMPATIBLE_INTERFACE_BOOL target property.  Each specified  property  must
       be  compatible between the consuming target and the corresponding property with an INTERFACE_ prefix from
       each dependency:

          add_library(lib1Version2 SHARED lib1_v2.cpp)
          set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
          set_property(TARGET lib1Version2 APPEND PROPERTY
            COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
          )

          add_library(lib1Version3 SHARED lib1_v3.cpp)
          set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON

          add_executable(exe2 exe2.cpp)
          target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic

       Non-boolean properties may also participate in "compatible interface" computations.  Properties specified
       in  the  COMPATIBLE_INTERFACE_STRING  property  must  be either unspecified or compare to the same string
       among all transitively specified dependencies. This can be useful to ensure  that  multiple  incompatible
       versions of a library are not linked together through transitive requirements of a target:

          add_library(lib1Version2 SHARED lib1_v2.cpp)
          set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
          set_property(TARGET lib1Version2 APPEND PROPERTY
            COMPATIBLE_INTERFACE_STRING LIB_VERSION
          )

          add_library(lib1Version3 SHARED lib1_v3.cpp)
          set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"

          add_executable(exe2 exe2.cpp)
          target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic

       The  COMPATIBLE_INTERFACE_NUMBER_MAX target property specifies that content will be evaluated numerically
       and the maximum number among all specified will be calculated:

          add_library(lib1Version2 SHARED lib1_v2.cpp)
          set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
          set_property(TARGET lib1Version2 APPEND PROPERTY
            COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
          )

          add_library(lib1Version3 SHARED lib1_v3.cpp)
          set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)

          add_executable(exe1 exe1.cpp)
          # CONTAINER_SIZE_REQUIRED will be "200"
          target_link_libraries(exe1 lib1Version2)

          add_executable(exe2 exe2.cpp)
          # CONTAINER_SIZE_REQUIRED will be "1000"
          target_link_libraries(exe2 lib1Version2 lib1Version3)

       Similarly, the COMPATIBLE_INTERFACE_NUMBER_MIN may be used to calculate the numeric minimum value  for  a
       property from dependencies.

       Each  calculated "compatible" property value may be read in the consumer at generate-time using generator
       expressions.

       Note that for each dependee, the set of properties specified in each compatible interface  property  must
       not intersect with the set specified in any of the other properties.

   Property Origin Debugging
       Because  build  specifications  can  be  determined  by  dependencies, the lack of locality of code which
       creates a target and code which is responsible for setting build specifications may make  the  code  more
       difficult to reason about.  cmake(1) provides a debugging facility to print the origin of the contents of
       properties which may be determined by dependencies.  The properties which can be debugged are  listed  in
       the CMAKE_DEBUG_TARGET_PROPERTIES variable documentation:

          set(CMAKE_DEBUG_TARGET_PROPERTIES
            INCLUDE_DIRECTORIES
            COMPILE_DEFINITIONS
            POSITION_INDEPENDENT_CODE
            CONTAINER_SIZE_REQUIRED
            LIB_VERSION
          )
          add_executable(exe1 exe1.cpp)

       In  the  case of properties listed in COMPATIBLE_INTERFACE_BOOL or COMPATIBLE_INTERFACE_STRING, the debug
       output shows which target was responsible for setting the property, and  which  other  dependencies  also
       defined     the     property.      In     the     case     of     COMPATIBLE_INTERFACE_NUMBER_MAX     and
       COMPATIBLE_INTERFACE_NUMBER_MIN, the debug output shows the value of the property from  each  dependency,
       and whether the value determines the new extreme.

   Build Specification with Generator Expressions
       Build  specifications  may use generator expressions containing content which may be conditional or known
       only at generate-time.  For example, the calculated "compatible" value of a property may be read with the
       TARGET_PROPERTY expression:

          add_library(lib1Version2 SHARED lib1_v2.cpp)
          set_property(TARGET lib1Version2 PROPERTY
            INTERFACE_CONTAINER_SIZE_REQUIRED 200)
          set_property(TARGET lib1Version2 APPEND PROPERTY
            COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
          )

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 lib1Version2)
          target_compile_definitions(exe1 PRIVATE
              CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
          )

       In this case, the exe1 source files will be compiled with -DCONTAINER_SIZE=200.

       The  unary  TARGET_PROPERTY generator expression and the TARGET_POLICY generator expression are evaluated
       with the consuming target context.  This means that a usage requirement specification  may  be  evaluated
       differently based on the consumer:

          add_library(lib1 lib1.cpp)
          target_compile_definitions(lib1 INTERFACE
            $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
            $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
            $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
          )

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 lib1)

          cmake_policy(SET CMP0041 NEW)

          add_library(shared_lib shared_lib.cpp)
          target_link_libraries(shared_lib lib1)

       The  exe1  executable  will be compiled with -DLIB1_WITH_EXE, while the shared_lib shared library will be
       compiled with -DLIB1_WITH_SHARED_LIB and -DCONSUMER_CMP0041_NEW, because policy CMP0041  is  NEW  at  the
       point where the shared_lib target is created.

       The  BUILD_INTERFACE expression wraps requirements which are only used when consumed from a target in the
       same buildsystem, or when consumed from a target exported to  the  build  directory  using  the  export()
       command.   The  INSTALL_INTERFACE  expression wraps requirements which are only used when consumed from a
       target which has been installed and exported with the install(EXPORT) command:

          add_library(ClimbingStats climbingstats.cpp)
          target_compile_definitions(ClimbingStats INTERFACE
            $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
            $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
          )
          install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
          install(EXPORT libExport NAMESPACE Upstream::
                  DESTINATION lib/cmake/ClimbingStats)
          export(EXPORT libExport NAMESPACE Upstream::)

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 ClimbingStats)

       In this case, the  exe1  executable  will  be  compiled  with  -DClimbingStats_FROM_BUILD_LOCATION.   The
       exporting  commands  generate  IMPORTED  targets with either the INSTALL_INTERFACE or the BUILD_INTERFACE
       omitted, and the *_INTERFACE marker stripped  away.   A  separate  project  consuming  the  ClimbingStats
       package would contain:

          find_package(ClimbingStats REQUIRED)

          add_executable(Downstream main.cpp)
          target_link_libraries(Downstream Upstream::ClimbingStats)

       Depending  on whether the ClimbingStats package was used from the build location or the install location,
       the  Downstream  target  would   be   compiled   with   either   -DClimbingStats_FROM_BUILD_LOCATION   or
       -DClimbingStats_FROM_INSTALL_LOCATION.   For  more about packages and exporting see the cmake-packages(7)
       manual.

   Include Directories and Usage Requirements
       Include directories require some special consideration when specified as usage requirements and when used
       with  generator expressions.  The target_include_directories() command accepts both relative and absolute
       include directories:

          add_library(lib1 lib1.cpp)
          target_include_directories(lib1 PRIVATE
            /absolute/path
            relative/path
          )

       Relative paths are interpreted relative to the source directory  where  the  command  appears.   Relative
       paths are not allowed in the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED targets.

       In  cases  where  a  non-trivial  generator expression is used, the INSTALL_PREFIX expression may be used
       within the argument of an INSTALL_INTERFACE expression.  It is a replacement marker which expands to  the
       installation prefix when imported by a consuming project.

       Include  directories usage requirements commonly differ between the build-tree and the install-tree.  The
       BUILD_INTERFACE and INSTALL_INTERFACE generator expressions  can  be  used  to  describe  separate  usage
       requirements  based  on  the  usage  location.   Relative  paths are allowed within the INSTALL_INTERFACE
       expression and are interpreted relative to the installation prefix.  For example:

          add_library(ClimbingStats climbingstats.cpp)
          target_include_directories(ClimbingStats INTERFACE
            $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
            $<INSTALL_INTERFACE:/absolute/path>
            $<INSTALL_INTERFACE:relative/path>
            $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
          )

       Two  convenience  APIs  are  provided  relating  to  include   directories   usage   requirements.    The
       CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE variable may be enabled, with an equivalent effect to:

          set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
          )

       for  each  target  affected.   The convenience for installed targets is an INCLUDES DESTINATION component
       with the install(TARGETS) command:

          install(TARGETS foo bar bat EXPORT tgts ${dest_args}
            INCLUDES DESTINATION include
          )
          install(EXPORT tgts ${other_args})
          install(FILES ${headers} DESTINATION include)

       This is equivalent to appending ${CMAKE_INSTALL_PREFIX}/include to the  INTERFACE_INCLUDE_DIRECTORIES  of
       each of the installed IMPORTED targets when generated by install(EXPORT).

       When the INTERFACE_INCLUDE_DIRECTORIES of an imported target is consumed, the entries in the property may
       be treated as system include directories.  The effects of that are toolchain-dependent,  but  one  common
       effect  is  to omit compiler warnings for headers found in those directories.  The SYSTEM property of the
       installed target determines this behavior (see the  EXPORT_NO_SYSTEM  property  for  how  to  modify  the
       installed value for a target).  It is also possible to change how consumers interpret the system behavior
       of consumed imported targets by setting the NO_SYSTEM_FROM_IMPORTED target property on the consumer.

       If a binary target is linked transitively to a macOS FRAMEWORK, the Headers directory of the framework is
       also  treated  as a usage requirement.  This has the same effect as passing the framework directory as an
       include directory.

   Link Libraries and Generator Expressions
       Like build specifications,  link  libraries  may  be  specified  with  generator  expression  conditions.
       However,  as  consumption of usage requirements is based on collection from linked dependencies, there is
       an additional limitation that the link dependencies must form a "directed acyclic graph".   That  is,  if
       linking  to  a  target  is  dependent  on the value of a target property, that target property may not be
       dependent on the linked dependencies:

          add_library(lib1 lib1.cpp)
          add_library(lib2 lib2.cpp)
          target_link_libraries(lib1 PUBLIC
            $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
          )
          add_library(lib3 lib3.cpp)
          set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 lib1 lib3)

       As the value of the POSITION_INDEPENDENT_CODE property of the exe1 target  is  dependent  on  the  linked
       libraries  (lib3),  and  the  edge  of  linking  exe1 is determined by the same POSITION_INDEPENDENT_CODE
       property, the dependency graph above contains a cycle.  cmake(1) issues an error message.

   Output Artifacts
       The buildsystem targets created by the add_library() and add_executable() commands create rules to create
       binary  outputs.   The  exact  output  location  of  the binaries can only be determined at generate-time
       because it can depend on the build-configuration  and  the  link-language  of  linked  dependencies  etc.
       TARGET_FILE,  TARGET_LINKER_FILE  and  related expressions can be used to access the name and location of
       generated binaries.  These expressions do not work for OBJECT libraries however, as there  is  no  single
       file generated by such libraries which is relevant to the expressions.

       There  are  three  kinds  of  output  artifacts that may be build by targets as detailed in the following
       sections.  Their classification differs between DLL platforms and non-DLL platforms.   All  Windows-based
       systems including Cygwin are DLL platforms.

   Runtime Output Artifacts
       A runtime output artifact of a buildsystem target may be:

       • The executable file (e.g. .exe) of an executable target created by the add_executable() command.

       • On  DLL  platforms:  the  executable  file  (e.g.  .dll)  of  a  shared  library  target created by the
         add_library() command with the SHARED option.

       The RUNTIME_OUTPUT_DIRECTORY and RUNTIME_OUTPUT_NAME target properties may be  used  to  control  runtime
       output artifact locations and names in the build tree.

   Library Output Artifacts
       A library output artifact of a buildsystem target may be:

       • The  loadable  module  file  (e.g. .dll or .so) of a module library target created by the add_library()
         command with the MODULE option.

       • On non-DLL platforms: the shared library file (e.g. .so or .dylib) of a shared library  target  created
         by the add_library() command with the SHARED option.

       The  LIBRARY_OUTPUT_DIRECTORY  and  LIBRARY_OUTPUT_NAME  target properties may be used to control library
       output artifact locations and names in the build tree.

   Archive Output Artifacts
       An archive output artifact of a buildsystem target may be:

       • The static library file (e.g. .lib or .a) of a static  library  target  created  by  the  add_library()
         command with the STATIC option.

       • On  DLL  platforms:  the  import  library  file  (e.g.  .lib) of a shared library target created by the
         add_library() command with the SHARED option.  This file is only guaranteed to  exist  if  the  library
         exports at least one unmanaged symbol.

       • On  DLL  platforms:  the  import  library  file  (e.g.  .lib)  of  an  executable target created by the
         add_executable() command when its ENABLE_EXPORTS target property is set.

       • On AIX: the linker import file (e.g. .imp) of an executable  target  created  by  the  add_executable()
         command when its ENABLE_EXPORTS target property is set.

       • On  macOS:  the  linker import file (e.g. .tbd) of a shared library target created by the add_library()
         command with the SHARED option and when its ENABLE_EXPORTS target property is set.

       The ARCHIVE_OUTPUT_DIRECTORY and ARCHIVE_OUTPUT_NAME target properties may be  used  to  control  archive
       output artifact locations and names in the build tree.

   Directory-Scoped Commands
       The target_include_directories(), target_compile_definitions() and target_compile_options() commands have
       an effect on only one target at a time.  The  commands  add_compile_definitions(),  add_compile_options()
       and include_directories() have a similar function, but operate at directory scope instead of target scope
       for convenience.

BUILD CONFIGURATIONS

       Configurations determine specifications for a certain type of build, such as Release or Debug.   The  way
       this  is specified depends on the type of generator being used.  For single configuration generators like
       Makefile Generators and Ninja, the configuration is specified at configure time by  the  CMAKE_BUILD_TYPE
       variable.  For  multi-configuration  generators  like  Visual  Studio, Xcode, and Ninja Multi-Config, the
       configuration  is  chosen  by  the  user  at  build  time  and  CMAKE_BUILD_TYPE  is  ignored.   In   the
       multi-configuration  case,  the  set  of  available  configurations is specified at configure time by the
       CMAKE_CONFIGURATION_TYPES variable, but the actual configuration used cannot be  known  until  the  build
       stage.  This difference is often misunderstood, leading to problematic code like the following:

          # WARNING: This is wrong for multi-config generators because they don't use
          #          and typically don't even set CMAKE_BUILD_TYPE
          string(TOLOWER ${CMAKE_BUILD_TYPE} build_type)
          if (build_type STREQUAL debug)
            target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
          endif()

       Generator expressions should be used instead to handle configuration-specific logic correctly, regardless
       of the generator used.  For example:

          # Works correctly for both single and multi-config generators
          target_compile_definitions(exe1 PRIVATE
            $<$<CONFIG:Debug>:DEBUG_BUILD>
          )

       In the presence of IMPORTED targets, the content of MAP_IMPORTED_CONFIG_DEBUG is also  accounted  for  by
       the above $<CONFIG:Debug> expression.

   Case Sensitivity
       CMAKE_BUILD_TYPE  and  CMAKE_CONFIGURATION_TYPES  are  just  like  other  variables  in  that  any string
       comparisons made with their values will be  case-sensitive.   The  $<CONFIG>  generator  expression  also
       preserves the casing of the configuration as set by the user or CMake defaults.  For example:

          # NOTE: Don't use these patterns, they are for illustration purposes only.

          set(CMAKE_BUILD_TYPE Debug)
          if(CMAKE_BUILD_TYPE STREQUAL DEBUG)
            # ... will never get here, "Debug" != "DEBUG"
          endif()
          add_custom_target(print_config ALL
            # Prints "Config is Debug" in this single-config case
            COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>"
            VERBATIM
          )

          set(CMAKE_CONFIGURATION_TYPES Debug Release)
          if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES)
            # ... will never get here, "Debug" != "DEBUG"
          endif()

       In  contrast,  CMake  treats the configuration type case-insensitively when using it internally in places
       that modify behavior based on the configuration.  For example, the $<CONFIG:Debug>  generator  expression
       will  evaluate  to  1  for  a  configuration  of  not  only  Debug,  but also DEBUG, debug or even DeBuG.
       Therefore, you can specify configuration types in CMAKE_BUILD_TYPE and CMAKE_CONFIGURATION_TYPES with any
       mixture  of  upper  and  lowercase, although there are strong conventions (see the next section).  If you
       must test the value in string comparisons, always convert the value  to  upper  or  lowercase  first  and
       adjust the test accordingly.

   Default And Custom Configurations
       By default, CMake defines a number of standard configurations:

       • DebugReleaseRelWithDebInfoMinSizeRel

       In  multi-config generators, the CMAKE_CONFIGURATION_TYPES variable will be populated with (potentially a
       subset of) the above list by default, unless overridden by the project or user.  The actual configuration
       used is selected by the user at build time.

       For  single-config  generators,  the  configuration  is  specified  with the CMAKE_BUILD_TYPE variable at
       configure time and cannot be changed at build time.  The default value will often be none  of  the  above
       standard  configurations  and will instead be an empty string.  A common misunderstanding is that this is
       the same as Debug, but that is not the case.  Users should  always  explicitly  specify  the  build  type
       instead to avoid this common problem.

       The  above  standard  configuration  types provide reasonable behavior on most platforms, but they can be
       extended to provide other types.  Each configuration defines a set of compiler and linker flag  variables
       for  the  language  in  use.   These  variables  follow the convention CMAKE_<LANG>_FLAGS_<CONFIG>, where
       <CONFIG> is always the uppercase configuration name.  When defining a  custom  configuration  type,  make
       sure these variables are set appropriately, typically as cache variables.

PSEUDO TARGETS

       Some  target  types  do  not  represent  outputs  of  the  buildsystem,  but only inputs such as external
       dependencies, aliases or other non-build artifacts.  Pseudo targets are not represented in the  generated
       buildsystem.

   Imported Targets
       An IMPORTED target represents a pre-existing dependency.  Usually such targets are defined by an upstream
       package and should be treated as immutable. After declaring an IMPORTED target one can adjust its  target
       properties     by    using    the    customary    commands    such    as    target_compile_definitions(),
       target_include_directories(), target_compile_options() or  target_link_libraries()  just  like  with  any
       other regular target.

       IMPORTED  targets  may  have  the  same usage requirement properties populated as binary targets, such as
       INTERFACE_INCLUDE_DIRECTORIES,         INTERFACE_COMPILE_DEFINITIONS,          INTERFACE_COMPILE_OPTIONS,
       INTERFACE_LINK_LIBRARIES, and INTERFACE_POSITION_INDEPENDENT_CODE.

       The  LOCATION may also be read from an IMPORTED target, though there is rarely reason to do so.  Commands
       such as add_custom_command() can transparently use an IMPORTED EXECUTABLE target as a COMMAND executable.

       The scope of the definition of an IMPORTED target is the directory where  it  was  defined.   It  may  be
       accessed and used from subdirectories, but not from parent directories or sibling directories.  The scope
       is similar to the scope of a cmake variable.

       It is also possible to define a GLOBAL IMPORTED target which is accessible globally in the buildsystem.

       See the cmake-packages(7) manual for more on creating packages with IMPORTED targets.

   Alias Targets
       An ALIAS target is a name which may be used interchangeably  with  a  binary  target  name  in  read-only
       contexts.   A  primary  use-case for ALIAS targets is for example or unit test executables accompanying a
       library, which may be part of the same buildsystem or built separately based on user configuration.

          add_library(lib1 lib1.cpp)
          install(TARGETS lib1 EXPORT lib1Export ${dest_args})
          install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})

          add_library(Upstream::lib1 ALIAS lib1)

       In another directory, we can link unconditionally to the Upstream::lib1 target, which may be an  IMPORTED
       target from a package, or an ALIAS target if built as part of the same buildsystem.

          if (NOT TARGET Upstream::lib1)
            find_package(lib1 REQUIRED)
          endif()
          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 Upstream::lib1)

       ALIAS  targets  are  not  mutable, installable or exportable.  They are entirely local to the buildsystem
       description.  A name can be tested for whether it is an ALIAS name by reading the ALIASED_TARGET property
       from it:

          get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
          if(_aliased)
            message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
          endif()

   Interface Libraries
       An  INTERFACE library target does not compile sources and does not produce a library artifact on disk, so
       it has no LOCATION.

       It may specify usage requirements such as  INTERFACE_INCLUDE_DIRECTORIES,  INTERFACE_COMPILE_DEFINITIONS,
       INTERFACE_COMPILE_OPTIONS,           INTERFACE_LINK_LIBRARIES,           INTERFACE_SOURCES,           and
       INTERFACE_POSITION_INDEPENDENT_CODE.  Only  the  INTERFACE  modes  of  the  target_include_directories(),
       target_compile_definitions(),  target_compile_options(),  target_sources(),  and  target_link_libraries()
       commands may be used with INTERFACE libraries.

       Since CMake 3.19, an INTERFACE library target may optionally contain source files.  An interface  library
       that  contains source files will be included as a build target in the generated buildsystem.  It does not
       compile sources, but may contain custom commands to generate other sources.  Additionally, IDEs will show
       the source files as part of the target for interactive reading and editing.

       A  primary use-case for INTERFACE libraries is header-only libraries.  Since CMake 3.23, header files may
       be associated with a library by adding them to a header set using the target_sources() command:

          add_library(Eigen INTERFACE)

          target_sources(Eigen PUBLIC
            FILE_SET HEADERS
              BASE_DIRS src
              FILES src/eigen.h src/vector.h src/matrix.h
          )

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 Eigen)

       When we specify the FILE_SET here, the BASE_DIRS we define automatically become  include  directories  in
       the  usage  requirements  for  the target Eigen.  The usage requirements from the target are consumed and
       used when compiling, but have no effect on linking.

       Another use-case is to employ an entirely target-focussed design for usage requirements:

          add_library(pic_on INTERFACE)
          set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
          add_library(pic_off INTERFACE)
          set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)

          add_library(enable_rtti INTERFACE)
          target_compile_options(enable_rtti INTERFACE
            $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
          )

          add_executable(exe1 exe1.cpp)
          target_link_libraries(exe1 pic_on enable_rtti)

       This way, the build specification of exe1 is expressed entirely as linked targets, and the complexity  of
       compiler-specific flags is encapsulated in an INTERFACE library target.

       INTERFACE  libraries  may be installed and exported. We can install the default header set along with the
       target:

          add_library(Eigen INTERFACE)

          target_sources(Eigen INTERFACE
            FILE_SET HEADERS
              BASE_DIRS src
              FILES src/eigen.h src/vector.h src/matrix.h
          )

          install(TARGETS Eigen EXPORT eigenExport
            FILE_SET HEADERS DESTINATION include/Eigen)
          install(EXPORT eigenExport NAMESPACE Upstream::
            DESTINATION lib/cmake/Eigen
          )

       Here, the headers defined in the header set are installed  to  include/Eigen.   The  install  destination
       automatically becomes an include directory that is a usage requirement for consumers.

       2000-2024 Kitware, Inc. and Contributors