From 2449c04d8d0e6d354df969573ca62cd5709f0822 Mon Sep 17 00:00:00 2001 From: Alex Neundorf Date: Tue, 7 May 2024 18:42:07 +0200 Subject: [PATCH] Help: improve docs for the EXCLUDE_FROM_ALL directory property This patch improves the wording of the documentation of the EXCLUDE_FROM_ALL directory property, and makes the add_subdirectory()- and fetchcontent-documentation refer to it. --- Help/command/add_subdirectory.rst | 17 ++++------------- Help/prop_dir/EXCLUDE_FROM_ALL.rst | 27 ++++++++++++++++++++++++--- Modules/FetchContent.cmake | 4 ++-- 3 files changed, 30 insertions(+), 18 deletions(-) diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst index ae063e6d60..b5fa459667 100644 --- a/Help/command/add_subdirectory.rst +++ b/Help/command/add_subdirectory.rst @@ -20,19 +20,10 @@ 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. -If the ``EXCLUDE_FROM_ALL`` argument is provided then targets in the -subdirectory will not be included in the ``ALL`` target of the parent -directory by default, and will be excluded from IDE project files. -Users must explicitly build targets in the subdirectory. This is -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 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. +If the ``EXCLUDE_FROM_ALL`` argument is provided then the +:prop_dir:`EXCLUDE_FROM_ALL` property will be set on the added directory. +This will exclude the directory from a default build. See the directory +property :prop_dir:`EXCLUDE_FROM_ALL` for full details. .. versionadded:: 3.25 If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory diff --git a/Help/prop_dir/EXCLUDE_FROM_ALL.rst b/Help/prop_dir/EXCLUDE_FROM_ALL.rst index 8e3cca0c23..1adb50e147 100644 --- a/Help/prop_dir/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_dir/EXCLUDE_FROM_ALL.rst @@ -8,6 +8,27 @@ subdirectory by default. This does not affect the "all" target of the subdirectory itself. Running e.g. ``make`` inside the subdirectory will still build its targets. -If the :prop_tgt:`EXCLUDE_FROM_ALL` target property is set on a target -then its value determines whether the target is included in the "all" -target of this directory and its ancestors. +``EXCLUDE_FROM_ALL`` is meant for when the subdirectory contains +a separate part of the project that is useful, but not necessary, +such as a set of examples, or e.g. an integrated 3rd party library. +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 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. + +If the ``EXCLUDE_FROM_ALL`` argument is provided, it has the following effects: + +* Targets defined in the subdirectory or below will not be + included in the ``ALL`` target of the parent directory. + Those targets must be built explicitly by the user, + or be a dependency of another target that will be built. +* Targets defined in the subdirectory or below will be + excluded from IDE project files. +* Any install rules defined in the subdirectory or below will + be ignored when installing the parent directory. + +Note that these effects are not the same as those for the +:prop_tgt:`EXCLUDE_FROM_ALL` target property. diff --git a/Modules/FetchContent.cmake b/Modules/FetchContent.cmake index 3c01c2aa52..f7d7a3e361 100644 --- a/Modules/FetchContent.cmake +++ b/Modules/FetchContent.cmake @@ -253,8 +253,8 @@ Commands If the ``EXCLUDE_FROM_ALL`` argument is provided, then targets in the subdirectory added by :command:`FetchContent_MakeAvailable` will not be included in the ``ALL`` target by default, and may be excluded from IDE - project files. See the :command:`add_subdirectory` ``EXCLUDE_FROM_ALL`` - argument documentation for a more detailed discussion of the effects. + project files. See the documentation for the directory property + :prop_dir:`EXCLUDE_FROM_ALL` for a detailed discussion of the effects. .. command:: FetchContent_MakeAvailable