Help: Clarify and update SYSTEM-related docs
This commit is contained in:
Craig Scott
parent
94131d632f
commit
dfab263825
@ -7,16 +7,16 @@ Add a subdirectory to the build.
|
||||
|
||||
add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])
|
||||
|
||||
Adds a subdirectory to the build. The source_dir specifies the
|
||||
directory in which the source CMakeLists.txt and code files are
|
||||
located. If it is a relative path it will be evaluated with respect
|
||||
Adds a subdirectory to the build. The ``source_dir`` specifies the
|
||||
directory in which the source ``CMakeLists.txt`` and code files are
|
||||
located. If it is a relative path, it will be evaluated with respect
|
||||
to the current directory (the typical usage), but it may also be an
|
||||
absolute path. The ``binary_dir`` specifies the directory in which to
|
||||
place the output files. If it is a relative path it will be evaluated
|
||||
place the output files. If it is a relative path, it will be evaluated
|
||||
with respect to the current output directory, but it may also be an
|
||||
absolute path. If ``binary_dir`` is not specified, the value of
|
||||
``source_dir``, before expanding any relative path, will be used (the
|
||||
typical usage). The CMakeLists.txt file in the specified source
|
||||
typical usage). The ``CMakeLists.txt`` file in the specified source
|
||||
directory will be processed immediately by CMake before processing in
|
||||
the current input file continues beyond this command.
|
||||
|
||||
@ -28,9 +28,9 @@ meant for use when the subdirectory contains a separate part of the
|
||||
project that is useful but not necessary, such as a set of examples.
|
||||
Typically the subdirectory should contain its own :command:`project`
|
||||
command invocation so that a full build system will be generated in the
|
||||
subdirectory (such as a VS IDE solution file). Note that inter-target
|
||||
dependencies supersede this exclusion. If a target built by the
|
||||
parent project depends on a target in the subdirectory, the dependee
|
||||
subdirectory (such as a Visual Studio IDE solution file). Note that
|
||||
inter-target dependencies supersede this exclusion. If a target built by
|
||||
the parent project depends on a target in the subdirectory, the dependee
|
||||
target will be included in the parent project build system to satisfy
|
||||
the dependency.
|
||||
|
||||
@ -38,6 +38,4 @@ the dependency.
|
||||
If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory
|
||||
property of the subdirectory will be set to true. This property is
|
||||
used to initialize the :prop_tgt:`SYSTEM` property of each non-imported
|
||||
target created in that subdirectory. The include directories of targets
|
||||
with :prop_tgt:`SYSTEM` set to true will be treated as ``SYSTEM`` when
|
||||
compiling consumers.
|
||||
target created in that subdirectory.
|
||||
|
||||
@ -672,14 +672,14 @@ This is equivalent to appending ``${CMAKE_INSTALL_PREFIX}/include`` to the
|
||||
|
||||
When the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an
|
||||
:ref:`imported target <Imported targets>` is consumed, the entries in the
|
||||
property are treated as ``SYSTEM`` include directories, as if they were
|
||||
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, or by setting the
|
||||
:prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets
|
||||
themselves.
|
||||
property may be treated as system include directories. The effects of that
|
||||
are toolchain-dependent, but one common effect is to omit compiler warnings
|
||||
for headers found in those directories. The :prop_tgt:`SYSTEM` property of
|
||||
the installed target determines this behavior (see the
|
||||
:prop_tgt:`EXPORT_NO_SYSTEM` property for how to modify the installed value
|
||||
for a target). It is also possible to change how consumers interpret the
|
||||
system behavior of consumed imported targets by setting the
|
||||
:prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property on the *consumer*.
|
||||
|
||||
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.
|
||||
|
||||
@ -3,8 +3,10 @@ EXPORT_NO_SYSTEM
|
||||
|
||||
.. versionadded:: 3.25
|
||||
|
||||
Specifies that :command:`install(EXPORT)` and :command:`export` commands will
|
||||
generate an imported target with :prop_tgt:`SYSTEM` property `OFF`.
|
||||
This property affects the behavior of the :command:`install(EXPORT)` and
|
||||
:command:`export` commands when they install or export the target respectively.
|
||||
When ``EXPORT_NO_SYSTEM`` is set to true, those commands generate an imported
|
||||
target with :prop_tgt:`SYSTEM` property set to false.
|
||||
|
||||
See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this
|
||||
behavior on the target *consuming* the include directories rather than the
|
||||
|
||||
@ -5,27 +5,31 @@ IMPORTED_NO_SYSTEM
|
||||
|
||||
.. deprecated:: 3.25
|
||||
|
||||
``IMPORTED_NO_SYSTEM`` is deprecated. Set :prop_tgt:`SYSTEM` to `OFF`
|
||||
instead if you don't want target's include directories to be ``SYSTEM``
|
||||
when compiling consumers. Set :prop_tgt:`EXPORT_NO_SYSTEM` to `ON` instead
|
||||
if you don't want the include directories of the imported target generated
|
||||
by :command:`install(EXPORT)` and :command:`export` commands to be
|
||||
``SYSTEM`` when compiling consumers.
|
||||
``IMPORTED_NO_SYSTEM`` is deprecated. Please use the following alternatives
|
||||
instead:
|
||||
|
||||
Specifies that an :ref:`Imported Target <Imported Targets>` is not
|
||||
a ``SYSTEM`` library. This has the following effects:
|
||||
* Set :prop_tgt:`SYSTEM` to false if you don't want a target's include
|
||||
directories to be treated as system directories when compiling consumers.
|
||||
* Set :prop_tgt:`EXPORT_NO_SYSTEM` to true if you don't want the include
|
||||
directories of the imported target generated by :command:`install(EXPORT)`
|
||||
and :command:`export` commands to be treated as system directories when
|
||||
compiling consumers.
|
||||
|
||||
Setting ``IMPORTED_NO_SYSTEM`` to true on an
|
||||
:ref:`imported target <Imported Targets>` specifies that it is not a
|
||||
system target. This has the following effects:
|
||||
|
||||
* Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated
|
||||
as ``SYSTEM`` include directories when compiling consumers (regardless of
|
||||
as system include directories when compiling consumers (regardless of
|
||||
the value of the consumed target's :prop_tgt:`SYSTEM` property), as they
|
||||
would be by default. Entries of
|
||||
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
|
||||
and will always be treated as ``SYSTEM`` include directories.
|
||||
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
|
||||
:command:`export` commands to enable it on the imported targets they generate.
|
||||
|
||||
See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this
|
||||
behavior on the target consuming the include directories rather than
|
||||
providing them.
|
||||
behavior on the target *consuming* the include directories rather than
|
||||
the one *providing* them.
|
||||
|
||||
@ -8,17 +8,17 @@ which contain system headers, and therefore should not result in
|
||||
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.
|
||||
When the :command:`target_include_directories` command is given the
|
||||
``SYSTEM`` keyword, it populates this property with values provided after 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
|
||||
during compilation. Adding directories to this property marks directories
|
||||
as ``SYSTEM`` which otherwise would be used in a non-``SYSTEM`` manner. This
|
||||
can appear similar to 'duplication', so prefer the
|
||||
high-level :command:`target_include_directories(SYSTEM)` command and avoid
|
||||
setting the property by low-level means.
|
||||
as system directories which otherwise would be used in a non-system manner.
|
||||
This can appear similar to duplication, so prefer the high-level
|
||||
:command:`target_include_directories` command with the ``SYSTEM`` keyword
|
||||
and avoid setting the property directly.
|
||||
|
||||
When target dependencies are specified using :command:`target_link_libraries`,
|
||||
CMake will read this property from all target dependencies to mark the
|
||||
|
||||
@ -2,19 +2,27 @@ NO_SYSTEM_FROM_IMPORTED
|
||||
-----------------------
|
||||
|
||||
Do not treat include directories from the interfaces of consumed
|
||||
:ref:`imported targets` as ``SYSTEM``.
|
||||
:ref:`imported targets` as system directories.
|
||||
|
||||
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. Either way, entries of
|
||||
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
|
||||
and will always be treated as ``SYSTEM`` include directories.
|
||||
are treated as system includes when the consumed target's :prop_tgt:`SYSTEM`
|
||||
property is set to true. By default, :prop_tgt:`SYSTEM` is true for imported
|
||||
targets and false for other target types. If the ``NO_SYSTEM_FROM_IMPORTED``
|
||||
property is set to true on a *consuming* target, compilation of sources in that
|
||||
consuming target will not treat the contents of the
|
||||
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of consumed imported targets as
|
||||
system includes, even if that imported target's :prop_tgt:`SYSTEM` property
|
||||
is false.
|
||||
|
||||
Directories listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`
|
||||
property of consumed targets are not affected by ``NO_SYSTEM_FROM_IMPORTED``.
|
||||
Those directories will always be treated as system include directories by
|
||||
consumers.
|
||||
|
||||
This property is initialized by the value of the
|
||||
:variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target
|
||||
is created.
|
||||
|
||||
See the :prop_tgt:`IMPORTED_NO_SYSTEM` target property to set this behavior
|
||||
on the target providing the include directories rather than consuming them.
|
||||
See the :prop_tgt:`EXPORT_NO_SYSTEM` target property to set this behavior
|
||||
on the target providing the include directories rather than the target
|
||||
consuming them.
|
||||
|
||||
@ -3,20 +3,20 @@ SYSTEM
|
||||
|
||||
.. versionadded:: 3.25
|
||||
|
||||
Specifies that a target is a ``SYSTEM`` library. This has the following
|
||||
Specifies that a target is a system target. This has the following
|
||||
effects:
|
||||
|
||||
* Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are treated as
|
||||
``SYSTEM`` include directories when compiling consumers.
|
||||
system include directories when compiling consumers.
|
||||
Entries of :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not
|
||||
affected, and will always be treated as ``SYSTEM`` include directories.
|
||||
affected, and will always be treated as system include directories.
|
||||
|
||||
For imported targets, this property defaults to true, which means
|
||||
that their :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are treated
|
||||
as ``SYSTEM`` by default. If their ``SYSTEM`` property is false,
|
||||
as system directories by default. If their ``SYSTEM`` property is false,
|
||||
then their :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` will not be
|
||||
treated as ``SYSTEM``, regardless of the value of the
|
||||
:prop_tgt:`IMPORTED_NO_SYSTEM` property.
|
||||
treated as system. Use the :prop_tgt:`EXPORT_NO_SYSTEM` property to change
|
||||
how a target's ``SYSTEM`` property is set when it is installed.
|
||||
|
||||
For non-imported targets, this target property is initialized from
|
||||
the :prop_dir:`SYSTEM` directory property when the target is created.
|
||||
|
||||
@ -159,9 +159,10 @@ Properties
|
||||
Modules
|
||||
-------
|
||||
|
||||
* The :module:`FetchContent` module :command:`FetchContent_Declare`
|
||||
command gained a ``SYSTEM`` option to enable the :prop_dir:`SYSTEM`
|
||||
directory property in the subdirectory.
|
||||
* The :module:`FetchContent` module's :command:`FetchContent_Declare`
|
||||
command gained a ``SYSTEM`` option which sets the :prop_dir:`SYSTEM`
|
||||
directory property on subdirectories created by
|
||||
:command:`FetchContent_MakeAvailable`.
|
||||
|
||||
* The :module:`FindCUDAToolkit` module now provides a target for
|
||||
:ref:`nvtx3 <cuda_toolkit_nvtx3>` for CUDA 10.0+, which supersedes
|
||||
|
||||
@ -233,12 +233,12 @@ Commands
|
||||
.. versionadded:: 3.25
|
||||
|
||||
``SYSTEM``
|
||||
If the ``SYSTEM`` argument is provided, targets created by
|
||||
the dependency will have their :prop_tgt:`SYSTEM` property
|
||||
set to true when populated by :command:`FetchContent_MakeAvailable`.
|
||||
The entries in their :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
|
||||
will be treated as ``SYSTEM`` include directories when
|
||||
compiling consumers.
|
||||
If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory
|
||||
property of a subdirectory added by
|
||||
:command:`FetchContent_MakeAvailable` will be set to true. This will
|
||||
affect non-imported targets created as part of that command.
|
||||
See the :prop_tgt:`SYSTEM` target property documentation for a more
|
||||
detailed discussion of the effects.
|
||||
|
||||
.. command:: FetchContent_MakeAvailable
|
||||
|
||||
@ -353,6 +353,11 @@ Commands
|
||||
adding a project that contains a ``CMakeLists.txt`` file in its top
|
||||
directory.
|
||||
|
||||
.. versionadded:: 3.25
|
||||
If the ``SYSTEM`` keyword was included in the call to
|
||||
:command:`FetchContent_Declare`, the ``SYSTEM`` keyword will be
|
||||
added to the :command:`add_subdirectory` command as well.
|
||||
|
||||
Projects should aim to declare the details of all dependencies they might
|
||||
use before they call ``FetchContent_MakeAvailable()`` for any of them.
|
||||
This ensures that if any of the dependencies are also sub-dependencies of
|
||||
|
||||
Loading…
Reference in New Issue
Block a user