Help: Add cmake-buildsystem.7 manual

Describe how to define a buildsystem of binary targets, how to
express dependencies between them, how to add build specifications,
how to specify usage requirements, transitive and compatible
propagation and the various pseudo targets.

2 files changed, 795 insertions, 0 deletions

diff --git a/Help/index.rst b/Help/index.rst
index a7a1bd9..551db75 100644
--- a/Help/index.rst
+++ b/Help/index.rst
@@ -25,6 +25,7 @@ Reference Manuals
 .. toctree::
    :maxdepth: 1
 
+   /manual/cmake-buildsystem.7
    /manual/cmake-commands.7
    /manual/cmake-developer.7
    /manual/cmake-generator-expressions.7
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
new file mode 100644
index 0000000..be60ebb
--- /dev/null
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -0,0 +1,794 @@
+.. cmake-manual-description: CMake Buildsystem Reference
+
+cmake-buildsystem(7)
+********************
+
+.. only:: html or latex
+
+   .. contents::
+
+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 :command:`add_library`
+and :command:`add_executable` commands.  The resulting binary files have
+appropriate prefixes, suffixes and extensions for the platform targeted.
+Dependencies between binary targets are expressed using the
+:command:`target_link_libraries` command:
+
+.. code-block:: cmake
+
+  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 Library Types
+--------------------
+
+By default, the :command:`add_library` command defines a static library,
+unless a type is specified.  A type may be specified when using the command:
+
+.. code-block:: cmake
+
+  add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)
+
+.. code-block:: cmake
+
+  add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
+
+The :variable:`BUILD_SHARED_LIBS` variable may be enabled to change the
+behavior of :command:`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 :command:`target_link_libraries` command.
+It is a type which is loaded as a plugin using runtime techniques.
+
+.. code-block:: cmake
+
+  add_library(archive MODULE 7z.cpp)
+
+The ``OBJECT`` library type is also not linked to. It defines a non-archival
+collection of object files resulting from compiling the given source files.
+The object files collection can be used as source inputs to other targets:
+
+.. code-block:: cmake
+
+  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)
+
+``OBJECT`` libraries may only be used locally as sources in a buildsystem --
+they may not be installed, exported, or used in the right hand side of
+:command:`target_link_libraries`.  They also may not be used as the ``TARGET``
+in a use of the :command:`add_custom_command(TARGET)` command signature.
+
+Commands such as :command:`add_custom_command`, which generates rules to be
+run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
+target as a ``COMMAND`` executable.  The buildsystem rules will ensure that
+the executable is built before attempting to run the command.
+
+Build Specification and Usage Requirements
+==========================================
+
+The :command:`target_include_directories`, :command:`target_compile_definitions`
+and :command:`target_compile_options` commands specify the build specifications
+and the usage requirements of binary targets.  The commands populate the
+:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and
+:prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
+and :prop_tgt:`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 repective target property.
+Each command may be invoked with multiple uses of each keyword:
+
+.. code-block:: cmake
+
+  target_compile_definitions(archive
+    PRIVATE BUILDING_WITH_LZMA
+    INTERFACE USING_ARCHIVE_LIB
+  )
+
+Target Properties
+-----------------
+
+The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`,
+:prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target
+properties are used appropriately when compiling the source files of a
+binary target.
+
+Entries in the :prop_tgt:`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 :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or
+``/D`` and added to the compile line in an unspecified order.  The
+:prop_tgt:`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 :prop_tgt:`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 :prop_tgt:`POSITION_INDEPENDENT_CODE`.
+
+The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
+:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and
+:prop_tgt:`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 :command:`target_link_libraries` command is
+consumed:
+
+.. code-block:: cmake
+
+  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 :prop_tgt:`INCLUDE_DIRECTORIES`, the
+:variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently
+add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of
+all targets.  The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`
+can be enabled to add the corresponding directories to the
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets.  This makes use of
+targets in multiple different directories convenient through use of the
+:command:`target_link_libraries` command.
+
+Transitive Usage Requirements
+-----------------------------
+
+The usage requirements of a target can transitively propagate to dependents.
+The :command:`target_link_libraries` command also has ``PRIVATE``,
+``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
+
+.. code-block:: cmake
+
+  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 ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the
+usage requirements of it are propagated to ``consumer`` too.  Because
+``serialization`` is a ``PRIVATE`` dependency of ``archive``, the usage
+requirements of it are not propagated to ``consumer``.
+
+Generally, a dependency should be specified in a use of
+:command:`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
+:command:`target_link_libraries` command may be invoked with multiple uses of
+each keyword:
+
+.. code-block:: cmake
+
+  target_link_libraries(archiveExtras
+    PUBLIC archive
+    PRIVATE serialization
+  )
+
+Compatible Interface Properties
+-------------------------------
+
+Some target properties are required to be compatible between a target and
+the interface of each dependency.  For example, the
+:prop_tgt:`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
+:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` to communicate that
+consumers must be compiled as position-independent-code.
+
+.. code-block:: cmake
+
+  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 :manual:`cmake(1)` issues a diagnostic:
+
+.. code-block:: cmake
+
+  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 diagnostic is
+issued.
+
+To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property,
+if set must be either the same, in a boolean sense, as the
+:prop_tgt:`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
+:prop_tgt:`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:
+
+.. code-block:: cmake
+
+  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
+:prop_tgt:`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:
+
+.. code-block:: cmake
+
+  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 :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` target property specifies
+that content will be evaluated numerically and the maximum number among all
+specified will be calculated:
+
+.. code-block:: cmake
+
+  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 lib1Version2 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 :prop_tgt:`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.
+
+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.
+:manual:`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 :prop_tgt:`INCLUDE_DIRECTORIES`,
+:prop_tgt:`COMPILE_DEFINITIONS`, :prop_tgt:`COMPILE_OPTIONS`,
+:prop_tgt:`AUTOUIC_OPTIONS`, and all properties listed in a
+``COMPATIBLE_INTERFACE_*`` target property:
+
+.. code-block:: cmake
+
+  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 :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` or
+:prop_tgt:`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
+:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and
+:prop_tgt:`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
+:manual:`generator expressions <cmake-generator-expressions(7)>` 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:
+
+.. code-block:: cmake
+
+  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``.
+
+Configuration determined build specifications may be conveniently set using
+the ``CONFIG`` generator expression.
+
+.. code-block:: cmake
+
+  target_compile_definitions(exe1 PRIVATE
+      $<$<CONFIG:Debug>:DEBUG_BUILD>
+  )
+
+The ``CONFIG`` parameter is compared case-insensitively with the configuration
+being built.  In the presence of :prop_tgt:`IMPORTED` targets, the content of
+:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_CONFIG>` is also
+accounted for by this expression.
+
+Some buildsystems generated by :manual:`cmake(1)` have a predetermined
+build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable.  The
+buildsystem for the IDEs such as Visual Studio and Xcode are generated
+independent of the build-configuration, and the actual build configuration
+is not known until build-time.  Therefore, code such as
+
+.. code-block:: cmake
+
+  string(TOLOWER ${CMAKE_BUILD_TYPE} _type)
+  if (_type STREQUAL debug)
+    target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
+  endif()
+
+may appear to work for ``Makefile`` based and ``Ninja`` generators, but is not
+portable to IDE generators.  Additionally, the :prop_tgt:`IMPORTED`
+configuration-mappings are not accounted for with code like this, so it should
+be avoided.
+
+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:
+
+.. code-block:: cmake
+
+  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 :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 :command:`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
+:command:`install(EXPORT)` command:
+
+.. code-block:: cmake
+
+  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
+:prop_tgt:`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:
+
+.. code-block:: cmake
+
+  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 :manual:`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
+:command:`target_include_directories` command accepts both relative and
+absolute include directories:
+
+.. code-block:: cmake
+
+  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
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :prop_tgt:`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 these
+expressions, and are interpreted relative to the current source directory
+or the installation prefix, as appropriate.
+
+Two convenience APIs are provided relating to include directories usage
+requirements.  The :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable
+may be enabled, with an equivalent effect to:
+
+.. code-block:: cmake
+
+  set_property(TARGET tgt APPEND PROPERTY
+    $<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 :command:`install(TARGETS)`
+command:
+
+.. code-block:: cmake
+
+  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
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of each of the installed
+:prop_tgt:`IMPORTED` targets when generated by :command:`install(EXPORT)`.
+
+If a binary target is linked transitively to a Mac OX 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, :prop_tgt:`link libraries <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:
+
+.. code-block:: cmake
+
+  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 :prop_tgt:`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
+:prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
+contains a cycle.  :manual:`cmake(1)` issues a diagnostic in this case.
+
+Output Files
+------------
+
+The buildsystem targets created by the :command:`add_library` and
+:command:`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.
+
+Directory-Scoped Commands
+-------------------------
+
+The :command:`target_include_directories`,
+:command:`target_compile_definitions` and
+:command:`target_compile_options` commands have an effect on only one
+target at a time.  The commands :command:`add_definitions`,
+:command:`add_compile_options` and :command:`include_directories` have
+a similar function, but operate at directory scope instead of target
+scope for convenience.
+
+Psuedo 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 :prop_tgt:`IMPORTED` target represents a pre-existing dependency.  Usually
+such targets are defined by an upstream package and should be treated as
+immutable.  It is not possible to use an :prop_tgt:`IMPORTED` target in the
+left-hand-side of the :command:`target_compile_definitions`,
+:command:`target_include_directories`, :command:`target_compile_options` or
+:command:`target_link_libraries` commands, as that would be an attempt to
+modify it.  :prop_tgt:`IMPORTED` targets are designed to be used only in the
+right-hand-side of those commands.
+
+:prop_tgt:`IMPORTED` targets may have the same usage requirement properties
+populated as binary targets, such as
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
+:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
+:prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
+:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
+:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
+
+The :prop_tgt:`LOCATION` may also be read from an IMPORTED target, though there
+is rarely reason to do so.  Commands such as :command:`add_custom_command` can
+transparently use an :prop_tgt:`IMPORTED` :prop_tgt:`EXECUTABLE <TYPE>` target
+as a ``COMMAND`` executable.
+
+The scope of the definition of an :prop_tgt:`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`` :prop_tgt:`IMPORTED` target which is
+accessible globally in the buildsystem.
+
+See the :manual:`cmake-packages(7)` manual for more on creating packages
+with :prop_tgt:`IMPORTED` targets.
+
+Alias Targets
+-------------
+
+An ``ALIAS`` target is a name which may be used interchangably 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.
+
+.. code-block:: cmake
+
+  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 :prop_tgt:`IMPORTED` target from a package, or an
+``ALIAS`` target if built as part of the same buildsystem.
+
+.. code-block:: cmake
+
+  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 :prop_tgt:`ALIASED_TARGET`
+property from it:
+
+.. code-block:: cmake
+
+  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`` target has no :prop_tgt:`LOCATION` and is mutable, but is
+otherwise similar to an :prop_tgt:`IMPORTED` target.
+
+It may specify usage requirements such as
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
+:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
+:prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
+:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
+:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
+Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
+:command:`target_compile_definitions`, :command:`target_compile_options`,
+and :command:`target_link_libraries` commands may be used with ``INTERFACE``
+libraries.
+
+A primary use-case for ``INTERFACE`` libraries is header-only libraries.
+
+.. code-block:: cmake
+
+  add_library(Eigen INTERFACE)
+  target_include_directories(Eigen INTERFACE
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
+    $<INSTALL_INTERFACE:include/Eigen>
+  )
+
+  add_executable(exe1 exe1.cpp)
+  target_link_libraries(exe1 Eigen)
+
+Here, the usage requirements from the ``Eigen`` target are consumed and used
+when compiling, but it has no effect on linking.
+
+Another use-case is to employ an entirely target-focussed design for usage
+requirements:
+
+.. code-block:: cmake
+
+  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.  Any content they refer
+to must be installed separately:
+
+.. code-block:: cmake
+
+  add_library(Eigen INTERFACE)
+  target_include_directories(Eigen INTERFACE
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
+    $<INSTALL_INTERFACE:include/Eigen>
+  )
+
+  install(TARGETS Eigen EXPORT eigenExport)
+  install(EXPORT eigenExport NAMESPACE Upstream::
+    DESTINATION lib/cmake/Eigen
+  )
+  install(FILES
+      ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h
+      ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h
+      ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h
+    DESTINATION include/Eigen
+  )