From b20c1f4880aa7fb764f4e2a47b92fca846e84941 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sat, 15 May 2021 16:23:54 +1000 Subject: Help: Make SHELL option examples more generic Comments at the bottom of the docs for add_compile_options() and target_compile_options() recommend using other commands if setting compiler definitions. Change the examples we use for the SHELL: functionality to use -option instead of -D so that we don't violate our own recommendations. This also makes the examples more appropriate for use with link options as well. Tweak the wording to not specify the type of option being discussed. This will already be clear from the page the text is included into and it avoids naming unrelated option types for the given page. --- Help/command/OPTIONS_SHELL.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 4051ffe..7f03f4e 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,11 +1,12 @@ -The final set of compile or link options used for a target is constructed by +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``. -- cgit v0.12 From 2eba7d75248142483107ca0194c718f4a9f1796d Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sat, 15 May 2021 16:12:22 +1000 Subject: Help: Add SHELL, LINKER and host/device discussions to property docs Section headings are also added for each common block to help guide the reader and improve navigation. Fixes: #21640 --- Help/command/DEVICE_LINK_OPTIONS.txt | 2 ++ Help/command/LINK_OPTIONS_LINKER.txt | 3 +++ Help/command/OPTIONS_SHELL.txt | 3 +++ Help/prop_tgt/COMPILE_OPTIONS.rst | 2 ++ Help/prop_tgt/LINK_OPTIONS.rst | 6 ++++++ Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst | 2 ++ 6 files changed, 18 insertions(+) diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt index 1297cd0..3d50208 100644 --- a/Help/command/DEVICE_LINK_OPTIONS.txt +++ b/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 diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index 3f66181..e71e5ea 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/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 diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 7f03f4e..4171f01 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,3 +1,6 @@ +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. diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst index 0cd6836..4bc190a 100644 --- a/Help/prop_tgt/COMPILE_OPTIONS.rst +++ 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 diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst index 8c0dfc4..27eadf9 100644 --- a/Help/prop_tgt/LINK_OPTIONS.rst +++ b/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 diff --git a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst index 2f4a3ba..f5d9437 100644 --- a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst +++ b/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 -- cgit v0.12