cmake_parse_arguments()构建清晰灵活的 CMake 函数接口

使用 `cmake_parse_arguments()` 构建清晰、灵活的 CMake 函数接口详解

在编写复杂的 CMake 函数或宏时，解析用户传入的参数是一项核心任务。相比手动解析 ${ARGV} 或 ${ARGN} 的繁琐做法，CMake 提供的 cmake_parse_arguments() 是一种更清晰、高效、可维护的方式。

本文将从基础语法讲起，结合多个实际例子，系统讲解 cmake_parse_arguments() 的使用方法、优势以及注意事项。

基础语法

cmake 复制代码

cmake_parse_arguments(PREFIX
  <noValueKeywords>
  <singleValueKeywords>
  <multiValueKeywords>
  ${ARGN})

PREFIX：用于生成变量前缀（如 ARG_ENABLE_NET）
noValueKeywords：只需出现即可为 TRUE 的布尔参数
singleValueKeywords：后面跟一个值的参数
multiValueKeywords：后面跟多个值的参数（通常为列表）
${ARGN}：表示传入的可变参数

CMake 关键字类型	类似命令行参数	说明
noValues	`--verbose`	出现即启用，布尔型
singleValues	`--target myApp`	后接一个值
multiValues	`--sources a.cpp b.cpp`	后接多个值（一般是文件列表）

示例代码

cmake 复制代码

function(func)
  set(prefix ARG)
  set(noValues ENABLE_NET COOL_STUFF)
  set(singleValues TARGET)
  set(multiValues SOURCES IMAGES)

  include(CMakeParseArguments)
  cmake_parse_arguments(${prefix}
    "${noValues}"
    "${singleValues}"
    "${multiValues}"
    ${ARGN})

  message("Option summary:")
  foreach(arg IN LISTS noValues)
    if(${${prefix}_${arg}})
      message(" ${arg} enabled")
    else()
      message(" ${arg} disabled")
    endif()
  endforeach()

  foreach(arg IN LISTS singleValues multiValues)
    message(" ${arg} = ${${prefix}_${arg}}")
  endforeach()
endfunction()

调用示例：

cmake 复制代码

func(SOURCES main.cpp utils.cpp TARGET myApp ENABLE_NET)
func(COOL_STUFF TARGET dummy IMAGES logo.png banner.png)

复制代码

Option summary:
 ENABLE_NET enabled
 COOL_STUFF disabled
 TARGET = myApp
 SOURCES = main.cpp;utils.cpp
 IMAGES = 
 
Option summary:
 ENABLE_NET disabled
 COOL_STUFF enabled
 TARGET = dummy
 SOURCES = 
 IMAGES = logo.png;banner.png

为什么使用 `cmake_parse_arguments()`？

清晰的结构

你可以清楚地区分哪些参数是开关（布尔），哪些是单值，哪些是多值。
避免手动解析错误

传统写法使用 while() + list(GET ...) 解析 ${ARGV}，容易出错。cmake_parse_arguments() 自动完成所有解析工作。
可预测的变量命名

每个参数会被映射到形如 ${PREFIX_KEYWORD} 的变量，如：
ARG_ENABLE_NET, ARG_TARGET, ARG_SOURCES

统一命名让代码更简洁，逻辑更清晰。
调用者顺序自由

参数顺序不固定，使用者可以按任何顺序组合调用函数，函数本体依然能准确解析。

`prefix` 是什么意思？

cmake 复制代码

set(prefix ARG)

这句的作用是设定所有变量的前缀。例如：

cmake 复制代码

cmake_parse_arguments(${prefix} ...)

等价于：

cmake 复制代码

cmake_parse_arguments(ARG ...)

所以在函数体内你会获得形如：

ARG_ENABLE_NET
ARG_TARGET
ARG_SOURCES

的变量，可以直接使用。你也可以用别的前缀（如 MYFUNC_），这样可以同时定义多个函数而不互相冲突。

参数类型详细解释

参数类别	关键字示例	调用方式	解析结果
noValues	ENABLE_NET	`func(ENABLE_NET)`	`ARG_ENABLE_NET = TRUE`
singleValue	TARGET	`func(TARGET app)`	`ARG_TARGET = app`
multiValue	SOURCES, IMAGES	`func(SOURCES a.cpp b.cpp)`	`ARG_SOURCES = a.cpp;b.cpp` (列表)

常见限制与注意事项

关键字不能重复出现在多个分类中

cmake 复制代码

# 错误示例
set(singleValues SOURCES)
set(multiValues SOURCES)  # 冲突！

每个关键字必须是单词

不能写成 "ENABLE NET"，否则会被拆成两个关键字。
多值参数会"吃"尽可能多的值

直到遇到下一个合法关键字为止，所以关键字必须准确匹配。

多个关键字可以一起定义吗？

当然可以！

cmake 复制代码

set(multiValues SOURCES IMAGES FILES CONFIGS HEADERS ...)

是否有上限？

理论上没有上限，你可以写几十个关键字也没问题，只要它们合法、互不冲突，CMake 都能解析。

实用建议

虽然没有硬性限制，但为保证代码的可读性和维护性，推荐将关键字分组管理：

cmake 复制代码

set(resourceKeys IMAGES FILES)
set(sourceKeys SOURCES HEADERS)
set(multiValues ${resourceKeys} ${sourceKeys})

高级技巧建议

动态前缀支持

你可以把 prefix 作为函数参数，让调用者传入不同的前缀，实现函数行为复用。

cmake 复制代码

function(myfunc prefix)
  cmake_parse_arguments(${prefix} ... ${ARGN})
endfunction()

myfunc(MYLIB SOURCES a.cpp b.cpp)

这样会自动生成 MYLIB_SOURCES 变量，便于组件隔离。

总结

特性	优点
关键字参数解析	支持布尔、单值、多值
自动生成前缀变量	简化代码，提高可读性
支持参数顺序任意	调用更灵活
可维护性强	易于添加/扩展参数
多个关键字支持	理论无限制，推荐有结构地组织关键字
替代手动参数提取	避免 `list(GET ARGV...)` 等易错逻辑

cmake_parse_arguments()构建清晰灵活的 CMake 函数接口

使用 cmake_parse_arguments() 构建清晰、灵活的 CMake 函数接口详解

基础语法

示例代码

为什么使用 cmake_parse_arguments()？

prefix 是什么意思？

参数类型详细解释

常见限制与注意事项

多个关键字可以一起定义吗？

是否有上限？

实用建议

高级技巧建议

动态前缀支持

总结

推荐使用场景

使用 `cmake_parse_arguments()` 构建清晰、灵活的 CMake 函数接口详解

为什么使用 `cmake_parse_arguments()`？

`prefix` 是什么意思？