CMake语法实用手册详解常用命令与配置助你轻松驾驭跨平台项目构建

威震华夏关云长

引言

CMake是一个开源、跨平台的构建自动化工具，它使用平台无关的配置文件（CMakeLists.txt）来生成标准的构建文件（如Unix的Makefile或Windows的Visual Studio项目）。CMake的设计初衷是解决跨平台构建的复杂性，使开发者能够用一套配置文件管理多个平台的项目构建。

在软件开发中，不同平台（Windows、Linux、macOS等）和不同编译器（GCC、Clang、MSVC等）有不同的构建系统和约定。CMake通过提供一个抽象层，让开发者可以专注于项目本身，而不必为每个平台维护不同的构建文件。

CMake广泛应用于开源项目和商业软件中，包括知名的软件如KDE、VTK、ITK、Blender等。掌握CMake不仅能够简化构建过程，还能提高项目的可维护性和可移植性。

本手册将详细介绍CMake的语法、常用命令和配置技巧，帮助你轻松驾驭跨平台项目构建。

CMake基础

CMake语法基础

CMake脚本语言具有简单直观的语法，主要由命令（命令名不区分大小写，但参数区分大小写）、变量和注释组成。

CMake中的注释以#开头，一直到行尾：

2. # 这是一个单行注释

复制代码

CMake命令的基本语法是：

2. command(参数1 参数2 参数3 ...)

复制代码

命令名不区分大小写，但按照惯例，通常使用小写。参数可以是变量、字符串或其他值。例如：

2. message(STATUS "Hello, CMake!")

复制代码

在CMake中，变量使用set()命令设置，使用${VAR_NAME}语法引用：

2. # 设置变量
3. set(MY_VARIABLE "Hello, World!")
5. # 引用变量
6. message(STATUS ${MY_VARIABLE})

复制代码

CMake有一些内置变量，如CMAKE_SOURCE_DIR（指向CMakeLists.txt所在的顶级目录）、CMAKE_BINARY_DIR（指向构建目录）等。

CMake中的变量可以存储列表，列表是以分号分隔的字符串：

2. # 创建列表
3. set(MY_LIST "item1" "item2" "item3")
5. # 或者使用分号分隔
6. set(ANOTHER_LIST "item1;item2;item3")
8. # 访问列表元素
9. message(STATUS ${MY_LIST})  # 输出: item1;item2;item3
10. message(STATUS ${MY_LIST[0]})  # 输出: item1

复制代码

CMake脚本执行流程

CMake按照以下顺序处理CMakeLists.txt文件：

1. 读取CMakeLists.txt文件
2. 解析并执行命令
3. 生成构建系统（如Makefile或Visual Studio项目）

CMake使用变量CMAKE_CURRENT_SOURCE_DIR和CMAKE_CURRENT_BINARY_DIR来跟踪当前处理的源目录和二进制目录。

常用CMake命令详解

项目设置命令

指定运行此CMakeLists.txt所需的最低CMake版本：

2. cmake_minimum_required(VERSION 3.10)

复制代码

这个命令应该在CMakeLists.txt的开头使用，以确保使用兼容的CMake版本。如果使用的CMake版本低于指定版本，CMake会报错。

设置项目名称和版本：

2. project(MyProject VERSION 1.0.0 LANGUAGES CXX)

复制代码

project()命令会设置一些变量，如PROJECT_NAME（项目名称）、PROJECT_VERSION（项目版本）等。LANGUAGES参数指定项目使用的编程语言，默认是C和CXX。

目标定义命令

添加一个可执行文件目标：

2. # 简单形式
3. add_executable(my_app main.cpp)
5. # 指定源文件列表
6. set(SOURCES main.cpp utils.cpp)
7. add_executable(my_app ${SOURCES})
9. # 指定WIN32_EXECUTABLE属性（Windows GUI应用）
10. add_executable(my_app WIN32 main.cpp)

复制代码

添加一个库目标：

2. # 静态库
3. add_library(my_lib STATIC source1.cpp source2.cpp)
5. # 共享库
6. add_library(my_lib SHARED source1.cpp source2.cpp)
8. # 模块库（某些平台不支持）
9. add_library(my_lib MODULE source1.cpp source2.cpp)
11. # 接口库（仅包含头文件，不编译源文件）
12. add_library(my_lib INTERFACE)

复制代码

为目标指定包含目录：

2. # 为my_lib目标添加包含目录
3. target_include_directories(my_lib PUBLIC
4.     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
5.     $<INSTALL_INTERFACE:include>
6. )
8. # 为my_app目标添加包含目录
9. target_include_directories(my_app PRIVATE
10.     ${CMAKE_CURRENT_SOURCE_DIR}/include
11. )

复制代码

这里的PUBLIC、PRIVATE和INTERFACE指定了包含目录的可见性：

• PUBLIC：对当前目标和依赖此目标的目标都可见
• PRIVATE：仅对当前目标可见
• INTERFACE：仅对依赖此目标的目标可见

为目标指定链接的库：

2. # 链接库
3. target_link_libraries(my_app PRIVATE my_lib)
5. # 链接外部库
6. target_link_libraries(my_app PRIVATE pthread)
8. # 链接系统库
9. target_link_libraries(my_app PRIVATE ${CMAKE_DL_LIBS})

复制代码

为目标指定编译定义：

2. # 为my_app添加编译定义
3. target_compile_definitions(my_app PRIVATE MY_DEFINE=1)
5. # 为my_lib添加公共编译定义
6. target_compile_definitions(my_lib PUBLIC USE_MY_LIB)

复制代码

为目标指定编译选项：

2. # 为my_app添加编译选项
3. target_compile_options(my_app PRIVATE -Wall -Wextra)
5. # 使用生成器表达式
6. target_compile_options(my_lib PRIVATE
7.     $<$<CXX_COMPILER_ID:GNU>:-Wall -Wextra>
8.     $<$<CXX_COMPILER_ID:MSVC>:/W4>
9. )

复制代码

查找依赖命令

查找并加载外部项目设置：

2. # 查找Boost库
3. find_package(Boost 1.70 REQUIRED COMPONENTS filesystem system)
5. # 如果找到，链接到目标
6. if(Boost_FOUND)
7.     target_link_libraries(my_app PRIVATE Boost::filesystem Boost::system)
8. endif()

复制代码

find_package有两种模式：Module模式和Config模式。Module模式查找Find.cmake文件，Config模式查找Config.cmake文件。

查找库文件：

2. # 查找math库
3. find_library(MATH_LIB m)
5. if(MATH_LIB)
6.     target_link_libraries(my_app PRIVATE ${MATH_LIB})
7. endif()

复制代码

查找包含文件的路径：

2. # 查找包含header.h的路径
3. find_path(HEADER_INCLUDE_DIR header.h
4.     PATHS /usr/include /usr/local/include
5. )
7. if(HEADER_INCLUDE_DIR)
8.     target_include_directories(my_app PRIVATE ${HEADER_INCLUDE_DIR})
9. endif()

复制代码

查找文件的完整路径：

2. # 查找config.txt文件
3. find_file(CONFIG_FILE config.txt
4.     PATHS /etc /usr/local/etc
5. )
7. if(CONFIG_FILE)
8.     message(STATUS "Found config file: ${CONFIG_FILE}")
9. endif()

复制代码

安装规则命令

定义安装规则：

2. # 安装目标
3. install(TARGETS my_app my_lib
4.     RUNTIME DESTINATION bin
5.     LIBRARY DESTINATION lib
6.     ARCHIVE DESTINATION lib
7. )
9. # 安装文件
10. install(FILES ${HEADER_FILES} DESTINATION include)
12. # 安装目录
13. install(DIRECTORY include/ DESTINATION include)
15. # 安装脚本
16. install(SCRIPT cmake_install.cmake)

复制代码

DESTINATION指定安装路径，是相对于CMAKE_INSTALL_PREFIX的相对路径。

测试相关命令

启用测试功能：

2. enable_testing()

复制代码

这个命令应该在CMakeLists.txt的顶层调用，以启用CTest测试功能。

添加测试：

2. # 添加简单测试
3. add_test(NAME my_test COMMAND my_app)
5. # 添加带参数的测试
6. add_test(NAME my_test_with_args COMMAND my_app arg1 arg2)
8. # 设置测试属性
9. set_tests_properties(my_test PROPERTIES
10.     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
11. )

复制代码

CMake变量与属性

CMake变量

CMake变量用于存储值，可以在整个构建过程中使用。变量的作用域取决于它们被定义的位置。

使用set()命令设置变量：

2. # 设置简单变量
3. set(MY_VAR "value")
5. # 设置列表变量
6. set(MY_LIST "item1" "item2" "item3")
8. # 设置缓存变量（在CMake运行之间保持）
9. set(MY_CACHE_VAR "value" CACHE STRING "Description")

复制代码

缓存变量存储在CMakeCache.txt文件中，可以在CMake运行之间保持。

使用${VAR_NAME}语法引用变量：

2. message(STATUS "MY_VAR = ${MY_VAR}")

复制代码

可以使用$ENV{VAR_NAME}语法访问环境变量：

2. message(STATUS "HOME directory: $ENV{HOME}")

复制代码

使用set(ENV{VAR_NAME} value)设置环境变量：

2. set(ENV{PATH} "$ENV{PATH};/new/path")

复制代码

CMake属性

属性是与目录、目标、源文件、测试等关联的命名值。属性可以控制构建过程的行为。

使用set_property()命令设置属性：

2. # 设置目标属性
3. set_property(TARGET my_app PROPERTY
4.     CXX_STANDARD 11
5.     CXX_STANDARD_REQUIRED ON
6. )
8. # 设置源文件属性
9. set_property(SOURCE main.cpp PROPERTY
10.     COMPILE_DEFINITIONS DEBUG=1
11. )
13. # 设置目录属性
14. set_property(DIRECTORY . PROPERTY
15.     INCLUDE_DIRECTORIES ${CMAKE_CURRENT_SOURCE_DIR}/include
16. )

复制代码

使用get_property()命令获取属性：

2. # 获取目标属性
3. get_property(MY_APP_CXX_STANDARD TARGET my_app PROPERTY CXX_STANDARD)
4. message(STATUS "my_app CXX standard: ${MY_APP_CXX_STANDARD}")

复制代码

使用define_property()命令定义自定义属性：

2. define_property(TARGET PROPERTY MY_CUSTOM_PROPERTY
3.     BRIEF_DOCS "My custom property"
4.     FULL_DOCS "More detailed description of my custom property"
5. )

复制代码

条件判断与流程控制

条件判断

CMake提供了if()、elseif()和else()命令进行条件判断：

2. # 简单条件
3. if(MY_VAR)
4.     message(STATUS "MY_VAR is true")
5. endif()
7. # 比较条件
8. if(MY_VAR STREQUAL "value")
9.     message(STATUS "MY_VAR is 'value'")
10. endif()
12. # 数值比较
13. if(MY_NUMBER EQUAL 42)
14.     message(STATUS "MY_NUMBER is 42")
15. endif()
17. # 逻辑操作
18. if(MY_VAR AND (MY_NUMBER GREATER 10 OR MY_NUMBER LESS 5))
19.     message(STATUS "Complex condition")
20. endif()
22. # 检查变量是否定义
23. if(DEFINED MY_VAR)
24.     message(STATUS "MY_VAR is defined")
25. endif()
27. # 检查命令是否存在
28. if(COMMAND some_command)
29.     message(STATUS "some_command exists")
30. endif()

复制代码

循环

CMake提供了foreach()和while()命令进行循环：

2. # foreach循环
3. foreach(item IN LISTS MY_LIST)
4.     message(STATUS "Item: ${item}")
5. endforeach()
7. # 范围循环
8. foreach(i RANGE 1 5)
9.     message(STATUS "i = ${i}")
10. endforeach()
12. # while循环
13. set(i 0)
14. while(i LESS 5)
15.     message(STATUS "i = ${i}")
16.     math(EXPR i "${i} + 1")
17. endwhile()

复制代码

流程控制

CMake提供了一些流程控制命令：

从函数或文件返回：

2. function(my_function)
3.     if(CONDITION)
4.         return()
5.     endif()
6.     # 其他代码
7. endfunction()

复制代码

跳出循环：

2. foreach(item IN LISTS MY_LIST)
3.     if(item STREQUAL "stop")
4.         break()
5.     endif()
6.     message(STATUS "Item: ${item}")
7. endforeach()

复制代码

继续下一次循环：

2. foreach(item IN LISTS MY_LIST)
3.     if(item STREQUAL "skip")
4.         continue()
5.     endif()
6.     message(STATUS "Item: ${item}")
7. endforeach()

复制代码

函数与宏的定义与使用

函数

使用function()命令定义函数：

2. # 定义函数
3. function(print_message message)
4.     message(STATUS "Message: ${message}")
5. endfunction()
7. # 调用函数
8. print_message("Hello, CMake!")

复制代码

函数有自己的变量作用域，参数通过${ARGN}、${ARGV}、${ARGC}等变量访问：

2. # 定义可变参数函数
3. function(print_all)
4.     message(STATUS "Number of arguments: ${ARGC}")
5.     foreach(i RANGE 1 ${ARGC})
6.         message(STATUS "Argument ${i}: ${ARGV${i}}")
7.     endforeach()
8. endfunction()
10. # 调用函数
11. print_all("arg1" "arg2" "arg3")

复制代码

宏

使用macro()命令定义宏：

2. # 定义宏
3. macro(print_message message)
4.     message(STATUS "Message: ${message}")
5. endmacro()
7. # 调用宏
8. print_message("Hello, CMake!")

复制代码

宏与函数的主要区别在于：

• 宏没有自己的变量作用域，它们在调用者的作用域中执行
• 宏的参数是文本替换，而不是值传递

返回值

CMake函数和宏不能直接返回值，但可以通过以下方式模拟返回值：

2. # 通过参数返回值
3. function(get_result out_var)
4.     set(${out_var} "result" PARENT_SCOPE)
5. endfunction()
7. # 调用函数
8. get_result(result)
9. message(STATUS "Result: ${result}")
11. # 使用return()命令
12. function(get_result)
13.     return("result")
14. endfunction()
16. # 调用函数
17. get_result(result)
18. message(STATUS "Result: ${result}")

复制代码

CMake项目结构最佳实践

基本项目结构

一个典型的CMake项目结构如下：

2. my_project/
3. ├── CMakeLists.txt          # 顶层CMakeLists.txt
4. ├── src/                    # 源代码目录
5. │   ├── CMakeLists.txt      # src目录的CMakeLists.txt
6. │   ├── lib/
7. │   │   ├── CMakeLists.txt
8. │   │   ├── my_lib.cpp
9. │   │   └── my_lib.h
10. │   └── app/
11. │       ├── CMakeLists.txt
12. │       └── main.cpp
13. ├── include/                # 头文件目录
14. │   └── my_lib/
15. │       └── my_lib.h
16. ├── tests/                  # 测试目录
17. │   ├── CMakeLists.txt
18. │   └── test_my_lib.cpp
19. ├── cmake/                  # CMake模块目录
20. │   └── FindSomeLib.cmake
21. ├── examples/               # 示例目录
22. │   ├── CMakeLists.txt
23. │   └── example.cpp
24. └── README.md

复制代码

顶层CMakeLists.txt示例

2. cmake_minimum_required(VERSION 3.10)
4. project(MyProject VERSION 1.0.0 LANGUAGES CXX)
6. # 设置C++标准
7. set(CMAKE_CXX_STANDARD 11)
8. set(CMAKE_CXX_STANDARD_REQUIRED ON)
10. # 添加子目录
11. add_subdirectory(src)
12. add_subdirectory(tests)
13. add_subdirectory(examples)
15. # 设置安装路径
16. include(GNUInstallDirs)
17. set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
18. set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
19. set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
21. # 配置文件
22. configure_file(
23.     "${PROJECT_SOURCE_DIR}/cmake/MyProjectConfig.cmake.in"
24.     "${PROJECT_BINARY_DIR}/MyProjectConfig.cmake"
25.     @ONLY
26. )
28. # 安装配置文件
29. install(FILES "${PROJECT_BINARY_DIR}/MyProjectConfig.cmake"
30.     DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyProject
31. )

复制代码

库CMakeLists.txt示例

2. # 设置源文件
3. set(LIB_SOURCES
4.     my_lib.cpp
5. )
7. # 创建库
8. add_library(my_lib ${LIB_SOURCES})
10. # 设置包含目录
11. target_include_directories(my_lib
12.     PUBLIC
13.         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../../include>
14.         $<INSTALL_INTERFACE:include>
15. )
17. # 设置编译定义
18. target_compile_definitions(my_lib
19.     PRIVATE MY_LIB_EXPORTS
20. )
22. # 设置链接库
23. target_link_libraries(my_lib
24.     PUBLIC
25.         # 公共依赖
26.     PRIVATE
27.         # 私有依赖
28. )
30. # 设置属性
31. set_target_properties(my_lib PROPERTIES
32.     VERSION ${PROJECT_VERSION}
33.     SOVERSION ${PROJECT_VERSION_MAJOR}
34. )
36. # 安装规则
37. install(TARGETS my_lib
38.     EXPORT MyProjectTargets
39.     LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
40.     ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
41.     RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
42. )
44. # 安装头文件
45. install(DIRECTORY ../../include/my_lib
46.     DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
47. )

复制代码

应用程序CMakeLists.txt示例

2. # 设置源文件
3. set(APP_SOURCES
4.     main.cpp
5. )
7. # 创建可执行文件
8. add_executable(my_app ${APP_SOURCES})
10. # 设置包含目录
11. target_include_directories(my_app
12.     PRIVATE
13.         ${CMAKE_CURRENT_SOURCE_DIR}/../../include
14. )
16. # 链接库
17. target_link_libraries(my_app
18.     PRIVATE
19.         my_lib
20. )
22. # 安装规则
23. install(TARGETS my_app
24.     RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
25. )

复制代码

跨平台构建技巧

平台检测

CMake提供了一些变量来检测当前平台：

2. # 操作系统检测
3. if(WIN32)
4.     message(STATUS "Windows")
5. elseif(UNIX AND NOT APPLE)
6.     message(STATUS "Linux")
7. elseif(APPLE)
8.     message(STATUS "macOS")
9. endif()
11. # 编译器检测
12. if(MSVC)
13.     message(STATUS "MSVC compiler")
14.     add_compile_options(/W4)
15. elseif(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
16.     message(STATUS "GCC or Clang compiler")
17.     add_compile_options(-Wall -Wextra)
18. endif()
20. # 架构检测
21. if(CMAKE_SIZEOF_VOID_P EQUAL 8)
22.     message(STATUS "64-bit system")
23. else()
24.     message(STATUS "32-bit system")
25. endif()

复制代码

平台特定的代码和库

处理平台特定的代码和库：

2. # 平台特定的源文件
3. if(WIN32)
4.     list(APPEND SOURCES win_specific.cpp)
5. elseif(UNIX)
6.     list(APPEND SOURCES unix_specific.cpp)
7. endif()
9. # 平台特定的库
10. find_package(Threads REQUIRED)
11. if(WIN32)
12.     target_link_libraries(my_app PRIVATE wsock32)
13. else()
14.     target_link_libraries(my_app PRIVATE pthread)
15. endif()
17. # 平台特定的编译选项
18. if(MSVC)
19.     target_compile_options(my_app PRIVATE /W4)
20. else()
21.     target_compile_options(my_app PRIVATE -Wall -Wextra)
22. endif()

复制代码

路径处理

处理跨平台路径问题：

2. # 使用file命令处理路径
3. file(TO_CMAKE_PATH "/path/to/file" PATH_VAR)
4. file(TO_NATIVE_PATH "${PATH_VAR}" NATIVE_PATH)
6. # 使用生成器表达式处理路径
7. target_include_directories(my_app PRIVATE
8.     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
9.     $<INSTALL_INTERFACE:include>
10. )
12. # 使用路径组件
13. get_filename_component(DIR ${PATH} DIRECTORY)
14. get_filename_component(NAME ${PATH} NAME_WE)
15. get_filename_component(EXT ${PATH} EXT)

复制代码

生成器表达式

生成器表达式是CMake的强大功能，可以在生成构建系统时进行条件评估：

2. # 基于配置的生成器表达式
3. target_compile_definitions(my_app PRIVATE
4.     $<$<CONFIG:Debug>:DEBUG_BUILD>
5.     $<$<CONFIG:Release>:NDEBUG>
6. )
8. # 基于平台的生成器表达式
9. target_link_libraries(my_app PRIVATE
10.     $<$<PLATFORM_ID:Windows>:ws2_32>
11.     $<$<PLATFORM_ID:Linux>:pthread>
12. )
14. # 基于编译器的生成器表达式
15. target_compile_options(my_app PRIVATE
16.     $<$<CXX_COMPILER_ID:MSVC>:/W4>
17.     $<$<CXX_COMPILER_ID:GNU>:-Wall -Wextra>
18. )
20. # 基于语言特性的生成器表达式
21. target_compile_features(my_app PRIVATE
22.     $<$<CXX_COMPILER_ID:GNU,Clang>:cxx_std_11>
23.     $<$<CXX_COMPILER_ID:MSVC>:cxx_std_14>
24. )

复制代码

高级主题

CMake模块

CMake模块是可重用的CMake代码片段，通常以.cmake为扩展名。可以使用include()命令包含模块：

2. # 包含模块
3. include(FindPackageHandleStandardArgs)
5. # 使用模块中的函数
6. find_package_handle_standard_args(MyLib
7.     DEFAULT_MSG
8.     MYLIB_INCLUDE_DIR
9.     MYLIB_LIBRARY
10. )

复制代码

自定义Find模块

创建自定义的Find模块来查找第三方库：

2. # FindMyLib.cmake
3. find_path(MYLIB_INCLUDE_DIR
4.     NAMES mylib.h
5.     PATHS /usr/include /usr/local/include
6. )
8. find_library(MYLIB_LIBRARY
9.     NAMES mylib
10.     PATHS /usr/lib /usr/local/lib
11. )
13. include(FindPackageHandleStandardArgs)
14. find_package_handle_standard_args(MyLib
15.     DEFAULT_MSG
16.     MYLIB_INCLUDE_DIR
17.     MYLIB_LIBRARY
18. )
20. if(MYLIB_FOUND)
21.     if(NOT TARGET MyLib::MyLib)
22.         add_library(MyLib::MyLib UNKNOWN IMPORTED)
23.         set_target_properties(MyLib::MyLib PROPERTIES
24.             IMPORTED_LOCATION "${MYLIB_LIBRARY}"
25.             INTERFACE_INCLUDE_DIRECTORIES "${MYLIB_INCLUDE_DIR}"
26.         )
27.     endif()
28. endif()
30. mark_as_advanced(MYLIB_INCLUDE_DIR MYLIB_LIBRARY)

复制代码

配置文件模板

使用配置文件模板生成配置文件：

2. # MyConfig.h.in
3. #pragma once
5. #define MY_APP_VERSION "@PROJECT_VERSION@"
6. #define MY_APP_NAME "@PROJECT_NAME@"
7. #cmakedefine USE_FEATURE_A
8. #cmakedefine USE_FEATURE_B
10. // 路径示例
11. #define INSTALL_PATH "@CMAKE_INSTALL_PREFIX@"

复制代码

2. # CMakeLists.txt
3. # 配置文件
4. configure_file(
5.     "${PROJECT_SOURCE_DIR}/MyConfig.h.in"
6.     "${PROJECT_BINARY_DIR}/MyConfig.h"
7.     @ONLY
8. )
10. # 添加包含目录
11. target_include_directories(my_app PRIVATE
12.     ${PROJECT_BINARY_DIR}
13. )

复制代码

自定义命令和目标

使用add_custom_command()和add_custom_target()创建自定义构建规则：

2. # 自定义命令（生成源文件）
3. add_custom_command(
4.     OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated.cpp
5.     COMMAND ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/generate.py
6.         -o ${CMAKE_CURRENT_BINARY_DIR}/generated.cpp
7.     DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/generate.py
8.     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
9.     COMMENT "Generating generated.cpp"
10. )
12. # 自定义目标（运行测试）
13. add_custom_target(run_tests
14.     COMMAND ${CMAKE_CTEST_COMMAND} --verbose
15.     DEPENDS my_app
16.     WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
17. )

复制代码

打包和分发

使用CPack创建安装包：

2. # 包含CPack
3. include(InstallRequiredSystemLibraries)
4. include(CPack)
6. # 设置CPack变量
7. set(CPACK_PACKAGE_NAME "MyProject")
8. set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION})
9. set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My Project Description")
10. set(CPACK_PACKAGE_VENDOR "My Company")
12. # 设置包类型
13. if(WIN32)
14.     set(CPACK_GENERATOR ZIP NSIS)
15. elseif(UNIX)
16.     set(CPACK_GENERATOR TGZ DEB RPM)
17. endif()

复制代码

实际案例：构建一个跨平台项目

让我们通过一个完整的例子来展示如何使用CMake构建一个跨平台项目。这个项目包含一个库和一个使用该库的应用程序。

项目结构

2. my_project/
3. ├── CMakeLists.txt
4. ├── include/
5. │   └── mylib/
6. │       └── mylib.h
7. ├── src/
8. │   ├── CMakeLists.txt
9. │   ├── mylib.cpp
10. │   └── app.cpp
11. └── tests/
12.     ├── CMakeLists.txt
13.     └── test_mylib.cpp

复制代码

头文件 (include/mylib/mylib.h)

2. #pragma once
4. #include <string>
6. namespace mylib {
8. class MyLib {
9. public:
10.     MyLib(const std::string& name);
11.     std::string greet() const;
12.    
13. private:
14.     std::string name_;
15. };
17. }  // namespace mylib

复制代码

库实现 (src/mylib.cpp)

2. #include "mylib/mylib.h"
3. #include <sstream>
5. namespace mylib {
7. MyLib::MyLib(const std::string& name) : name_(name) {}
9. std::string MyLib::greet() const {
10.     std::ostringstream oss;
11.     oss << "Hello, " << name_ << "!";
12.     return oss.str();
13. }
15. }  // namespace mylib

复制代码

应用程序 (src/app.cpp)

2. #include "mylib/mylib.h"
3. #include <iostream>
5. int main() {
6.     mylib::MyLib lib("World");
7.     std::cout << lib.greet() << std::endl;
8.     return 0;
9. }

复制代码

测试文件 (tests/test_mylib.cpp)

2. #include "mylib/mylib.h"
3. #include <cassert>
4. #include <string>
6. int main() {
7.     mylib::MyLib lib("Test");
8.     std::string result = lib.greet();
9.     assert(result == "Hello, Test!");
10.     return 0;
11. }

复制代码

顶层CMakeLists.txt

2. cmake_minimum_required(VERSION 3.10)
4. project(MyProject VERSION 1.0.0 LANGUAGES CXX)
6. # 设置C++标准
7. set(CMAKE_CXX_STANDARD 11)
8. set(CMAKE_CXX_STANDARD_REQUIRED ON)
10. # 添加子目录
11. add_subdirectory(src)
12. add_subdirectory(tests)
14. # 设置输出目录
15. set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
16. set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
17. set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
19. # 打包支持
20. include(InstallRequiredSystemLibraries)
21. include(CPack)
23. set(CPACK_PACKAGE_NAME "MyProject")
24. set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION})
25. set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My Project")
26. set(CPACK_PACKAGE_VENDOR "My Company")

复制代码

src/CMakeLists.txt

2. # 库
3. add_library(mylib SHARED mylib.cpp)
5. target_include_directories(mylib
6.     PUBLIC
7.         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
8.         $<INSTALL_INTERFACE:include>
9. )
11. # 设置属性
12. set_target_properties(mylib PROPERTIES
13.     VERSION ${PROJECT_VERSION}
14.     SOVERSION ${PROJECT_VERSION_MAJOR}
15. )
17. # 应用程序
18. add_executable(myapp app.cpp)
20. target_link_libraries(myapp PRIVATE mylib)
22. # 安装规则
23. install(TARGETS mylib myapp
24.     EXPORT MyProjectTargets
25.     LIBRARY DESTINATION lib
26.     ARCHIVE DESTINATION lib
27.     RUNTIME DESTINATION bin
28. )
30. install(DIRECTORY ../include/mylib
31.     DESTINATION include
32. )
34. # 导出配置
35. install(EXPORT MyProjectTargets
36.     FILE MyProjectTargets.cmake
37.     DESTINATION lib/cmake/MyProject
38. )
40. # 配置文件
41. include(CMakePackageConfigHelpers)
42. configure_package_config_file(
43.     "${CMAKE_CURRENT_SOURCE_DIR}/MyProjectConfig.cmake.in"
44.     "${CMAKE_CURRENT_BINARY_DIR}/MyProjectConfig.cmake"
45.     INSTALL_DESTINATION lib/cmake/MyProject
46. )
48. write_basic_package_version_file(
49.     "${CMAKE_CURRENT_BINARY_DIR}/MyProjectConfigVersion.cmake"
50.     VERSION ${PROJECT_VERSION}
51.     COMPATIBILITY AnyNewerVersion
52. )
54. install(FILES
55.     "${CMAKE_CURRENT_BINARY_DIR}/MyProjectConfig.cmake"
56.     "${CMAKE_CURRENT_BINARY_DIR}/MyProjectConfigVersion.cmake"
57.     DESTINATION lib/cmake/MyProject
58. )

复制代码

tests/CMakeLists.txt

2. # 启用测试
3. enable_testing()
5. # 测试可执行文件
6. add_executable(test_mylib test_mylib.cpp)
8. target_link_libraries(test_mylib PRIVATE mylib)
10. # 添加测试
11. add_test(NAME test_mylib COMMAND test_mylib)

复制代码

MyProjectConfig.cmake.in (src/MyProjectConfig.cmake.in)

2. @PACKAGE_INIT@
4. include("${CMAKE_CURRENT_LIST_DIR}/MyProjectTargets.cmake")
6. check_required_components(MyProject)

复制代码

构建和测试

2. # 创建构建目录
3. mkdir build && cd build
5. # 配置项目
6. cmake ..
8. # 构建
9. cmake --build .
11. # 运行测试
12. ctest --verbose
14. # 安装
15. cmake --install . --prefix /path/to/install
17. # 创建包
18. cpack -G TGZ

复制代码

常见问题与解决方案

问题1：如何处理第三方依赖？

解决方案：使用ExternalProject或FetchContent模块。

2. # 使用FetchContent (CMake 3.11+)
3. include(FetchContent)
5. FetchContent_Declare(
6.     googletest
7.     GIT_REPOSITORY https://github.com/google/googletest.git
8.     GIT_TAG main
9. )
11. FetchContent_MakeAvailable(googletest)
13. # 使用FetchContent获取的库
14. target_link_libraries(myapp PRIVATE gtest_main)

复制代码

问题2：如何处理不同构建类型（Debug、Release等）？

解决方案：使用CMAKE_BUILD_TYPE变量和生成器表达式。

2. # 设置构建类型
3. if(NOT CMAKE_BUILD_TYPE)
4.     set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Build type" FORCE)
5. endif()
7. # 基于构建类型的设置
8. target_compile_definitions(myapp PRIVATE
9.     $<$<CONFIG:Debug>:DEBUG>
10.     $<$<CONFIG:Release>:NDEBUG>
11. )
13. # 设置输出目录基于构建类型
14. set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/${CMAKE_BUILD_TYPE})
15. set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/${CMAKE_BUILD_TYPE})
16. set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin/${CMAKE_BUILD_TYPE})

复制代码

问题3：如何处理不同平台的路径分隔符？

解决方案：使用CMake的路径处理函数和生成器表达式。

2. # 使用file命令处理路径
3. file(TO_CMAKE_PATH "C:\\Path\\To\\File" CMAKE_PATH)
4. file(TO_NATIVE_PATH "/unix/path/to/file" NATIVE_PATH)
6. # 使用路径组件
7. get_filename_component(DIR ${PATH} DIRECTORY)
8. get_filename_component(NAME ${PATH} NAME_WE)
10. # 使用生成器表达式处理路径
11. target_include_directories(myapp PRIVATE
12.     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
13.     $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/include>
14. )

复制代码

问题4：如何处理编译器特定的警告和标志？

解决方案：使用生成器表达式和编译器ID检测。

2. # 检测编译器
3. if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
4.     add_compile_options(-Wall -Wextra -pedantic)
5. elseif(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
6.     add_compile_options(/W4)
7. endif()
9. # 使用生成器表达式
10. target_compile_options(myapp PRIVATE
11.     $<$<CXX_COMPILER_ID:GNU>:-Wall -Wextra>
12.     $<$<CXX_COMPILER_ID:MSVC>:/W4>
13. )

复制代码

问题5：如何创建可重用的CMake函数和宏？

解决方案：定义函数和宏，并将它们放在单独的.cmake文件中。

2. # CMakeFunctions.cmake
3. function(add_my_library name)
4.     cmake_parse_arguments(ARG
5.         ""
6.         "VERSION"
7.         "SOURCES;HEADERS;DEPENDENCIES"
8.         ${ARGN}
9.     )
10.    
11.     add_library(${name} ${ARG_SOURCES})
12.    
13.     target_include_directories(${name}
14.         PUBLIC
15.             $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
16.             $<INSTALL_INTERFACE:include>
17.     )
18.    
19.     if(ARG_VERSION)
20.         set_target_properties(${name} PROPERTIES VERSION ${ARG_VERSION})
21.     endif()
22.    
23.     if(ARG_DEPENDENCIES)
24.         target_link_libraries(${name} PUBLIC ${ARG_DEPENDENCIES})
25.     endif()
26.    
27.     # 安装规则
28.     install(TARGETS ${name}
29.         EXPORT ${name}Targets
30.         LIBRARY DESTINATION lib
31.         ARCHIVE DESTINATION lib
32.         RUNTIME DESTINATION bin
33.     )
34.    
35.     if(ARG_HEADERS)
36.         install(FILES ${ARG_HEADERS} DESTINATION include)
37.     endif()
38. endfunction()

复制代码

然后在CMakeLists.txt中包含并使用：

2. include(CMakeFunctions)
4. add_my_library(mylib
5.     VERSION 1.0.0
6.     SOURCES mylib.cpp
7.     HEADERS mylib.h
8.     DEPENDENCIES some_other_lib
9. )

复制代码

总结与资源推荐

CMake是一个强大的跨平台构建工具，掌握它能够大大简化项目构建和管理的复杂性。本手册介绍了CMake的基本语法、常用命令、变量和属性、条件判断与流程控制、函数与宏、项目结构最佳实践、跨平台构建技巧以及高级主题。

通过学习这些内容，你应该能够：

• 编写基本的CMakeLists.txt文件
• 管理项目依赖和链接库
• 创建可安装的库和应用程序
• 处理跨平台构建问题
• 使用高级CMake特性解决复杂问题

推荐资源

1. 官方文档：CMake官方文档CMake教程
2. CMake官方文档
3. CMake教程
4. 书籍：“Professional CMake: A Practical Guide” by Craig Scott“Mastering CMake” by Ken Martin and Bill Hoffman
5. “Professional CMake: A Practical Guide” by Craig Scott
6. “Mastering CMake” by Ken Martin and Bill Hoffman
7. 在线资源：CMake Discourse论坛CMake WikiModern CMake
8. CMake Discourse论坛
9. CMake Wiki
10. Modern CMake
11. 示例项目：CMake示例集合Effective Modern CMake
12. CMake示例集合
13. Effective Modern CMake

官方文档：

• CMake官方文档
• CMake教程

书籍：

• “Professional CMake: A Practical Guide” by Craig Scott
• “Mastering CMake” by Ken Martin and Bill Hoffman

在线资源：

• CMake Discourse论坛
• CMake Wiki
• Modern CMake

示例项目：

• CMake示例集合
• Effective Modern CMake

通过不断实践和学习，你将能够熟练使用CMake来管理复杂的跨平台项目构建。记住，CMake是一个不断发展的工具，保持对新版本特性的关注将帮助你更好地利用它的强大功能。

版权声明

1、转载或引用本网站内容(CMake语法实用手册详解常用命令与配置助你轻松驾驭跨平台项目构建)须注明原网址及作者(威震华夏关云长)，并标明本网站网址(https://pixtech.cc/)。

2、对于不当转载或引用本网站内容而引起的民事纷争、行政处理或其他损失，本网站不承担责任。

3、对不遵守本声明或其他违法、恶意使用本网站内容者，本网站保留追究其法律责任的权利。

本文地址: https://pixtech.cc/thread-40244-1-1.html