Set up C++ with CMake on Windows, macOS and Linux
Install a C++20 compiler and CMake, then configure, build and test a project from the command line. The same three commands on every operating system.
To build modern C++ projects you need two things: a C++20 compiler and CMake. Any editor works on top of that. This guide gets you from nothing to a passing test on Windows, macOS or Linux.
1. Install the tools
Windows. Install Visual Studio Community with the Desktop development with C++ workload. It includes the MSVC compiler and CMake. Use the Developer PowerShell for VS so the tools are on your path.
macOS. Install the command line tools with xcode-select --install (that gives you Clang), then
CMake with Homebrew: brew install cmake.
Linux (Ubuntu or Debian). sudo apt install build-essential cmake installs GCC and CMake.
Check both:
cmake --version # 3.20 or newer
g++ --version # GCC 11+ (or clang++ 14+, or MSVC 19.30+)2. The three commands
Every CMake project builds the same way, from the folder that contains CMakeLists.txt:
cmake -S . -B build # configure: generate build files into ./build
cmake --build build # compile
ctest --test-dir build # run the tests-S . is the source folder, -B build the build folder. Keeping build output in its own folder
means you can delete it any time and start clean.
On Windows with Visual Studio, add -C Debug to ctest, because Visual Studio builds several
configurations side by side.
3. A minimal CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(frostline LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_library(frost src/readings.cpp) # your code, as a library
target_include_directories(frost PUBLIC include)
enable_testing()
add_executable(tests tests/readings_test.cpp)
target_link_libraries(tests PRIVATE frost)
add_test(NAME tests COMMAND tests)Putting your code in a library and linking both the tests and any program against it is a good habit: tests exercise exactly the code you ship.
4. Turn on warnings
Warnings catch real bugs. Add them right after project():
if(MSVC)
add_compile_options(/W4 /permissive-)
else()
add_compile_options(-Wall -Wextra -Wpedantic)
endif()Common problems
- "No CMAKE_CXX_COMPILER could be found": the compiler isn't installed or not on the path. On Windows, use the Developer PowerShell.
- Changes don't seem to compile: run
cmake --build buildagain; configure only needs repeating whenCMakeLists.txtchanges. - Strange errors after switching compilers: delete the
buildfolder and configure again.
Every Devventura C++ starter ships with this setup ready to go, plus a BUILDING.md with these steps.
Next: unit testing in C++.
Questions and answers
- Do I need Visual Studio to write C++ on Windows?
- You need a compiler. The free Visual Studio Community (with the 'Desktop development with C++' workload) is the simplest way to get MSVC and CMake together. MSYS2 with GCC works too.
- What does CMake actually do?
- CMake describes your project once (sources, libraries, tests) and generates the native build files for your platform: Makefiles or Ninja files on Linux and macOS, a Visual Studio solution on Windows.
Practise it in a project
These projects put this guide to work, with tickets, tests and code review.
Hopwire
Link shortener for Hopwire
Build the core of Hopwire's link shortener: turn long campaign URLs into short codes and back again, then give the support team a console to use it.
- hash maps
- number bases
- input validation
- streams
- unit tests
Frostline Cold Storage
Sensor readings summary for Frostline
Turn the raw export of Frostline's freezer sensors into a summary per freezer, and flag readings outside the safe range.
- parsing text
- structs
- std::map
- floating point
Read next
- How to escape tutorial hell and start building on your own
Stuck watching tutorials but unable to build anything alone? Why it happens, and a step-by-step way out using small projects with tests and a clear definition of done.