Help: Document CMake's environment variables

29 files changed, 261 insertions, 0 deletions

diff --git a/Help/envvar/ASM_DIALECT.rst b/Help/envvar/ASM_DIALECT.rst
new file mode 100644
index 0000000..ec48f71
--- /dev/null
+++ b/Help/envvar/ASM_DIALECT.rst
@@ -0,0 +1,11 @@
+ASM<DIALECT>
+------------
+
+Preferred executable for compiling a specific dialect of assembly language
+files. ``ASM<DIALECT>`` can be ``ASM``, ``ASM_NASM``, ``ASM_MASM`` or
+``ASM-ATT``. Will only be used by CMake on the first configuration to determine
+``ASM<DIALECT>`` compiler, after which the value for ``ASM<DIALECT>`` is stored
+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>`.
diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst
new file mode 100644
index 0000000..4ed02fe
--- /dev/null
+++ b/Help/envvar/ASM_DIALECTFLAGS.rst
@@ -0,0 +1,11 @@
+ASM<DIALECT>FLAGS
+-----------------
+
+Default compilation flags to be used when compiling a specific dialect of an
+assembly language. ``ASM<DIALECT>FLAGS`` can be ``ASMFLAGS``, ``ASM_NASMFLAGS``,
+``ASM_MASMFLAGS`` or ``ASM-ATTFLAGS``. Will only be used by CMake on the
+first configuration to determine ``ASM<DIALECT>`` default compilation flags, after
+which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache as
+:variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
+run (including the first), the environment variable will be ignored if the
+:variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
diff --git a/Help/envvar/CC.rst b/Help/envvar/CC.rst
new file mode 100644
index 0000000..7e68110
--- /dev/null
+++ b/Help/envvar/CC.rst
@@ -0,0 +1,9 @@
+CC
+--
+
+Preferred executable for compiling ``C`` language files. Will only be used by
+CMake on the first configuration to determine ``C`` compiler, after which the
+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.
diff --git a/Help/envvar/CFLAGS.rst b/Help/envvar/CFLAGS.rst
new file mode 100644
index 0000000..60b2cd3
--- /dev/null
+++ b/Help/envvar/CFLAGS.rst
@@ -0,0 +1,9 @@
+CFLAGS
+------
+
+Default compilation flags to be used when compiling ``C`` files. Will only be
+used by CMake on the first configuration to determine ``CC`` default compilation
+flags, after which the value for ``CFLAGS`` is stored in the cache
+as :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run
+(including the first), the environment variable will be ignored if the
+:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
diff --git a/Help/envvar/CMAKE_CONFIG_TYPE.rst b/Help/envvar/CMAKE_CONFIG_TYPE.rst
new file mode 100644
index 0000000..1306b47
--- /dev/null
+++ b/Help/envvar/CMAKE_CONFIG_TYPE.rst
@@ -0,0 +1,5 @@
+CMAKE_CONFIG_TYPE
+-----------------
+
+The default build configuration for :ref:`Build Tool Mode` and
+``ctest`` build handler when there is no explicit configuration given.
diff --git a/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst
new file mode 100644
index 0000000..54d5f9e
--- /dev/null
+++ b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst
@@ -0,0 +1,8 @@
+CMAKE_MSVCIDE_RUN_PATH
+----------------------
+
+Extra PATH locations for custom commands when using
+:generator:`Visual Studio 9 2008` (or above) generators.
+
+The ``CMAKE_MSVCIDE_RUN_PATH`` environment variable sets the default value for
+the :variable:`CMAKE_MSVCIDE_RUN_PATH` variable if not already explicitly set.
diff --git a/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst
new file mode 100644
index 0000000..8bbf993
--- /dev/null
+++ b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst
@@ -0,0 +1,8 @@
+CMAKE_OSX_ARCHITECTURES
+-----------------------
+
+Target specific architectures for OS X.
+
+The ``CMAKE_OSX_ARCHITECTURES`` environment variable sets the default value for
+the :variable:`CMAKE_OSX_ARCHITECTURES` variable. See
+:prop_tgt:`OSX_ARCHITECTURES` for more information.
diff --git a/Help/envvar/CSFLAGS.rst b/Help/envvar/CSFLAGS.rst
new file mode 100644
index 0000000..251ddc5
--- /dev/null
+++ b/Help/envvar/CSFLAGS.rst
@@ -0,0 +1,9 @@
+CSFLAGS
+-------
+
+Preferred executable for compiling ``CSharp`` language 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
+run (including the first), the environment variable will be ignored if the
+:variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
diff --git a/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst
new file mode 100644
index 0000000..25ed14f
--- /dev/null
+++ b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst
@@ -0,0 +1,5 @@
+CTEST_INTERACTIVE_DEBUG_MODE
+----------------------------
+
+Environment variable that will exist and be set to ``1`` when a test executed
+by CTest is run in interactive mode.
diff --git a/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst
new file mode 100644
index 0000000..1fcf42b
--- /dev/null
+++ b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst
@@ -0,0 +1,7 @@
+CTEST_OUTPUT_ON_FAILURE
+-----------------------
+
+Boolean environment variable that controls if the output should be logged for
+failed tests. Set the value to 1, True, or ON to enable output on failure.
+See :manual:`ctest(1)` for more information on controlling output of failed
+tests.
diff --git a/Help/envvar/CTEST_PARALLEL_LEVEL.rst b/Help/envvar/CTEST_PARALLEL_LEVEL.rst
new file mode 100644
index 0000000..c767a01
--- /dev/null
+++ b/Help/envvar/CTEST_PARALLEL_LEVEL.rst
@@ -0,0 +1,5 @@
+CTEST_PARALLEL_LEVEL
+--------------------
+
+Specify the number of tests for CTest to run in parallel. See :manual:`ctest(1)`
+for more information on parallel test execution.
diff --git a/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst b/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst
new file mode 100644
index 0000000..8d8eea5
--- /dev/null
+++ b/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst
@@ -0,0 +1,4 @@
+CTEST_USE_LAUNCHERS_DEFAULT
+---------------------------
+
+Initializes the :variable:`CTEST_USE_LAUNCHERS` variable if not already defined.
diff --git a/Help/envvar/CUDACXX.rst b/Help/envvar/CUDACXX.rst
new file mode 100644
index 0000000..8a5fd4b
--- /dev/null
+++ b/Help/envvar/CUDACXX.rst
@@ -0,0 +1,9 @@
+CUDACXX
+-------
+
+Preferred executable for compiling ``CUDA`` language files. Will only be used by
+CMake on the first configuration to determine ``CUDA`` compiler, after which the
+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.
diff --git a/Help/envvar/CUDAFLAGS.rst b/Help/envvar/CUDAFLAGS.rst
new file mode 100644
index 0000000..3dff49f
--- /dev/null
+++ b/Help/envvar/CUDAFLAGS.rst
@@ -0,0 +1,9 @@
+CUDAFLAGS
+---------
+
+Default compilation flags to be used when compiling ``CUDA`` files. Will only be
+used by CMake on the first configuration to determine ``CUDA`` default
+compilation flags, after which the value for ``CUDAFLAGS`` is stored in the
+cache as :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
+run (including the first), the environment variable will be ignored if
+the :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst
new file mode 100644
index 0000000..f0f94f6
--- /dev/null
+++ b/Help/envvar/CUDAHOSTCXX.rst
@@ -0,0 +1,9 @@
+CUDAHOSTCXX
+-----------
+
+Preferred executable for compiling host code when compiling ``CUDA``
+language files. Will only be used by CMake on the first configuration to
+determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is
+stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any
+configuration run (including the first), the environment variable will be
+ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined.
diff --git a/Help/envvar/CXX.rst b/Help/envvar/CXX.rst
new file mode 100644
index 0000000..3b1e445
--- /dev/null
+++ b/Help/envvar/CXX.rst
@@ -0,0 +1,9 @@
+CXX
+---
+
+Preferred executable for compiling ``CXX`` language files. Will only be used by
+CMake on the first configuration to determine ``CXX`` compiler, after which the
+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.
diff --git a/Help/envvar/CXXFLAGS.rst b/Help/envvar/CXXFLAGS.rst
new file mode 100644
index 0000000..8b58abd
--- /dev/null
+++ b/Help/envvar/CXXFLAGS.rst
@@ -0,0 +1,9 @@
+CXXFLAGS
+--------
+
+Default compilation flags to be used when compiling ``CXX`` (C++) files. Will
+only be used by CMake on the first configuration to determine ``CXX`` default
+compilation flags, after which the value for ``CXXFLAGS`` is stored in the cache
+as :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run (
+including the first), the environment variable will be ignored if
+the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
diff --git a/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst
new file mode 100644
index 0000000..fab1c0c
--- /dev/null
+++ b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst
@@ -0,0 +1,5 @@
+DASHBOARD_TEST_FROM_CTEST
+-------------------------
+
+Environment variable that will exist when a test executed by CTest is run
+in non-interactive mode. The value will be equal to :variable:`CMAKE_VERSION`.
diff --git a/Help/envvar/FC.rst b/Help/envvar/FC.rst
new file mode 100644
index 0000000..7d293fd
--- /dev/null
+++ b/Help/envvar/FC.rst
@@ -0,0 +1,10 @@
+FC
+--
+
+Preferred executable for compiling ``Fortran`` language files. Will only be used
+by CMake on the first configuration to determine ``Fortran`` compiler, after
+which the value for ``Fortran`` is stored in the cache as
+:variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>`. For any
+configuration run (including the first), the environment variable will be
+ignored if the :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>`
+variable is defined.
diff --git a/Help/envvar/FFLAGS.rst b/Help/envvar/FFLAGS.rst
new file mode 100644
index 0000000..19d6169
--- /dev/null
+++ b/Help/envvar/FFLAGS.rst
@@ -0,0 +1,9 @@
+FFLAGS
+------
+
+Default compilation flags to be used when compiling ``Fortran`` files. Will only
+be used by CMake on the first configuration to determine ``Fortran`` default
+compilation flags, after which the value for ``FFLAGS`` is stored in the cache
+as :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
+run (including the first), the environment variable will be ignored if
+the :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
diff --git a/Help/envvar/LDFLAGS.rst b/Help/envvar/LDFLAGS.rst
new file mode 100644
index 0000000..52da99c
--- /dev/null
+++ b/Help/envvar/LDFLAGS.rst
@@ -0,0 +1,10 @@
+LDFLAGS
+-------
+
+Will only be used by CMake on the first configuration to determine the default
+linker flags, after which the value for ``LDFLAGS`` is stored in the cache
+as :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`,
+:variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and
+:variable:`CMAKE_MODULE_LINKER_FLAGS_INIT`. For any configuration run
+(including the first), the environment variable will be ignored if the
+equivalent  ``CMAKE_<TYPE>_LINKER_FLAGS_INIT`` variable is defined.
diff --git a/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst
new file mode 100644
index 0000000..e6051b4
--- /dev/null
+++ b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst
@@ -0,0 +1,8 @@
+MACOSX_DEPLOYMENT_TARGET
+------------------------
+
+Specify the minimum version of OS X on which the target binaries are
+to be deployed.
+
+The ``MACOSX_DEPLOYMENT_TARGET`` environment variable sets the default value for
+the :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable.
diff --git a/Help/envvar/RC.rst b/Help/envvar/RC.rst
new file mode 100644
index 0000000..6c2db19
--- /dev/null
+++ b/Help/envvar/RC.rst
@@ -0,0 +1,9 @@
+RC
+--
+
+Preferred executable for compiling ``resource`` files. Will only be used by CMake
+on the first configuration to determine ``resource`` compiler, after which the
+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.
diff --git a/Help/envvar/RCFLAGS.rst b/Help/envvar/RCFLAGS.rst
new file mode 100644
index 0000000..4f2f31c
--- /dev/null
+++ b/Help/envvar/RCFLAGS.rst
@@ -0,0 +1,9 @@
+RCFLAGS
+-------
+
+Default compilation flags to be used when compiling ``resource`` files. Will
+only be used by CMake on the first configuration to determine ``resource``
+default compilation flags, after which the value for ``RCFLAGS`` is stored in
+the cache as :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any
+configuration run (including the first), the environment variable will be ignored
+if the :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
diff --git a/Help/index.rst b/Help/index.rst
index 97cd107..3dccdda 100644
--- a/Help/index.rst
+++ b/Help/index.rst
@@ -40,6 +40,7 @@ Reference Manuals
    /manual/cmake-qt.7
    /manual/cmake-toolchains.7
    /manual/cmake-variables.7
+   /manual/cmake-env-variables.7
 
 .. only:: html or text
 
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
new file mode 100644
index 0000000..fed129e
--- /dev/null
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -0,0 +1,54 @@
+.. cmake-manual-description: CMake Environment Variables Reference
+
+cmake-env-variables(7)
+**********************
+
+.. only:: html
+
+   .. contents::
+
+Environment Variables that Control the Build
+============================================
+
+.. toctree::
+   :maxdepth: 1
+
+   /envvar/CMAKE_CONFIG_TYPE
+   /envvar/CMAKE_MSVCIDE_RUN_PATH
+   /envvar/CMAKE_OSX_ARCHITECTURES
+   /envvar/LDFLAGS
+   /envvar/MACOSX_DEPLOYMENT_TARGET
+
+Environment Variables for Languages
+===================================
+
+.. toctree::
+   :maxdepth: 1
+
+   /envvar/ASM_DIALECT
+   /envvar/ASM_DIALECTFLAGS
+   /envvar/CC
+   /envvar/CFLAGS
+   /envvar/CSFLAGS
+   /envvar/CUDACXX
+   /envvar/CUDAFLAGS
+   /envvar/CUDAHOSTCXX
+   /envvar/CXX
+   /envvar/CXXFLAGS
+   /envvar/FC
+   /envvar/FFLAGS
+   /envvar/RC
+   /envvar/RCFLAGS
+
+Environment Variables for CTest
+===============================
+
+.. toctree::
+   :maxdepth: 1
+
+   /envvar/CMAKE_CONFIG_TYPE
+   /envvar/CTEST_INTERACTIVE_DEBUG_MODE
+   /envvar/CTEST_OUTPUT_ON_FAILURE
+   /envvar/CTEST_PARALLEL_LEVEL
+   /envvar/CTEST_USE_LAUNCHERS_DEFAULT
+   /envvar/DASHBOARD_TEST_FROM_CTEST
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 52395c9..ca9ce5b 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -366,6 +366,7 @@ Variables for Languages
    /variable/CMAKE_COMPILER_IS_GNUCC
    /variable/CMAKE_COMPILER_IS_GNUCXX
    /variable/CMAKE_COMPILER_IS_GNUG77
+   /variable/CMAKE_CUDA_HOST_COMPILER
    /variable/CMAKE_CUDA_EXTENSIONS
    /variable/CMAKE_CUDA_STANDARD
    /variable/CMAKE_CUDA_STANDARD_REQUIRED
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 8aece23..e159ced 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -138,6 +138,8 @@ Options
 
 .. include:: OPTIONS_HELP.txt
 
+.. _`Build Tool Mode`:
+
 Build Tool Mode
 ===============
 
diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst
new file mode 100644
index 0000000..72e8e66
--- /dev/null
+++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst
@@ -0,0 +1,7 @@
+CMAKE_CUDA_HOST_COMPILER
+------------------------
+
+Executable to use when compiling host code when compiling ``CUDA`` language
+files. Maps to the nvcc -ccbin option.  Will only be used by CMake on the first
+configuration to determine a valid host compiler for ``CUDA``. After a valid
+host compiler has been found, this value is read-only.