Getting Started with CMake

Introduction

CMake (https://cmake.org/) is an open-source, cross-platform family of tools designed to build, test and package software.

In this tutorial we will guide you through the creation of your first CMake makefiles.

Prerequisites

Installation

Windows

The CMake downloads page has several options to install CMake on Windows. The Windows Installer packages (MSI) are probably the easiest way to get started.

The Windows Installer package will install CMake in C:\Program Files\CMake (unless you chose a different location). In C:\Program Files\CMake\bin you will find the main executable, cmake.exe, but also the CMake GUI, cmake-gui.exe.

A simple Hello World application

We start with a simple example which shows how CMake can generate build files for a simple console application. We will run this example on Windows and Ubuntu. The full example is available from our GitHub repository: CMakeTutorials/HelloWorld.

Our goal in this example is to create makefiles to build our HelloWorld application. This application contains a single source file, main.cpp, which is shown below. It simply has a main function that prints "Hello World!" on the console.

 File: main.cpp
#include <stdio.h>

int main(int argc, char* argv[])
{
    printf("Hello World!\r\n");
    return 0;
}

The Hello World makefile

CMake makefiles are named "CMakeLists.txt". We created the following CMakeLists.txt file to build our Hello World application.

 File: CMakeLists.txt
cmake_minimum_required(VERSION 3.7.2)
project(HelloWorld)
add_executable(HelloWorld main.cpp)

The contents are fairly self-explanatory.

  • The cmake_minimum_required directive indicates the minimum CMake version that is needed to execute this makefile (we probably do not need 3.7.2 in our case but I simply used the version that I have installed).
  • The project directive sets the name of our project.
  • The add_executable directive adds an executable target called "HelloWorld" to be built from the source files listed (the single source file "main.cpp" in this case).

We now have everything we need to start building our project. We will show the procedure on Windows and Ubuntu.

Running CMake

There are 2 ways to run CMake:

  • From the command line using the cmake executable.
  • With the CMake GUI using the cmake-gui executable.

We will present both options in the following pages.

Creating a Visual Studio project from the command line

Let's now use CMake to execute the CMakeLists.txt file. This section assumes that "cmake.exe" is in your path.

Getting a Visual Studio command prompt

When using the command line it is recommended to use the developer prompts provided by Visual Studio. This is to make sure all the required environment variables are set correctly. This topic is covered in the following MSDN article: Building on the Command Line.

Choosing the version of Visual Studio

On Windows there is a large choice of compilers including different versions of Visual Studio. CMake is able to generate makefiles for several of them. While it is possible to invoke CMake without specifying the specific compiler to target, this will result in CMake making the decision for you which can lead to surprising results. In particular 32 bit builds will be the default for Visual Studio and that may not be what you want.

To get a list of all the compilers supported you can run cmake -help. You should see something similar to the output below. I have only listed the Visual Studio entries as the complete list is quite long. Note that this gives you the list of generators supported by CMake on your platform but generating the makefiles will actually only work if the selected compiler is actually installed on your machine.

 Console output
Generators
The following generators are available on this platform:
  Visual Studio 15 2017 [arch] = Generates Visual Studio 2017 project files.
                                 Optional [arch] can be "Win64" or "ARM".
  Visual Studio 14 2015 [arch] = Generates Visual Studio 2015 project files.
                                 Optional [arch] can be "Win64" or "ARM".
  Visual Studio 12 2013 [arch] = Generates Visual Studio 2013 project files.
                                 Optional [arch] can be "Win64" or "ARM".
  Visual Studio 11 2012 [arch] = Generates Visual Studio 2012 project files.
                                 Optional [arch] can be "Win64" or "ARM".
  Visual Studio 10 2010 [arch] = Generates Visual Studio 2010 project files.
                                 Optional [arch] can be "Win64" or "IA64".
  Visual Studio 9 2008 [arch]  = Generates Visual Studio 2008 project files.
                                 Optional [arch] can be "Win64" or "IA64".
  Visual Studio 8 2005 [arch]  = Generates Visual Studio 2005 project files.
                                 Optional [arch] can be "Win64".
  Visual Studio 7 .NET 2003    = Deprecated.  Generates Visual Studio .NET
                                 2003 project files.

You pass in the desired generator by using the -G option e.g. cmake . -G "Visual Studio 15 2017 Win64".

Generating the project

Now that we have highlighted two potential issues to be aware of we are ready to generate the project.

It is recommended to create a build directory and to execute cmake in that directory rather than in the same directory as the one where CMakeLists.txt resides. This is because CMake generate several files that are best kept separate from the actual source code.

In my case I created a subdirectory called build and I will build from there. I also have Visual Studio 14 2015 installed and I prefer to build a 64-bit executable. I will therefore execute the following command: cmake .. -G "Visual Studio 14 2015 Win64".

References