CMake最佳实践

前言

相信每个人都写过CMakeLists，然而，“一千个读者心中有一千个哈姆雷特”，一千个程序员也能写出一千种CMakeLists。这是因为CMake在发展的过程中始终保持向后兼容，在不断添加新特性的同时，仍然保留旧的语法规则。这样一来，同一个问题就会有多种写法。虽然无论哪种写法都可以成功构建，但在2019年的今天，我们应该与时俱进，摒弃不好的用法，采用官方推荐的最佳用法。这就是本文的主题。

面向Target编程

首先需要明确的是，CMake本身就是一种编程语言。我们所写的CMakeLists，其实就是在用CMake语法来编程，实现构建的功能。

我们习惯于这样写CMakeLists：

find_package(OpenCV REQUIRED) 

include_directories(${OpenCV_INCLUDE_DIRS})

add_library(my_library SHARED my_library.cpp)
target_link_libraries(my_library ${OpenCV_LIBRARIES})

add_executable(main main.cpp)
target_link_libraries(main my_library)

这种写法被无数人使用，但它存在严重的缺陷。请思考，如果我们构建的是一个库，当这个库被其它程序调用的时候，如何传递依赖？比如上面的例子，my_library依赖于OpenCV，main又依赖于my_library，那么main就会间接依赖于OpenCV。在这个例子中，my_library和main这两个Target是放在一起创建的。但实际工程应用中，库和使用该库的程序应该是分开构建的，在构建main的过程中就势必需要获得它所有的间接依赖，否则在编译期可能找不到头文件，在链接期可能出现“未定义的引用”。

你可能会想，间接依赖的问题不应该由CMake自动帮我们完成吗。从CMake设计者的角度来考虑，如果他要实现这一功能，就必须把include_directories中的所有目录导出到间接依赖。但他不能这样做，因为显然大部分头文件都只在内部使用，作为API的头文件只是一小部分。所以不同用途的头文件必须使用不同的标识区分，之后才可以由CMake负责导出。

另一方面，如果同一个CMakeLists中包含了多个Target，单一的include_directories就显得不太合理，应该为每个Target单独设置。

Modern CMake

CMake从3.0开始进入Modern时代，也就是前文所说的面向Target编程。下面我们用一个具体的例子讲解如何做到这一点。

例子包含一个库MyLibrary和一个可执行程序App，但我们会在两个工程中分别构建它们。

首先来看MyLibrary库的目录结构：

my_library
-- cmake
   -- MyLibraryConfig.cmake
-- include
   -- my_library
      -- my_library.h
-- src
   -- my_library.cpp
-- CMakeLists.txt

头文件和源文件不必说了，直接看怎么写CMakeLists.txt。首先常规部分，声明工程名称，查找依赖库OpenCV。

cmake_minimum_required(VERSION 3.5)
project(MyLibrary VERSION 1.0.0 LANGUAGES CXX)

find_package(OpenCV REQUIRED)

接下来创建Target。

## Add an empty library first. Then set properties for it.
add_library(MyLibrary)
target_compile_features(MyLibrary PRIVATE cxx_std_11)
target_sources(MyLibrary PRIVATE src/my_library.cpp)
target_include_directories(MyLibrary
        PUBLIC
            $<INSTALL_INTERFACE:include>
            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
        PRIVATE
            ${OpenCV_INCLUDE_DIRS}
        )
target_link_libraries(MyLibrary PRIVATE ${OpenCV_LIBRARIES})

与传统CMake不同的是，我们用target_compile_features替代了对变量CMAKE_CXX_FLAGS的赋值。用target_sources声明源文件列表。用target_include_directories声明头文件包含路径。

此外，每个命令都用到了PRIVATE和PUBLIC关键字。在CMake的官方说明中，称PRIVATE声明的依赖为build-requirement，INTERFACE声明的依赖为usage-requirement，PUBLIC声明的依赖相当于同时声明了PRIVATE和INTERFACE。这里的build表明了该依赖仅存在于构建阶段，而usage则表明该依赖存在于这个库的使用阶段。举个简单的例子，如果我们的库依赖于OpenCV，但我们暴露给用户的接口与OpenCV毫无关系，那么这个依赖就是PRIVATE依赖。本文的案例就属于这种情况。

接下来，安装Target到系统目录中。

## We firstly install the generated libraries to /usr/local. The path
## comes from GNUInstallDirs, which includes lots of predefined system
## paths.
include(GNUInstallDirs)
install(TARGETS MyLibrary
        EXPORT MyLibraryTargets
        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
        )

## Then we install the auto-generated target file, in which have many
## exported names and paths of our target.
install(EXPORT MyLibraryTargets
        FILE MyLibraryTargets.cmake
        NAMESPACE MyLibrary::
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyLibrary)

## And we should install the header files.
install(DIRECTORY include/
        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
        )

## Finally, install the <package>Config.cmake file, which is provided
## for users.
install(FILES ${CMAKE_CURRENT_LIST_DIR}/cmake/MyLibraryConfig.cmake
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyLibrary)

每一步都有详细的注释，大致流程是把生成的库文件拷到安装路径下，然后把生成的MyLibraryTargets.cmake文件拷到安装路径下，然后把头文件、MyLibraryConfig.cmake文件也拷到安装路径下。

需要特别指出的是，MyLibraryConfig.cmake文件是需要开发者自己写的，该文件的用途是让使用者通过find_packge找到这个库。好在这个文件并不难写，只有下面几行。

## Get the directory path of the <target>.cmake file
get_filename_component(MyLibrary_CMAKE_DIR "${CMAKE_CURRENT_LIST_FILE}" DIRECTORY)

## Add the dependencies of our library
include(CMakeFindDependencyMacro)
find_dependency(OpenCV REQUIRED)

## Import the targets
if(NOT TARGET MyLibrary::MyLibrary)
    include("${MyLibrary_CMAKE_DIR}/MyLibraryTargets.cmake")
endif()

里面总共做了两件事，第一是用find_dependency找到依赖库，这是我们作为库的作者所必须负责做的事情（因为用户根本不知道我们用到了OpenCV）。第二是导入MyLibraryTargets.cmake，这个文件里保存了前面我们声明的各种依赖的名称和路径。

现在，我们就可以编译、安装MyLibrary。接下来，看看怎么使用我们刚刚安装好的库。

App工程的目录结构如下：

app
-- main.cpp
-- CMakeLists.txt

CMakeLists.txt是这样写的：

cmake_minimum_required(VERSION 3.5)
project(App VERSION 1.0.0 LANGUAGES CXX)

find_package(MyLibrary REQUIRED)

## Create the executable target
add_executable(App main.cpp)
target_compile_features(App PRIVATE cxx_std_11)
target_link_libraries(App PRIVATE MyLibrary::MyLibrary)

可以说是非常清爽了，完全不必关心对于OpenCV的间接依赖。链接库的方式也从传统的${MyLibrary_LIBRARIES}变成了MyLibrary::MyLibrary。

这个示例到这里就结束了，虽然非常简单，但已经给出了Modern CMake的大体框架。如果每个C++开发者都遵循Modern CMake的构建模式，整个C++开源社区将会变得更加高效。

完整代码可以从我的GitHub下载：jingedawang/modern_cmake_example

参考资料

Meeting C++ 2018: More Modern CMake Deniz Bahadir
C++ Now 2017: Effective CMake Daniel Pfeifer
It's Time To Do CMake Right Pablo
An Introduction to Modern CMake Henry Schreiner
CMake Documentation