CMakeLists.txt

Posted on by

Last update : June 13, 2015

A CMakelists.txt file is the only thing needed by CMake to generate makefiles for many platforms and IDEs. CMake is a cross-platform free and open-source configurator for managing the build process of software using a compiler-independent method. It is designed to support directory hierarchies and applications that depend on multiple libraries. It is used in conjunction with native build environments such as make, Apple’s Xcode, and Microsoft Visual Studio. CMake has minimal dependencies, requiring only a C++ compiler on its own build system. It refers to the entire family of tools : CMake, CTest, CDash, and CPack.

CMake development began in the year 1999 in response to the need for a cross-platform build environment for the Insight Segmentation and Registration Toolkit (ITK). The project was funded by the United States National Library of Medicine (NLM) as part of the Visible Human Project. It was inspired by the Visualization Toolkit (VTK) at Kitware who maintains the CMake software. The latest version of CMake is  3.2.2 released on April 14, 2015.

The ability to build a directory tree outside the source tree is a key feature of CMake, ensuring that if a build directory is removed, the source file remains unaffected.

A CMake generator translates the platform-agnostic CMakeLists.txt file and produces a platform-dependent build system that you can use to compile the project. CMake can find dependencies, do conditional builds and even set different compile or link flags depending on the choice of different options by the user.

During a build with CMake there are three directories involved :

  • source dir
  • build dir
  • install dir

CMake source directory

The source directory is where the project’s sources are stored. This is the directory to which you extract the project source archive or to where you checked out the sources from a version control system.  Typically a source is any file that is explicitly modified by the developer. The source directory also contains the files which describe the build to CMake : a bunch of CMakeLists.txt files in the source directory and probably in several sub-directories. Eventually additional CMake scripts with the extension .cmake are stored in a special CMake directory. By default CMake does not alter any file in the source directory and doesn’t add new ones.

CMake build directory

The build directory is where all compiler outputs are stored, which includes both object files as well as final executables and libraries. CMake also stores several files of its own there, including its cache. You can have more than one build directory for the same source directory with different build options. The concept to have a build directory separated from the source directory is called Out of source Build. Its much easier to convince yourself that your build has been cleaned since you can simply delete the build folder and start over again.

CMake install directory

CMake is able to copy all relevant files for the build project to an install directory.

CMake GUI

The most basic CMake frontend is the CMake console which is available on all platforms. CMake has also a GUI frontend called cmake-gui.

CMake build options

I mainly use CMake with Visual Studio C++ 2010 and with Xcode on Mac OSX Yosemite.

There are three Visual Studio 2010 generators :

  • Visual Studio 10 2010 : creates project files for the x86 (32bit) processor, running also on x64 processors
  • Visual Studio 10 2010 IA64 : creates project files for the x64 processor
  • Visual Studio 10 2010 Win64 : creates project files for the Itanium processor

Visual Studio 2010 itself is a 32bit program.

There is only one Xcode generator.

CMake Language Syntax

CMake has its own basic scripting language. A listfile may contain only commands and comments. Comments start with a # character and stop at the end of a line. The names of commands are case insensitive, the arguments are case sensitive. A list of all commands is available at the CMake website. The main commands are :

  • add_definitions
  • add_executable
  • add_library
  • cmake_minimum_required
  • find_library
  • include_directories
  • link_directories
  • message
  • project
  • set
  • set_property
  • source_group
  • target_link_libraries

The basic type in CMake is a string. The SET command is used to set the value of a variable to some string. It takes two arguments: the name of the variable and its new value. To access the value of a variable, you perform a substitution with the syntax ${variable name}.

Examples :

# create a list of strings
set (VAR a b c)
# use the system version of BOOST
set (USE_SYSTEM_BOOST ON)
# use CACHE to let user set a value in CMake GUI
set (USE_SYSTEM_SQLITE OFF CACHE BOOL "Don't use the system version")

Finding dependencies

CMake can automatically search for the location of dependency libraries to include in the project.

CMake Cross-Compiling

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

CMake Example

The following example shows the CMakeLists.txt file of the OrthancWebViewer 1.0 project. The following parameters are used :

  1. parameters of the build : set (VAR ON CACHE BOOL “some text”)
  2. parameters to fine-tune linking against system libraries  :
    set (VAR ON CACHE BOOL “some text”)
  3. distribution specific settings : set (VAR OFF CACHE BOOL “some text”)
  4. include resources and abcde.cmake files
  5. check the availability of the Orthanc SDK
  6. add specific definitions
  7. set (CORE_SOURCES …)
  8. add libraries and set target properties
  9. install targets
  10. add UnitTests

The following figures show the CMake GUI on Windows and Mac OSX handling the OrthancWebViewer project.

CMake

CMake version 3.0.1 on Windows 8.1

CMake

CMake version 3.2.3 on Mac OSX

On Mac OSX Cmake generated a CMakeCache.txt file in the Build folder and a CMakeOutput.log file in the Build/CMakeFiles folder.

CMake links

The following list provides links to websites with addition informations about Cmake :