The only good, down to earth, practical and noob friendly CMake tutorial in the world aka “CMake in 2 minutes”

Learning programming has been difficult for me. You can’t believe the amount of suffering I have experienced to learn everything from scratch. There are awesome resources online but so many are cryptic and missing key information. I have this dream of “XYZ for total and utter dummies” tutorial series where I explain simply and with examples all the key concepts for the given topics. This is one of those tutorials.

CMake is exceptionally difficult to understand for beginners. Like, get an intuition on how it works. Their webpage is good but they don’t have “for dummies” section. 90% of the CMake tutorials in 2023 are the old CMake, not the modern one. They teach you bad habits. I don’t like that.

Now that I have convinced you that you need this tutorial, please read on.

What is CMake? Do I need it?

CMake is a tool for automating Make. In general we use CMake in similar ways than chefs use recipes: we explain, what are the ingredients in the software and how to create applications and libraries out of them.

If you wish to develop c++ in 2023 (or in the future) you must know this tool. 99% of the open source projects I see in Github or in private sector are using this tool. The rest are using Make, Bazel, Ninja.

You may use many different compiler versions and programming languages in CMake projects.

How do I make Hello World with CMake?

Install dependencies on apt:

sudo apt install cmake g++ make

Create a new folder for your project and there these files:

CMakeLists.txt
main.cpp

You don’t need anything else. Inside main.cpp copy (or even better if you type) these lines

#include <cstdio>
int main(void)
{
  printf("Hello world!\n");
  return 0;
}

Then, add these lines inside CMakeLists.txt

project(CmakeForDummies)
add_executable(app main.cpp)

This will tell that we have a project named CmakeForDummies (the project name does not matter) and we have an executable called app that uses only a single source file, main.cpp.

You can build it like this:

cmake -S . -B build && cmake --build build

You’ll get the following output if everything goes well. Note that the warning does not matter now.

CMake Warning (dev) at CMakeLists.txt:1 (project):
  cmake_minimum_required() should be called prior to this top-level project()
  call.  Please see the cmake-commands(7) manual for usage documentation of
  both commands.
This warning is for project developers.  Use -Wno-dev to suppress it.

-- Configuring done (0.0s)
-- Generating done (0.0s)
-- Build files have been written to: source/build
[ 50%] Building CXX object CMakeFiles/app.dir/main.cpp.o
[100%] Linking CXX executable app
[100%] Built target app

Then, run the app:

./build/app

You should see this output:

Hello world!

Yay! Your first CMake application. It’s not that difficult eh?

Learning to walk

What if you want to add more files to your project?

If it’s your own source files:

  1. You need to tell the compiler where the source files are
  2. You need to tell the linker where the source files are

In practise:

Add a folder src/ and create a file cat.cpp there. Add a folder include/ and create a file cat.hpp there.

You may add a class or just any code in those files or leave them empty for the sake of the example.

Make these changes to your CMakeLists.txt:

project(CmakeForDummies)
add_executable(app main.cpp src/cat.cpp)
target_include_directories(app PRIVATE include/)

Add #include "cat.hpp" to main.cpp. You should be now able to use the new files in your project. Just always remember to tell the linker where to look for the .hpp or .h files by using target_include_directories. You need to update CMakeLists.txt every time you add new files. That’s not too big of a thing in my opinion.

Rebuild: cmake -S . -B build && cmake --build build and test your app: ./build/app.

Now you have learned, how to use CMake to build projects that have files in different folders. There are many ways to do what I just showed you. I’m trying to keep things simple.

That’s it. This was the bare minimum of CMake that you will need to get started. I suggest you start slowly using it in your projects and learning more skills regarding CMake and build systems.

More reading:

  • https://hsf-training.github.io/hsf-training-cmake-webpage/index.html
  • https://cliutils.gitlab.io/modern-cmake/

More learning:

  • folder structure
  • multiple CMakeLists.txt files
  • targets
  • dependencies: find_package and more
  • compile options
  • conditionals