From 907e422bc889135e9789ead872c0fd644ba76186 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 2 Jun 2014 10:30:49 -0400 Subject: [PATCH] Help: Explain build/install-tree include dirs in more places (#14946) Explain how to use $ and $ 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. --- Help/command/target_include_directories.rst | 14 ++++++++++++++ Help/manual/cmake-buildsystem.7.rst | 6 +++--- .../prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst | 18 ++++++++++++++++++ 3 files changed, 35 insertions(+), 3 deletions(-) diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 75f917dac..581bacef5 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -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 + $ + $ # /include/mylib + ) diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 3e1f01135..f3a577032 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -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 diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst index bf4ab46e6..899e821f7 100644 --- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -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 + $ + $ # /include/mylib + )