Step 1: A Basic Starting Point — CMake 3.29.3 Documentation

# Step 1: A Basic Starting Point

Where do I start with CMake? This step will provide an introduction to some of CMake's basic syntax, commands, and variables. As these concepts are introduced, we will work through three exercises and create a simple CMake project.

Each exercise in this step will start with some background information. Then, a goal and list of helpful resources are provided. Each file in the `Files to Edit` section is in the `Step1` directory and contains one or more `TODO` comments. Each `TODO` represents a line or two of code to change or add. The `TODO` s are intended to be completed in numerical order, first complete `TODO 1` then `TODO 2`, etc. The `Getting Started` section will give some helpful hints and guide you through the exercise. Then the `Build and Run` section will walk step-by-step through how to build and test the exercise. Finally, at the end of each exercise the intended solution is discussed.

Also note that each step in the tutorial builds on the next. So, for example, the starting code for `Step2` is the complete solution to `Step1`.

## Exercise 1 - Building a Basic Project

The most basic CMake project is an executable built from a single source code file. For simple projects like this, a `CMakeLists.txt` file with three commands is all that is required.

Note: Although upper, lower and mixed case commands are supported by CMake, lower case commands are preferred and will be used throughout the tutorial.

Any project's top most CMakeLists.txt must start by specifying a minimum CMake version using the `cmake_minimum_required()` command. This establishes policy settings and ensures that the following CMake functions are run with a compatible version of CMake.

To start a project, we use the `project()` command to set the project name. This call is required with every project and should be called soon after `cmake_minimum_required()`. As we will see later, this command can also be used to specify other project level information such as the language or version number.

Finally, the `add_executable()` command tells CMake to create an executable using the specified source code files.

### 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 the `Help/guide/tutorial/Step1` directory and can be used to compute the square root 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 build and run our project! First, run the `cmake` executable or the `cmake-gui` to configure the project and then build it with your chosen build tool.

For example, from the command line we could navigate to the `Help/guide/tutorial` directory of the CMake source code tree and create a build directory:

    mkdir Step1_build

Next, navigate to that build directory and run `cmake` to configure the project and generate a native build system:

    cd Step1_build
    cmake ../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 the appropriate subdirectory, for example:

    cd Debug

Finally, try to use the newly built `Tutorial`:

    Tutorial 4294967296
    Tutorial 10
    Tutorial

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

### Solution

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

TODO 1: Click to show/hide answer
TODO 1: CMakeLists.txt

    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:

TODO 2: Click to show/hide answer
TODO 2: CMakeLists.txt

    project(Tutorial)

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

TODO 3: Click to show/hide answer
TODO 3: CMakeLists.txt

    add_executable(Tutorial tutorial.cxx)

## Exercise 2 - Specifying the C++ Standard

CMake has some special variables that are either created behind the scenes or have meaning to CMake when set by project code. Many of these variables start with `CMAKE_`. Avoid this naming convention when creating variables for your projects. Two of these special user settable variables are `CMAKE_CXX_STANDARD` and `CMAKE_CXX_STANDARD_REQUIRED`. These may be used together to specify the C++ standard needed to build the project.

### 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` and complete through `TODO 6`.

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

### Build and Run

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

    cd Step1_build
    cmake --build .

Now we can try to use the newly built `Tutorial` with same commands as before:

    Tutorial 4294967296
    Tutorial 10
    Tutorial

### Solution

We start by adding some C++11 features to our project by replacing `atof` with `std::stod` in `tutorial.cxx`. This looks like the following:

TODO 4: Click to show/hide answer
TODO 4: tutorial.cxx

      const double 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 the correct flags. One way to enable support for a specific C++ standard in CMake is by using the `CMAKE_CXX_STANDARD` variable. For this tutorial, set the `CMAKE_CXX_STANDARD` variable in the `CMakeLists.txt` file to `11` and `CMAKE_CXX_STANDARD_REQUIRED` to `True`. Make sure to add the `CMAKE_CXX_STANDARD` declarations above the call to `add_executable()`.

TODO 6: Click to show/hide answer
TODO 6: CMakeLists.txt

    set(CMAKE_CXX_STANDARD 11)
    set(CMAKE_CXX_STANDARD_REQUIRED True)

## Exercise 3 - Adding a Version Number and Configured Header File

Sometimes it may be useful to have a variable that is defined in your `CMakelists.txt` file also be available in your source code. In this case, we would like to print the project version.

One way to accomplish this is by using a configured header file. We create an input file with one or more variables to replace. These variables have special syntax which looks like `@VAR@`. Then, we use the `configure_file()` command to copy the input file to a given output file and replace these variables with the current value of `VAR` in the `CMakelists.txt` file.

While we could edit the version directly in the source code, using this feature is preferred since it creates a single source of truth and avoids duplication.

### 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`

### Getting Started

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

Next, create an input header file `TutorialConfig.h.in` defining version numbers 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 directory and ran CMake so we can skip to the build step:

    cd Step1_build
    cmake --build .

Verify that the version number is now reported when running the executable without 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.txt` lets us maintain a single source of data for the version number.

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

TODO 7: Click to show/hide answer
TODO 7: CMakeLists.txt

    project(Tutorial VERSION 1.0)

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

TODO 8: Click to show/hide answer
TODO 8: CMakeLists.txt

    configure_file(TutorialConfig.h.in TutorialConfig.h)

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

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

We used `target_include_directories()` to specify where the executable target should look for include files.

TODO 9: Click to show/hide answer
TODO 9: CMakeLists.txt

    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`, the values for `@Tutorial_VERSION_MAJOR@` and `@Tutorial_VERSION_MINOR@` will be replaced with the corresponding version numbers from the project in `TutorialConfig.h`.

TODO 10: Click to show/hide answer
TODO 10: TutorialConfig.h.in

    // 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`.

TODO 11: Click to show/hide answer
TODO 11: tutorial.cxx

    #include "TutorialConfig.h"

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

TODO 12: Click to show/hide answer
TODO 12 : tutorial.cxx

      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;
      }