VS: Add policy to build custom commands concurrently

In commit 33c15ae2b9 (VS: Build custom commands concurrently when
possible, 2023-01-19, v3.26.0-rc1~56^2) we added `BuildInParallel` to
custom commands in `.vcxproj` files, but that had to be reverted by
commit abb1c12162 (VS: Revert "Build custom commands concurrently when
possible", 2023-03-07, v3.26.0-rc6~3^2) because some projects may have
custom commands that accidentally rely on serial execution in MSBuild.

Add a policy to use `BuildInParallel` for custom commands in projects
that have been updated to set the policy to `NEW`.

Fixes: #18405

1 files changed, 24 insertions, 0 deletions

diff --git a/Help/policy/CMP0147.rst b/Help/policy/CMP0147.rst
new file mode 100644
index 0000000000..0f25096633
--- /dev/null
+++ b/Help/policy/CMP0147.rst
@@ -0,0 +1,24 @@
+CMP0147
+-------
+
+.. versionadded:: 3.27
+
+:ref:`Visual Studio Generators` build custom commands in parallel.
+
+Visual Studio 15.8 (2017) and newer support building custom commands in
+parallel.  CMake 3.27 and above prefer to enable this behavior by adding
+a ``BuildInParallel`` setting to custom commands in ``.vcxproj`` files.
+This policy provides compatibility for projects that have not been updated
+to expect this, e.g., because their custom commands were accidentally
+relying on serial execution by MSBuild.
+
+The ``OLD`` behavior for this policy is to not add ``BuildInParallel``.
+The ``NEW`` behavior for this policy is to add ``BuildInParallel`` for
+VS 15.8 and newer.
+
+This policy was introduced in CMake version 3.27.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt