CMake Tutorial: Learn The Basic

August 15, 2019

So, I'll be honest. After a long time not playing around with my own C/C++ Project, I'm started to forget how to write Makefiles. After exploring around Github and the documentation to find some decent Makefiles example, it starts to make me think:

Should it be better for me to use CMake instead?

Yep, that makes me consider and decided to go with it for various reason:

  1. Cleaner and easier to deal with.
  2. Cross-Platform
  3. Can be used to generate config for other build systems

With that said I start to play around with CMake documentation lets dig into the basics.

The Basic

For a simple/small project it's quite straight forward, just creates CMakeLists.txt on your root directory and add the following line into your CMakeLists.txt

cmake_minimum_required (VERSION 3.14.5)
project (MyProject)
add_executable(MyApp MyApp.cpp)

Here we have the most basic CMake configuration, I will explain what all this command do inside your CMakeLists in a second.

On the first line, we have cmake_minimum_required(VERSION <version-number>) command.

With this command, we declare the most minimum CMake version that can be used to generate or build your CMake config.

I see most people set the minimum version value to version 2.6, but I prefer to set it to whatever CMake version I have when I create that CMakeLists. Not sure if it's bad practice but I don't think that going to be an issue. Let me know if you have opinions on this...

On the second line we got project(<project-name>) command, it's simply letting the CMake know what our project going to be called.

And on the last line, we have add_executable(<executable-name> <source-file>) command, here you will define your main app source and final executable name to be built with CMake.

Dealing With Libraries

With complex projects we usually want to add / link libraries into our final executable, we can also do this with CMake. Let's say we have this structure for our project:

├── CMakeLists.txt
├── Lib
│   └── FancyLibrary
│       ├── FancyLibrary.cpp
│       └── FancyLibrary.h
└── MyApp.cpp

And we would like to use FancyLibrary into our app, we can just add a few more lines into our CMakeLists and create another CMakeLists into our FancyLibrary directory as follows.

Inside our FancyLibrary CMakeLists we can add this command:

add_library(FancyLibrary FancyLibrary.cpp)

what this command do is add and build our FancyLibrary.cpp source file as a library object, so on our top level CMakeLists we can add target_link_library(<executable name> <library-name>) to link it into our final executable.

But, before we can link that into our top-level CMakeLists, the first thing to do, we must let our top-level CMake know that we're going to use source inside FancyLibrary directory to be part of our final build.

Because we already have created another CMakeLists.txt inside the FancyLibrary directory we can easily include it by adding add_subdirectory(<path-to-subdirectory-with-cmakelists>) command on our top-level CMakeLists.

With that addition in place, our top-level CMakeLists.txt will be look something like this:

cmake_minimum_required (VERSION 3.14.5)
project (MyProject)


add_executable(MyApp MyApp.cpp)
target_link_libraries(MyApp FancyLibrary)

There's a lot of other cool things we could do with CMake, what I just cover here just the very basic functionality that you can do with CMake.

But for now i'll just stop here with the basic because i surely need to explore more thing about CMake before I can cover it in my writings XD

Get in Touch