7.1 使用函數和宏重用代碼 · cmake-cookbook

# 7.1 使用函數和宏重用代碼 **NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-7/recipe-01 中找到，其中包含一個C++例子。該示例在CMake 3.5版(或更高版本)中是有效的，并且已經在GNU/Linux、macOS和Windows上進行過測試。* 任何編程語言中，函數允許我們抽象(隱藏)細節并避免代碼重復，CMake也不例外。本示例中，我們將以宏和函數為例進行討論，并介紹一個宏，以便方便地定義測試和設置測試的順序。我們的目標是定義一個宏，能夠替換`add_test `和`set_tests_properties`，用于定義每組和設置每個測試的預期開銷(第4章，第8節)。 ## 準備工作我們將基于第4章第2節中的例子。`main.cpp`、`sum_integers.cpp`和`sum_integers.hpp`文件不變，用來計算命令行參數提供的整數隊列的和。單元測試(`test.cpp`)的源代碼也沒有改變。我們還需要Catch 2頭文件，` catch.hpp `。與第4章相反，我們將把源文件放到子目錄中，并形成以下文件樹(稍后我們將討論CMake代碼): ```shell . ├── CMakeLists.txt ├── src │ ├── CMakeLists.txt │ ├── main.cpp │ ├── sum_integers.cpp │ └── sum_integers.hpp └── tests ├── catch.hpp ├── CMakeLists.txt └── test.cpp ``` ## 具體實施 1. 定義了CMake最低版本、項目名稱和支持的語言，并要求支持C++11標準: ```cmake cmake_minimum_required(VERSION 3.5 FATAL_ERROR) project(recipe-01 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_EXTENSIONS OFF) set(CMAKE_CXX_STANDARD_REQUIRED ON) ``` 2. 根據GNU標準定義`binary`和`library`路徑: ```cmake include(GNUInstallDirs) set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}) set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}) set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}) ``` 3. 最后，使用`add_subdirectory`調用`src/CMakeLists.txt`和`tests/CMakeLists.txt`: ```cmake add_subdirectory(src) enable_testing() add_subdirectory(tests) ``` 4. `src/CMakeLists.txt`定義了源碼目標: ```cmake set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON) add_library(sum_integers sum_integers.cpp) add_executable(sum_up main.cpp) target_link_libraries(sum_up sum_integers) ``` 5. `tests/CMakeLists.txt`中，構建并鏈接`cpp_test`可執行文件: ```cmake add_executable(cpp_test test.cpp) target_link_libraries(cpp_test sum_integers) ``` 6. 定義一個新宏`add_catch_test`: ```cmake macro(add_catch_test _name _cost) math(EXPR num_macro_calls "${num_macro_calls} + 1") message(STATUS "add_catch_test called with ${ARGC} arguments: ${ARGV}") set(_argn "${ARGN}") if(_argn) message(STATUS "oops - macro received argument(s) we did not expect: ${ARGN}") endif() add_test( NAME ${_name} COMMAND $<TARGET_FILE:cpp_test> [${_name}] --success --out ${PROJECT_BINARY_DIR}/tests/${_name}.log --durations yes WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} ) set_tests_properties( ${_name} PROPERTIES COST ${_cost} ) endmacro() ``` 7. 最后，使用`add_catch_test`定義了兩個測試。此外，還設置和打印了變量的值: ```cmake set(num_macro_calls 0) add_catch_test(short 1.5) add_catch_test(long 2.5 extra_argument) message(STATUS "in total there were ${num_macro_calls} calls to add_catch_test") ``` 8. 現在，進行測試。配置項目(輸出行如下所示): ```cmake $ mkdir -p build $ cd build $ cmake .. -- ... -- add_catch_test called with 2 arguments: short;1.5 -- add_catch_test called with 3 arguments: long;2.5;extra_argument -- oops - macro received argument(s) we did not expect: extra_argument -- in total there were 2 calls to add_catch_test -- ... ``` 9. 最后，構建并運行測試: ```shell $ cmake --build . $ ctest ``` 10. 長時間的測試會先開始: ```shell Start 2: long 1/2 Test #2: long ............................. Passed 0.00 sec Start 1: short 2/2 Test #1: short ............................ Passed 0.00 sec 100% tests passed, 0 tests failed out of 2 ``` ## 工作原理這個配置中的新添加了`add_catch_test`宏。這個宏需要兩個參數`_name`和`_cost`，可以在宏中使用這些參數來調用`add_test`和`set_tests_properties`。參數前面的下劃線，是為了向讀者表明這些參數只能在宏中訪問。另外，宏自動填充了`${ARGC}`(參數數量)和`${ARGV}`(參數列表)，我們可以在輸出中驗證了這一點: ```shell -- add_catch_test called with 2 arguments: short;1.5 -- add_catch_test called with 3 arguments: long;2.5;extra_argument ``` 宏還定義了`${ARGN}`，用于保存最后一個參數之后的參數列表。此外，我們還可以使用`${ARGV0}`、`${ARGV1}`等來處理參數。我們演示一下，如何捕捉到調用中的額外參數(`extra_argument`): ```camek add_catch_test(long 2.5 extra_argument) ``` 我們使用了以下方法: ```cmake set(_argn "${ARGN}") if(_argn) message(STATUS "oops - macro received argument(s) we did not expect: ${ARGN}") endif() ``` 這個`if`語句中，我們引入一個新變量，但不能直接查詢`ARGN`，因為它不是通常意義上的CMake變量。使用這個宏，我們可以通過它們的名稱和命令來定義測試，還可以指示預期的開銷，這會讓耗時長的測試在耗時短測試之前啟動，這要歸功于`COST`屬性。我們可以用一個函數來實現它，而不是使用相同語法的宏: ```cmake function(add_catch_test _name _cost) ... endfunction() ``` 宏和函數之間的區別在于它們的變量范圍。宏在調用者的范圍內執行，而函數有自己的變量范圍。換句話說，如果我們使用宏，需要設置或修改對調用者可用的變量。如果不去設置或修改輸出變量，最好使用函數。我們注意到，可以在函數中修改父作用域變量，但這必須使用`PARENT_SCOPE`顯式表示: ```cmake set(variable_visible_outside "some value" PARENT_SCOPE) ``` 為了演示作用域，我們在定義宏之后編寫了以下調用: ```cmake set(num_macro_calls 0) add_catch_test(short 1.5) add_catch_test(long 2.5 extra_argument) message(STATUS "in total there were ${num_macro_calls} calls to add_catch_test") ``` 在宏內部，將`num_macro_calls`加1: ```cmake math(EXPR num_macro_calls "${num_macro_calls} + 1") ``` 這時產生的輸出: ```cmake -- in total there were 2 calls to add_catch_test ``` 如果我們將宏更改為函數，測試仍然可以工作，但是`num_macro_calls`在父范圍內的所有調用中始終為0。將CMake宏想象成類似函數是很有用的，這些函數被直接替換到它們被調用的地方(在C語言中內聯)。將CMake函數想象成黑盒函數很有必要。黑盒中，除非顯式地將其定義為`PARENT_SCOPE`，否則不會返回任何內容。CMake中的函數沒有返回值。 ## 更多信息可以在宏中嵌套函數調用，也可以在函數中嵌套宏調用，但是這就需要仔細考慮變量的作用范圍。如果功能可以使用函數實現，那么這可能比宏更好，因為它對父范圍狀態提供了更多的默認控制。我們還應該提到在`src/cmakelist .txt`中使用`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`: ```cmake set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON) ``` 這個命令會將當前目錄，添加到`CMakeLists.txt`中定義的所有目標的`interface_include_directory`屬性中。換句話說，我們不需要使用`target_include_directory`來添加`cpp_test`所需頭文件的位置。