echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Clarify documentation on SYSTEM include directories

Browse Source 
Mention that system include directories are searched after normal
include directories.

Document that `IMPORTED_NO_SYSTEM` and `NO_SYSTEM_FROM_IMPORTED`
do not affect `INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`.
This commit is contained in:
Brad King 2022-02-03 06:10:08 -05:00
parent 9245925810
commit ec29a6a1a9
5 changed files with 24 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
Help/command/target_include_directories.rst
View File

@ -28,12 +28,15 @@ The following arguments specify include directories.
Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
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
considered in dependency calculations - see compiler docs). If ``SYSTEM``
is used together with ``PUBLIC`` or ``INTERFACE``, the
If ``SYSTEM`` is specified, the compiler will be told the directories
are meant as system include directories on some platforms. This may
have effects such as suppressing warnings or skipping the contained
headers in dependency calculations (see compiler documentation).
Additionally, system include directories are searched after normal
include directories regardless of the order specified.
If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
populated with the specified directories.

4
Help/manual/cmake-buildsystem.7.rst
View File

@ -675,7 +675,9 @@ listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the
dependency. This can result in omission of compiler warnings for headers
found in those directories. This behavior for :ref:`imported targets` may
be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target
property on the *consumers* of imported targets.
property on the *consumers* of imported targets, or by setting the
:prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets
themselves.
If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the
``Headers`` directory of the framework is also treated as a usage requirement.

4
Help/prop_tgt/IMPORTED_NO_SYSTEM.rst
View File

@ -6,7 +6,9 @@ a ``SYSTEM`` library. This has the following effects:
* Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated
as ``SYSTEM`` include directories when compiling consumers, as they
would be by default.
would be by default. Entries of
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
and will always be treated as ``SYSTEM`` include directories.
This property can also be enabled on a non-imported target. Doing so does
not affect the build system, but does tell the :command:`install(EXPORT)` and

9
Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
View File

@ -5,9 +5,12 @@ List of public system include directories for a library.
Targets may populate this property to publish the include directories
which contain system headers, and therefore should not result in
compiler warnings. The :command:`target_include_directories(SYSTEM)`
command signature populates this property with values given to the
``PUBLIC`` and ``INTERFACE`` keywords.
compiler warnings. Additionally, system include directories are searched
after normal include directories regardless of the order specified.
The :command:`target_include_directories(SYSTEM)` command signature
populates this property with values given to the ``PUBLIC`` and
``INTERFACE`` keywords.
Projects may also get and set the property directly, but must be aware that
adding directories to this property does not make those directories used

4
Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst
View File

@ -8,7 +8,9 @@ The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property
of imported targets are treated as ``SYSTEM`` includes by default. If this
property is enabled on a target, compilation of sources in that target will
not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed
imported targets as system includes.
imported targets as system includes. Either way, entries of
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
and will always be treated as ``SYSTEM`` include directories.
This property is initialized by the value of the
:variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target