<<Modern CMake>> 翻译 2. CMake 基础
<<Modern CMake>> 翻译 2. CMake 基础
最低版本
这是每个 CMakeLists.txt
文件的第一行。CMakeLists.txt
是 CMake 所需的配置文件名称:
cmake_minimum_required(VERSION 3.1)
我们来了解一点 CMake 语法。 命令名称 cmake_minimum_required
不区分大小写,因此通常的做法是使用小写。1 这里 VERSION 是该命令所需的特殊关键字。 版本号紧跟在 VERSION 关键字之后。 与本书中的任何其他地方一样,你只需单击命令名称即可链接到官方文档,然后可以使用下拉列表切换不同版本的 CMake 文档。
这一行很特别!2 版本号也同时指明了 CMake 的行为变化。 因此,如果你设置 minimum_required
为 VERSION 2.8
,在macOS上你就会获得错误的链接行为, 例如,在最新的 CMake 版本中也是如此。 如果你把版本设置为 3.3 或更低,你会得到错误的符号隐藏行为,等等。 在 policies 有一个策略和版本列表。
在 CMake 3.12 中,可以这样写来指定支持的 CMake 版本范围,例如 VERSION 3.1...3.12
; 这意味着您最低支持 3.1,同时也测试过并支持到 3.12 的新策略。 这对于需要更好设置的用户来说很不错,并且由于语法上的技巧,它向后兼容旧版本的 CMake(尽管实际运行 CMake 3.2-3.11 只会在此示例中设置 3.1 版本的策略)。 新版本的策略对于 macOS 和 Windows 用户来说往往是最重要的,他们通常也有最新版本的 CMake。
新项目应该这样写:
cmake_minimum_required(VERSION 3.1...3.15)
if(${CMAKE_VERSION} VERSION_LESS 3.12)
cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
endif()
如果 CMake 版本小于 3.12,则 if 块将为 true,并且策略将设置为当前 CMake 版本。 如果 CMake 为 3.12 或更高,if 块将为 false,此时新语法 cmake_minimum_required
将起作用,这将能够正常工作!
警告:MSVC 的 CMake 服务器模式最初在读取此格式时有一个 bug, 因此如果您需要支持旧版 MSVC 的非命令行 Windows 版本,则需要执行以下操作:
cmake_minimum_required(VERSION 3.1)
if(${CMAKE_VERSION} VERSION_LESS 3.15)
cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
else()
cmake_policy(VERSION 3.15)
endif()
如果您确实需要在此处设置较低的版本,则可以使用 cmake_policy
有条件地增加策略级别或设置特定策略。 请至少为您的 macOS 用户执行此操作!
设置项目
现在,每个顶级 CMake 文件(CMakeLists.txt
)都有下面这一行:
project(MyProject VERSION 1.0
DESCRIPTION "非常出色的项目"
LANGUAGES CXX)
现在我们看到了更多的新语法。 字符串被引号包围起来,空格可多可少,项目名称是第一个参数(位置参数)。 这里的所有的关键字参数都是可选的。 通过 VERSION
参数,这会设置了一堆变量,比如 MyProject_VERSION
和 PROJECT_VERSION
。 LANGUAGE
可以是 C,CXX,Fortran 和 CUDA(CMake 3.7+)。 C CXX 是默认值。 在 CMake 3.9 中,DESCRIPTION 添加进来设置对项目的描述。 你可以参考 project
这个文档。
你可以通过使用 #
开头来添加 注释。 CMake 也有注释的内联语法,但很少需要,因为空格并不重要。
项目名称没什么特别之处。此时不添加任何目标。
生成可执行文件
虽然链接库更有趣,通常我们大部分时间都在生成链接库,但这里我们要从一个简单的可执行文件开始。
add_executable(one two.cpp three.h)
这里有几件要说明的事情。 one
是生成的可执行文件的名称,同时也是创建的 CMake 目标的名称(我保证你会很快听到很多关于目标的信息)。 可执行文件名称后紧接的是源文件列表,您可以根据需要列出任意数量的源文件列表。 CMake 很聪明,会根据文件扩展名正确识别源文件,所以列表中的头文件会被 CMake 理解并忽略。 大多数时候,我们在源文件列表中列出头文件的唯一原因是让它们出现在 IDE 中。 有关通用构建系统和目标的更多信息,请参见 buildsystem。
生成链接库
使用 add_library
生成链接库, 也是非常简单:
add_library(one STATIC two.cpp three.h)
您可以选择链接库类型:STATIC,SHARED 或 MODULE。 如果没有设置,CMake 会根据变量 BUILD_SHARED_LIBS
的值在 STATIC 和 SHARED 之间选择。
正如您将在下一节中看到的那样,通常您需要创建一个伪目标,也就是一个不需要编译任何文件的目标,例如,对于仅包含头文件的库。这也可以称为 INTERFACE 库; 唯一的区别是接口库不能跟文件名。
您还可以用一个现有的链接库生成一个 ALIAS
链接库,该库简单地为您提供目标的新名称。这样做的一个好处是你可以生成一个名称中带 ::
的链接库(稍后会看到)。3
配置构建目标
现在我们已经指定了目标,然后我们怎么给它添加相关信息呢?例如,它可能需要一个 include
目录:
target_include_directories(one PUBLIC include)
target_include_directories
将 include
目录添加到目标. PUBLIC
对可执行文件来说意义不大; 对于一个链接库,它让 CMake 知道链接到这个目标的任何目标也必须包含该目录。 其他选项是 PRIVATE
(仅影响当前目标,而不影响依赖项)和 INTERFACE
(仅限依赖项所需)。
现在,我们可以把目标串联起来:
add_library(another STATIC another.cpp another.h)
target_link_libraries(another PUBLIC one)
target_link_libraries
可能是 CMake 中最有用也最令人困惑的命令。 它需要一个target(another)并添加依赖目标项。 如果名为 one
的目标不存在,则它会添加指向路径上的一个叫做 one
链接库(即命令的名称)。 或者你可以给它一个完整的链接库路径。或链接器标志。 最后还有一点容易混淆的东西,那就是经典的 CMake 允许你忽略关键字 PUBLIC
,等等。 如果目标已经链接完成,尝试在链中进一步混合样式,你会收到错误。
主要关注在任何地方使用目标和关键字,这就对了。
目标可以包含目录,链接库(或链接目标),编译选项,编译定义,编译特征(参见 C++11 章节)等。 正如您将在两个包括项目章节中看到的那样,您通常可以使用目标(并始终制作目标)来表示所有你使用的链接库。 即使那不是真正的链接库的,比如 OpenMP,也可以用目标来表示。 这就是现代 CMake 很棒的原因!
开始动手实践
看看您是否可以理解以下文件操作。 它创建了一个简单的 C++11 链接库和一个使用它的程序。 没有依赖。 我稍后将使用 CMake 3.8 系统讨论更多 C++ 标准选项。
cmake_minimum_required(VERSION 3.8)
project(Calculator LANGUAGES CXX)
add_library(calclib STATIC src/calclib.cpp include/calc/lib.hpp)
target_include_directories(calclib PUBLIC include)
target_compile_features(calclib PUBLIC cxx_std_11)
add_executable(calc apps/calc.cpp)
target_link_libraries(calc PUBLIC calclib)
1. 在这本书中,我将尽可能避免向你展示错误的做事方式; 你可以在网上找到很多这方面的例子。我偶尔会提到替代做法,但除非绝对必要,否则不推荐这些。通常它们只是帮助您阅读较老的 CMake 代码。 ↩
2. 你有时会看到 FATAL_ERROR
, 在 CMake <2.6 版本中,需要使用它来支持失败,现在已经不需要了。↩
3.::
语法最初用来生成INTERFACE IMPORTED
链接库, 但是,正因为如此,大多数target_*
命令都不适用于IMPORTED
链接库。这使得它们很难自行设置。所以现在不要使用IMPORTED
关键字,请使用ALIAS
构件目标; 这在你导出目标前都能正常工作。此限制已经在 CMake 3.11 中修复。 ↩