CMake Cross Compiling

From KitwarePublic
Revision as of 17:38, 12 June 2007 by Alex (talk | contribs)
Jump to navigationJump to search

Cross compiling is supported by CMake starting with version 2.6.0.

Cross compiling means that the software is built for a different system than the one which does the build. This means

  • CMake cannot autodetect the target system
  • usually the executables don't run on the build host
  • the build process has to use a different set of include files and libraries for building, i.e. not the native ones


So since CMake cannot guess the target system, you have to preset the following cmake variables:

CMAKE_SYSTEM_NAME
this one is mandatory, it is the name of the target system, i.e. the same as CMAKE_SYSTEM_NAME would have if CMake would run on the target system. Typical examples are "Linux" and "Windows". This variable is used for constructing the file names of the platform files like Linux.cmake or Windows-gcc.cmake. If your target is an embedded system without OS set CMAKE_SYSTEM_NAME to "Generic". If CMAKE_SYSTEM_NAME is preset, the CMake variable CMAKE_CROSSCOMPILING is automatically set to TRUE, so this can be used for testing in the CMake files.
CMAKE_SYSTEM_VERSION
optional, version of your target system, not used very much.
CMAKE_SYSTEM_PROCESSOR
optional, processor (or hardware) of the target system. This variable is not used very much except for one purpose, it is used to load a CMAKE_SYSTEM_NAME-compiler-CMAKE_SYSTEM_PROCESSOR.cmake file, which can be used to modify settings like compiler flags etc. for the target. You probably only have to set this one if you are using a cross compiler where every target hardware needs special build settings.

Since CMake cannot guess the target system, it also cannot guess which compiler it should use, so you have to preset this too:

CMAKE_C_COMPILER
the C compiler executable, may be the full path or just the filename. If it is specified with full path, then this path will be prefered when searching the C++ compiler and the other tools (binutils, linker, etc.). If this compiler is a gcc-cross compiler with a prefixed name (e.g. "arm-elf-gcc") CMake will detect this and automatically find the corresponding C++ compiler (i.e. "arm-elf-c++"). (this may also work for MS cross compilers). The compiler can also be preset via the CC environment variables.
CMAKE_CXX_COMPILER
the C++ compiler executable, may be the full path or just the filename. It is handled the same way as CMAKE_C_COMPILER. If the toolchain is a GNU toolchain, you only need to set one of both.


For testing the host system, there is a corresponding set of variables, which is set automatically by CMake:

  • CMAKE_HOST_SYSTEM_NAME
  • CMAKE_HOST_SYSTEM_VERSION
  • CMAKE_HOST_SYSTEM_PROCESSOR
  • CMAKE_HOST_SYSTEM

Without cross compiling the variables for the host system and the target system are identical. In most cases you will want to test for the target system, then the same way as without cross compiling use the CMAKE_SYSTEM_xxx variables, this will work both for cross compiling and for native building.

With these variables correctly set, CMake will now use the cross compiling toolchain for building and in the CMakeLists.txt you can still use the CMAKE_SYSTEM_XXX variables for testing for which system you are building.

Finding software

System introspection

Many non-trivial software projects will have a set of system introspection tests for finding out properties of the (target) system. In CMake there are e.g. macros provided like CHECK_INCLUDE_FILES() or CHECK_C_SOURCE_RUNS(). Most of these tests will internally use either the TRY_COMPILE() or the TRY_RUN() CMake commands. The TRY_COMPILE() commands still work as expected when cross compiling, they will try to compile the piece of software with the cross compiling toolchain, which will give the expected result. All tests using TRY_RUN() internally cannot work, since the executables produced cannot run on the build host system. At first TRY_RUN() tries to compile the software, which will work the same way when cross compiling. If this succeeded, it will check the variable CMAKE_CROSSCOMPILING whether the resulting executable is runnable or not. If not, it will create two cache variables, which then have to be set by the user or via the CMake cache: