AI Skills
cmake

cmake

热门

用于C/C++项目的CMake构建系统技能。在编写或重构CMakeLists.txt、配置外部构建、选择生成器（Ninja、Make、VS）、使用target_link_libraries管理目标和依赖、通过find_package或FetchContent集成外部包、启用sanitizers、设置交叉编译工具链文件或导出CMake包时使用。在有关CMakeLists.txt、cmake配置错误、目标属性、安装规则、CPack或CMake预设的查询时激活。

188Star
25Fork
更新于 2026/6/27
获取 Skill源代码

相关 Skills

plan-canvas24万homelab-vlan-segmentation24万backend-code-review15万
SKILL.md
只读
名称
cmake
描述

用于C/C++项目的CMake构建系统技能。在编写或重构CMakeLists.txt、配置外部构建、选择生成器（Ninja、Make、VS）、使用target_link_libraries管理目标和依赖、通过find_package或FetchContent集成外部包、启用sanitizers、设置交叉编译工具链文件或导出CMake包时使用。在有关CMakeLists.txt、cmake配置错误、目标属性、安装规则、CPack或CMake预设的查询时激活。

CMake

目的

指导代理使用现代（目标优先）CMake进行C/C++项目：外部构建、依赖管理、生成器选择以及与CI和IDE的集成。

触发条件

  • "如何为我的项目编写CMakeLists.txt？"
  • "如何使用CMake添加外部库？"
  • "CMake找不到我的包/库"
  • "如何在CMake中启用sanitizers？"
  • "如何使用CMake进行交叉编译？"
  • "如何使用CMake预设？"

工作流程

1. 现代CMake原则

  • 定义目标，而不是变量。使用target_*命令。
  • 使用PUBLIC/PRIVATE/INTERFACE控制属性传播。
  • 永远不要使用include_directories()或link_libraries()（旧式）。
  • 最低CMake版本：cmake_minimum_required(VERSION 3.20)以获得大多数功能。

2. 最小项目

cmake_minimum_required(VERSION 3.20)
project(MyApp VERSION 1.0 LANGUAGES C CXX)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(myapp
    src/main.c
    src/utils.c
)

target_include_directories(myapp PRIVATE include)
target_compile_options(myapp PRIVATE -Wall -Wextra)

3. 静态/共享库

# 静态库
add_library(mylib STATIC lib/foo.c lib/bar.c)
target_include_directories(mylib
    PUBLIC  include      # 消费者获得此包含路径
    PRIVATE src          # 只有mylib自身看到此路径
)

# 共享库
add_library(myshared SHARED lib/foo.c)
set_target_properties(myshared PROPERTIES
    VERSION   1.0.0
    SOVERSION 1
)

# 将可执行文件链接到库
add_executable(myapp src/main.c)
target_link_libraries(myapp PRIVATE mylib)

4. 配置和构建

# 外部构建（始终这样做）
cmake -S . -B build
cmake --build build

# 使用生成器
cmake -S . -B build -G Ninja
cmake --build build -- -j$(nproc)

# Debug构建
cmake -S . -B build-debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build-debug

# Release构建
cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release
cmake --build build-release

# 安装
cmake --install build --prefix /usr/local

构建类型：Debug、Release、RelWithDebInfo、MinSizeRel。

5. 外部依赖

find_package（系统安装的库）
find_package(OpenSSL REQUIRED)
target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto)

find_package(Threads REQUIRED)
target_link_libraries(myapp PRIVATE Threads::Threads)

find_package(ZLIB REQUIRED)
target_link_libraries(myapp PRIVATE ZLIB::ZLIB)
FetchContent（下载并构建依赖）
include(FetchContent)

FetchContent_Declare(
    googletest
    GIT_REPOSITORY https://github.com/google/googletest.git
    GIT_TAG        v1.14.0
)
FetchContent_MakeAvailable(googletest)

add_executable(mytest test/test_foo.cpp)
target_link_libraries(mytest PRIVATE GTest::gtest_main mylib)
pkg-config 回退
find_package(PkgConfig REQUIRED)
pkg_check_modules(LIBFOO REQUIRED libfoo>=1.2)
target_link_libraries(myapp PRIVATE ${LIBFOO_LIBRARIES})
target_include_directories(myapp PRIVATE ${LIBFOO_INCLUDE_DIRS})

6. 按配置的编译器选项

target_compile_options(myapp PRIVATE
    $<$<CONFIG:Debug>:-g -Og -fsanitize=address>
    $<$<CONFIG:Release>:-O2 -DNDEBUG>
    $<$<CXX_COMPILER_ID:GNU>:-fanalyzer>
    $<$<CXX_COMPILER_ID:Clang>:-Weverything>
)

target_link_options(myapp PRIVATE
    $<$<CONFIG:Debug>:-fsanitize=address>
)

生成器表达式：$<condition:value>在构建时求值。

7. 启用sanitizers

option(ENABLE_ASAN "Enable AddressSanitizer" OFF)

if(ENABLE_ASAN)
    target_compile_options(myapp PRIVATE -fsanitize=address -fno-omit-frame-pointer -g -O1)
    target_link_options(myapp PRIVATE -fsanitize=address)
endif()

构建：cmake -DENABLE_ASAN=ON -S . -B build-asan && cmake --build build-asan

8. 交叉编译工具链文件

# toolchain-aarch64.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER   aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
set(CMAKE_SYSROOT /opt/aarch64-sysroot)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

cmake -S . -B build-arm -DCMAKE_TOOLCHAIN_FILE=toolchain-aarch64.cmake

9. CMake预设（CMake 3.20+）

{
  "version": 6,
  "configurePresets": [
    {
      "name": "release",
      "displayName": "Release",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/release",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release",
        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
      }
    },
    {
      "name": "debug",
      "displayName": "Debug",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/debug",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "ENABLE_ASAN": "ON"
      }
    }
  ],
  "buildPresets": [
    { "name": "release", "configurePreset": "release" },
    { "name": "debug",   "configurePreset": "debug" }
  ]
}

cmake --preset release
cmake --build --preset release

10. 常见错误

错误 原因 修复
Could not find package Foo 包未安装或前缀错误 安装开发包；设置CMAKE_PREFIX_PATH
No CMAKE_CXX_COMPILER 未找到C++编译器 安装g++/clang++；检查PATH
target_link_libraries called with wrong number of arguments 缺少PUBLIC/PRIVATE/INTERFACE 添加关键字
Cannot find source file 拼写错误或相对路径错误 检查相对于CMakeLists.txt的路径
generator expression错误 $<>语法错误 查看CMake文档了解表达式名称

完整的CMakeLists.txt模板，请参阅references/templates.md。

相关技能

  • 使用skills/build-systems/ninja了解Ninja生成器详情
  • 使用skills/build-systems/make了解Make生成器
  • 使用skills/compilers/cross-gcc进行交叉编译工具链设置
  • 使用skills/runtimes/sanitizers了解sanitizer集成详情