Merge topic 'cmake-toolchains-manual'

c45b5ce Help: Add cmake-toolchains.7 manual
3e3f8b4 Help: Document the CMAKE_FIND_ROOT_PATH* variables.
531c108 Help: Document the CMAKE_TOOLCHAIN_FILE.

19 files changed, 230 insertions, 14 deletions

diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt
index efc076f..b5cab68 100644
--- a/Help/command/FIND_XXX_ROOT.txt
+++ b/Help/command/FIND_XXX_ROOT.txt
@@ -1,9 +1,9 @@
-The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
+The CMake variable :variable:`CMAKE_FIND_ROOT_PATH` specifies one or more
 directories to be prepended to all other search directories.  This
 effectively "re-roots" the entire search under given locations.
 Paths which are descendants of the :variable:`CMAKE_STAGING_PREFIX` are excluded
 from this re-rooting, because that variable is always a path on the host system.
-By default the CMAKE_FIND_ROOT_PATH is empty.
+By default the :variable:`CMAKE_FIND_ROOT_PATH` is empty.
 
 The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one
 directory to use as a prefix.  Setting :variable:`CMAKE_SYSROOT` also has other
@@ -12,12 +12,12 @@ effects.  See the documentation for that variable for more.
 These variables are especially useful when cross-compiling to
 point to the root directory of the target environment and CMake will
 search there too.  By default at first the directories listed in
-CMAKE_FIND_ROOT_PATH are searched, then the :variable:`CMAKE_SYSROOT` directory is
-searched, and then the non-rooted directories will be
+:variable:`CMAKE_FIND_ROOT_PATH` are searched, then the :variable:`CMAKE_SYSROOT`
+directory is searched, and then the non-rooted directories will be
 searched.  The default behavior can be adjusted by setting
 |CMAKE_FIND_ROOT_PATH_MODE_XXX|.  This behavior can be manually
 overridden on a per-call basis.  By using CMAKE_FIND_ROOT_PATH_BOTH
 the search order will be as described above.  If
-NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
+NO_CMAKE_FIND_ROOT_PATH is used then :variable:`CMAKE_FIND_ROOT_PATH` will not be
 used.  If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
 directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched.
diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst
index 549b317..db7e151 100644
--- a/Help/command/find_file.rst
+++ b/Help/command/find_file.rst
@@ -22,6 +22,6 @@ find_file
 .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
 
 .. include:: FIND_XXX.txt
diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst
index 8598be7..91342ba 100644
--- a/Help/command/find_library.rst
+++ b/Help/command/find_library.rst
@@ -22,7 +22,7 @@ find_library
 .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`
 
 .. include:: FIND_XXX.txt
 
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index c394a08..f09cb41 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -320,7 +320,7 @@ hard-coded guesses.
 .. |FIND_XXX| replace:: find_package
 .. |FIND_ARGS_XXX| replace:: <package>
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
 
 .. include:: FIND_XXX_MAC.txt
 .. include:: FIND_XXX_ROOT.txt
diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst
index c85011a..95d49e7 100644
--- a/Help/command/find_path.rst
+++ b/Help/command/find_path.rst
@@ -22,7 +22,7 @@ find_path
 .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
 
 .. include:: FIND_XXX.txt
 
diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst
index da5a41d..c62a8a5 100644
--- a/Help/command/find_program.rst
+++ b/Help/command/find_program.rst
@@ -20,6 +20,6 @@ find_program
 .. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM`
 
 .. include:: FIND_XXX.txt
diff --git a/Help/index.rst b/Help/index.rst
index 0d33825..4ef5c3f 100644
--- a/Help/index.rst
+++ b/Help/index.rst
@@ -27,6 +27,7 @@ Reference Manuals
 
    /manual/cmake-commands.7
    /manual/cmake-generators.7
+   /manual/cmake-toolchains.7
    /manual/cmake-modules.7
    /manual/cmake-policies.7
    /manual/cmake-properties.7
diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst
new file mode 100644
index 0000000..fbe546e
--- /dev/null
+++ b/Help/manual/cmake-toolchains.7.rst
@@ -0,0 +1,160 @@
+.. cmake-manual-description: CMake Toolchains Reference
+
+cmake-toolchains(7)
+*******************
+
+.. only:: html or latex
+
+   .. contents::
+
+Introduction
+============
+
+CMake uses a toolchain of utilities to compile, link libraries and create
+archives, and other tasks to drive the build. The toolchain utilities available
+are determined by the languages enabled. In normal builds, CMake automatically
+determines the toolchain for host builds based on system introspection and
+defaults. In cross-compiling scenarios, a toolchain file may be specified
+with information about compiler and utility paths.
+
+Languages
+=========
+
+Languages are enabled by the :command:`project` command. If no project command
+is in the top-level CMakeLists file, one will be implicitly generated. By default
+the enabled languages are C and CXX::
+
+  project(C_Only C)
+
+A special value of NONE can also be used with the :command:`project` command
+to enable no languages::
+
+  project(MyProject NONE)
+
+The :command:`enable_language` command can be used to enable languages after the
+:command:`project` command::
+
+  enable_language(CXX)
+
+When a language is enabled, CMake finds a compiler for that language, and
+determines some information, such as the vendor and version of the compiler,
+the target architecture and bitwidth, the location of corresponding utilities
+etc.
+
+The :prop_gbl:`ENABLED_LANGUAGES` global property contains the languages which
+are currently enabled.
+
+Variables and Properties
+========================
+
+Several variables relate to the language components of a toolchain which are
+enabled. :variable:`CMAKE_<LANG>_COMPILER` is the full path to the compiler used
+for ``<LANG>``. :variable:`CMAKE_<LANG>_COMPILER_ID` is the identifier used
+by CMake for the compiler and :variable:`CMAKE_<LANG>_COMPILER_VERSION` is the
+version of the compiler.
+
+The :variable:`CMAKE_<LANG>_FLAGS` variables and the configuration-specific
+equivalents contain flags that will be added to the compile command when
+compiling a file of a particular language.
+
+As the linker is invoked by the compiler driver, CMake needs a way to determine
+which compiler to use to invoke the linker. This is calculated by the
+:prop_sf:`LANGUAGE` of source files in the target, and in the case of static
+libraries, the language of the dependent libraries. The choice CMake makes may
+be overridden with the :prop_tgt:`LINKER_LANGUAGE` target property.
+
+Toolchain Features
+==================
+
+CMake provides the :command:`try_compile` command and wrapper macros such as
+:module:`CheckCXXSourceCompiles`, :module:`CheckCXXSymbolExists` and
+:module:`CheckIncludeFile` to test capability and availability of various
+toolchain features. These APIs test the toolchain in some way and cache the
+result so that the test does not have to be performed again the next time
+CMake runs.
+
+Some toolchain features have built-in handling in CMake, and do not require
+compile-tests. For example, :prop_tgt:`POSITION_INDEPENDENT_CODE` allows
+specifying that a target should be built as position-independent code, if
+the compiler supports that feature. The :prop_tgt:`<LANG>_VISIBILITY_PRESET`
+and :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties add flags for
+hidden visibility, if supported by the compiler.
+
+Cross Compiling
+===============
+
+If :manual:`cmake(1)` is invoked with the command line parameter
+``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set
+values for the compilers. A typical cross-compiling toolchain has content such
+as::
+
+  set(CMAKE_SYSTEM_NAME Linux)
+
+  set(CMAKE_SYSROOT /home/devel/rasp-pi-rootfs)
+  set(CMAKE_STAGING_PREFIX /home/devel/stage)
+
+  set(CMAKE_C_COMPILER /home/devel/gcc-4.7-linaro-rpi-gnueabihf/bin/arm-linux-gnueabihf-gcc)
+  set(CMAKE_CXX_COMPILER /home/devel/gcc-4.7-linaro-rpi-gnueabihf/bin/arm-linux-gnueabihf-g++)
+
+  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+  set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
+
+The :variable:`CMAKE_SYSTEM_NAME` is the CMake-identifier of the target platform
+to build for.
+
+The :variable:`CMAKE_SYSROOT` is optional, and may be specified if a sysroot
+is available.
+
+The :variable:`CMAKE_STAGING_PREFIX` is also optional. It may be used to specify
+a path on the host to install to. The :variable:`CMAKE_INSTALL_PREFIX` is always
+the runtime installation location, even when cross-compiling.
+
+The :variable:`CMAKE_<LANG>_COMPILER` variables may be set to full paths, or to
+names of compilers to search for in standard locations. In cases where CMake does
+not have enough information to extract information from the compiler, the
+:module:`CMakeForceCompiler` module can be used to bypass some of the checks.
+
+CMake ``find_*`` commands will look in the sysroot, and the :variable:`CMAKE_FIND_ROOT_PATH`
+entries by default in all cases, as well as looking in the host system root prefix.
+Although this can be controlled on a case-by-case basis, when cross-compiling, it
+can be useful to exclude looking in either the host or the target for particular
+artifacts. Generally, includes, libraries and packages should be found in the
+target system prefixes, whereas executables which must be run as part of the build
+should be found only on the host and not on the target. This is the purpose of
+the ``CMAKE_FIND_ROOT_PATH_MODE_*`` variables.
+
+Some compilers are inherently cross compilers, such as Clang and the QNX QCC
+compiler. The :variable:`CMAKE_<LANG>_COMPILER_TARGET` can be set to pass a
+value to those supported compilers when compiling::
+
+  set(CMAKE_SYSTEM_NAME Linux)
+
+  set(triple arm-linux-gnueabihf)
+
+  set(CMAKE_C_COMPILER clang)
+  set(CMAKE_C_COMPILER_TARGET ${triple})
+  set(CMAKE_CXX_COMPILER clang++)
+  set(CMAKE_CXX_COMPILER_TARGET ${triple})
+
+Or, for QCC::
+
+  set(CMAKE_SYSTEM_NAME QNX)
+
+  set(arch gcc_ntoarmv7le)
+
+  set(CMAKE_C_COMPILER qcc)
+  set(CMAKE_C_COMPILER_TARGET ${arch})
+  set(CMAKE_CXX_COMPILER QCC)
+  set(CMAKE_CXX_COMPILER_TARGET ${arch})
+
+
+Similarly, some compilers do not ship their own supplementary utilities
+such as linkers, but provide a way to specify the location of the external
+toolchain which will be used by the compiler driver. The
+:variable:`CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN` variable can be set in a
+toolchain file to pass the path to the compiler driver.
+
+The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is
+cross-compiling.
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 0f5f1ec..6756bb9 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -64,6 +64,7 @@ Variables that Provide Information
    /variable/CMAKE_STANDARD_LIBRARIES
    /variable/CMAKE_STATIC_LIBRARY_PREFIX
    /variable/CMAKE_STATIC_LIBRARY_SUFFIX
+   /variable/CMAKE_TOOLCHAIN_FILE
    /variable/CMAKE_TWEAK_VERSION
    /variable/CMAKE_VERBOSE_MAKEFILE
    /variable/CMAKE_VERSION
@@ -96,8 +97,13 @@ Variables that Change Behavior
    /variable/CMAKE_SYSROOT
    /variable/CMAKE_FIND_LIBRARY_PREFIXES
    /variable/CMAKE_FIND_LIBRARY_SUFFIXES
-   /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE
    /variable/CMAKE_FIND_NO_INSTALL_PREFIX
+   /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE
+   /variable/CMAKE_FIND_ROOT_PATH
+   /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
+   /variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
+   /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
+   /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
    /variable/CMAKE_IGNORE_PATH
    /variable/CMAKE_INCLUDE_PATH
    /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE
diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst
new file mode 100644
index 0000000..67948f7
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst
@@ -0,0 +1,8 @@
+CMAKE_FIND_ROOT_PATH
+--------------------
+
+List of root paths to search on the filesystem.
+
+This variable is most useful when cross-compiling. CMake uses the paths in
+this list as alternative roots to find filesystem items with :command:`find_package`,
+:command:`find_library` etc.
diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst
new file mode 100644
index 0000000..df1af5a
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst
@@ -0,0 +1,6 @@
+CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
+---------------------------------
+
+.. |FIND_XXX| replace:: :command:`find_file` and :command:`find_path`
+
+.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst
new file mode 100644
index 0000000..52ab89d
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst
@@ -0,0 +1,6 @@
+CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
+---------------------------------
+
+.. |FIND_XXX| replace:: :command:`find_library`
+
+.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst
new file mode 100644
index 0000000..3872947
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst
@@ -0,0 +1,6 @@
+CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
+---------------------------------
+
+.. |FIND_XXX| replace:: :command:`find_package`
+
+.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst
new file mode 100644
index 0000000..d24a78a
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst
@@ -0,0 +1,6 @@
+CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
+---------------------------------
+
+.. |FIND_XXX| replace:: :command:`find_program`
+
+.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
new file mode 100644
index 0000000..ab65e09
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
@@ -0,0 +1,8 @@
+This variable controls whether the :variable:`CMAKE_FIND_ROOT_PATH` and
+:variable:`CMAKE_SYSROOT` are used by |FIND_XXX|.
+
+If set to ``ONLY``, then only the roots in :variable:`CMAKE_FIND_ROOT_PATH`
+will be searched. If set to ``NEVER``, then the roots in
+:variable:`CMAKE_FIND_ROOT_PATH` will be ignored and only the host system
+root will be used. If set to ``BOTH``, then the host system paths and the
+paths in :variable:`CMAKE_FIND_ROOT_PATH` will be searched.
diff --git a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst
index 86c0b0e..033998d 100644
--- a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst
+++ b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst
@@ -10,4 +10,4 @@ may be set to a path to a path to the external toolchain and will be passed
 to the compiler driver if supported.
 
 This variable may only be set in a toolchain file specified by
-the ``CMAKE_TOOLCHAIN_FILE`` variable.
+the :variable:`CMAKE_TOOLCHAIN_FILE` variable.
diff --git a/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst
index 7c8efee..656c57d 100644
--- a/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst
+++ b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst
@@ -8,4 +8,4 @@ QNX qcc. These compiler drivers support a command-line argument to specify
 the target to cross-compile for.
 
 This variable may only be set in a toolchain file specified by
-the ``CMAKE_TOOLCHAIN_FILE`` variable.
+the :variable:`CMAKE_TOOLCHAIN_FILE` variable.
diff --git a/Help/variable/CMAKE_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst
index e42e63a..7aa0450 100644
--- a/Help/variable/CMAKE_SYSROOT.rst
+++ b/Help/variable/CMAKE_SYSROOT.rst
@@ -9,4 +9,4 @@ necessary on installation.  The ``CMAKE_SYSROOT`` is also used to prefix
 paths searched by the ``find_*`` commands.
 
 This variable may only be set in a toolchain file specified by
-the ``CMAKE_TOOLCHAIN_FILE`` variable.
+the :variable:`CMAKE_TOOLCHAIN_FILE` variable.
diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst
new file mode 100644
index 0000000..e1a65e1
--- /dev/null
+++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst
@@ -0,0 +1,9 @@
+CMAKE_TOOLCHAIN_FILE
+--------------------
+
+Path to toolchain file supplied to :manual:`cmake(1)`.
+
+This variable is specified on the command line when cross-compiling with CMake.
+It is the path to a file which is read early in the CMake run and which specifies
+locations for compilers and toolchain utilities, and other target platform and
+compiler related information.