Support job pools in custom commands and targets

Provide a way for custom commands and targets to set the pool variable
of the ninja build statement. Setting `JOB_POOL` is not compatible with
`USES_TERMINAL`, which implies the `console` pool.

The option is silently ignored with other generators.

Closes: #18483

4 files changed, 27 insertions, 0 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index 9bf0d87..ed321fc 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -23,6 +23,7 @@ The first signature is for adding a custom command to produce an output:
                      [WORKING_DIRECTORY dir]
                      [COMMENT comment]
                      [DEPFILE depfile]
+                     [JOB_POOL job_pool]
                      [VERBATIM] [APPEND] [USES_TERMINAL]
                      [COMMAND_EXPAND_LISTS])
 
@@ -144,6 +145,13 @@ The options are:
   Note that the ``IMPLICIT_DEPENDS`` option is currently supported
   only for Makefile generators and will be ignored by other generators.
 
+``JOB_POOL``
+  Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
+  generator. Incompatible with ``USES_TERMINAL``, which implies
+  the ``console`` pool.
+  Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
+  an error by ninja at build time.
+
 ``MAIN_DEPENDENCY``
   Specify the primary input source file to the command.  This is
   treated just like any value given to the ``DEPENDS`` option
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index c63dd23..08b9516 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -11,6 +11,7 @@ Add a target with no output so it will always be built.
                     [BYPRODUCTS [files...]]
                     [WORKING_DIRECTORY dir]
                     [COMMENT comment]
+                    [JOB_POOL job_pool]
                     [VERBATIM] [USES_TERMINAL]
                     [COMMAND_EXPAND_LISTS]
                     [SOURCES src1 [src2...]])
@@ -97,6 +98,13 @@ The options are:
   ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
   to be properly expanded.
 
+``JOB_POOL``
+  Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
+  generator. Incompatible with ``USES_TERMINAL``, which implies
+  the ``console`` pool.
+  Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
+  an error by ninja at build time.
+
 ``SOURCES``
   Specify additional source files to be included in the custom target.
   Specified source files will be added to IDE project files for
diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst
index b904f7a..21da4662 100644
--- a/Help/prop_gbl/JOB_POOLS.rst
+++ b/Help/prop_gbl/JOB_POOLS.rst
@@ -18,6 +18,11 @@ Defined pools could be used globally by setting
 :variable:`CMAKE_JOB_POOL_COMPILE` and :variable:`CMAKE_JOB_POOL_LINK`
 or per target by setting the target properties
 :prop_tgt:`JOB_POOL_COMPILE` and :prop_tgt:`JOB_POOL_LINK`.
+:command:`Custom commands <add_custom_command>` and
+:command:`custom targets <add_custom_target>` can specify pools using the
+option ``JOB_POOL``.
+Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
+an error by ninja at build time.
 
 If not set, this property uses the value of the :variable:`CMAKE_JOB_POOLS`
 variable.
diff --git a/Help/release/dev/ninja-add_custom_command-pool.rst b/Help/release/dev/ninja-add_custom_command-pool.rst
new file mode 100644
index 0000000..f5a2db9
--- /dev/null
+++ b/Help/release/dev/ninja-add_custom_command-pool.rst
@@ -0,0 +1,6 @@
+ninja-add_custom_command-pool
+--------------------------------
+
+* The commands :command:`add_custom_command` and :command:`add_custom_target`
+  gained a new ``JOB_POOL`` option that works with the :generator:`Ninja`
+  generator to set the pool variable on the build statement.