Help: Add cmake-toolchains.7 manual

Create a manual for toolchain related docs.

1 files changed, 160 insertions, 0 deletions

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.