CodeTheRobot
Course outline

C++ Intermediate · Lesson 21 of 27

Basic CMakeLists

cmake_minimum_required, project, add_executable and an out-of-source build.

Estimated time · 45–75 min

Learning goals

What you will understand

  • Explain basic cmakelists in your own words
  • Use it in a small robotics example
  • Verify the result instead of assuming it worked

Understand the idea first

The mental model

CMake does not compile code itself: it reads CMakeLists.txt and generates build files for Make or Ninja. Always build 'out of source' into a separate build/ folder so generated files never mix with your code.

A minimal file names the CMake version, the project, the C++ standard, and one executable. ROS 2's ament_cmake is a set of extra CMake helpers on top of this same syntax.

Guided lesson

Work through these steps

  1. 1.

    Read the basic cmakelists example and identify what each line owns or changes.

  2. 2.

    Create a small source file, compile with -std=c++17 and warnings enabled, and run it.

  3. 3.

    Change one input, predict the result before running, then compare the output.

  4. 4.

    Record one compiler or runtime error and explain the correction in your own words.

Worked example

Read it before you run it

cmake_minimum_required(VERSION 3.16)
# Require CMake 3.16 or newer; it fixes the rules the file is read with.
project(robot_app LANGUAGES CXX)
# Name the project and enable the C++ compiler.
set(CMAKE_CXX_STANDARD 17)
# Use the C++17 language standard.
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# Fail instead of silently falling back to an older standard.
set(CMAKE_CXX_EXTENSIONS OFF)
# Use -std=c++17, not the GNU extension -std=gnu++17.
add_executable(robot_app src/main.cpp)
# Build an executable named robot_app from src/main.cpp.
# Build: cmake -S . -B build && cmake --build build && ./build/robot_app
# Configure into build/, compile, and run (in a shell, not in this file).

What the example is doing

  1. 1.Read declarations from right to left: identify each value's type, name, and initial value.
  2. 2.Follow the data through each expression before considering syntax shortcuts.
  3. 3.Compile with warnings enabled; a clean build is part of the result, not an optional polish step.

Watch it run · Build and run

See what this code does

The terminal types this lesson's practice solution and runs it. The scene shows the kind of robot behaviour that code drives. It plays by itself and loops.

sourcecompilerprogramBUILD AND RUN

Demo for Basic CMakeLists. Expected result: Built target robot_app

Practice code

Now type it yourself

Copy the starter into the file named in its first line and replace every TODO. Then configure and build: cmake -S . -B build && cmake --build build

# CMakeLists.txt  (next to src/main.cpp, which contains: int main() { return 0; })
cmake_minimum_required(VERSION 3.16)
project(robot_app LANGUAGES CXX)
# TODO: require C++17 without compiler extensions (three set() lines)
# TODO: build an executable named robot_app from src/main.cpp
# Build: cmake -S . -B build && cmake --build build

Expected output

Built target robot_app
Stuck? Show the full solution (try it yourself first)
# CMakeLists.txt  (next to src/main.cpp, which contains: int main() { return 0; })
cmake_minimum_required(VERSION 3.16)
project(robot_app LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
add_executable(robot_app src/main.cpp)
# Build: cmake -S . -B build && cmake --build build

Expected result

How you know it worked

  • After adding the shown fragment to the guided exercise with its listed headers and surrounding program, the finished program builds with -Wall -Wextra -Wpedantic.
  • Changing the stated input produces the result you predicted.

Practical exercise

Apply the lesson

Create a project with CMakeLists.txt and src/main.cpp. Configure and build it out of source, run it, delete build/ and rebuild. Then print CMAKE_CXX_STANDARD with message() to see it.

Before you continue

  • The program builds with -std=c++17 and no warnings
  • You can explain the key rule without reading the example
  • The normal and edge cases both have recorded results

If something goes wrong

The compiler reports that a name or type is unknown.

Start at the first error. Check spelling, required #include lines, and whether the declaration appears before use.

The program runs but the value is wrong.

Print the inputs and intermediate values, then check conversions, units, and collection order.