CMake最佳實踐

前言

相信每個人都寫過CMakeLists购公，然而，“一千個讀者心中有一千個哈姆雷特”知残，一千個程序員也能寫出一千種CMakeLists比庄。這是因為CMake在發(fā)展的過程中始終保持向后兼容佳窑，在不斷添加新特性的同時，仍然保留舊的語法規(guī)則净神。這樣一來，同一個問題就會有多種寫法爱榕。雖然無論哪種寫法都可以成功構(gòu)建坡慌，但在2019年的今天，我們應(yīng)該與時俱進(jìn)跪者，摒棄不好的用法梨树，采用官方推薦的最佳用法岖寞。這就是本文的主題仗谆。

面向Target編程

首先需要明確的是，CMake本身就是一種編程語言藻雪。我們所寫的CMakeLists狸吞，其實就是在用CMake語法來編程蹋偏，實現(xiàn)構(gòu)建的功能。

我們習(xí)慣于這樣寫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)

這種寫法被無數(shù)人使用枢纠，但它存在嚴(yán)重的缺陷黎棠。請思考，如果我們構(gòu)建的是一個庫木西，當(dāng)這個庫被其它程序調(diào)用的時候随静，如何傳遞依賴？比如上面的例子叼丑，my_library依賴于OpenCV鸠信，main又依賴于my_library，那么main就會間接依賴于OpenCV爽茴。在這個例子中绰垂，my_library和main這兩個Target是放在一起創(chuàng)建的。但實際工程應(yīng)用中劲装，庫和使用該庫的程序應(yīng)該是分開構(gòu)建的胧沫，在構(gòu)建main的過程中就勢必需要獲得它所有的間接依賴，否則在編譯期可能找不到頭文件占业，在鏈接期可能出現(xiàn)“未定義的引用”绒怨。

你可能會想，間接依賴的問題不應(yīng)該由CMake自動幫我們完成嗎谦疾。從CMake設(shè)計者的角度來考慮南蹂，如果他要實現(xiàn)這一功能，就必須把include_directories中的所有目錄導(dǎo)出到間接依賴念恍。但他不能這樣做六剥，因為顯然大部分頭文件都只在內(nèi)部使用，作為API的頭文件只是一小部分峰伙。所以不同用途的頭文件必須使用不同的標(biāo)識區(qū)分，之后才可以由CMake負(fù)責(zé)導(dǎo)出词爬。

另一方面秃嗜，如果同一個CMakeLists中包含了多個Target，單一的include_directories就顯得不太合理顿膨，應(yīng)該為每個Target單獨設(shè)置锅锨。

Modern CMake

CMake從3.0開始進(jìn)入Modern時代，也就是前文所說的面向Target編程恋沃。下面我們用一個具體的例子講解如何做到這一點必搞。

例子包含一個庫MyLibrary和一個可執(zhí)行程序App，但我們會在兩個工程中分別構(gòu)建它們囊咏。

首先來看MyLibrary庫的目錄結(jié)構(gòu)：

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

頭文件和源文件不必說了恕洲，直接看怎么寫CMakeLists.txt塔橡。首先常規(guī)部分，聲明工程名稱霜第，查找依賴庫OpenCV葛家。

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

find_package(OpenCV REQUIRED)

接下來創(chuàng)建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})

與傳統(tǒng)CMake不同的是泌类，我們用target_compile_features替代了對變量CMAKE_CXX_FLAGS的賦值癞谒。用target_sources聲明源文件列表。用target_include_directories聲明頭文件包含路徑刃榨。

此外弹砚，每個命令都用到了PRIVATE和PUBLIC關(guān)鍵字。在CMake的官方說明中枢希，稱PRIVATE聲明的依賴為build-requirement桌吃，INTERFACE聲明的依賴為usage-requirement，PUBLIC聲明的依賴相當(dāng)于同時聲明了PRIVATE和INTERFACE苞轿。這里的build表明了該依賴僅存在于構(gòu)建階段茅诱，而usage則表明該依賴存在于這個庫的使用階段。舉個簡單的例子呕屎，如果我們的庫依賴于OpenCV让簿，但我們暴露給用戶的接口與OpenCV毫無關(guān)系敬察，那么這個依賴就是PRIVATE依賴秀睛。本文的案例就屬于這種情況。

接下來莲祸，安裝Target到系統(tǒng)目錄中蹂安。

## 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)

每一步都有詳細(xì)的注釋，大致流程是把生成的庫文件拷到安裝路徑下锐帜，然后把生成的MyLibraryTargets.cmake文件拷到安裝路徑下田盈，然后把頭文件、MyLibraryConfig.cmake文件也拷到安裝路徑下缴阎。

需要特別指出的是允瞧，MyLibraryConfig.cmake文件是需要開發(fā)者自己寫的，該文件的用途是讓使用者通過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找到依賴庫畦韭，這是我們作為庫的作者所必須負(fù)責(zé)做的事情（因為用戶根本不知道我們用到了OpenCV）。第二是導(dǎo)入MyLibraryTargets.cmake肛跌，這個文件里保存了前面我們聲明的各種依賴的名稱和路徑艺配。

現(xiàn)在察郁，我們就可以編譯、安裝MyLibrary转唉。接下來皮钠，看看怎么使用我們剛剛安裝好的庫。

App工程的目錄結(jié)構(gòu)如下：

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)

可以說是非常清爽了赠法，完全不必關(guān)心對于OpenCV的間接依賴鳞芙。鏈接庫的方式也從傳統(tǒng)的${MyLibrary_LIBRARIES}變成了MyLibrary::MyLibrary。

這個示例到這里就結(jié)束了期虾，雖然非常簡單原朝，但已經(jīng)給出了Modern CMake的大體框架。如果每個C++開發(fā)者都遵循Modern CMake的構(gòu)建模式镶苞，整個C++開源社區(qū)將會變得更加高效喳坠。

完整代碼可以從我的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