Help: Document order of flags from CMAKE_<LANG>_FLAGS and COMPILE_OPTIONS

5 files changed, 26 insertions, 8 deletions

diff --git a/Help/prop_sf/COMPILE_FLAGS.rst b/Help/prop_sf/COMPILE_FLAGS.rst
index c211b89..eefe7bf 100644
--- a/Help/prop_sf/COMPILE_FLAGS.rst
+++ b/Help/prop_sf/COMPILE_FLAGS.rst
@@ -4,8 +4,11 @@ COMPILE_FLAGS
 Additional flags to be added when compiling this source file.
 
 The ``COMPILE_FLAGS`` property, managed as a string, sets additional compiler
-flags used to build source files.  Use :prop_sf:`COMPILE_DEFINITIONS` to pass
-additional preprocessor definitions.
+flags used that will be added to the list of compile flags when this source
+file builds.  The flags will be added after target-wide flags (except in
+some cases not supported by the :generator:`Visual Studio 9 2008` generator).
+
+Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions.
 
 Contents of ``COMPILE_FLAGS`` may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
diff --git a/Help/prop_sf/COMPILE_OPTIONS.rst b/Help/prop_sf/COMPILE_OPTIONS.rst
index a694c3e..84c543a 100644
--- a/Help/prop_sf/COMPILE_OPTIONS.rst
+++ b/Help/prop_sf/COMPILE_OPTIONS.rst
@@ -5,9 +5,10 @@ COMPILE_OPTIONS
 
 List of additional options to pass to the compiler.
 
-This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
-and will be added to the list of compile flags when this
-source file builds.
+This property holds a :ref:`semicolon-separated list <CMake Language Lists>`
+of options and will be added to the list of compile flags when this source
+file builds.  The options will be added after target-wide options (except in
+some cases not supported by the :generator:`Visual Studio 9 2008` generator).
 
 Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the
 syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual
diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst
index 4bc190a..0fd6aac 100644
--- a/Help/prop_tgt/COMPILE_OPTIONS.rst
+++ b/Help/prop_tgt/COMPILE_OPTIONS.rst
@@ -3,9 +3,13 @@ COMPILE_OPTIONS
 
 List of options to pass to the compiler.
 
-This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
-specified so far for its target.  Use the :command:`target_compile_options`
-command to append more options.
+This property holds a :ref:`semicolon-separated list <CMake Language Lists>`
+of options specified so far for its target.  Use the
+:command:`target_compile_options` command to append more options.
+The options will be added after after flags in the
+:variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+variables, but before those propagated from dependencies by the
+:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property.
 
 This property is initialized by the :prop_dir:`COMPILE_OPTIONS` directory
 property when a target is created, and is used by the generators to set
diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst
index 11864f8..2784397 100644
--- a/Help/variable/CMAKE_LANG_FLAGS.rst
+++ b/Help/variable/CMAKE_LANG_FLAGS.rst
@@ -18,3 +18,8 @@ This is initialized for each language from environment variables:
 
 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.
diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
index 1dbd036..f0900fd 100644
--- a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
+++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
@@ -2,3 +2,8 @@ CMAKE_<LANG>_FLAGS_<CONFIG>
 ---------------------------
 
 Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration.
+
+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.