Cmake tutorial

Cmake, as a cross-platform builder, only needs a configuration file named CMakeLists.txt, at the root directory of the software you develop, so-called source directory. This configuration file is independent of the compiler and the platform. In order to generate native makefiles or workspaces of your favorite IDE (Visual Studio, Xcode, Eclipse, CodeBlocks, …), Cmake needs another directory, so-called build directory, in which files generated during the build process will be written.

The build directory is recommended not to be the source directory. For XLiFE++ compilation, we suggest you to set the build directory as a subdirectory of XLiFE++ install directory, with the name build for instance.

On the command line

On Unix/Linux and macOS, you can use the cmake command or its default GUI ccmake. On Windows, you can use the cmake.exe command.

Fig. 34 ccmake (macOS, Unix/Linux)

As it was said during introduction, a Cmake call needs 2 directories : the source directory (command-line option -S) and the build directory (command-line option -B), but there is an easier way to call Cmake : by calling it from the build directory and giving only the source directory, as in the following :

$ cmake relative/path/to/CMakeLists.txt [options]
$ ccmake [options] relative/path/to/CMakeLists.txt

Through GUI applications

When running Cmake GUI application, you have to set the source directory and the build directory. Then, you click the Configure button. It will ask ou the generator and the compiler you want. Then, you click the Generate button, to generate your IDE project file or your Makefile.

Fig. 35 Cmake application (macOS on the left and Windows on the right)

Cmake options and cache entries

On the command line

The Cmake help will give you the full list of command-line options. Only 2 are eventually useful:

-G

to define the generator. By default, the cmake command generates a Makefile. This is the Unix Makefiles generator on Unix/Linux and macOS or MinGW Makefiles generator on Windows. But you can use other generators to have IDE files for your favorite IDE, such as Eclipse, CodeBlocks, Xcode, Visual Studio, …:

$ cmake relative/path/to/CMakeLists.txt -G <generator_name> [options]

The following command chooses for instance to use codeblocks on unix platform:

$ cmake relative/path/to/CMakeLists.txt -G "CodeBlocks - Unix Makefiles" [options]

Please read the cmake command help to know the potential list of available generators on your computer.

-D

to define cache entries. Cache entries can be shown as dedicated configuration options for the software you want to build.

$ cmake relative/path/to/CMakeLists.txt [-G <generator_name>] -DKEY1=value1 -DKEY2=value2 -DKEY3=value3 ...

Warning

Please notice that the key is always sticked to the -D option, and that the equal sign is sticked to both key and value

Through GUI applications

Available cache entries appears in the main frame after the first click on configure. You can organise them by grouping (cache entries beginning with the same prefix are in the same group whose name is the prefix in common) or by showing/hiding advanced cache entries.

Each time you change the value of one or several cache entries, you have to click on the Configure button again, before clicking on Generate