CMakeLists.txt文件编写学习总结

一、CMakeLists.txt基础知识

CMakeLists.txt 是 CMake 构建系统用于定义项目的配置文件。CMake 是一个跨平台的自动化构建系统，它使用一个名为 CMakeLists.txt 的文件来指定如何构建项目。这个文件可以包含各种命令，用于指定项目名称、源文件、编译选项、库依赖等。下面是一个详细的指南，介绍如何使用 CMakeLists.txt 文件。

1.1 基本结构

一个基本的 CMakeLists.txt 文件可能如下所示：

cmake_minimum_required(VERSION 3.10)# 设置项目名称和版本
project(MyProject VERSION 1.0)# 添加一个可执行文件
add_executable(MyExecutable main.cpp)

1.2 主要命令

cmake_minimum_required

• 用来指定CMake的最小版本要求。
• 语法：cmake_minimum_required(VERSION major.minor[.patch[.tweak[.id]]])

project

• 定义项目的名称和可选的版本号。
• 语法：project(ProjectName [VERSION major.minor[.patch[.tweak[.id]]]] [DESCRIPTION summary])

add_executable

• 添加一个可执行文件到项目中。
• 语法：add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] source1 source2 ... sourceN)

add_library

• 添加一个库到项目中。
• 语法：add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] source1 source2 ... sourceN)

include_directories

• 向编译过程添加包含目录。
• 语法：include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)

target_include_directories

• 为目标（如可执行文件或库）添加包含目录。
• 语法：target_include_directories(<target> [SYSTEM] [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [...])

find_package

• 查找并加载外部项目。
• 语法：find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [COMPONENTS [components...]] [OPTIONAL_COMPONENTS [components...]] [CONFIG|NO_MODULE|NO_CONFIG|NO_POLICY_SCOPE] [NAMES name1 [...]])

target_link_libraries

• 为目标（如可执行文件或库）添加需要链接的库。
• 语法：target_link_libraries(<target> ... <PRIVATE|PUBLIC|INTERFACE> <item>... [...])

假设你有一个项目，它包含两个源文件 main.cpp 和 MyClass.cpp，以及对应的头文件 MyClass.h。你想编译这两个源文件为一个可执行文件，并且链接到一个名为 MyLibrary 的外部库。

cmake_minimum_required(VERSION 3.10)project(MyProject)# 设置包含目录
include_directories(${CMAKE_SOURCE_DIR}/include)# 添加一个可执行文件
add_executable(MyExecutable main.cpp MyClass.cpp)# 查找并链接外部库
find_package(MyLibrary REQUIRED)
target_link_libraries(MyExecutable MyLibrary::MyLibrary)# 如果MyLibrary是一个CMake库，可能需要使用下面的语法
# target_link_libraries(MyExecutable PRIVATE MyLibrary)

二、CMakelists 常用的变量

CMakeLists.txt 文件中使用的变量在 CMake 构建系统中扮演着重要角色，它们用于存储和传递配置信息、路径、选项等。CMake 提供了许多预定义的变量，同时也允许用户定义自己的变量。以下是一些在 CMakeLists.txt 文件中常用的变量：

2.1 CMake 预定义变量

1. CMAKE_BINARY_DIR：

   • 当前处理的二进制目录的绝对路径（即构建目录）。

2. CMAKE_SOURCE_DIR：

   • 当前处理的源代码目录的绝对路径（即源代码的顶层目录）。

3. CMAKE_CURRENT_SOURCE_DIR：

   • 当前正在处理的 CMakeLists.txt 文件所在的目录的绝对路径。

4. CMAKE_CURRENT_BINARY_DIR：

   • 当前正在处理的 CMakeLists.txt 文件对应的二进制目录的绝对路径。这可能与源代码目录不同，尤其是在使用 out-of-source 构建时。

5. CMAKE_INSTALL_PREFIX：

   • 安装路径的前缀，用于 make install 时的安装目标路径。

6. CMAKE_CXX_COMPILER、CMAKE_C_COMPILER：

   • 分别用于指定 C++ 和 C 编译器的完整路径。

7. CMAKE_BUILD_TYPE：

   • 构建类型（如 Debug、Release、MinSizeRel、RelWithDebInfo），用于设置优化和调试信息级别。

8. CMAKE_CXX_FLAGS、CMAKE_C_FLAGS：

   • 分别用于设置 C++ 和 C 编译器的标志（flags）。

9. CMAKE_LIBRARY_OUTPUT_DIRECTORY、CMAKE_ARCHIVE_OUTPUT_DIRECTORY、CMAKE_RUNTIME_OUTPUT_DIRECTORY：

   • 分别用于设置库、归档文件（如静态库）和可执行文件的输出目录。

10. PROJECT_NAME

    • 项目名称，这个名称由project设置

2.2 CMakeLists.txt 中定义的变量

在 CMakeLists.txt 文件中，你可以使用 set() 命令来定义自己的变量。这些变量可以是任何类型的数据，如字符串、列表或路径。

set(MY_VARIABLE "SomeValue")
set(MY_LIST_VARIABLE my_file1.cpp my_file2.cpp)

2.3 使用变量

在 CMakeLists.txt 文件中，你可以通过 ${} 语法来引用变量。

add_executable(MyExecutable ${MY_LIST_VARIABLE})

2.4 变量作用域

CMake 中的变量有作用域的概念。在 CMakeLists.txt 文件中定义的变量默认具有函数作用域（如果你在函数或宏中定义它们）或目录作用域（如果你在顶层 CMakeLists.txt 或子目录的 CMakeLists.txt 中定义它们）。这意味着在函数或宏内部定义的变量在外部是不可见的，除非你使用 set() 命令的 PARENT_SCOPE 选项来显式地修改父作用域中的变量。

三、cmake安装编写

在 CMakeLists.txt 文件中编写关于安装的部分，主要是使用 install() 命令来指定哪些文件、目标（如可执行文件、库等）以及目录需要被安装到指定的位置。这通常在项目的顶层 CMakeLists.txt 文件中进行配置，但也可以在子目录的 CMakeLists.txt 中配置特定于该子目录的安装指令。

以下是一些常用的 install() 命令示例：

3.1 cmake安装可执行文件

add_executable(my_executable main.cpp)
install(TARGETS my_executable DESTINATION bin)

这条命令将 my_executable 安装到 ${CMAKE_INSTALL_PREFIX}/bin 目录下，其中 ${CMAKE_INSTALL_PREFIX} 是通过 cmake 命令行选项 -DCMAKE_INSTALL_PREFIX=/path/to/prefix 指定的安装前缀，或者在 CMakeLists.txt 文件中通过 set(CMAKE_INSTALL_PREFIX "/path/to/prefix") 设置。

3.2 cmake安装库

对于库，你可能想要安装库文件本身以及任何相关的头文件或模块文件。

add_library(my_library SHARED my_library.cpp)
install(TARGETS my_library LIBRARY DESTINATION lib ARCHIVE DESTINATION lib RUNTIME DESTINATION bin)
install(FILES my_library.h DESTINATION include/my_library)

在这个例子中，my_library 是一个共享库，它被安装到 ${CMAKE_INSTALL_PREFIX}/lib 目录下。对于静态库（ARCHIVE），通常也会安装到同一个目录，但在这里我们显式地指定了库文件的安装目录。头文件 my_library.h 被安装到 ${CMAKE_INSTALL_PREFIX}/include/my_library 目录下。

3.3 cmake安装目录

如果你想要安装一个完整的目录（比如文档、资源等），可以使用 install(DIRECTORY ...) 命令。

install(DIRECTORY doc/ DESTINATION share/doc/my_project)

这条命令将 doc/ 目录及其内容安装到 ${CMAKE_INSTALL_PREFIX}/share/doc/my_project 目录下。注意，默认情况下，install(DIRECTORY ...) 命令会安装目录中的所有内容，但你可以通过 FILES_MATCHING 选项来指定要安装的文件模式。

四、CMake测试

在 CMakeLists.txt 文件中编写关于测试的部分，主要是使用 enable_testing() 命令来启用测试，并通过 add_test() 命令来添加具体的测试用例。CMake 提供了一个基本的测试框架，它允许你定义和执行测试，但并不直接提供断言或测试报告工具，这些通常需要与像 Google Test（GTest）这样的外部测试库结合使用。

以下是一个基本的 CMakeLists.txt 测试部分示例：

4.1 启用测试

首先，你需要在 CMakeLists.txt 文件中调用 enable_testing() 命令来启用测试功能。这通常放在文件的顶部或靠近配置指令（如 project()）的地方。

cmake_minimum_required(VERSION 3.10)
project(MyProject)# 启用测试
enable_testing()

4.2 添加测试

然后，你可以使用 add_test() 命令来添加测试用例。这个命令可以接收一个名称和一个命令行命令作为参数，当测试被触发时，CMake 会执行这个命令。

4.3 直接运行可执行文件作为测试

# 假设你有一个名为 my_test 的可执行文件
add_executable(my_test test/my_test.cpp)# 添加测试，运行 my_test 可执行文件
add_test(NAME MyTest COMMAND my_test)

在这个例子中，my_test 是一个可执行文件，它应该能够自行报告测试的成功或失败（例如，通过返回 0 表示成功，非 0 表示失败）。

4.4 使用外部测试框架（如 Google Test）

如果你使用的是像 Google Test 这样的外部测试框架，你的测试命令可能会更复杂一些，因为你需要设置环境变量、指定测试筛选器等。

# 假设你有一个使用 Google Test 编写的测试可执行文件
add_executable(my_tests test/my_tests.cpp)
target_link_libraries(my_tests GTest::GTest GTest::Main)# 添加测试，使用 Google Test 的命令行界面来运行测试
# 注意：这里假设你的 Google Test 可执行文件能够接收 --gtest_filter 等参数
add_test(NAME MyTests COMMAND my_tests --gtest_filter=SomeTest.SomeCase)# 或者，如果你想为所有测试用例都运行测试可执行文件
add_test(NAME MyTests COMMAND my_tests)

在这个例子中，my_tests 是一个使用 Google Test 编写的测试可执行文件。我们将其链接到 Google Test 库，并通过 add_test() 命令添加了一个测试，该测试将运行 my_tests 并可能通过 --gtest_filter 参数来指定要运行的特定测试用例。

4.5 运行测试

在 CMake 中配置并生成项目后，你可以使用 ctest 命令来运行测试。ctest 是 CMake 提供的一个命令行工具，用于运行 CMakeLists.txt 文件中定义的测试。

cmake -S . -B build
cmake --build build
ctest --test-dir build

这些命令将分别在源代码目录（.）中配置项目，在 build 目录中生成项目，并在 build 目录中运行测试。

四、CMake其他

3.1 GLOB_RECURSE引用全局内容

在CMake中，GLOB_RECURSE命令用于在指定目录及其子目录中寻找文件。如果你想要排除某些目录，可以使用LIST_EXCLUDE选项配合正则表达式来实现。

以下是一个简单的例子，展示了如何使用GLOB_RECURSE命令并排除特定的目录：

cmake_minimum_required(VERSION 3.0)
project(ExcludeDirectories)

• 假设我们要寻找所有的源文件，但是要排除名为"exclude_dir"的目录
  file(GLOB_RECURSE ALL_SOURCES
  RELATIVE “$CMAK{E}_{C}URREN{T}_{S}OURC{E}_{D}IR""${CMAKE_CURRENT_SOURCE_DIR}/.cpp"
  "${CMAKE_CURRENT_SOURCE_DIR}/.h”
  )

• 排除名为"exclude_dir"的目录
  list(FILTER ALL_SOURCES EXCLUDE REGEX “exclude_dir/”)

message(STATUS “All Sources: ${ALL_SOURCES}”)

在这个例子中，我们使用file(GLOB_RECURSE)命令寻找当前源代码目录下的所有.cpp和.h文件。然后，我们使用list(FILTER)命令配合EXCLUDE和REGEX选项来排除名为exclude_dir的目录。这样，在ALL_SOURCES变量中就不会包含该目录下的任何文件。