A Basic Starting Point — CMake 4.0.3 Documentation (2025)

Goal¶

Understand how to create a simple CMake project.

Helpful Resources¶

• add_executable()

• cmake_minimum_required()

• project()

Files to Edit¶

• CMakeLists.txt

Getting Started¶

The source code for tutorial.cxx is provided in theHelp/guide/tutorial/Step1 directory and can be used to compute the squareroot of a number. This file does not need to be edited in this step.

In the same directory is a CMakeLists.txt file which you will complete.Start with TODO 1 and work through TODO 3.

Build and Run¶

Once TODO 1 through TODO 3 have been completed, we are ready to buildand run our project! First, run the cmake executable or thecmake-gui to configure the project and then build itwith your chosen build tool.

For example, from the command line we could navigate to theHelp/guide/tutorial directory of the CMake source code tree and create abuild directory:

mkdir Step1_build

Next, navigate to that build directory and runcmake to configure the project and generate a native buildsystem:

cd Step1_buildcmake ../Step1

Then call that build system to actually compile/link the project:

cmake --build .

For multi-config generators (e.g. Visual Studio), first navigate to theappropriate subdirectory, for example:

cd Debug

Finally, try to use the newly built Tutorial:

Tutorial 4294967296Tutorial 10Tutorial

Note: Depending on the shell, the correct syntax may be Tutorial,./Tutorial or .\Tutorial. For simplicity, the exercises will useTutorial throughout.

Solution¶

As mentioned above, a three line CMakeLists.txt is all that we need to getup and running. The first line is to use cmake_minimum_required() toset the CMake version as follows:

cmake_minimum_required(VERSION 3.10)

The next step to make a basic project is to use the project()command as follows to set the project name:

project(Tutorial)

The last command to call for a basic project isadd_executable(). We call it as follows:

add_executable(Tutorial tutorial.cxx)

Goal¶

Add a feature that requires C++11.

Helpful Resources¶

• CMAKE_CXX_STANDARD

• CMAKE_CXX_STANDARD_REQUIRED

• set()

Files to Edit¶

• CMakeLists.txt

• tutorial.cxx

Getting Started¶

Continue editing files in the Step1 directory. Start with TODO 4 andcomplete through TODO 6.

First, edit tutorial.cxx by adding a feature that requires C++11. Thenupdate CMakeLists.txt to require C++11.

Build and Run¶

Let's build our project again. Since we already created a build directory andran CMake for Exercise 1, we can skip to the build step:

cd Step1_buildcmake --build .

Now we can try to use the newly built Tutorial with same commands asbefore:

Tutorial 4294967296Tutorial 10Tutorial

Solution¶

We start by adding some C++11 features to our project by replacingatof with std::stod in tutorial.cxx. This looks likethe following:

 double const inputValue = std::stod(argv[1]);

To complete TODO 5, simply remove #include <cstdlib>.

We will need to explicitly state in the CMake code that it should use thecorrect flags. One way to enable support for a specific C++ standard in CMakeis by using the CMAKE_CXX_STANDARD variable. For this tutorial, setthe CMAKE_CXX_STANDARD variable in the CMakeLists.txt file to11 and CMAKE_CXX_STANDARD_REQUIRED to True. Make sure toadd the CMAKE_CXX_STANDARD declarations above the call toadd_executable().

set(CMAKE_CXX_STANDARD 11)set(CMAKE_CXX_STANDARD_REQUIRED True)

Goal¶

Define and report the project's version number.

Helpful Resources¶

• <PROJECT-NAME>_VERSION_MAJOR

• <PROJECT-NAME>_VERSION_MINOR

• configure_file()

• target_include_directories()

Files to Edit¶

• CMakeLists.txt

• tutorial.cxx

• TutorialConfig.h.in

Getting Started¶

Continue to edit files from Step1. Start on TODO 7 and complete throughTODO 12. In this exercise, we start by adding a project version number inCMakeLists.txt. In that same file, use configure_file() to copy agiven input file to an output file and substitute some variable values in theinput file content.

Next, create an input header file TutorialConfig.h.in defining versionnumbers which will accept variables passed from configure_file().

Finally, update tutorial.cxx to print out its version number.

Build and Run¶

Let's build our project again. As before, we already created a build directoryand ran CMake so we can skip to the build step:

cd Step1_buildcmake --build .

Verify that the version number is now reported when running the executablewithout any arguments.

Solution¶

In this exercise, we improve our executable by printing a version number.While we could do this exclusively in the source code, using CMakeLists.txtlets us maintain a single source of data for the version number.

First, we modify the CMakeLists.txt file to use theproject() command to set both the project name and version number.When the project() command is called, CMake definesTutorial_VERSION_MAJOR and Tutorial_VERSION_MINOR behind the scenes.

project(Tutorial VERSION 1.0)

Then we used configure_file() to copy the input file with thespecified CMake variables replaced:

configure_file(TutorialConfig.h.in TutorialConfig.h)

Since the configured file will be written into the project binarydirectory, we must add that directory to the list of paths to search forinclude files.

Note: Throughout this tutorial, we will refer to the project build andthe project binary directory interchangeably. These are the same and are notmeant to refer to a bin/ directory.

We used target_include_directories() to specifywhere the executable target should look for include files.

target_include_directories(Tutorial PUBLIC "${PROJECT_BINARY_DIR}" )

TutorialConfig.h.in is the input header file to be configured.When configure_file() is called from our CMakeLists.txt, thevalues for @Tutorial_VERSION_MAJOR@ and @Tutorial_VERSION_MINOR@ willbe replaced with the corresponding version numbers from the project inTutorialConfig.h.

// the configured options and settings for Tutorial#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@

Next, we need to modify tutorial.cxx to include the configured header file,TutorialConfig.h.

#include "TutorialConfig.h"

Finally, we print out the executable name and version number by updatingtutorial.cxx as follows:

 if (argc < 2) { // report version std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." << Tutorial_VERSION_MINOR << std::endl; std::cout << "Usage: " << argv[0] << " number" << std::endl; return 1; }