CMake 从入门到精通：完整教程 / 第 2 章：安装与环境配置

第 2 章：安装与环境配置

2.1 安装方法

2.1.1 Linux 安装

Ubuntu / Debian

# 通过包管理器安装（版本可能较旧）
sudo apt update
sudo apt install cmake

# 验证安装
cmake --version

# 安装图形界面（可选）
sudo apt install cmake-curses-gui    # ccmake（终端界面）
sudo apt install cmake-gui           # GUI 界面

⚠️ 注意：apt 仓库中的 CMake 版本通常较旧。如果需要最新版本，推荐使用以下方式。

安装最新版本（推荐）

# 方式一：使用官方脚本
wget https://github.com/Kitware/CMake/releases/download/v3.28.3/cmake-3.28.3-linux-x86_64.sh
chmod +x cmake-3.28.3-linux-x86_64.sh
sudo ./cmake-3.28.3-linux-x86_64.sh --prefix=/usr/local --skip-license

# 方式二：使用 pip 安装
pip install cmake --upgrade

# 方式三：使用 Snap
sudo snap install cmake --classic

# 方式四：使用 Homebrew（Linux 上也可用）
brew install cmake

CentOS / RHEL / Fedora

# Fedora
sudo dnf install cmake

# CentOS 8+ / RHEL 8+
sudo dnf install cmake

# CentOS 7（旧版本需要 SCL）
sudo yum install centos-release-scl
sudo yum install devtoolset-9
scl enable devtoolset-9 bash

2.1.2 macOS 安装

# 方式一：Homebrew（推荐）
brew install cmake

# 安装指定版本
brew install cmake@3.27

# 方式二：直接下载
# 从 https://cmake.org/download/ 下载 .dmg 安装包

# 方式三：MacPorts
sudo port install cmake

2.1.3 Windows 安装

# 方式一：Chocolatey
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'

# 方式二：Scoop
scoop install cmake

# 方式三：winget
winget install Kitware.CMake

# 方式四：官网下载安装包
# https://cmake.org/download/
# 下载 .msi 安装包，安装时勾选 "Add CMake to the system PATH"

💡 提示：Windows 上建议同时安装 Visual Studio 或 MinGW-w64 作为编译工具链。

2.1.4 安装方式对比

安装方式	优点	缺点	适用平台
系统包管理器	简单、自动更新	版本可能较旧	Linux
pip install cmake	跨平台、版本可控	与 Python 绑定	全平台
官方安装包	版本最新、包含 GUI	需手动更新	全平台
Homebrew	简单、版本较新	需要 Homebrew	macOS/Linux
Snap	自动更新	占用空间较大	Linux
vcpkg	与项目绑定	额外依赖	全平台

2.2 版本管理

2.2.1 检查版本

# 查看当前版本
cmake --version
# 输出示例：cmake version 3.28.3

# 查看详细信息
cmake --system-information  # 输出大量系统和配置信息

2.2.2 项目中的版本约束

在 CMakeLists.txt 中声明最低版本要求：

# 必须放在文件的第一行（在 project() 之前）
cmake_minimum_required(VERSION 3.16)

# 同时指定最低和最高策略版本（推荐）
cmake_minimum_required(VERSION 3.16...3.28)

策略版本的含义：

# 3.16 是最低要求版本
# 3.28 是策略版本 — 告诉 CMake 使用 3.28 的策略行为
cmake_minimum_required(VERSION 3.16...3.28)

# 等价于：
cmake_minimum_required(VERSION 3.16)
if(POLICY CMP0144)
    cmake_policy(SET CMP0144 NEW)
endif()

2.2.3 多版本共存

# 使用 update-alternatives 管理多版本（Linux）
sudo update-alternatives --install /usr/bin/cmake cmake /usr/local/bin/cmake 100
sudo update-alternatives --config cmake

# 使用 CMake 工具链文件指定版本
# toolchain.cmake
set(CMAKE_VERSION_MINIMUM "3.20")

2.2.4 版本选择建议

项目类型	建议最低版本	理由
新项目	3.16+	Ubuntu 20.04 自带版本
使用 FetchContent	3.11+	FetchContent 引入版本
使用 Presets	3.19+	CMakePresets.json 支持
使用 C++20 模块	3.28+	模块支持成熟
最大兼容性	3.10+	Ubuntu 18.04 自带版本

2.3 CMake GUI

2.3.1 命令行 GUI（ccmake）

ccmake 是一个基于 ncurses 的终端图形界面：

mkdir build && cd build
ccmake ..

操作方式：

↑ / ↓：导航
Enter：编辑变量
c：配置（Configure）
g：生成（Generate）
q：退出
t：切换高级选项显示

2.3.2 图形 GUI（cmake-gui）

# 启动图形界面
cmake-gui

使用步骤：

设置源码路径（“Where is the source code”）
设置构建路径（“Where to build the binaries”）
点击 “Configure” 选择生成器
修改红色高亮的缓存变量
点击 “Generate” 生成构建文件

2.3.3 命令行配置（推荐）

# 基本配置
cmake -S . -B build

# 指定生成器
cmake -S . -B build -G Ninja

# 设置变量
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON

# 查看所有缓存变量
cmake -S . -B build -L     # 用户变量
cmake -S . -B build -LA    # 包含高级变量

2.4 预设（Presets）简介

CMake 3.19+ 支持使用 JSON 文件定义配置预设：

{
    "version": 6,
    "configurePresets": [
        {
            "name": "default",
            "displayName": "Default Config",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Debug"
            }
        },
        {
            "name": "release",
            "displayName": "Release Config",
            "inherits": "default",
            "binaryDir": "${sourceDir}/build-release",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Release"
            }
        }
    ],
    "buildPresets": [
        {
            "name": "default",
            "configurePreset": "default"
        },
        {
            "name": "release",
            "configurePreset": "release"
        }
    ]
}

使用方式：

# 列出可用预设
cmake --list-presets

# 使用预设配置
cmake --preset default

# 使用预设构建
cmake --build --preset default

💡 提示：预设文件是团队协作的最佳实践，详见第 12 章。

2.5 IDE 集成

2.5.1 Visual Studio Code

推荐扩展：

CMake Tools（Microsoft）：CMake 项目管理核心
CMake Language Support：语法高亮
C/C++（Microsoft）：IntelliSense

// .vscode/settings.json
{
    "cmake.configureOnOpen": true,
    "cmake.generator": "Ninja",
    "cmake.buildDirectory": "${workspaceFolder}/build",
    "cmake.configureSettings": {
        "CMAKE_BUILD_TYPE": "Debug",
        "BUILD_TESTS": "ON"
    }
}

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug",
            "type": "cppdbg",
            "request": "launch",
            "program": "${command:cmake.launchTargetPath}",
            "args": [],
            "cwd": "${workspaceFolder}"
        }
    ]
}

2.5.2 CLion（JetBrains）

CLion 原生支持 CMake：

CLion 设置：
├── File > Settings > Build > CMake
│   ├── CMake options: -DCMAKE_BUILD_TYPE=Debug
│   ├── Build directory: cmake-build-debug
│   └── Generator: 让 CMake 自动选择（推荐 Ninja）
└── 工具栏按钮：Build / Run / Debug

2.5.3 Visual Studio

Visual Studio 2019+ 原生支持 CMake 项目：

// CMakeSettings.json（VS 专用配置，已被 CMakePresets.json 取代）
{
    "configurations": [
        {
            "name": "x64-Debug",
            "generator": "Ninja",
            "configurationType": "Debug",
            "buildRoot": "${projectDir}\\build\\${name}",
            "cmakeCommandArgs": "",
            "buildCommandArgs": "",
            "ctestCommandArgs": "",
            "inheritEnvironments": ["msvc_x64_x64"]
        }
    ]
}

💡 建议：使用 CMakePresets.json 替代 CMakeSettings.json，因为它跨 IDE 兼容。

2.5.4 Xcode（macOS）

# 生成 Xcode 项目
cmake -S . -B build -G Xcode

# 打开项目
open build/MyProject.xcodeproj

2.5.5 IDE 支持对比

IDE	原生支持	配置方式	推荐度
CLion	✅	内置 CMake 支持	⭐⭐⭐⭐⭐
VS Code	✅	CMake Tools 扩展	⭐⭐⭐⭐⭐
Visual Studio	✅	内置 + CMakePresets	⭐⭐⭐⭐
Xcode	⚠️	通过 `-G Xcode` 生成	⭐⭐⭐
Qt Creator	✅	内置 CMake 支持	⭐⭐⭐⭐
Vim/Neovim	⚠️	通过 LSP + cmake-language-server	⭐⭐⭐

2.6 常用命令行工具

CMake 安装后会提供以下工具：

工具	用途
`cmake`	主程序，用于配置和构建
`ccmake`	终端 GUI 配置工具
`cmake-gui`	图形界面配置工具
`ctest`	测试驱动程序
`cpack`	打包工具
`cmake-gui`	GUI 配置工具

# 查看工具路径
which cmake
which ctest
which cpack

2.7 业务场景：团队环境标准化

场景：统一团队的 CMake 版本

一个 8 人的 C++ 团队，成员使用不同的操作系统和 IDE：

方案一：使用 .cmake-version 文件

# .cmake-version（放在项目根目录）
3.28.3

# 检查脚本 check_cmake_version.sh
#!/bin/bash
REQUIRED=$(cat .cmake-version)
CURRENT=$(cmake --version | head -1 | grep -oP '\d+\.\d+\.\d+')
if [ "$REQUIRED" != "$CURRENT" ]; then
    echo "警告: CMake 版本不匹配"
    echo "  需要: $REQUIRED"
    echo "  当前: $CURRENT"
fi

方案二：使用 CMakePresets.json

{
    "version": 6,
    "cmakeMinimumRequired": {
        "major": 3,
        "minor": 28,
        "patch": 0
    },
    "configurePresets": [
        {
            "name": "default",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build"
        }
    ]
}

方案三：使用 Docker

# Dockerfile.build
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y cmake=3.28* g++ ninja-build
WORKDIR /project

2.8 常见问题

Q1: `cmake: command not found`

# 检查是否安装
which cmake

# 如果使用 pip 安装，确认 Python 路径在 PATH 中
export PATH="$HOME/.local/bin:$PATH"

Q2: 版本太旧，不支持某个特性

# 查看当前版本
cmake --version

# 如果需要新版本，用 pip 安装
pip install cmake==3.28.3

Q3: 多个 CMake 版本冲突

# 查看所有 cmake 路径
whereis cmake

# 使用完整路径指定
/usr/local/bin/cmake --version

# 或使用 update-alternatives（Linux）
sudo update-alternatives --config cmake

2.9 扩展阅读

上一章：第 1 章 — CMake 简介与背景 | 下一章：第 3 章 — 基础入门 →