Merge topic 'doc-add_subdirectory-EXCLUDE_FROM_ALL' into release-3.30

2449c04d8d Help: improve docs for the EXCLUDE_FROM_ALL directory property

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9497

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

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.

Modules/FetchContent.cmake

@@ -232,8 +232,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