Merge topic 'ninja-parallel'

0e5250e63c Ninja: Add option for parallel install
daeb8fffa2 Help: Add Builtin Targets section to Ninja help

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

3 files changed, 53 insertions, 7 deletions

diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst
index f3ba222..5f5ffb8 100644
--- a/Help/generator/Ninja.rst
+++ b/Help/generator/Ninja.rst
@@ -1,11 +1,35 @@
 Ninja
 -----
 
-Generates ``build.ninja`` files.
+Generates a ``build.ninja`` file into the build tree.
 
-A ``build.ninja`` file is generated into the build tree.  Use the ninja
-program to build the project through the ``all`` target and install the
-project through the ``install`` (or ``install/strip``) target.
+Builtin Targets
+^^^^^^^^^^^^^^^
+
+``all``
+
+  Depends on all targets required by the project, except those with
+  :prop_tgt:`EXCLUDE_FROM_ALL` set to true.
+
+``install``
+
+  Runs the install step.
+
+``install/strip``
+
+  .. versionadded:: 3.7
+
+    Runs the install followed by a ``CMAKE_STRIP`` command, if any.
+
+    The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which
+    removes symbols information from generated binaries.
+
+``install/parallel``
+
+  .. versionadded:: 3.30
+
+    Created only if the :prop_gbl:`INSTALL_PARALLEL` global property is ``ON``.
+    Runs the install step for each subdirectory independently and in parallel.
 
 For each subdirectory ``sub/dir`` of the project, additional targets
 are generated:
@@ -25,12 +49,10 @@ are generated:
 ``sub/dir/install/strip``
 
   .. versionadded:: 3.7
+
     Runs the install step in the subdirectory followed by a ``CMAKE_STRIP`` command,
     if any.
 
-    The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which
-    removes symbols information from generated binaries.
-
 ``sub/dir/test``
 
   .. versionadded:: 3.7
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 549ec53..f37e72f 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -39,6 +39,7 @@ Properties of Global Scope
    /prop_gbl/GENERATOR_IS_MULTI_CONFIG
    /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE
    /prop_gbl/GLOBAL_DEPENDS_NO_CYCLES
+   /prop_gbl/INSTALL_PARALLEL
    /prop_gbl/IN_TRY_COMPILE
    /prop_gbl/JOB_POOLS
    /prop_gbl/PACKAGES_FOUND
diff --git a/Help/prop_gbl/INSTALL_PARALLEL.rst b/Help/prop_gbl/INSTALL_PARALLEL.rst
new file mode 100644
index 0000000..7b6632e
--- /dev/null
+++ b/Help/prop_gbl/INSTALL_PARALLEL.rst
@@ -0,0 +1,23 @@
+INSTALL_PARALLEL
+----------------
+
+.. versionadded:: 3.30
+
+Enables parallel installation option for the Ninja generator.
+
+When this property is ``ON``, ``install/local`` targets have the
+console pool disabled, allowing them to run concurrently.
+
+This property also provides the target ``install/parallel``, which has an
+explicit dependency on the ``install/local`` target for each subdirectory,
+recursing down the project.
+
+Setting this property has no affect on the behavior of ``cmake --install``.
+The install must be invoked by building the ``install/parallel`` target
+directly.
+
+Calls to :command:`install(CODE)` or :command:`install(SCRIPT)` might depend
+on actions performed by an earlier :command:`install` command in a different
+directory such as files installed or variable settings. If the project has
+such order-dependent installation logic, parallel installation should be
+not be enabled, in order to prevent possible race conditions.