I've noticed C++ beginners asking how to compile code beyond the usual minimal examples. It seems that many tutorials are so busy explaining basics such as variables, if/else flow-control, & loops, that they forget to explain how to compile anything but the most basic single file programs. I'm going to rectify that today. Here's how to compile a multi-file program using CMake.

Want to get up to speed with CMake quickly? Click here...

Why CMake?

CMake is the de-facto standard C++ build system. If you find a C++ project online, there's a very good chance that it uses CMake for building. So, it's a very good idea to learn how to use it (just ignore those who tell you how horrible it is).

A Minimal Example

Here's the smallest CMakelists.txt file for compiling a program with multiple source files:

cmake_minimum_required(VERSION 3.24)
project(hello_world)

# Our Project
set(SOURCE_FILES
	Main.cpp
	Hello.cpp)

add_executable(${PROJECT_NAME} ${SOURCE_FILES})

That's it! Just a few lines. It really is that simple. I bet you could take this file and modify it for your own software.

Lets go through it line by line. The first line indicates the minimum version of CMake needed to compile the software:

cmake_minimum_required(VERSION 3.24)

After that, we give our project a name ("hello_world"):

project(hello_world)

Next, we set a variable called SOURCE_FILES with the names of all source files to compile:

set(SOURCE_FILES Main.cpp Hello.cpp)

And in the final line, we define an executable to build. It's given the project name, and all our source files will be compiled and linked into the executable:

add_executable(${PROJECT_NAME} ${SOURCE_FILES})

Building the Executable Program

CMake generates a lot of files during building. To keep things clean, let's create a build directory, and enter it:

mkdir build
cd build

Next, we ask CMake to generate the makefiles needed to build our hello_world executable. CMake doesn't directly build anything, but generates makefiles for your chosen compiler instead:

cmake ..

The double-dot (..) indicates that CMake should read the CMakelists.txt file from the parent directory.

Now it's time to compile/build the source-code:

cmake --build .

All going well, there should now be a hello_world executable ready for us to run.

NOTE: The dot (.) is short-form for the current directory (i.e., the build directory).

Here's where things depend on which OS and compiler you're using. With Visual Studio, hello_world will be in a Debug/ subdirectory (and be hello_world.exe). On other systems hello_world will be in the build directory itself, and may or may not have .exe at the end (depending on the OS. Whatever the case.

Congratulations! You just compiled and built a program from multiple source files.

Using CMake with Visual Studio Code

I recommend watching the video above to learn how to use CMake with Visual Studio Code (a.k.a., VS Code). It's easier to follow in video form.

That said, here's how in a nutshell:

  • Download & install CMake from here
    NOTE: Linux users can install CMake via their package manager.
  • Download & install Visual Studio code from here
  • Go to the Extensions page in VS Code (look for this icon VSCode Extensions in the left column), and install the "C/C++" and "CMake Tools" extensions written by Microsoft
  • Click on "No active kit" in the blue bar down the bottom of the window, and select which compiler you wish to use

Now you can open the folder containing your code (in the menu, click File -> Open Folder), and build it by clicking the build button in the blue bar (bottom of the window). The blue bar also contains debug and run buttons.

Download the Full Example

I skipped the actual source files because I want to focus 100% on the CMake build file (i.e., CMakelists.txt). You can download the full example here, so that you have a fully buildable project/template:

Click here to download the full code.

Save Yourself The Frustration. Learn CMake Fast...

I went through a lot of pain and frustration to learn CMake's fundamentals. Since then, I've learnt even more, and distilled everything down into The CMake Tutorial. It's the book/course I wish I'd had when I first encountered CMake.

It'll get you up to speed quickly, saving you time, pain and frustration. That way you can focus on mastering the art of software, and writing quality code that does awesome stuff.

The CMake Tutorial Cover