diff options
| -rw-r--r-- | Help/index.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 160 |
2 files changed, 161 insertions, 0 deletions
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. |