[Cmake-commits] CMake branch, next, updated. v2.8.12.1-6001-g24adc1b
Brad King
brad.king at kitware.com
Tue Dec 3 09:45:05 EST 2013
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, next has been updated
via 24adc1b366da8a291f8f7cfd18b1230e2aabb28a (commit)
via c45b5ceb6684518d06a7e185ea620031e03b2efe (commit)
from 6e6e41de564789fab0b6ce935e580dc1d8f4da32 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=24adc1b366da8a291f8f7cfd18b1230e2aabb28a
commit 24adc1b366da8a291f8f7cfd18b1230e2aabb28a
Merge: 6e6e41d c45b5ce
Author: Brad King <brad.king at kitware.com>
AuthorDate: Tue Dec 3 09:45:03 2013 -0500
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Tue Dec 3 09:45:03 2013 -0500
Merge topic 'cmake-toolchains-manual' into next
c45b5ce Help: Add cmake-toolchains.7 manual
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=c45b5ceb6684518d06a7e185ea620031e03b2efe
commit c45b5ceb6684518d06a7e185ea620031e03b2efe
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Sat Oct 19 00:50:26 2013 +0200
Commit: Brad King <brad.king at kitware.com>
CommitDate: Tue Dec 3 09:44:31 2013 -0500
Help: Add cmake-toolchains.7 manual
Create a manual for toolchain related docs.
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.
-----------------------------------------------------------------------
Summary of changes:
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list