Quick’n’easy Cmake tutorial

Introduction

Cmake is a tool used to generate build files. Build files are what is used to build a project. An example of a build file would be a makefile. You can then use make tool (or mingw32-make on Windows) to build the project and generate an executable. Cmake is not a build tool itself, but rather a build file generator. If you type:

cmake -G

You will get a list of all supported build file generators. These generators are essentially all build file formats that Cmake supports. But now we are getting ahead of ourselves. Lets first install Cmake and then we can talk more about what it is and how to use it.

Installing Cmake

Cmake installation is very easy on Windows. If installing with installer just make sure that you check the option which automatically adds Cmake to your PATH variable. Of course you can do it yourself, but for anyone that doesn’t know how, I would recommend to select this automatic option.

I won’t go into further details about this since there are a lot of tutorials available on internet on this topic. What is important for this tutorial is that you have Cmake installed, and somewhere in your PATH, so we can invoke it from terminal.

If you don’t want to add it to your path, that is fine also, you just have to write the whole path to the executable every time you want to run it, but you probably already know that. 🙂

So quickly check if you have it installed:

cmake --version

And we can move on.

Required tools

The tools you will also need for completing this tutorial are:

  • C and C++ compilers
  • some build system supported with Cmake, would recommend make (mingw32-make on Windows), or Ninja

You can find instructions on how to install these tools easily, so we won’t go through that.

Basic Cmake file

Without any further ado, I present to you a basic Cmake file, the CMakeLists.txt:

cmake_minimum_required(VERSION 3.12.2)

# If you dont have CC and CXX global variables set you can set compilers manualy.
set(CMAKE_C_COMPILER "D:/MinGW/bin/gcc.exe")
set(CMAKE_CXX_COMPILER "D:/MinGW/bin/g++.exe")

# Define project name.
project (cmake_tut)

include_directories("./mydir1/"
                    "./mydir2/")

# Adding sources to compilation.
add_executable(cmake_tut ./main.c
                         ./mydir1/test.c
                         ./mydir2/test.cpp)

And that is really that! Very simple and short. The name of this cmake file is very important and it should be CMakeLists.txt .

If you have compiler path set globally you don’t even need :

set(CMAKE_C_COMPILER "D:/MinGW/bin/gcc.exe")
set(CMAKE_CXX_COMPILER "D:/MinGW/bin/g++.exe")

These two lines. But I would recommend to have them, so that your compilers are explicitly defined. This way you always know what you are using to compile your code.

You should always define your compilers before project() function because otherwise it might not work.

include_directories() function is used to tell the compiler where to look for include files (.h), while add_executable() function determines the executable name and source files (.c and .cpp) to compile.

There is a github repository with the example project that uses this cmake file. You can find it here.

Basic command line usage

Now that we have our basic Cmake file ready, lets see how to use it. I will be using already mentioned repository as an example.

First things first, we need to change compiler paths. Find gcc and g++ executables on your machine and replace D:/MinGW/bin/gcc.exe and D:/MinGW/bin/g++.exe in the CMakeLists.txt file with full paths to compilers on your machine.

set(CMAKE_C_COMPILER "path/to/your/gcc.exe")
set(CMAKE_CXX_COMPILER "path/to/your/g++.exe")

Paths need to be enclosed in quotation marks, use “/” not “\” and if on Linux or Mac you won’t have to include .exe extension.

Ok, now that that is out of the way we need to create a build folder in this example repository. You can call it “build”. Open build folder and start a terminal in it. Type one of the following, depending on the build tool that you use:

#MinGW Makefiles
cmake -G "MinGW Makefiles" ..
#Unix Makefiles
cmake -G "Unix Makefiles" ..
#Ninja
cmake -G "Ninja" ..

For a complete list of available generators just type:

cmake -G

If everything went smoothly you should now have all your build files generated in the build folder and by typing:

mingw32-make

or

make

or

ninja

The project will get compiled, and executable with the name of cmake_tut should be generated in the build folder. If you run the executable you should see the following printout:

The program doesn’t do anything smart, it just showcases that both .c and .cpp files get compiled and used in the same project.

Conclusion

And that concludes the very basic Cmake tutorial! This very basic file template can serve as a foundation to build on top off. Cmake has a ton of cool stuff that are not covered in this short introduction, but that is for some other time. Also, it would be interesting to see how we can build a project for some embedded platform, like STM, but those are all topics for some other time.