cmake之旅（2）

cmake之旅21 从一个最小的 CMakeLists.txt 开始2 cmake_minimum_required —— 版本约束3 project —— 项目定义4 message —— 打印信息5 set —— 变量定义5.1 普通变量5.2 CMake 内置变量5.3 缓存变量6 add_executable —— 生成可执行文件7 include_directories —— 指定头文件搜索路径8 完整示例9 补充CMake 中容易踩的坑10 本篇命令速查表11 总结与下一篇预告同系列文章cmake之旅(1):构建的过程cmake之旅(2):CMakeLists.txt 核心语法cmake之旅(3):多目录项目管理cmake之旅(4):静态库与动态库cmake之旅5):函数、宏与 .cmake 模块cmake之旅6查找和使用第三方库cmake之旅7编译选项与条件编译cmake之旅8Modern CMake 与 target 思维cmake之旅9安装与导出cmake之旅10自动化测试与 CTest在上一篇中我们从手动编译一步步走到了 CMake体验了 CMake 带来的便利。但上一篇中的 CMakeLists.txt 只是一个能跑就行的版本我们对里面的每一行到底在做什么可能还是一知半解。这一篇我们就来系统地学习 CMakeLists.txt 的核心语法搞清楚每条命令的含义和用法为后续写出更复杂的 CMakeLists.txt 打下基础。1 从一个最小的 CMakeLists.txt 开始还是使用上一篇中的简单程序#includeiostreamintmain(){std::coutHello Cmakestd::endl;return0;}对应的 CMakeLists.txt 最少只需要三行# 设定 CMake 的最低版本要求 cmake_minimum_required(VERSION 3.10) # 定义项目名称 project(HelloCMake) # 生成可执行文件第一个参数是可执行文件名后面是源文件 add_executable(main main.cpp)没错就这三行就够了。这三行也是任何一个 CMakeLists.txt 的骨架。接下来我们逐一拆解。2 cmake_minimum_required —— 版本约束cmake_minimum_required(VERSION 3.10)这条命令指定了构建这个项目所需要的 CMake 最低版本。为什么需要它因为不同版本的 CMake 支持的特性不同比如某些命令在旧版本中根本不存在。加上这个约束后如果用户的 CMake 版本太低CMake 会直接报错提示而不是跑出一堆莫名其妙的错误。建议一般设置为 3.10 或更高就可以了3.10 之后的版本支持了大部分常用的现代 CMake 特性。如果你不确定选什么版本可以在终端中运行cmake --version看看自己当前的版本选一个不高于当前版本的值即可。3 project —— 项目定义project(HelloCMake)这条命令做了两件事情定义了项目名称为HelloCMakeCMake 自动帮你设置了一系列相关的变量我们来验证一下它到底生成了哪些变量。修改 CMakeLists.txtcmake_minimum_required(VERSION 3.10) project(HelloCMake) # 打印 project 自动生成的变量 message(项目名称: ${PROJECT_NAME}) message(项目源码目录: ${PROJECT_SOURCE_DIR}) message(项目构建目录: ${PROJECT_BINARY_DIR}) add_executable(main main.cpp)执行构建命令后你会在终端中看到类似这样的输出项目名称: HelloCMake 项目源码目录: /home/user/my_project 项目构建目录: /home/user/my_project/buildproject()不仅仅是起个名字它还自动帮我们设置好了几个有用的路径变量。project 还可以指定更多信息project(HelloCMake VERSION 1.0.0 DESCRIPTION 一个学习cmake的项目 LANGUAGES CXX )VERSION项目版本号设置后可以通过${PROJECT_VERSION}获取DESCRIPTION项目描述LANGUAGES指定项目使用的语言CXX表示 CC表示 C。如果不写默认支持 C 和 C4 message —— 打印信息刚才我们已经用到了message它是 CMake 中的打印函数在调试 CMakeLists.txt 时非常有用。# 普通信息 message(这是一条普通信息) # 状态信息推荐使用输出时会带 -- 前缀 message(STATUS 这是一条状态信息) # 警告信息黄色提醒不会中断构建 message(WARNING 这是一条警告) # 错误信息会中断构建 message(FATAL_ERROR 出错了构建终止)执行后输出大概是这样的这是一条普通信息 -- 这是一条状态信息 CMake Warning at CMakeLists.txt:x (message): 这是一条警告 CMake Error at CMakeLists.txt:x (message): 出错了构建终止建议日常调试推荐使用message(STATUS ...)输出整齐容易和 CMake 本身的输出区分。5 set —— 变量定义set是 CMake 中最常用的命令之一用于定义变量。5.1 普通变量# 定义一个变量 set(MY_VAR hello) # 使用变量通过 ${} 取值 message(STATUS MY_VAR 的值是: ${MY_VAR})输出-- MY_VAR 的值是: hello一个常见的用法用 set 管理源文件列表# 将源文件列表存入变量 set(SOURCES main.cpp add/add.cpp de/de.cpp ) # 使用变量来生成可执行文件 add_executable(main ${SOURCES})这样做的好处是当源文件增多时只需要在set里面加一行不用去改其他地方。5.2 CMake 内置变量CMake 预定义了很多有用的内置变量最常用的几个如下变量名含义示例值CMAKE_CXX_STANDARDC 标准版本11、14、17、20CMAKE_CXX_STANDARD_REQUIRED是否强制要求该标准True / FalseCMAKE_BUILD_TYPE构建类型Debug / ReleaseCMAKE_SOURCE_DIR顶层源码目录/home/user/projectCMAKE_BINARY_DIR顶层构建目录/home/user/project/buildCMAKE_CURRENT_SOURCE_DIR当前 CMakeLists.txt 所在目录随文件位置变化最常用的就是设置 C 标准# 使用 C17 标准 set(CMAKE_CXX_STANDARD 17) # 如果编译器不支持 C17则报错而不是降级到更低标准 set(CMAKE_CXX_STANDARD_REQUIRED True)思考一下如果不设置CMAKE_CXX_STANDARD_REQUIRED为 True 会怎样假设你代码中用了 C17 的特性但编译器只支持 C14CMake 不会报错而是静默降级到 C14然后你的代码就编译失败了报出一堆看不懂的编译错误。所以强烈建议始终将CMAKE_CXX_STANDARD_REQUIRED设为 True。5.3 缓存变量除了普通变量CMake 还有一种缓存变量它的值会被保存到构建目录下的CMakeCache.txt文件中在多次运行 CMake 时不会丢失。# 定义一个缓存变量类型为 STRING默认值为 default带描述信息 set(MY_OPTION default CACHE STRING 这是一个可配置的选项)缓存变量通常用于提供可配置的选项让使用者在不修改 CMakeLists.txt 的情况下调整构建行为。比如你可以在命令行中覆盖它cmake-DMY_OPTIONcustom_value..不过目前阶段你只需要知道有这个概念就行后续我们会在讲条件编译的时候深入使用它。6 add_executable —— 生成可执行文件add_executable(main main.cpp)这条命令告诉 CMake用 main.cpp 编译生成一个叫 main 的可执行文件。如果有多个源文件直接往后面加就行add_executable(main main.cpp add/add.cpp de/de.cpp)或者配合前面讲的set变量set(SOURCES main.cpp add/add.cpp de/de.cpp ) add_executable(main ${SOURCES})两种写法效果完全相同但后者更整洁。7 include_directories —— 指定头文件搜索路径回忆一下上一篇的例子我们的头文件分布在 add 和 de 目录中。如果不告诉 CMake 去哪里找头文件编译就会报错“找不到 add.h”。# 告诉编译器去 add 和 de 目录下寻找头文件 include_directories(add de)加上这行之后代码中的#include add.h就能被正确找到了。注意include_directories是一个全局命令它会影响当前 CMakeLists.txt 中所有的目标。在后续的文章中我们会学到更精准的替代方案target_include_directories它可以只针对某个特定目标生效。这里先了解即可。8 完整示例我们把上面的知识串起来用上一篇的多文件项目来写一个完整的 CMakeLists.txt文件结构├──add│ ├── add.cpp │ └── add.h ├── de │ ├── de.cpp │ └── de.h ├── main.cpp └── CMakeLists.txtCMakeLists.txt# # 项目HelloCMake # 描述cmake之旅2的完整示例 # # 设定 CMake 的最低版本要求 cmake_minimum_required(VERSION 3.10) # 定义项目信息 project(HelloCMake VERSION 1.0.0 DESCRIPTION cmake之旅学习项目 LANGUAGES CXX ) # 设定 C 标准为 C17并强制要求 set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED True) # 打印一些调试信息 message(STATUS 项目名称: ${PROJECT_NAME}) message(STATUS 项目版本: ${PROJECT_VERSION}) message(STATUS C 标准: ${CMAKE_CXX_STANDARD}) # 定义源文件列表 set(SOURCES main.cpp add/add.cpp de/de.cpp ) # 指定头文件搜索路径 include_directories(add de) # 生成可执行文件 add_executable(${PROJECT_NAME} ${SOURCES})构建和运行mkdirbuildcdbuild cmake..make./HelloCMake注意这里我们用了${PROJECT_NAME}作为可执行文件名这样可执行文件的名字就和项目名称自动保持一致。执行cmake ..时你会看到我们用message打印的信息-- 项目名称: HelloCMake -- 项目版本: 1.0.0 -- C 标准: 179 补充CMake 中容易踩的坑在刚开始写 CMakeLists.txt 的时候有一些常见问题值得提前了解。变量未定义不会报错在 CMake 中如果你引用了一个不存在的变量它不会报错而是返回空字符串message(STATUS 值: ${NOT_EXIST})输出只会是-- 值:不会有任何警告。这在调试时容易让人困惑——明明写了变量怎么值是空的所以拼写的时候要格外注意。命令名不区分大小写变量名区分大小写# 以下两行等价 message(STATUS hello) MESSAGE(STATUS hello) # 但是变量名是区分大小写的 set(myVar aaa) set(MYVAR bbb) message(STATUS ${myVar}) # 输出 aaa message(STATUS ${MYVAR}) # 输出 bbb建议命令统一使用小写这是现代 CMake 的约定变量名使用大写或大写加下划线。CMakeLists.txt 文件名大小写敏感文件名必须是CMakeLists.txt首字母 C、M、L 大写其余小写。写成cmakelists.txt或CMAKELISTS.TXT都是不行的。10 本篇命令速查表命令作用示例cmake_minimum_required设定 CMake 最低版本cmake_minimum_required(VERSION 3.10)project定义项目名称和信息project(MyApp VERSION 1.0 LANGUAGES CXX)message打印信息调试用message(STATUS hello)set定义变量set(MY_VAR value)add_executable生成可执行文件add_executable(app main.cpp)include_directories添加头文件搜索路径include_directories(include/)11 总结与下一篇预告这一篇我们系统学习了 CMakeLists.txt 的核心语法版本约束、项目定义、变量、打印信息、生成可执行文件、指定头文件路径。掌握这些之后对于简单的项目已经可以自如地编写 CMakeLists.txt 了。但是你可能已经发现了一个问题目前所有的源文件都平铺在同一个 CMakeLists.txt 中。如果项目变大了比如有十几个模块、几十个源文件全都塞在一个 CMakeLists.txt 里管理起来就非常痛苦了。有没有办法让每个模块都有自己的 CMakeLists.txt然后由一个顶层的 CMakeLists.txt 来统一管理呢