Merge topic 'doc-lang-flags'
561ae21f40 Help: Clarify that {add,target}_compile_options are not used for linking
530faee017 Help: Clarify that CMAKE_<LANG>_FLAGS are used when driving linking
f93b13151e Help: Link to COMPILE_LANGUAGE genex from add_compile_options
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Alex <leha-bot@yandex.ru>
Merge-request: !8384
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst
index 0ccebc6..869d0c2 100644
--- a/Help/command/add_compile_options.rst
+++ b/Help/command/add_compile_options.rst
@@ -11,6 +11,11 @@
These options are used when compiling targets from the current
directory and below.
+.. note::
+
+ These options are not used when linking.
+ See the :command:`add_link_options` command for that.
+
Arguments
^^^^^^^^^
@@ -48,5 +53,15 @@
* The command :command:`target_compile_options` adds target-specific options.
+* This command adds compile options for all languages.
+ Use the :genex:`COMPILE_LANGUAGE` generator expression to specify
+ per-language compile options.
+
* The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
source file.
+
+* :command:`add_link_options` adds options for linking.
+
+* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+ add language-wide flags passed to all invocations of the compiler.
+ This includes invocations that drive compiling and those that drive linking.
diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst
index c09e106..df72715 100644
--- a/Help/command/add_link_options.rst
+++ b/Help/command/add_link_options.rst
@@ -38,3 +38,7 @@
* :command:`link_libraries`
* :command:`target_link_libraries`
* :command:`target_link_options`
+
+* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+ add language-wide flags passed to all invocations of the compiler.
+ This includes invocations that drive compiling and those that drive linking.
diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst
index f3ac97b..7cfb24b 100644
--- a/Help/command/target_compile_options.rst
+++ b/Help/command/target_compile_options.rst
@@ -15,6 +15,11 @@
created by a command such as :command:`add_executable` or
:command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`.
+.. note::
+
+ These options are not used when linking the target.
+ See the :command:`target_link_options` command for that.
+
Arguments
^^^^^^^^^
@@ -60,3 +65,7 @@
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`
+
+* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+ add language-wide flags passed to all invocations of the compiler.
+ This includes invocations that drive compiling and those that drive linking.
diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst
index 0d026f2..dca9598 100644
--- a/Help/command/target_link_options.rst
+++ b/Help/command/target_link_options.rst
@@ -62,3 +62,7 @@
* :command:`target_link_directories`
* :command:`target_precompile_headers`
* :command:`target_sources`
+
+* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+ add language-wide flags passed to all invocations of the compiler.
+ This includes invocations that drive compiling and those that drive linking.
diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst
index 4b39b1d..909a001 100644
--- a/Help/variable/CMAKE_LANG_FLAGS.rst
+++ b/Help/variable/CMAKE_LANG_FLAGS.rst
@@ -1,9 +1,10 @@
CMAKE_<LANG>_FLAGS
------------------
-Flags for all build types.
-
-``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`.
+Language-wide flags for language ``<LANG>`` used when building for
+all configurations. These flags will be passed to all invocations
+of the compiler. This includes invocations that drive compiling
+and those that drive linking.
For each language, if this variable is not defined, it is initialized
and stored in the cache using values from environment variables in
@@ -27,7 +28,10 @@
This value is a command-line string fragment. Therefore, multiple options
should be separated by spaces, and options with spaces should be quoted.
-The flags in this variable will be passed to the compiler before those
-in the per-configuration :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variant,
-and before flags added by the :command:`add_compile_options` or
-:command:`target_compile_options` commands.
+The flags in this variable will be passed before those in the
+per-configuration :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable.
+On invocations driving compiling, flags from both variables will be passed
+before flags added by commands such as :command:`add_compile_options` and
+:command:`target_compile_options`. On invocations driving linking,
+they will be passed before flags added by commands such as
+:command:`add_link_options` and :command:`target_link_options`.
diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
index f0900fd..5daa4c0 100644
--- a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
+++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
@@ -1,9 +1,16 @@
CMAKE_<LANG>_FLAGS_<CONFIG>
---------------------------
-Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration.
+Language-wide flags for language ``<LANG>`` used when building for
+the ``<CONFIG>`` configuration. These flags will be passed to all
+invocations of the compiler in the corresponding configuration.
+This includes invocations that drive compiling and those that drive
+linking.
-The flags in this variable will be passed to the compiler after those
-in the :variable:`CMAKE_<LANG>_FLAGS` variable, but before flags added
-by the :command:`add_compile_options` or :command:`target_compile_options`
-commands.
+The flags in this variable will be passed after those in the
+:variable:`CMAKE_<LANG>_FLAGS` variable. On invocations driving compiling,
+flags from both variables will be passed before flags added by commands
+such as :command:`add_compile_options` and :command:`target_compile_options`.
+On invocations driving linking, they will be passed before flags added by
+commands such as :command:`add_link_options` and
+:command:`target_link_options`.
