Toolchain: Update documentation for initial compiler flags
diff --git a/Help/envvar/ASM_DIALECT.rst b/Help/envvar/ASM_DIALECT.rst
index 768d8fe..a606280 100644
--- a/Help/envvar/ASM_DIALECT.rst
+++ b/Help/envvar/ASM_DIALECT.rst
@@ -14,3 +14,11 @@
:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. For subsequent
configuration runs, the environment variable will be ignored in favor of
:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`.
+
+.. note::
+ Options that are required to make the compiler work correctly can be included;
+ they can not be changed.
+
+.. code-block:: console
+
+ $ export ASM="custom-compiler --arg1 --arg2"
diff --git a/Help/envvar/CC.rst b/Help/envvar/CC.rst
index 7d2b870..4c970b4 100644
--- a/Help/envvar/CC.rst
+++ b/Help/envvar/CC.rst
@@ -11,3 +11,11 @@
:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run
(including the first), the environment variable will be ignored if the
:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+ Options that are required to make the compiler work correctly can be included;
+ they can not be changed.
+
+.. code-block:: console
+
+ $ export CC="custom-compiler --arg1 --arg2"
diff --git a/Help/envvar/CSFLAGS.rst b/Help/envvar/CSFLAGS.rst
index e8c0a11..d875209 100644
--- a/Help/envvar/CSFLAGS.rst
+++ b/Help/envvar/CSFLAGS.rst
@@ -5,7 +5,7 @@
.. include:: ENV_VAR.txt
-Preferred executable for compiling ``CSharp`` language files. Will only be
+Default compilation flags to be used when compiling ``CSharp`` files. Will only be
used by CMake on the first configuration to determine ``CSharp`` default
compilation flags, after which the value for ``CSFLAGS`` is stored in the cache
as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
diff --git a/Help/envvar/CUDACXX.rst b/Help/envvar/CUDACXX.rst
index 1affab6..69471b0 100644
--- a/Help/envvar/CUDACXX.rst
+++ b/Help/envvar/CUDACXX.rst
@@ -11,3 +11,11 @@
:variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration
run (including the first), the environment variable will be ignored if the
:variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+ Options that are required to make the compiler work correctly can be included;
+ they can not be changed.
+
+.. code-block:: console
+
+ $ export CUDACXX="custom-compiler --arg1 --arg2"
diff --git a/Help/envvar/CXX.rst b/Help/envvar/CXX.rst
index df927d5..908a521 100644
--- a/Help/envvar/CXX.rst
+++ b/Help/envvar/CXX.rst
@@ -11,3 +11,11 @@
:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration
run (including the first), the environment variable will be ignored if the
:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+ Options that are required to make the compiler work correctly can be included;
+ they can not be changed.
+
+.. code-block:: console
+
+ $ export CXX="custom-compiler --arg1 --arg2"
diff --git a/Help/envvar/FC.rst b/Help/envvar/FC.rst
index f1c26b0..dcee02d 100644
--- a/Help/envvar/FC.rst
+++ b/Help/envvar/FC.rst
@@ -12,3 +12,11 @@
configuration run (including the first), the environment variable will be
ignored if the :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>`
variable is defined.
+
+.. note::
+ Options that are required to make the compiler work correctly can be included;
+ they can not be changed.
+
+.. code-block:: console
+
+ $ export FC="custom-compiler --arg1 --arg2"
diff --git a/Help/envvar/RC.rst b/Help/envvar/RC.rst
index 3ec1788..adfaecc 100644
--- a/Help/envvar/RC.rst
+++ b/Help/envvar/RC.rst
@@ -11,3 +11,11 @@
:variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run
(including the first), the environment variable will be ignored if the
:variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+ Options that are required to make the compiler work correctly can be included;
+ they can not be changed.
+
+.. code-block:: console
+
+ $ export RC="custom-compiler --arg1 --arg2"
diff --git a/Help/envvar/SWIFTC.rst b/Help/envvar/SWIFTC.rst
index ce01ca2..896e156 100644
--- a/Help/envvar/SWIFTC.rst
+++ b/Help/envvar/SWIFTC.rst
@@ -11,3 +11,11 @@
:variable:`CMAKE_Swift_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run
(including the first), the environment variable will be ignored if the
:variable:`CMAKE_Swift_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+ Options that are required to make the compiler work correctly can be included;
+ they can not be changed.
+
+.. code-block:: console
+
+ $ export SWIFTC="custom-compiler --arg1 --arg2"
diff --git a/Help/release/dev/compiler_flags.rst b/Help/release/dev/compiler_flags.rst
new file mode 100644
index 0000000..7138e80
--- /dev/null
+++ b/Help/release/dev/compiler_flags.rst
@@ -0,0 +1,9 @@
+compiler_flags
+-----------------
+
+* The :variable:`CMAKE_<LANG>_COMPILER` variable may now be used to
+ store "mandatory" compiler flags like the :envvar:`CC` and other environment variables.
+
+* The :variable:`CMAKE_<LANG>_FLAGS_INIT` variable will now be considered during
+ the compiler indentification check if other sources like :variable:`CMAKE_<LANG>_FLAGS`
+ or :envvar:`CFLAGS` are not set.
diff --git a/Help/variable/CMAKE_LANG_COMPILER.rst b/Help/variable/CMAKE_LANG_COMPILER.rst
index 89df495..e694b33 100644
--- a/Help/variable/CMAKE_LANG_COMPILER.rst
+++ b/Help/variable/CMAKE_LANG_COMPILER.rst
@@ -5,3 +5,28 @@
This is the command that will be used as the ``<LANG>`` compiler. Once
set, you can not change this variable.
+
+Usage
+^^^^^
+
+This variable can be set by the user during the first time a build tree is configured.
+
+If a non-full path value is supplied then CMake will resolve the full path of
+the compiler.
+
+The variable could be set in a user supplied toolchain file or via `-D` on the command line.
+
+.. note::
+ Options that are required to make the compiler work correctly can be included
+ as items in a list; they can not be changed.
+
+.. code-block:: cmake
+
+ #set within user supplied toolchain file
+ set(CMAKE_C_COMPILER /full/path/to/qcc --arg1 --arg2)
+
+or
+
+.. code-block:: console
+
+ $ cmake ... -DCMAKE_C_COMPILER='qcc;--arg1;--arg2'
