CMake基础：CMakeLists.txt 文件结构和语法

十五年专注C++开发2025-05-25 13:08

目录

1.CMakeLists.txt基本结构

2.核心语法规则

3.关键命令详解

4.常用预定义变量

5.变量和缓存

6.变量作用域与传递

7.注意事项

1.CMakeLists.txt基本结构

CMakeLists.txt 是 CMake 构建系统的核心配置文件，采用命令式语法组织项目结构和编译流程。主要用于定义项目的构建规则、依赖关系、编译选项等。每个 CMake 项目通常都有一个或多个 CMakeLists.txt 文件。

一个完整的 CMakeLists.txt 通常包含以下部分：

cpp 复制代码 
# 1. CMake 最低版本要求
cmake_minimum_required(VERSION 3.10)

# 2. 项目信息
project(MyProject VERSION 1.0.0 LANGUAGES CXX)

# 3. 全局配置（可选）
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)  # 生成 compile_commands.json

# 4. 查找依赖（可选）
find_package(Threads REQUIRED)
find_package(Boost 1.70 COMPONENTS system REQUIRED)

# 5. 添加子目录（可选）
add_subdirectory(src)
add_subdirectory(tests)

# 6. 定义目标（可执行文件或库）
add_executable(myapp main.cpp)
add_library(mylib STATIC src/lib.cpp src/utils.cpp)

# 7. 配置目标属性
target_include_directories(mylib PUBLIC include)
target_link_libraries(myapp PRIVATE mylib Threads::Threads)
target_compile_definitions(myapp PRIVATE DEBUG_MODE=1)

# 8. 安装规则（可选）
install(TARGETS myapp DESTINATION bin)
install(FILES include/mylib.h DESTINATION include)

# 9. 测试配置（可选）
enable_testing()
add_test(NAME MyTest COMMAND myapp_test)

2.核心语法规则

1.命令格式

cpp 复制代码 
command(arg1 arg2 ...)  # 命令名不区分大小写，但参数区分
  • 命令和参数用空格或括号分隔。
  • 参数可用双引号括起（如包含空格时）：set(NAME "My Project")。

2.变量引用

cpp 复制代码 
set(SOURCE_FILES main.cpp src/foo.cpp)
add_executable(myapp ${SOURCE_FILES})  # 使用 ${} 引用变量
  • 变量作用域：当前目录及子目录，可用 PARENT_SCOPE 提升作用域。

3.注释

cpp 复制代码 
# 单行注释

4.条件语句

cpp 复制代码 
if(WIN32)
    set(PLATFORM_LIBS ws2_32)
else()
    set(PLATFORM_LIBS pthread)
endif()

target_link_libraries(myapp PRIVATE ${PLATFORM_LIBS})
  • 条件表达式：WIN32、APPLE、UNIX、DEFINED var、NOT、AND、OR 等。

5.循环

cpp 复制代码 
foreach(file IN LISTS source_files)
    message("Processing file: ${file}")
endforeach()

6.函数和宏

cpp 复制代码 
# 函数（有独立作用域）
function(print_info name)
    message("Project name: ${name}")
endfunction()

# 宏（直接替换）
macro(add_example name)
    add_executable(${name} examples/${name}.cpp)
endmacro()

print_info(${PROJECT_NAME})
add_example(example1)

3.关键命令详解

1.项目设置

  • cmake_minimum_required(VERSION <version>)：指定所需的最低 CMake 版本。
  • project(<name> [VERSION <ver>] [LANGUAGES <langs>])：定义项目名称、版本和支持的语言。

示例如下：

cpp 复制代码 
#1
cmake_minimum_required(VERSION 3.10)
#2
project(MyProject CXX)

2.目标定义

  • add_executable(<name> <sources>)：创建可执行文件。
  • add_library(<name> [STATIC|SHARED|MODULE] <sources>)：创建库（静态 / 共享 / 模块）。
  • add_custom_target(<name> [COMMAND <cmd>] [DEPENDS <deps>])：创建自定义目标（如构建脚本）。

示例代码：

cpp 复制代码 
#1
add_executable(MyExecutable main.cpp other_file.cpp)
#2
add_library(MyLibrary STATIC library.cpp)
#3
add_library(MyLibrary SHARED library.cpp)

3.依赖管理

  • find_package(<package> [REQUIRED] [VERSION <ver>])：查找并导入外部包。
  • add_subdirectory(<dir>)：添加子目录中的 CMakeLists.txt。
  • target_link_libraries(<target> <PRIVATE|PUBLIC|INTERFACE> <libs>)：链接库到目标。
复制代码 
include_directories(<dirs>...)

示例代码：

cpp 复制代码 
#1
find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Widgets Network)
find_package(Qt${QT_VERSION_MAJOR} CONFIG REQUIRED COMPONENTS Widgets Network)

#2
add_subdirectory(tutorial)

#3
target_link_libraries(QSimpleUpdater PUBLIC Qt${QT_VERSION_MAJOR}::Core Qt${QT_VERSION_MAJOR}::Widgets PRIVATE Qt${QT_VERSION_MAJOR}::Network)

#4
include_directories(${PROJECT_SOURCE_DIR}/include)

4.编译选项

  • target_include_directories(<target> <PRIVATE|PUBLIC|INTERFACE> <dirs>)：添加头文件搜索路径。
  • target_compile_definitions(<target> <PRIVATE|PUBLIC|INTERFACE> <defs>) ：添加编译定义（如 -DDEBUG）。
  • target_compile_options(<target> <PRIVATE|PUBLIC|INTERFACE> <options>) ：添加编译选项（如 -Wall）。

示例代码：

cpp 复制代码 
#1
target_include_directories(QSimpleUpdater PUBLIC include)

5.安装规则

cpp 复制代码 
install(TARGETS target1 [target2 ...]
        [RUNTIME DESTINATION dir]
        [LIBRARY DESTINATION dir]
        [ARCHIVE DESTINATION dir]
        [INCLUDES DESTINATION [dir ...]]
        [PRIVATE_HEADER DESTINATION dir]
        [PUBLIC_HEADER DESTINATION dir])

示例代码：

cpp 复制代码 
#1
install(TARGETS <targets>
        RUNTIME DESTINATION bin
        LIBRARY DESTINATION lib
        ARCHIVE DESTINATION lib/static)

install(FILES <files> DESTINATION include)
install(DIRECTORY <dir> DESTINATION share)

#2
install(TARGETS MyExecutable RUNTIME DESTINATION bin)

6.自定义命令 (add_custom_command 命令)

cpp 复制代码 
add_custom_command(
   TARGET target
   PRE_BUILD | PRE_LINK | POST_BUILD
   COMMAND command1 [ARGS] [WORKING_DIRECTORY dir]
   [COMMAND command2 [ARGS]]
   [DEPENDS [depend1 [depend2 ...]]]
   [COMMENT comment]
   [VERBATIM]
)

示例代码：

cpp 复制代码 
add_custom_command(
   TARGET MyExecutable POST_BUILD
   COMMAND ${CMAKE_COMMAND} -E echo "Build completed."
)

7.测试配置

cpp 复制代码 
enable_testing()
add_test(NAME <test_name> COMMAND <executable> <args>)
add_test(NAME <test_name> WORKING_DIRECTORY <dir> COMMAND <cmd>)

4.常用预定义变量

1. 项目信息

变量名 描述 示例值
PROJECT_NAME 当前项目名称 MyProject
PROJECT_VERSION 项目版本（通过 project() 设置） 1.2.3
PROJECT_SOURCE_DIR 当前项目的源目录 /path/to/myproject
PROJECT_BINARY_DIR 当前项目的构建目录 /path/to/myproject/build

2.路径相关

变量名 描述 示例值
CMAKE_SOURCE_DIR 顶级 CMakeLists.txt 所在目录 /path/to/myproject
CMAKE_BINARY_DIR 顶级构建目录 /path/to/myproject/build
CMAKE_CURRENT_SOURCE_DIR 当前 CMakeLists.txt 所在目录 /path/to/myproject/src
CMAKE_CURRENT_BINARY_DIR 当前构建目录 /path/to/myproject/build/src
CMAKE_INSTALL_PREFIX 安装路径前缀 /usr/local（默认）
LIBRARY_OUTPUT_PATH 库文件输出的默认路径 库路径不设置的话，默认放在BINARY_DIR下，即构建时执行cmake命令的目录下

3.构建配置

变量名 描述 示例值
CMAKE_BUILD_TYPE 构建类型 Debug, Release, RelWithDebInfo
CMAKE_C_COMPILER C 编译器路径 /usr/bin/gcc
CMAKE_CXX_COMPILER C++ 编译器路径 /usr/bin/g++
CMAKE_CXX_STANDARD C++ 标准版本 11, 14, 17, 20
CMAKE_GENERATOR 当前使用的生成器 Unix Makefiles, Ninja
CMAKE_C_STANDARD_REQUIRED * ON：若编译器不支持指定的 C 标准，CMake 会终止配置并报错。 * OFF（默认）：若编译器不支持，CMake 会尝试降级到兼容版本（可能导致意外行为）。 set(CMAKE_C_STANDARD 11) # 指定 C 语言标准为 C11 set(CMAKE_C_STANDARD_REQUIRED ON) # 强制要求此标准
CMAKE_CXX_STANDARD_REQUIRED * ON：若编译器不支持指定的 C++ 标准，CMake 会终止配置并报错。 * OFF（默认）：若编译器不支持，CMake 会尝试降级到兼容版本（可能导致意外行为）。 set(CMAKE_CXX_STANDARD 20) # 指定 C++ 标准为 C++20 set(CMAKE_CXX_STANDARD_REQUIRED ON) # 强制要求此标准
CMAKE_DEBUG_POSTFIX cpp 设置调试版本后缀 set(CMAKE_DEBUG_POSTFIX d)

4.系统信息

变量名 描述 示例值
CMAKE_SYSTEM_NAME 操作系统名称 Linux, Windows, Darwin
CMAKE_SYSTEM_VERSION 系统版本 10.0（Windows）
CMAKE_HOST_SYSTEM_PROCESSOR 处理器架构 x86_64, arm64

5.目标属性（Target Properties）

通过 set_target_properties 或 get_target_property 操作，影响特定目标的行为。

常用属性

属性名 描述 设置命令
OUTPUT_NAME 输出文件名 set_target_properties(myapp PROPERTIES OUTPUT_NAME "custom_name")
VERSION 库版本号 set_target_properties(mylib PROPERTIES VERSION "1.2.3")
SOVERSION 共享库 API 版本 set_target_properties(mylib PROPERTIES SOVERSION "1")
COMPILE_DEFINITIONS 编译定义（如 -DDEBUG） target_compile_definitions(myapp PRIVATE DEBUG)
INCLUDE_DIRECTORIES 头文件搜索路径 target_include_directories(myapp PUBLIC include)
LINK_LIBRARIES 链接库 target_link_libraries(myapp PRIVATE pthread)
POSITION_INDEPENDENT_CODE 是否生成位置无关代码（共享库必需） set_target_properties(mylib PROPERTIES POSITION_INDEPENDENT_CODE ON)

5.变量和缓存

CMake 使用变量来存储和传递信息，这些变量可以在 CMakeLists.txt 文件中定义和使用。

变量可以分为普通变量和缓存变量。

1.变量定义与使用

定义变量：

cpp 复制代码 
set(MY_VAR "Hello World")

使用变量：

cpp 复制代码 
message(STATUS "Variable MY_VAR is ${MY_VAR}")

2.缓存变量

缓存变量存储在 CMake 的缓存文件中，用户可以在 CMake 配置时修改这些值。缓存变量通常用于用户输入的设置，用户可通过命令行（-D）或 CMake GUI 修改，例如编译选项和路径。

定义缓存变量：

cpp 复制代码 
set(MY_CACHE_VAR "DefaultValue" CACHE STRING "A cache variable")

set(BUILD_SHARED_LIBS ON CACHE BOOL "Build shared libraries")
set(CMAKE_INSTALL_PREFIX "/usr/local" CACHE PATH "Installation directory")

使用缓存变量：

cpp 复制代码 
message(STATUS "Cache variable MY_CACHE_VAR is ${MY_CACHE_VAR}")

3.环境变量

  • 访问方式 ：$ENV{VARIABLE_NAME}
  • 修改方式 ：set(ENV{VARIABLE_NAME} value)
cpp 复制代码 
message("PATH: $ENV{PATH}")  # 读取环境变量
set(ENV{MY_LIB_PATH} "${CMAKE_SOURCE_DIR}/libs")  # 设置环境变量

6.变量作用域与传递

  1. 默认作用域：当前目录及子目录。
  2. 提升作用域 ：PARENT_SCOPE 参数。
cpp 复制代码 
# 在子目录 CMakeLists.txt 中
set(CHILD_VAR "value" PARENT_SCOPE)  # 将变量传递到父目录

7.注意事项

1.模块化结构

cpp 复制代码 
project/
├── CMakeLists.txt       # 顶级配置
├── src/                 # 源代码
│   └── CMakeLists.txt
├── include/             # 公共头文件
├── tests/               # 测试代码
│   └── CMakeLists.txt
├── examples/            # 示例
└── CMakeModules/        # 自定义 CMake 模块

2.使用现代 CMake 模式

  • 优先使用 target_* 命令（如 target_include_directories）而非全局设置。
  • 通过 PUBLIC/PRIVATE/INTERFACE 明确依赖范围。

3.避免硬编码路径

cpp 复制代码 
# 不好的做法
include_directories("/usr/local/include/mylib")

# 好的做法
find_package(MyLib REQUIRED)
target_link_libraries(myapp PRIVATE MyLib::MyLib)

4.添加版本控制

cpp 复制代码 
project(MyProject VERSION 1.2.3)
configure_file(version.h.in version.h)
target_include_directories(myapp PRIVATE ${CMAKE_BINARY_DIR})

掌握 CMakeLists.txt 的结构和语法是高效管理 C/C++ 项目的关键，合理组织文件可大幅提升项目的可维护性和跨平台兼容性。

相关链接

相关推荐
m0_748240251 小时前
Windows编程+使用C++编写EXE加壳程序
开发语言·c++·windows
兮兮能吃能睡2 小时前
R语言模型分析（一）（1）
开发语言·r语言
LoveXming3 小时前
Chapter14—中介者模式
c++·microsoft·设计模式·中介者模式·开闭原则
wuk9984 小时前
基于有限差分法的二维平面热传导模型MATLAB实现
开发语言·matlab·平面
杨筱毅6 小时前
【C++】【常见面试题】最简版带大小和超时限制的LRU缓存实现
c++·面试
初见无风6 小时前
2.5 Lua代码中string类型常用API
开发语言·lua·lua5.4
做运维的阿瑞6 小时前
用 Python 构建稳健的数据分析流水线
开发语言·python·数据分析
左师佑图6 小时前
综合案例：Python 数据处理——从Excel文件到数据分析
开发语言·python·数据分析·excel·pandas
陌路207 小时前
C23构造函数与析构函数
开发语言·c++
_OP_CHEN7 小时前
C++进阶：（二）多态的深度解析
开发语言·c++·多态·抽象类·虚函数·多态的底层原理·多态面试题
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03BongoCat - 跨平台键盘猫动画工具04GitLab 零基础入门指南：从安装到项目管理全流程05Linux下V2Ray安装配置指南06NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南07安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）08在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）09Labelme从安装到标注：零基础完整指南10jdk21下载、安装（Windows、Linux、macOS）