# 7.4 用指定参数定义函数或宏

**NOTE**:*此示例代码可以在* <https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-7/recipe-04> *中找到，其中包含一个C++示例。该示例在CMake 3.5版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。*

前面的示例中，我们研究了函数和宏，并使用了位置参数。这个示例中，我们将定义一个带有命名参数的函数。我们将复用第1节中的示例，使用函数和宏重用代码，而不是使用以下代码定义测试：`add_catch_test(short 1.5)`。

我们将这样调用函数:

```
add_catch_test(
    NAME
      short
  LABELS
      short
      cpp_test
  COST
      1.5
  )
```

## 准备工作

我们使用第1节中的示例，使用函数和宏重用代码，并保持C++源代码不变，文件树保持不变：

```
.
├── cmake
│     └── testing.cmake
├── CMakeLists.txt
├── src
│     ├── CMakeLists.txt
│     ├── main.cpp
│     ├── sum_integers.cpp
│     └── sum_integers.hpp
└── tests
    ├── catch.hpp
    ├── CMakeLists.txt
    └── test.cpp
```

## 具体实施

我们对CMake代码进行一些修改，如下所示:

1. `CMakeLists.txt`顶部中只增加了一行，因为我们将包括位于`cmake`下面的模块:

   ```
   list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
   ```
2. 保持`src/CMakeLists.txt`。
3. `tests/CMakeLists.txt`中，将`add_catch_test`函数定义移动到`cmake/testing.cmake`，并且定义两个测试:

   ```
   add_executable(cpp_test test.cpp)
   target_link_libraries(cpp_test sum_integers)

   include(testing)

   add_catch_test(
     NAME
         short
     LABELS
         short
         cpp_test
     COST
         1.5
     )

   add_catch_test(
     NAME
         long
     LABELS
         long
         cpp_test
     COST
         2.5
     )
   ```
4. `add_catch_test`在`cmake/testing.cmake`中定义:

   ```
   function(add_catch_test)
     set(options)
     set(oneValueArgs NAME COST)
     set(multiValueArgs LABELS DEPENDS REFERENCE_FILES)
     cmake_parse_arguments(add_catch_test
       "${options}"
       "${oneValueArgs}"
       "${multiValueArgs}"
       ${ARGN}
       )
     message(STATUS "defining a test ...")
     message(STATUS " NAME: ${add_catch_test_NAME}")
     message(STATUS " LABELS: ${add_catch_test_LABELS}")
     message(STATUS " COST: ${add_catch_test_COST}")
     message(STATUS " REFERENCE_FILES: ${add_catch_test_REFERENCE_FILES}")

     add_test(
       NAME
           ${add_catch_test_NAME}
       COMMAND
           $<TARGET_FILE:cpp_test>
       [${add_catch_test_NAME}] --success --out
           ${PROJECT_BINARY_DIR}/tests/${add_catch_test_NAME}.log --durations yes
       WORKING_DIRECTORY
           ${CMAKE_CURRENT_BINARY_DIR}
       )

     set_tests_properties(${add_catch_test_NAME}
       PROPERTIES
           LABELS "${add_catch_test_LABELS}"
       )

     if(add_catch_test_COST)
       set_tests_properties(${add_catch_test_NAME}
       PROPERTIES
           COST ${add_catch_test_COST}
       )
     endif()

     if(add_catch_test_DEPENDS)
       set_tests_properties(${add_catch_test_NAME}
         PROPERTIES
             DEPENDS ${add_catch_test_DEPENDS}
         )
     endif()

     if(add_catch_test_REFERENCE_FILES)
       file(
         COPY
             ${add_catch_test_REFERENCE_FILES}
         DESTINATION
             ${CMAKE_CURRENT_BINARY_DIR}
         )
     endif()
   endfunction()
   ```
5. 测试输出:

   ```
   $ mkdir -p build
   $ cd build
   $ cmake ..

   -- ...
   -- defining a test ...
   -- NAME: short
   -- LABELS: short;cpp_test
   -- COST: 1.5
   -- REFERENCE_FILES:
   -- defining a test ...
   -- NAME: long
   -- LABELS: long;cpp_test
   -- COST: 2.5
   -- REFERENCE_FILES:
   -- ...
   ```
6. 最后，编译并测试：

   ```
   $ cmake --build .
   $ ctest
   ```

## 工作原理

示例的特点是其命名参数，因此我们可以将重点放在`cmake/testing.cmake`模块上。CMake提供`cmake_parse_arguments`命令，我们使用函数名(`add_catch_test`)选项(我们的例子中是`none`)、单值参数(`NAME`和`COST`)和多值参数(`LABELS`、`DEPENDS`和`REFERENCE_FILES`)调用该命令:

```
function(add_catch_test)
  set(options)
  set(oneValueArgs NAME COST)
  set(multiValueArgs LABELS DEPENDS REFERENCE_FILES)
  cmake_parse_arguments(add_catch_test
    "${options}"
    "${oneValueArgs}"
    "${multiValueArgs}"
    ${ARGN}
    )
...
endfunction()
```

`cmake_parse_arguments`命令解析选项和参数，并在例子中定义如下:

* add\_catch\_test\_NAME
* add\_catch\_test\_COST
* add\_catch\_test\_LABELS
* add\_catch\_test\_DEPENDS
* add\_catch\_test\_REFERENCE\_FILES

可以查询，并在函数中使用这些变量。这种方法使我们有机会用更健壮的接口和更具有可读的函数/宏调用，来实现函数和宏。

## 更多信息

选项关键字(本例中我们没有使用)由`cmake_parse_arguments`定义为`TRUE`或`FALSE`。`add_catch_test`函数，还提供`test`命令作为一个命名参数，为了更简洁的演示，我们省略了这个参数。

**TIPS**:*`cmake_parse_arguments`命令在cmake 3.5的版本前中的`CMakeParseArguments.cmake`定义。因此，可以在`CMake/test.cmake`顶部的使用`include(CMakeParseArguments)`命令使此示例能与CMake早期版本一起工作。*