target_compile_options: Add syntax to specify shell strings

Options specified via `COMPILE_OPTIONS` and `INTERFACE_COMPILE_OPTIONS`
are deduplicated, but individual options can legitimately be duplicated
when grouped with other options, e.g.

    -D A -D B

After deduplication that becomes `-D A B`.  Therefore we need a way to
treat groups of options as units during deduplication.  A simple approach
is to specify each group as one option, e.g.

    "-D A" "-D B"

However, that conflicts with options that legitimately have spaces.  To
break this ambiguity, add a `SHELL:` prefix syntax to specify that an
option should be parsed like shell command line arguments after
deduplication, e.g.

    "SHELL:-D A" "SHELL:-D B"

These will survive deduplication intact, and then be parsed to produce
`-D A -D B` on the final command line.

Fixes: #15826

3 files changed, 13 insertions, 0 deletions

diff --git a/Help/command/COMPILE_OPTIONS_SHELL.txt b/Help/command/COMPILE_OPTIONS_SHELL.txt
new file mode 100644
index 0000000..a1316c8
--- /dev/null
+++ b/Help/command/COMPILE_OPTIONS_SHELL.txt
@@ -0,0 +1,9 @@
+The final set of compile options used for a target is constructed by
+accumulating options from the current target and the usage requirements of
+it dependencies.  The set of options is de-duplicated to avoid repetition.
+While beneficial for individual options, the de-duplication step can break
+up option groups.  For example, ``-D A -D B`` becomes ``-D A B``.  One may
+specify a group of options using shell-like quoting along with a ``SHELL:``
+prefix.  The ``SHELL:`` prefix is dropped and the rest of the option string
+is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode.
+For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``.
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst
index 3fe2a33..44924e6 100644
--- a/Help/command/add_compile_options.rst
+++ b/Help/command/add_compile_options.rst
@@ -21,3 +21,5 @@ Arguments to ``add_compile_options`` may use "generator expressions" with
 the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
+
+.. include:: COMPILE_OPTIONS_SHELL.txt
diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst
index 3e7dc47..b7b4dc1 100644
--- a/Help/command/target_compile_options.rst
+++ b/Help/command/target_compile_options.rst
@@ -38,3 +38,5 @@ Arguments to ``target_compile_options`` may use "generator expressions"
 with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
+
+.. include:: COMPILE_OPTIONS_SHELL.txt