Mirrors
/
cmake
mirror of https://gitlab.kitware.com/cmake/cmake.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Help: Clarify relative path handling for target_include_directories() 

Fixes: #22853
pipelines/265803
Craig Scott 2022-01-30 22:59:57 +11:00
parent 4b033ca0eb
commit 3efa3251e9
2 changed files with 20 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
Help/command/target_include_directories.rst
View File

@ -27,9 +27,8 @@ The following arguments specify include directories.
.. versionadded:: 3.11
Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called. If
``SYSTEM`` is specified, the compiler will be told the
Repeated calls for the same ``<target>`` append items in the order called.
If ``SYSTEM`` is specified, the compiler will be told the
directories are meant as system include directories on some platforms
(signalling this setting might achieve effects such as the compiler
skipping warnings, or these fixed-install system files not being
@ -43,12 +42,22 @@ 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.
Specified include directories may be absolute paths or relative paths.
A relative path will be interpreted as relative to the current source
directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an
absolute path before storing it in the associated target property.
If the path starts with a generator expression, it will always be assumed
to be an absolute path (with one exception noted below) and will be used
unmodified.
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:
and the install-tree. The :genex:`BUILD_INTERFACE` and
:genex:`INSTALL_INTERFACE` generator expressions can be used to describe
separate usage requirements based on the usage location. Relative paths
are allowed within the :genex:`INSTALL_INTERFACE` expression and are
interpreted as relative to the installation prefix. Relative paths should not
be used in :genex:`BUILD_INTERFACE` expressions because they will not be
converted to absolute. For example:
.. code-block:: cmake

6
Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
View File

@ -1,11 +1,11 @@
Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
Note that it is not advisable to populate the :genex:`INSTALL_INTERFACE` of
the |INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
directories of dependencies. That would hard-code into installed packages
the include directory paths for dependencies
**as found on the machine the package was made on**.
The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
The :genex:`INSTALL_INTERFACE` of the |INTERFACE_PROPERTY_LINK| is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target