Install: Add parallel installation option

Fixes: #26000

5 files changed, 40 insertions, 8 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index b2742d6..ffc1926 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -38,6 +38,13 @@ are executed in order during installation.
   The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
   default copying behavior of ``install()``.
 
+.. versionchanged:: 3.31
+  Projects can enable :prop_gbl:`INSTALL_PARALLEL` to enable a parallel
+  installation. When using the parallel install, subdirectories added by calls
+  to the :command:`add_subdirectory` command are installed independently
+  and the order that install rules added in different subdirectories will run is
+  not guaranteed.
+
 .. _`common options`:
 
 There are multiple signatures for this command.  Some of them define
diff --git a/Help/envvar/CMAKE_INSTALL_PARALLEL_LEVEL.rst b/Help/envvar/CMAKE_INSTALL_PARALLEL_LEVEL.rst
new file mode 100644
index 0000000..84b5930
--- /dev/null
+++ b/Help/envvar/CMAKE_INSTALL_PARALLEL_LEVEL.rst
@@ -0,0 +1,11 @@
+CMAKE_INSTALL_PARALLEL_LEVEL
+----------------------------
+
+.. versionadded:: 3.31
+
+.. include:: ENV_VAR.txt
+
+Specifies the default maximum number of concurrent processes to use when
+installing using ``cmake --install``.
+
+This has no impact unless :prop_gbl:`INSTALL_PARALLEL` is enabled.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index a69ace6..68ee79a 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -52,6 +52,7 @@ Environment Variables that Control the Build
    /envvar/CMAKE_GENERATOR_PLATFORM
    /envvar/CMAKE_GENERATOR_TOOLSET
    /envvar/CMAKE_INSTALL_MODE
+   /envvar/CMAKE_INSTALL_PARALLEL_LEVEL
    /envvar/CMAKE_INSTALL_PREFIX
    /envvar/CMAKE_LANG_COMPILER_LAUNCHER
    /envvar/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 48a9219..b1cd381 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -745,6 +745,15 @@ The options are:
 
   This option can be omitted if :envvar:`VERBOSE` environment variable is set.
 
+.. option:: -j <jobs>, --parallel <jobs>
+
+  .. versionadded:: 3.31
+
+  Install in parallel using the given number of jobs. Only available if
+  :prop_gbl:`INSTALL_PARALLEL` is enabled. The
+  :envvar:`CMAKE_INSTALL_PARALLEL_LEVEL` environment variable specifies a
+  default parallel level when this option is not provided.
+
 Run :option:`cmake --install` with no options for quick help.
 
 Open a Project
diff --git a/Help/prop_gbl/INSTALL_PARALLEL.rst b/Help/prop_gbl/INSTALL_PARALLEL.rst
index 7b6632e..c30d6c9 100644
--- a/Help/prop_gbl/INSTALL_PARALLEL.rst
+++ b/Help/prop_gbl/INSTALL_PARALLEL.rst
@@ -3,18 +3,22 @@ INSTALL_PARALLEL
 
 .. versionadded:: 3.30
 
-Enables parallel installation option for the Ninja generator.
+Enables parallel installation option for a project. The install code for each
+subdirectory added with ``add_subdirectory`` can run independently.
 
-When this property is ``ON``, ``install/local`` targets have the
-console pool disabled, allowing them to run concurrently.
+When using the Ninja generator, setting this property to ``ON``, causes
+``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.
+explicit dependency on the ``install/local`` target for each subdirectory.
 
-Setting this property has no affect on the behavior of ``cmake --install``.
-The install must be invoked by building the ``install/parallel`` target
-directly.
+  .. versionadded:: 3.31
+
+  When this property is ``ON``, ``cmake --install`` can be given the ``-j <jobs>``
+  or ``--parallel <jobs>`` option to specify a maximum number of jobs.
+  The :envvar:`CMAKE_INSTALL_PARALLEL_LEVEL` environment variable specifies a
+  default parallel level if this option is not provided.
 
 Calls to :command:`install(CODE)` or :command:`install(SCRIPT)` might depend
 on actions performed by an earlier :command:`install` command in a different