CodeTheRobot
Course outline

C++ Intermediate · Lesson 24 of 27

Organizing multi-file projects

Folder layout, add_subdirectory, tests and a public include tree.

Estimated time · 60–90 min

Learning goals

What you will understand

  • Explain organizing multi-file projects 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

Larger projects use one CMakeLists.txt per folder and add_subdirectory to pull them together: src/ for libraries, apps/ for executables and tests/ for tests. Each library owns its own headers under include/<name>/, so users write #include <name/header.hpp>.

Enable tests with enable_testing() and add_test(), then run them with ctest. A build that anyone can start with three commands is the goal, and it is exactly how a colcon workspace expects packages to behave.

Guided lesson

Work through these steps

  1. 1.

    Read the organizing multi-file projects 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)
# Top-level file: required version.
project(robot_suite LANGUAGES CXX)
# The whole suite is one project.
set(CMAKE_CXX_STANDARD 17)
# One standard for every subfolder.
enable_testing()
# Turn on ctest support for this build.
add_subdirectory(src)
# Read src/CMakeLists.txt, which defines the libraries.
add_subdirectory(apps)
# Read apps/CMakeLists.txt, which defines executables.
add_subdirectory(tests)
# Read tests/CMakeLists.txt, which defines the test programs.
add_test(NAME math_tests COMMAND math_tests)
# Register the test executable so ctest can run it (this line lives in tests/CMakeLists.txt).

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 Organizing multi-file projects. Expected result: 100% tests passed, 0 tests failed out of 1

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

# Top-level CMakeLists.txt  (folders: src/, apps/, tests/, each with its own CMakeLists.txt)
cmake_minimum_required(VERSION 3.16)
project(robot_suite LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
# TODO: turn on testing and pull in the three subfolders
# tests/CMakeLists.txt would contain:
#   add_executable(math_tests math_tests.cpp)
#   add_test(NAME math_tests COMMAND math_tests)
# Run: cmake -S . -B build && cmake --build build && ctest --test-dir build

Expected output

100% tests passed, 0 tests failed out of 1
Stuck? Show the full solution (try it yourself first)
# Top-level CMakeLists.txt  (folders: src/, apps/, tests/, each with its own CMakeLists.txt)
cmake_minimum_required(VERSION 3.16)
project(robot_suite LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
enable_testing()
add_subdirectory(src)
add_subdirectory(apps)
add_subdirectory(tests)
# tests/CMakeLists.txt would contain:
#   add_executable(math_tests math_tests.cpp)
#   add_test(NAME math_tests COMMAND math_tests)
# Run: cmake -S . -B build && cmake --build build && ctest --test-dir 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 src/, apps/ and tests/ with one library, one app and one test that checks clamp(). Build from an empty directory and run ctest --output-on-failure. Break the test on purpose and confirm ctest reports 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.