CMakeLists.txt 語法介紹與例項演練

阿新 • • 發佈：2019-01-25

一、Cmake 簡介

cmake 是一個跨平臺、開源的構建系統。它是一個集軟體構建、測試、打包於一身的軟體。它使用與平臺和編譯器獨立的配置檔案來對軟體編譯過程進行控制。

二、常用命令

1. 指定 cmake 的最小版本

cmake_minimum_required(VERSION 3.4.1)

這行命令是可選的，我們可以不寫這句話，但在有些情況下，如果 CMakeLists.txt 檔案中使用了一些高版本 cmake 特有的一些命令的時候，就需要加上這樣一行，提醒使用者升級到該版本之後再執行 cmake。

2. 設定專案名稱

project(demo)

這個命令不是強制性的，但最好都加上。它會引入兩個變數 demo_BINARY_DIR 和 demo_SOURCE_DIR，同時，cmake 自動定義了兩個等價的變數 PROJECT_BINARY_DIR 和 PROJECT_SOURCE_DIR。

3. 設定編譯型別

add_executable(demo demo.cpp) # 生成可執行檔案
add_library(common STATIC util.cpp) # 生成靜態庫
add_library(common SHARED util.cpp) # 生成動態庫或共享庫

add_library 預設生成是靜態庫，通過以上命令生成檔名字，

在 Linux 下是：
demo
libcommon.a
libcommon.so
在 Windows 下是：
demo.exe
common.lib
common.dll

4. 指定編譯包含的原始檔

4.1 明確指定包含哪些原始檔

add_library(demo demo.cpp test.cpp util.cpp)

4.2 搜尋所有的 cpp 檔案

aux_source_directory(dir VAR) 發現一個目錄下所有的原始碼檔案並將列表儲存在一個變數中。

aux_source_directory(. SRC_LIST) # 搜尋當前目錄下的所有.cpp檔案
add_library(demo ${SRC_LIST})

4.3 自定義搜尋規則

file(GLOB SRC_LIST "*.cpp" "protocol/*.cpp")
add_library(demo ${SRC_LIST})
# 或者
file(GLOB SRC_LIST "*.cpp")
file(GLOB SRC_PROTOCOL_LIST "protocol/*.cpp")
add_library(demo ${SRC_LIST} ${SRC_PROTOCOL_LIST})
# 或者
aux_source_directory(. SRC_LIST)
aux_source_directory(protocol SRC_PROTOCOL_LIST)
add_library(demo ${SRC_LIST} ${SRC_PROTOCOL_LIST})

5. 查詢指定的庫檔案

find_library(VAR name path)查詢到指定的預編譯庫，並將它的路徑儲存在變數中。
預設的搜尋路徑為 cmake 包含的系統庫，因此如果是 NDK 的公共庫只需要指定庫的 name 即可。

find_library( # Sets the name of the path variable.
              log-lib
 
              # Specifies the name of the NDK library that
              # you want CMake to locate.
              log )

類似的命令還有 find_file()、find_path()、find_program()、find_package()。

6. 設定包含的目錄

include_directories(
    ${CMAKE_CURRENT_SOURCE_DIR}
    ${CMAKE_CURRENT_BINARY_DIR}
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

Linux 下還可以通過如下方式設定包含的目錄

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -I${CMAKE_CURRENT_SOURCE_DIR}")

7. 設定連結庫搜尋目錄

link_directories(
    ${CMAKE_CURRENT_SOURCE_DIR}/libs
)

Linux 下還可以通過如下方式設定包含的目錄

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -L${CMAKE_CURRENT_SOURCE_DIR}/libs")

8. 設定 target 需要連結的庫

target_link_libraries( # 目標庫
                       demo
 
                       # 目標庫需要連結的庫
                       # log-lib 是上面 find_library 指定的變數名
                       ${log-lib} )

在 Windows 下，系統會根據連結庫目錄，搜尋xxx.lib 檔案，Linux 下會搜尋 xxx.so 或者 xxx.a 檔案，如果都存在會優先連結動態庫（so 字尾）。

8.1 指定連結動態庫或靜態庫

target_link_libraries(demo libface.a) # 連結libface.a
target_link_libraries(demo libface.so) # 連結libface.so

8.2 指定全路徑

target_link_libraries(demo ${CMAKE_CURRENT_SOURCE_DIR}/libs/libface.a)
target_link_libraries(demo ${CMAKE_CURRENT_SOURCE_DIR}/libs/libface.so)

8.3 指定連結多個庫

target_link_libraries(demo
    ${CMAKE_CURRENT_SOURCE_DIR}/libs/libface.a
    boost_system.a
    boost_thread
    pthread)

9. 設定變數

9.1 set 直接設定變數的值

set(SRC_LIST main.cpp test.cpp)
add_executable(demo ${SRC_LIST})

9.2 set 追加設定變數的值

set(SRC_LIST main.cpp)
set(SRC_LIST ${SRC_LIST} test.cpp)
add_executable(demo ${SRC_LIST})

9.3 list 追加或者刪除變數的值

set(SRC_LIST main.cpp)
list(APPEND SRC_LIST test.cpp)
list(REMOVE_ITEM SRC_LIST main.cpp)
add_executable(demo ${SRC_LIST})

10. 條件控制

10.1 if…elseif…else…endif

邏輯判斷和比較：
if (expression)：expression 不為空（0,N,NO,OFF,FALSE,NOTFOUND）時為真
if (not exp)：與上面相反
if (var1 AND var2)
if (var1 OR var2)
if (COMMAND cmd)：如果 cmd 確實是命令並可呼叫為真
if (EXISTS dir) if (EXISTS file)：如果目錄或檔案存在為真
if (file1 IS_NEWER_THAN file2)：當 file1 比 file2 新，或 file1/file2 中有一個不存在時為真，檔名需使用全路徑
if (IS_DIRECTORY dir)：當 dir 是目錄時為真
if (DEFINED var)：如果變數被定義為真
if (var MATCHES regex)：給定的變數或者字串能夠匹配正則表示式 regex 時為真，此處 var 可以用 var 名，也可以用 ${var}
if (string MATCHES regex)

數字比較：
if (variable LESS number)：LESS 小於
if (string LESS number)
if (variable GREATER number)：GREATER 大於
if (string GREATER number)
if (variable EQUAL number)：EQUAL 等於
if (string EQUAL number)

字母表順序比較：
if (variable STRLESS string)
if (string STRLESS string)
if (variable STRGREATER string)
if (string STRGREATER string)
if (variable STREQUAL string)
if (string STREQUAL string)
示例：

if(MSVC)
    set(LINK_LIBS common)
else()
    set(boost_thread boost_log.a boost_system.a)
endif()
target_link_libraries(demo ${LINK_LIBS})
# 或者
if(UNIX)
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11 -fpermissive -g")
else()
    add_definitions(-D_SCL_SECURE_NO_WARNINGS
    D_CRT_SECURE_NO_WARNINGS
    -D_WIN32_WINNT=0x601
    -D_WINSOCK_DEPRECATED_NO_WARNINGS)
endif()
 
if(${CMAKE_BUILD_TYPE} MATCHES "debug")
    ...
else()
    ...
endif()

10.2 while…endwhile

while(condition)
    ...
endwhile()

10.3 foreach…endforeach

foreach(loop_var RANGE start stop [step])
    ...
endforeach(loop_var)

start 表示起始數，stop 表示終止數，step 表示步長，示例：

foreach(i RANGE 1 9 2)
    message(${i})
endforeach(i)
# 輸出：13579

11. 列印資訊

message(${PROJECT_SOURCE_DIR})
message("build with debug mode")
message(WARNING "this is warnning message")
message(FATAL_ERROR "this build has many error") # FATAL_ERROR 會導致編譯失敗

12. 包含其它 cmake 檔案

include(./common.cmake) # 指定包含檔案的全路徑
include(def) # 在搜尋路徑中搜索def.cmake檔案
set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake) # 設定include的搜尋路徑

三、常用變數

1. 預定義變數

PROJECT_SOURCE_DIR：工程的根目錄
PROJECT_BINARY_DIR：執行 cmake 命令的目錄，通常是 ${PROJECT_SOURCE_DIR}/build
PROJECT_NAME：返回通過 project 命令定義的專案名稱
CMAKE_CURRENT_SOURCE_DIR：當前處理的 CMakeLists.txt 所在的路徑
CMAKE_CURRENT_BINARY_DIR：target 編譯目錄
CMAKE_CURRENT_LIST_DIR：CMakeLists.txt 的完整路徑
CMAKE_CURRENT_LIST_LINE：當前所在的行
CMAKE_MODULE_PATH：定義自己的 cmake 模組所在的路徑，SET(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)，然後可以用INCLUDE命令來呼叫自己的模組
EXECUTABLE_OUTPUT_PATH：重新定義目標二進位制可執行檔案的存放位置
LIBRARY_OUTPUT_PATH：重新定義目標連結庫檔案的存放位置

2. 環境變數

使用環境變數

 $ENV{Name}

寫入環境變數

 set(ENV{Name} value) # 這裡沒有“$”符號

3. 系統資訊

CMAKE_MAJOR_VERSION：cmake 主版本號，比如 3.4.1 中的 3
CMAKE_MINOR_VERSION：cmake 次版本號，比如 3.4.1 中的 4
CMAKE_PATCH_VERSION：cmake 補丁等級，比如 3.4.1 中的 1
CMAKE_SYSTEM：系統名稱，比如 Linux-2.6.22
CMAKE_SYSTEM_NAME：不包含版本的系統名，比如 Linux
CMAKE_SYSTEM_VERSION：系統版本，比如 2.6.22
CMAKE_SYSTEM_PROCESSOR：處理器名稱，比如 i686
UNIX：在所有的類 UNIX 平臺下該值為 TRUE，包括 OS X 和 cygwin
WIN32：在所有的 win32 平臺下該值為 TRUE，包括 cygwin

4. 主要開關選項

BUILD_SHARED_LIBS：這個開關用來控制預設的庫編譯方式，如果不進行設定，使用 add_library 又沒有指定庫型別的情況下，預設編譯生成的庫都是靜態庫。如果 set(BUILD_SHARED_LIBS ON) 後，預設生成的為動態庫
CMAKE_C_FLAGS：設定 C 編譯選項，也可以通過指令 add_definitions() 新增
CMAKE_CXX_FLAGS：設定 C++ 編譯選項，也可以通過指令 add_definitions() 新增

add_definitions(-DENABLE_DEBUG -DABC) # 引數之間用空格分隔

四、專案示例

1. 簡單專案（單個原始檔）

一個經典的 C 程式，如何通過 cmake 來編譯呢？

1.1 新建檔案 main.c

#include <stdio.h>
int main() {
    printf("Hello World!/n");
    return 0;
}

1.2 新建檔案 CMakeLists.txt（命名必須是 CMakeLists.txt，注意大小寫和不要漏字母）

project(HELLO)
add_executable(hello main.c)

1.3 編譯和執行

新建一個 build 資料夾，目錄情況如下：

為什麼要新建一個 build 資料夾？
一般我們採用 cmake 的 out-of-source 方式來構建（即生成的中間產物和原始碼分離），這樣做可以讓生成的檔案和原始檔不會弄混，且目錄結構看起來也會清晰明瞭。所以推薦使用這種方式，至於這個資料夾的命名並無限制，我們習慣命名為 build。

依次執行以下命令：

cd build
cmake ..

首先進入到 build 目錄，然後就是 cmake .. 命令，另外要注意將 cmake 配置到環境變數中去才可直接使用，否則需要使用絕對路徑，.. 表示上一級目錄，cmake 會在上一級目錄下找到 CMakeLists.txt 檔案並編譯，並生成如下圖所示的一些中間檔案：

直接執行 make 命令，生成可執行程式，如下圖：

執行程式，如下所示：執行程式，如下所示：

2. 複雜專案（多個目錄，多個原始檔，多個專案）

目錄結構如下：

demo 根目錄下的 CMakeLists.txt 檔案如下：

cmake_minimum_required (VERSION 2.8)
project(demo)
aux_source_directory(. DIR_SRCS)
# 新增math子目錄
add_subdirectory(math)
# 指定生成目標
add_executable(demo ${DIR_SRCS})
# 新增連結庫
target_link_libraries(demo MathFunctions)

math 目錄下的 CMakeLists.txt 檔案如下：

aux_source_directory(. DIR_LIB_SRCS)
# 生成連結庫
add_library(MathFunctions ${DIR_LIB_SRCS})

3. 自定義編譯選項

cmake 允許為專案增加編譯選項，從而可以根據使用者的環境和需求選擇最合適的編譯方案。
例如，可以將 MathFunctions 庫設為一個可選的庫，如果該選項為 ON ，就使用該庫定義的數學函式來進行運算，否則就呼叫標準庫中的數學函式庫。
修改根目錄下的 CMakeLists.txt 檔案如下：

# CMake 最低版本號要求
cmake_minimum_required (VERSION 2.8)
# 專案資訊
project (Demo)
# 加入一個配置標頭檔案，用於處理 CMake 對原始碼的設定
configure_file (
    "${PROJECT_SOURCE_DIR}/config.h.in"
    "${PROJECT_BINARY_DIR}/config.h"
    )
# 是否使用自己的 MathFunctions 庫
option (USE_MYMATH
        "Use provided math implementation" ON)
# 是否加入 MathFunctions 庫
if (USE_MYMATH)
    include_directories ("${PROJECT_SOURCE_DIR}/math")
    add_subdirectory (math)
    set (EXTRA_LIBS ${EXTRA_LIBS} MathFunctions)
endif (USE_MYMATH)
# 查詢當前目錄下的所有原始檔
# 並將名稱儲存到 DIR_SRCS 變數
aux_source_directory(. DIR_SRCS)
# 指定生成目標
add_executable(Demo ${DIR_SRCS})
target_link_libraries (Demo ${EXTRA_LIBS})

configure_file 命令用於加入一個配置標頭檔案 config.h ，這個檔案由 cmake 從 config.h.in 生成，通過這樣的機制，將可以通過預定義一些引數和變數來控制程式碼的生成。
option 命令添加了一個 USE_MYMATH 選項，並且預設值為 ON 。根據 USE_MYMATH 變數的值來決定是否使用我們自己編寫的 MathFunctions 庫。

修改 main.cc 檔案，讓其根據 USE_MYMATH 的預定義值來決定是否呼叫標準庫還是MathFunctions 庫：

#include "config.h"
#ifdef USE_MYMATH
    #include "math/MathFunctions.h"
#else
    #include
#endif
 
int main(int argc, char *argv[])
{
    if (argc < 3){
        printf("Usage: %s base exponent \n", argv[0]);
        return 1;
    }
    double base = atof(argv[1]);
    int exponent = atoi(argv[2]);
 
#ifdef USE_MYMATH
    printf("Now we use our own Math library. \n");
    double result = power(base, exponent);
#else
    printf("Now we use the standard library. \n");
    double result = pow(base, exponent);
#endif
    printf("%g ^ %d is %g\n", base, exponent, result);
    return 0;
}

編寫 config.h.in 檔案
注意 main.cc 的第一行，這裡引用了一個 config.h 檔案，這個檔案預定義了 USE_MYMATH 的值。但我們並不直接編寫這個檔案，為了方便從 CMakeLists.txt 中匯入配置，我們編寫一個 config.h.in 檔案，內容如下：

#cmakedefine USE_MYMATH

這樣 cmake 會自動根據 CMakeLists.txt 配置檔案中的設定自動生成 config.h 檔案。

其它：