Toolchain: Update documentation for initial compiler flags

10 files changed, 91 insertions, 1 deletions

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 @@ in the cache as
 :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 @@ value for ``CC`` is stored in the cache as
 :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 @@ CSFLAGS
 
 .. 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 @@ value for ``CUDA`` is stored in the cache as
 :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 @@ value for ``CXX`` is stored in the cache as
 :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 @@ which the value for ``Fortran`` is stored in the cache as
 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 @@ value for ``RC`` is stored in the cache as
 :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 @@ value for ``SWIFTC`` is stored in the cache as
 :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 @@ The full path to the compiler for ``LANG``.
 
 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'