/flags/cmake/cmake-build-target
cmake --build build --target NAME: build only one target
- tool
- CMake
- command
- cmake --build
- flag
- -t, --target <tgt>...
- default
- the all target (everything not excluded with EXCLUDE_FROM_ALL)
- since
- CMake 3.15 (several targets and the -t short form)
cmake --build build --target app builds only the target named app (and whatever it depends on) instead of the default all target. The same option runs utility targets: --target clean deletes built files, --target install installs, --target test runs CTest with Makefile and Ninja generators. Since CMake 3.15 you can pass several names after one --target, and -t is the short form. Target names come from add_executable, add_library and add_custom_target in CMakeLists.txt.
One target, several targets, unknown target
The example uses CMake 4.4.4 and Ninja 1.13.0 from PyPI through uv. Two custom targets stand in for real executables, so no compiler is needed:
cat > CMakeLists.txt <<'EOF'
cmake_minimum_required(VERSION 3.20)
project(demo NONE)
add_custom_target(app COMMAND ${CMAKE_COMMAND} -E echo "building app" COMMENT "app")
add_custom_target(docs COMMAND ${CMAKE_COMMAND} -E echo "building docs" COMMENT "docs")
EOF
cmake() { uv run -q --no-project --python 3.13 --with cmake==4.4.4 --with ninja==1.13.0 cmake "$@"; }
cmake -S . -B build -G Ninja > /dev/null
echo "--- --target app"; cmake --build build --target app
echo "--- -t app docs -j 1"; cmake --build build -t app docs -j 1
echo "--- --target nope"; cmake --build build --target nope; echo "exit: $?"Output
--- --target app [1/1] app building app --- -t app docs -j 1 [1/2] app building app [2/2] docs building docs --- --target nope ninja: error: unknown target 'nope', did you mean 'app'? exit: 1
Custom targets are not part of all unless they are declared with ALL, so cmake --build build alone would build nothing here. A name that does not exist is reported by the build tool, not by CMake: Ninja prints unknown target 'nope' with a suggestion and the command fails. Makefile generators print No rule to make target 'nope' instead.
Useful built-in targets
| Target | Effect | Generators |
|---|---|---|
| all | Default: everything not marked EXCLUDE_FROM_ALL | Makefiles, Ninja (ALL_BUILD in Visual Studio) |
| clean | Delete the build outputs, keep the cache | All |
| install | Build all, then install to CMAKE_INSTALL_PREFIX | All (INSTALL in Visual Studio) |
| test | Run CTest (needs enable_testing) | Makefiles, Ninja (RUN_TESTS in Visual Studio) |
| help | List the targets | Makefiles, Ninja |
| edit_cache, rebuild_cache | Open the cache editor, re-run the configure step | Makefiles, Ninja |
For installing, cmake --install build is the newer, generator-independent alternative to --target install; see install prefix. For cleaning, see clean a CMake build.
Related cmake --build options
| Option | Effect |
|---|---|
| --config Release | Configuration to build with multi-config generators (Visual Studio, Xcode, Ninja Multi-Config) |
| -j N, --parallel N | Number of parallel jobs passed to the build tool |
| --clean-first | Build the clean target first, then the requested targets |
| -v, --verbose | Print the full commands the build tool runs |
| -- ARGS | Pass the remaining arguments straight to make, ninja or MSBuild |
Pitfalls
- Visual Studio names. With Visual Studio generators the targets are projects in the solution;
alldoes not exist there (useALL_BUILD), and--targetis case-sensitive like the project names. - Directory names are not targets.
--target src/appdoes not work; use the target name given toadd_executable. Run--target helpwhen unsure. - Configure first.
--targetonly works on a configured build directory; the -S and -B options create it.
FAQ
How do I list the targets of a CMake build directory?
Run cmake --build build --target help. With Makefile and Ninja generators it prints every target the build knows, including the utility targets all, clean, install, edit_cache and rebuild_cache.
Can I build several targets in one command?
Yes, since CMake 3.15: cmake --build build --target app tests, or cmake --build build -t app tests. Older versions accept only one --target value.
Does --target also build the dependencies?
Yes. The build tool builds the target and everything it depends on, for example the libraries an executable links to, but nothing else.