kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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.
This commit is contained in:
Brad King 2013-12-03 09:45:28 -05:00 committed by CMake Topic Stage
parent 1af0c41278 c45b5ceb66
commit a6b45087a1
19 changed files with 230 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Help/command/FIND_XXX_ROOT.txt
View File

@ -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.

2
Help/command/find_file.rst
View File

@ -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

2
Help/command/find_library.rst
View File

@ -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

2
Help/command/find_package.rst
View File

@ -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

2
Help/command/find_path.rst
View File

@ -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

2
Help/command/find_program.rst
View File

@ -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

1
Help/index.rst
View File

@ -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

160
Help/manual/cmake-toolchains.7.rst Normal file
View File

@ -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.

8
Help/manual/cmake-variables.7.rst
View File

@ -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

8
Help/variable/CMAKE_FIND_ROOT_PATH.rst Normal file
View File

@ -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.

6
Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst Normal file
View File

@ -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

6
Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst Normal file
View File

@ -0,0 +1,6 @@
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
---------------------------------
.. |FIND_XXX| replace:: :command:`find_library`
.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt

6
Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst Normal file
View File

@ -0,0 +1,6 @@
CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
---------------------------------
.. |FIND_XXX| replace:: :command:`find_package`
.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt

6
Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst Normal file
View File

@ -0,0 +1,6 @@
CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
---------------------------------
.. |FIND_XXX| replace:: :command:`find_program`
.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt

8
Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt Normal file
View File

@ -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.

2
Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst
View File

@ -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.

2
Help/variable/CMAKE_LANG_COMPILER_TARGET.rst
View File

@ -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.

2
Help/variable/CMAKE_SYSROOT.rst
View File

@ -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.

9
Help/variable/CMAKE_TOOLCHAIN_FILE.rst Normal file
View File

@ -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.