Commit 907e422b authored by Brad King's avatar Brad King
Browse files

Help: Explain build/install-tree include dirs in more places (#14946)

Explain how to use $<BUILD_INTERFACE> and $<INSTALL_INTERFACE> directly
in the documentation of the target_include_directories command and
INTERFACE_INCLUDE_DIRECTORIES target property.  Otherwise readers need
to notice the link to the cmake-buildsystem(7) manual and find the
example in that to understand the need for these expressions.

Also fix the explanation in cmake-buildsystem(7) to not claim that
relative paths may be used inside a BUILD_INTERFACE expression.
parent 6fbd9a8f
......@@ -40,3 +40,17 @@ Arguments to ``target_include_directories`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
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:
.. code-block:: cmake
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
......@@ -578,9 +578,9 @@ 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:
based on the usage location. Relative paths are allowed within the
``INSTALL_INTERFACE`` expression and are interpreted relative to the
installation prefix. For example:
.. code-block:: cmake
......
......@@ -3,6 +3,10 @@ INTERFACE_INCLUDE_DIRECTORIES
List of public include directories for a library.
The :command:`target_include_directories` command populates this property
with values given to the ``PUBLIC`` and ``INTERFACE`` keywords. Projects
may also get and set the property directly.
Targets may populate this property to publish the include directories
required to compile against the headers for the target. Consuming
targets can add entries to their own :prop_tgt:`INCLUDE_DIRECTORIES`
......@@ -13,3 +17,17 @@ Contents of ``INTERFACE_INCLUDE_DIRECTORIES`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
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:
.. code-block:: cmake
set_property(TARGET mylib APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment