Configure, build, run

You just ran two commands and got a working program. Now let us understand exactly what happened, because every CMake workflow for the rest of your career is this same cycle.

The three steps

# 1. CONFIGURE. Read CMakeLists.txt and generate build files.
cmake -S . -B build

# 2. BUILD. Compile and link using the generated build files.
cmake --build build

# 3. RUN. Execute your program.
./build/hello

Step 1. Configure

cmake -S . -B build means:

• -S . is the source directory, the current folder where CMakeLists.txt lives.
• -B build is the build directory.

CMake reads your CMakeLists.txt, checks that your tools exist, and writes the actual build files. After this step, the build/ folder contains files like build.ninja (Ninja) or Makefile (Make), plus a file called CMakeCache.txt.

Why

The -S and -B pair keeps your build files completely separate from your source. This out-of-source build is the standard. Your source folder stays clean, and you can have several build folders (build-debug/, build-release/) for the same source. Old tutorials used cmake .. Do not.

Step 2. Build

cmake --build build is the portable way to say “compile my project”. It works no matter which generator is underneath (Ninja, Make, Visual Studio). It also understands targets:

cmake --build build --target hello   # build only the "hello" target

Step 3. Run

Not CMake’s job. Just run the produced binary.

What CMake creates in build/

build/
├── CMakeCache.txt      # your options, remembered between runs
├── build.ninja         # the actual build files (Ninja here)
├── CMakeFiles/         # CMake's internal bookkeeping
└── hello               # your executable

Two files matter to you:

• CMakeCache.txt stores every option you set (lesson 16). It is why you do not re-type options every time.
• The build files are generated from your CMakeLists.txt and are regenerated automatically whenever it changes.

Note

Edit a source file and rebuild. CMake notices nothing special, it just recompiles. Edit CMakeLists.txt and the next build triggers a re-configure automatically, because CMake tracks its own files. You almost never need to re-run step 1 manually.

A clean rebuild

When something looks corrupted or a rename confuses the build system, delete the build folder and reconfigure from scratch:

rm -rf build
cmake -S . -B build
cmake --build build

This is always safe. Everything in build/ is generated from CMakeLists.txt.

Git hygiene

.gitignore
build/

Pitfall

Never commit build/. It is machine-specific and regenerated, and committing it causes exactly the kind of “works on my machine” bug you are trying to avoid. A one-line .gitignore fixes it forever.

Tip

In lesson 20 you will replace these two commands with a single one, cmake --preset dev. For now, remember this cycle. Presets are just shortcuts for it.

Read the docs

• cmake(1)
• --build option