CMake 工具链定位

CMake 的定位是“生成构建系统的配置工具”。它通常不直接编译源码，而是读取 CMakeLists.txt，生成 Makefile、Ninja 文件、Visual Studio 工程等，再由后端执行真正构建。

CMakeLists.txt
  -> cmake configure
  -> Makefile / build.ninja / .sln
  -> make / ninja / MSBuild
  -> 编译器
  -> 产物

CMake 生成什么

生成器	生成内容	常见命令
Unix Makefiles	Makefile	cmake -S . -B build -G "Unix Makefiles"
Ninja	build.ninja	cmake -S . -B build -G Ninja
Visual Studio	.sln、.vcxproj	cmake -S . -B build -G "Visual Studio 17 2022"

各阶段做什么

阶段	命令	作用
configure	cmake -S . -B build	读取 CMakeLists.txt，检查编译器和依赖，生成构建文件
build	cmake --build build	调用后端构建，例如 Ninja、Make、MSBuild
install	cmake --install build --prefix out	按安装规则复制头文件、库、可执行文件
test	ctest --test-dir build	运行 CMake/CTest 注册的测试

build 目录到底包含什么

常见内容：

文件/目录	作用
CMakeCache.txt	配置缓存，例如编译器、路径、选项
CMakeFiles/	CMake 内部文件
build.ninja 或 Makefile	后端构建文件
.o、.obj	中间目标文件
可执行文件/库文件	构建产物
Testing/	CTest 测试记录

build 目录可以删除。删除后重新执行：

cmake -S . -B build
cmake --build build

够用的 CMakeLists 示例

目录结构：

hello-cmake-toolchain/
├── CMakeLists.txt
├── include/
│   └── hello.h
└── src/
    ├── hello.cpp
    └── main.cpp

CMakeLists.txt：

cmake_minimum_required(VERSION 3.20)
 
project(HelloToolchain LANGUAGES CXX)
 
add_library(hello_lib
    src/hello.cpp
)
 
target_include_directories(hello_lib
    PUBLIC
        ${CMAKE_CURRENT_SOURCE_DIR}/include
)
 
target_compile_features(hello_lib
    PUBLIC
        cxx_std_17
)
 
add_executable(hello
    src/main.cpp
)
 
target_link_libraries(hello
    PRIVATE
        hello_lib
)
 
install(TARGETS hello hello_lib)
install(DIRECTORY include/ DESTINATION include)

include/hello.h：

#pragma once
 
void say_hello();

src/hello.cpp：

#include "hello.h"
#include <iostream>
 
void say_hello()
{
    std::cout << "Hello CMake toolchain" << std::endl;
}

src/main.cpp：

#include "hello.h"
 
int main()
{
    say_hello();
    return 0;
}

配置、构建、安装、测试：

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build
cmake --install build --prefix install
ctest --test-dir build

核心命令自查表

命令	作用
cmake -S . -B build	配置项目
cmake -S . -B build -G Ninja	用 Ninja 作为后端
cmake --build build	构建项目
cmake --build build --target hello	构建指定目标
cmake --build build --parallel 8	并行构建
cmake --install build --prefix out	安装到 out
ctest --test-dir build	运行测试
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release	单配置生成器下设置 Release

常见错误

现象	原因	处理
改了生成器后报错	同一个 build 目录混用了生成器	删除 build 或换新目录
找不到编译器	环境没配置	确认 g++、clang++、cl 可用
CMAKE_BUILD_TYPE 没效果	Visual Studio 是多配置生成器	构建时用 --config Debug
找不到库	没接入包管理器或 find_package 失败	检查 vcpkg/Conan toolchain 和包名

注意事项

• 修改源码后通常只需要 cmake --build build。
• 修改 CMakeLists.txt 后，CMake 通常会自动重新配置；出问题时手动执行 configure。
• 不要把生成的 build.ninja、Makefile 当作主要维护对象。