Step 1: A Basic Starting Point — CMake 3.24.2 Documentation

# Step 1: A Basic Starting Point

The most basic project is an executable built from source code files. For simple projects, a three line `CMakeLists.txt` file is all that is required. This will be the starting point for our tutorial. Create a `CMakeLists.txt` file in the `Step1` directory that looks like:

CMakeLists.txt

    cmake_minimum_required(VERSION 3.10)

    # set the project name
    project(Tutorial)

    # add the executable
    add_executable(Tutorial tutorial.cxx)

Note that this example uses lower case commands in the `CMakeLists.txt` file. Upper, lower, and mixed case commands are supported by CMake. The source code for `tutorial.cxx` is provided in the `Step1` directory and can be used to compute the square root of a number.

## Build and Run

That's all that is needed - we can build and run our project now! 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 the 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 .

Finally, try to use the newly built `Tutorial` with these commands:

    Tutorial 4294967296
    Tutorial 10
    Tutorial

## Adding a Version Number and Configured Header File

The first feature we will add is to provide our executable and project with a version number. While we could do this exclusively in the source code, using `CMakeLists.txt` provides more flexibility.

First, modify the `CMakeLists.txt` file to use the `project()` command to set the project name and version number.

CMakeLists.txt

    cmake_minimum_required(VERSION 3.10)

    # set the project name and version
    project(Tutorial VERSION 1.0)

Then, configure a header file to pass the version number to the source code:

CMakeLists.txt

    configure_file(TutorialConfig.h.in TutorialConfig.h)

Since the configured file will be written into the binary tree, we must add that directory to the list of paths to search for include files. Add the following lines to the end of the `CMakeLists.txt` file:

CMakeLists.txt

    target_include_directories(Tutorial PUBLIC
                               "${PROJECT_BINARY_DIR}"
                               )

Using your favorite editor, create `TutorialConfig.h.in` in the source directory with the following contents:

TutorialConfig.h.in

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

When CMake configures this header file the values for `@Tutorial_VERSION_MAJOR@` and `@Tutorial_VERSION_MINOR@` will be replaced.

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

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

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

## Specify the C++ Standard

Next let's add some C++11 features to our project by replacing `atof` with `std::stod` in `tutorial.cxx`. At the same time, remove `#include <cstdlib>`.

tutorial.cxx

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

We will need to explicitly state in the CMake code that it should use the correct flags. The easiest 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`.

CMakeLists.txt

    cmake_minimum_required(VERSION 3.10)

    # set the project name and version
    project(Tutorial VERSION 1.0)

    # specify the C++ standard
    set(CMAKE_CXX_STANDARD 11)
    set(CMAKE_CXX_STANDARD_REQUIRED True)

## Rebuild

Let's build our project again. We already created a build directory and ran CMake, so 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

Check that the version number is now reported when running the executable without any arguments.