Merge topic 'doc-ep-configure-build-passthrough'

cf3bc271d1 Help: Clarify details passed to ExternalProject configure and build

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

1 files changed, 20 insertions, 3 deletions

diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 45b6124..026d1fc 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -456,9 +456,16 @@ External Project Definition
     overridden if required.
 
     ``CONFIGURE_COMMAND <cmd>...``
-      The default configure command runs CMake with options based on the main
-      project. For non-CMake external projects, the ``CONFIGURE_COMMAND``
-      option must be used to override this behavior
+      The default configure command runs CMake with a few options based on
+      the main project.  The options added are typically only those needed to
+      use the same generator as the main project, but the ``CMAKE_GENERATOR``
+      option can be given to override this.  The project is responsible for
+      adding any toolchain details, flags or other settings it wants to
+      re-use from the main project or otherwise specify (see ``CMAKE_ARGS``,
+      ``CMAKE_CACHE_ARGS`` and ``CMAKE_CACHE_DEFAULT_ARGS`` below).
+
+      For non-CMake external projects, the ``CONFIGURE_COMMAND`` option must
+      be used to override the default configure command
       (:manual:`generator expressions <cmake-generator-expressions(7)>` are
       supported). For projects that require no configure step, specify this
       option with an empty string as the command to execute.
@@ -564,6 +571,16 @@ External Project Definition
     default build step. This can be overridden with custom build commands if
     required.
 
+    If both the main project and the external project use make as their build
+    tool, the build step of the external project is invoked as a recursive
+    make using ``$(MAKE)``.  This will communicate some build tool settings
+    from the main project to the external project.  If either the main project
+    or external project is not using make, no build tool settings will be
+    passed to the external project other than those established by the
+    configure step (i.e. running ``ninja -v`` in the main project will not
+    pass ``-v`` to the external project's build step, even if it also uses
+    ``ninja`` as its build tool).
+
     ``BUILD_COMMAND <cmd>...``
       Overrides the default build command
       (:manual:`generator expressions <cmake-generator-expressions(7)>` are