CMake is a sophisticated, cross-platform, open-source build system developed by Kitware in 2001. CMake is the name used to refer to the entire family of tools: CMake, CTest, CDash, and CPack. These tools are used to…

CMake – An intelligent build system used to build simple, to very elaborate projects.

CTest, CDash – These are used to test and debug your projects.

CPack – A packaging tool that finalizes your project for distribution.

CMake simplifies the potentially monstrous build system into a few easy to write files. It is targeted towards C and C++ and is usable with various compiler/OS support. At the risk of over simplifying things, CMake looks at your project and sees a ‘file system’. You tell it where all your files are at, what you want it to do with them, and it does it. In a nut shell it’s really that easy. More elaborately however, CMake is wonderful for it’s design to support complex directory hierarchies. When you use CMake it will locate include files, libraries, executables, other optional build directives, then link everything for you. No more messy Makefiles.

CMake basically requires one thing, a CMakeLists.txt file. We’ll start with a simple example.

Here is a very simple program I wrote in C called fib.c which lists the Fibonacci Sequence up to a given value. That value is passed to the main function when it is called.

# include "stdio.h" # include "stdlib.h" int main( int argc, char** argv) { if ( argc > 2 || argc == 1 ) { printf("Fibonacci takes one postitive integer greater\ than two as it's argument

"); return EXIT_SUCCESS; } int a, b; a = 0; b = 1; printf( "%d", b ); for( int i = 0; i + a <= atof( argv[1] ); b = i ) { i = a + b; a = b; printf( ", %d", i ); } printf("

"); return EXIT_SUCCESS; }

So let's say you'd like to compile this and give it a go. We could just compile it directly with one line...

gcc -std=c99 fib.c

Notice we need a -std flag. We set it to c99 because loop initial declarations are only allowed in c99 mode. Alternatively you could just change that in your gcc compiler to use by default. Another option would be to use a Makefile..... Nah... Or we could use CMake. I declare the winner to be CMake.

Download

Let's make sure we have CMake on our systems, I'm using Ubuntu 10.04.

sudo apt-get install cmake cmake-curses-gui

The cmake-curses-gui provides a somewhat-helpful-gui (a lot like the Windows version) if that's what you're into. There is pretty much no setup required here, we just need to make our CMakeLists.txt file in the main directory of our project, then run CMake from our build folder.

Setup Project

fib is the name of the folder/main directory, where the fib.c file is, as well as the soon to be disclosed CMakeLists.txt file. It's a good programming practice to do all of your builds in a build folder. Not doing so clutters your project folder with a bunch of confusing files. You'll see this after we run cmake. So let's set this up.

mkdir /where/you/want/your/project/fib cd fib mkdir build

So this is what your project file system looks like.

fib / build

Now use your favorite text editor (should be vim ) to create your own fib.c file, as well as a CMakeLists.txt file in your fib directory.

CMake Syntax

Here is the CMakeLists.txt file used to compile the fib.c program.

#Specify the version being used aswell as the language cmake_minimum_required(VERSION 2.6) #Name your project here project(fibonacci) #Sends the -std=c99 flag to the gcc compiler add_definitions(-std=c99) #This tells CMake to fib.c and name it fibonacci add_executable(fibonacci fib.c)

The basic syntax of CMake consists of three things; comments, commands, and white spaces. A comment is made by beginning a line with the '#' character

#Chocolate Curry is my favorite

And a command is constructed with the command name, opening parenthesis, whitespace separated arguments, and a closing parenthesis.

command(arg1 agr2 agr3 ...)

The basic data type in CMake is a string. You can even create lists of strings using the set command.

set(VAR a b c)

This creates variable VAR which is composed of three strings a, b, and c. Referencing a variable should look familiar to most of you. ${VAR} is the correct syntax to refer to the list of strings VAR at a later time. For instance these three command calls are the same.

command(${VAR}) command(a b c) command(a;b;c)

You can also separate strings with semicolons. Placing quotations around anything will allow it to be read as a string. For instance, the following command

command("${VAR}")

will read in "${VAR}" not "a b c". CMake syntax also provides some useful flow control options. First is the if else logic structure.

# some_command will be called if the variable's value is not: # empty, 0, N, NO, OFF, FALSE, NOTFOUND, or -NOTFOUND. if(var) some_command(...) endif(var)

They also provide looping commands, foreach and while.

set(VAR a b c) # loop over a, b,c with the variable f foreach(f ${VAR}) message(${f}) endforeach(f)

Simple function and macro constructions are also supported.

# define a macro hello macro(hello MESSAGE) message(${MESSAGE}) endmacro(hello) # call the macro with the string "hello world" hello("hello world") # define a function hello function(hello MESSAGE) message(${MESSAGE}) endfunction(hello)

Lastly CMake also supports all of your common Regular Expressions

^ Matches at beginning of a line or string

$ Matches at end of a line or string

. Matches any single character other than a newline

[ ] Matches any character(s) inside the brackets

[^ ] Matches any character(s) not inside the brackets

[-] Matches any character in range on either side of a dash

* Matches preceding pattern zero or more times

+ Matches preceding pattern one or more times

? Matches preceding pattern zero or once only

() Saves a matched expression and uses it in a later replacement

For a more detailed description of CMake syntax go here.

Building The Project

So back to the CMakeLists.txt file to build our example

#Specify the version being used as well as the language cmake_minimum_required(VERSION 2.6) #Name your project here project(fibonacci) #Sends the -std=c99 flag to the gcc compiler add_definitions(-std=c99) #This tells CMake to fib.c and name it fibonacci add_executable(fibonacci fib.c)

CMake is case insensitive, thus it does not distinguish between command() and COMMAND(). I prefer all lowercase because it is faster to type. so here is the breakdown of the CMakeLists.txt

cmake_minimum_required(VERSION 2.6) - This signifies the version of CMake that you're using and allows you to pass the language into documentation.

project(fibonacci) - This allows you to name your project and you can later on refer to the project as a whole using this string.

add_definitions(-std=c99) - This command sends arguments to the compiler, which CMake will choose for you unless otherwise told so.

add_executable(fibonacci fib.c) - This does the magic. Here CMake takes fib.c, and using all of the libraries it was handed (none in this simple example) compiles it into the output file named fibonacci.

Beautiful, we're almost done. Now we want to compile things. Once run for the first time CMake will configure itself to your system, and place the binaries (your output files) into the directory you called it from. This is where we cd into the build folder, and run

cmake ..

The ' .. ' argument is the same as the one used in BASH, it tells CMake to execute from the CMakeLists.txt in the previous directory. This call just produced your Makefile, so let's finish it off with the last command.

make

Now if you ls into the build folder you'll see all kinds of stuff.

CMakeCache.txt - Think of this as a configuration file. It has many advanced settings to optimize the build process for large projects. (Such as building the Linux Kernel! )

) CMakeFiles (directory) - This has a lot of the stuff CMake uses under the hood to build your project. I recommend you poke around through there and take a look at stuff...

cmake_install.cmake - Your install file. We didn't use one in this program.

fibonacci - Hooray it's our program!

Makefile - remember your last command 'make'? This is the Makefile produced by Cmake, this is really what it all came down to.

You've Now built a program using CMake. If you'd like to see a more sophisticated example of Cmake look for my series on OpenCV under the Computer Vision tab. I use Cmake there to link all of the OpenCV libraries, and even make some of my own.

Strengthen Your CMake Muscles Here