Merge topic 'doc-link-compile-options'

2eba7d7524 Help: Add SHELL, LINKER and host/device discussions to property docs
b20c1f4880 Help: Make SHELL option examples more generic

Acked-by: Kitware Robot <[email protected]>
Merge-request: !6130

Help/command/DEVICE_LINK_OPTIONS.txt

@@ -1,3 +1,5 @@
+Host And Device Specific Link Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.18
   When a device link step is involved, which is controlled by

Help/command/LINK_OPTIONS_LINKER.txt

@@ -1,3 +1,6 @@
+Handling Compiler Driver Differences
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 To pass options to the linker tool, each compiler driver has its own syntax.
 The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable
 way, options to pass to the linker tool. ``LINKER:`` is replaced by the

Help/command/OPTIONS_SHELL.txt

@@ -1,11 +1,15 @@
-The final set of compile or link options used for a target is constructed by
+Option De-duplication
+^^^^^^^^^^^^^^^^^^^^^
+
+The final set of options used for a target is constructed by
 accumulating options from the current target and the usage requirements of
 its dependencies.  The set of options is de-duplicated to avoid repetition.
 
 .. versionadded:: 3.12
   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``.
+  up option groups.  For example, ``-option A -option B`` becomes
+  ``-option 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:-option A" "SHELL:-option B"`` becomes ``-option A -option B``.

Help/prop_tgt/COMPILE_OPTIONS.rst

@@ -15,3 +15,5 @@ Contents of ``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:: ../command/OPTIONS_SHELL.txt

Help/prop_tgt/LINK_OPTIONS.rst

@@ -28,3 +28,9 @@ for more on defining buildsystem properties.
 .. note::
 
   This property must be used in preference to :prop_tgt:`LINK_FLAGS` property.
+
+.. include:: ../command/DEVICE_LINK_OPTIONS.txt
+
+.. include:: ../command/OPTIONS_SHELL.txt
+
+.. include:: ../command/LINK_OPTIONS_LINKER.txt

Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst

@@ -20,3 +20,5 @@ for more on defining buildsystem properties.
 
   This property must be used in preference to :prop_tgt:`STATIC_LIBRARY_FLAGS`
   property.
+
+.. include:: ../command/OPTIONS_SHELL.txt