Meson Build Options 完全指南：从 meson.options 到内置选项的配置体系

• 构建工具

导读：本文以 Meson 构建系统的 Build-options.md 为主体，系统讲解项目自定义构建选项（build options）的完整体系：从meson.options/meson_options.txt选项定义文件的六种选项类型、弃用（deprecated）机制、yield继承语义，到meson configure -D的命令行配置方式，并结合仓库源码（mesonbuild/optinterpreter.py、mesonbuild/options.py、mesonbuild/mconf.py）深入印证底层实现。读完本文，你将能够为自己的项目定义可配置、可版本化的构建选项，熟练通过命令行、机器文件与子项目作用域精确控制构建行为，并理解内置选项（如buildtype、optimization、b_sanitize）与项目选项之间的协作关系。

为什么需要构建选项：meson.options文件

大多数非平凡项目都需要用户可设置的选项。例如，一个程序可能有两个不同的数据后端，需要在构建时选择。Meson 通过一个选项定义文件来支持这一需求：

• 自 Meson 1.1 起，标准文件名是meson.options，放在源码树根目录；
• 更早的版本（1.1 之前）使用meson_options.txt这一名称。

仓库源码印证了这一加载优先级：mesonbuild/interpreterbase/interpreterbase.py 中的_load_option_file()会优先查找meson.options，其次才是meson_options.txt；如果两个文件同时存在但不是同一个文件（os.path.samefile判断），会直接抛出meson.options and meson_options.txt both exist, but are not the same file.异常；若旧版meson_options.txt配合低版本meson.build使用，会提示迁移到meson.options（该文件名特性自 1.1 引入，见FeatureNew.single_use('meson.options file', '1.1', ...)）。

注意：meson.options文件只允许出现option()调用。mesonbuild/optinterpreter.py 的evaluate_statement()明确校验：文件中的每一条语句必须是FunctionNode且函数名必须是option，否则抛出Only calls to option() are allowed in option files.。

下面是一个完整的选项文件示例（覆盖全部六种类型）：

option('someoption', type : 'string', value : 'optval', description : 'An option') option('other_one', type : 'boolean', value : false) option('combo_opt', type : 'combo', choices : ['one', 'two', 'three'], value : 'three') option('integer_opt', type : 'integer', min : 0, max : 5, value : 3) # Since 0.45.0 option('free_array_opt', type : 'array', value : ['one', 'two']) # Since 0.44.0 option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one', 'two']) option('some_feature', type : 'feature', value : 'enabled') # Since 0.47.0 option('long_desc', type : 'string', value : 'optval', description : 'An option with a very long description' + 'that does something in a specific context') # Since 0.55.0

这里有两个值得注意的源码级细节：

1. 选项名合法性：optinterpreter.py 定义了OPTNAME_REGEX = re.compile('[^a-zA-Z0-9_-]')，选项名只能包含字母、数字、下划线和连字符；并且func_option()会通过OptionKey.from_string()解析，若与内置选项重名会报"保留名"错误（Option name ... is reserved.）。
2. 文件内的表达式能力：optinterpreter.py 的reduce_single()允许在选项文件中使用括号、字符串字面量、布尔/数字字面量、数组、字典、一元负号（0.54.1 起）、not取反（0.54.1 起）以及字符串+拼接（0.55.0 起）——上面的long_desc示例就是字符串拼接的用法。

内置选项（built-in options）不在meson.options中定义，参见 Built-in options。

六种构建选项类型详解

所有类型都支持description关键字描述选项；若未设置，则默认使用选项名本身作为描述（这一默认行为同样体现在 optinterpreter.py 的description = kwargs['description'] or opt_name中）。

Strings（字符串）

自由形式的字符串。若未提供默认value，默认值为空字符串。

源码实现见 options.py 的UserStringOption.validate_value()：只接受str类型值，否则抛出The value of option "..." is "...", which is not a string.。

Booleans（布尔）

取值只有true/false。如果未提供默认值，默认值为true（注意与直觉相反）。

源码中 optinterpreter.py 的boolean_parser用KwargInfo('value', (bool, str), default=True)定义，且UserBooleanOption.validate_value()（options.py）会把字符串'true'/'false'（不区分大小写）归一化为布尔值，其余输入抛异常。

Combos（枚举组合）

允许在choices参数列出的值中选择恰好一个。若未设置默认value，列表的第一个值作为默认值。

optinterpreter.py 的combo_parser要求choices非空且必填；UserComboOption.validate_value()（options.py）会校验新值必须命中某个 choice，否则报错并列出所有可选值。

Integers（整数）

单个整数，可用min/max关键字指定可选上下界。该类型自 Meson 0.45.0 起可用。

_UserIntegerBase.validate_value()（options.py）先做字符串到整数的转换（toint()），随后依次检查"是否为整数"、"是否小于 min"、"是否大于 max"，任一不满足即抛MesonException。printable_choices()会把范围渲染成>= 0, <= 5这样的形式展示给用户。

Arrays（数组）

表示字符串数组。默认情况下数组可以包含任意字符串；通过choices参数可限制可选值集合（数组可以为空）。value指定默认值；若未设置value，则以choices的全部值作为默认值。

• 自 0.47.0 起，-Dopt=和-Dopt=[]都表示空列表；在此之前-Dopt=会得到一个包含空字符串的列表。
• 该类型自0.44.0起可用。

实现上，optinterpreter.py 的string_array_parser中value = kwargs['value'] if kwargs['value'] is not None else choices印证了"默认值回退到 choices"的规则；而 options.py 的UserStringArrayOption.validate_value()会逐元素校验字符串类型与 choices 约束（Value... not in allowed choices: ...），还会对重复值给出弃用警告（将在 Meson 2.0 变为硬错误）。

Features（特性开关）

feature选项有三种状态：enabled、disabled、auto。它专为传递给大多数函数的required关键字参数而设计，目前支持于add_languages、compiler.find_library、compiler.has_header、dependency、find_program、import和subproject等函数。

• enabled等价于传入required : true；
• auto等价于传入required : false；
• disabled则根本不查找依赖，总是返回not-found。

当用get_option()读取 feature 选项时，返回的不是字符串，而是一个特殊的@feature对象（该类型自 0.47.0 起可用），可以直接传给required：

d = dependency('foo', required : get_option('myfeature')) if d.found() app = executable('myapp', 'main.c', dependencies : [d]) endif

该对象提供三个无参返回布尔的方法用于自定义逻辑判断：

• .enabled()
• .disabled()
• .auto()

if get_option('myfeature').enabled() # ... endif

源码层面，mesonbuild/interpreterbase/helpers.py 定义了Feature类：内部用FeatureValue枚举（ENABLED/DISABLED/AUTO）保存状态，is_enabled()/is_disabled()/is_auto()正是上述三个方法的底层实现；__str__()返回枚举值字符串，说明@feature对象在字符串拼接场景下会退化为其字面值。

关于auto_features的联动语义：如果某个feature选项的值被设为auto，该值会被全局的auto_features选项覆盖（auto_features默认值为auto）。这一设计面向打包维护者：他们希望完全掌控哪些依赖是必需的、哪些被禁用，而不是依赖构建依赖（build-deps）恰好安装了正确版本来决定特性是否启用。例如设置auto_features=enabled可一次性启用所有 auto 特性，再显式禁用少数不需要的。

选项弃用（Deprecated）机制

自 0.60.0 起，项目选项可以被标记为 deprecated，Meson 在用户为它设置值时给出警告。还可以只弃用部分 choices，并把弃用值映射到新值。自 0.63.0 起，deprecated关键字还可以接收一个新选项的名字：此时给旧选项赋值会同时设置新旧两个名字（前提是它们接受相同的值集合）。

完整示例：

# 选项整体弃用：设置任意值都会警告。 option('o1', type: 'boolean', deprecated: true) # 某个 choice 弃用：仅当 'a' 出现在值列表中时警告。 option('o2', type: 'array', choices: ['a', 'b'], deprecated: ['a']) # 某个 choice 弃用并映射到新值：'a' 出现时警告并替换为 'c'。 option('o3', type: 'array', choices: ['a', 'b', 'c'], deprecated: {'a': 'c'}) # 布尔选项被 feature 取代：旧的 true/false 被映射到新值。 option('o4', type: 'feature', deprecated: {'true': 'enabled', 'false': 'disabled'}) # feature 选项被布尔取代：enabled/disabled/auto 被映射到新值。 option('o5', type: 'boolean', deprecated: {'enabled': 'true', 'disabled': 'false', 'auto': 'false'}) # 布尔选项被更名为另一个 feature 选项，旧值仍兼容（0.63.0+）。 option('o6', type: 'boolean', value: 'true', deprecated: 'o7') option('o7', type: 'feature', value: 'enabled', deprecated: {'true': 'enabled', 'false': 'disabled'}) # 项目选项被模块选项取代。 option('o8', type: 'string', value: '', deprecated: 'python.platlibdir')

源码级原理：options.py 的set_option()中，opt.deprecated的三种形态（True/ 列表 / 字典）分别触发：

• True→ 无条件输出Option "..." is deprecated弃用警告；
• 列表 → 仅当新值命中列表中的某个值时才警告；
• 字典 → 逐值检查映射，命中的值输出... is replaced by ...并用映射后的新值覆盖原值。

同时，optinterpreter.py 中deprecated关键字本身的类型校验支持bool、str、dict[str, str]、list[str]四种形式，其中字符串形式标注为 0.63.0 引入（since_values={str: '0.63.0'}），正好对应"更名为新选项"的用法。

在构建脚本中读取选项：get_option()

在meson.build中使用get_option()读取选项值：

optval = get_option('opt_name')

它同样可以查询 Meson 的内置项目选项，例如获取安装前缀：

prefix = get_option('prefix')

重要限制：你不能在meson.build脚本中设置选项值。选项只能通过外部的meson configure命令行工具设置。在构建目录中不带参数运行meson configure，会列出所有可设置的选项。

在源码层面，选项读取经过 options.py 的get_option_and_value_for()/get_value_for()：先resolve_option()解析出选项对象，再应用augments覆盖与yield继承（见下文）后返回最终值；不存在的选项会抛Tried to access nonexistant project option ...之类的 KeyError。

命令行配置：meson configure 与 -D 语法

修改选项值使用-D前缀：

$ meson configure -Doption=newvalue

关于数组值的设定有一些特殊规则：

• 如果只传单个字符串，会被视为"以逗号分隔"的多个值。例如：

$ meson configure -Darray_opt=foo,bar

会把值设置为包含两个元素foo和bar的数组。

• 如果字符串内部需要包含逗号，则需要配合 shell 引号传递：

$ meson configure "-Doption=['a,b', 'c,d']"

内部值必须用单引号，外层必须用双引号。

• 修改子项目的选项时，在选项名前加子项目名和冒号：

$ meson configure -Dsubproject:option=newvalue

兼容性提示：如果无法调用meson configure，说明 Meson 版本较旧，可以改用mesonconf（在新版本中已弃用）。

源码印证：数组"逗号分隔"解析逻辑位于 mesonbuild/mesonlib.py 的listify_array_value()（被 options.py 的UserStringArrayOption.listify()调用，选项名错误时统一包装为error in option "...": ...）；而 mesonbuild/mconf.py 的run_impl()展示了meson configure的完整流程：Conf(builddir)加载构建目录 → 校验默认值仅打印（default_values_only）→coredata.set_from_configure_command(options)应用命令行变更 →c.save()持久化 → 调用mintro.update_build_options()与write_meson_info_file()同步构建信息。

向超级项目让渡：yield 关键字

假设你有一个主项目（master project）和一个子项目（subproject），有时希望某个选项在两个项目中保持相同的值。这可以通过yield关键字实现：

option('some_option', type : 'string', value : 'value', yield : true)

行为语义：

• 该项目独立构建时，该选项表现如常；
• 该项目作为另一个项目（超级项目）的子项目构建，且超级项目也有一个名为some_option的选项时，get_option()返回的是超级项目的值；
• 若yield为false，get_option()返回子项目自身选项的值；
• 自 1.8.0 起，-Dsub:some_option=anothervalue配合 yielding 选项使用时，会为子项目单独设置一个值，与它让渡到的那个选项互不影响。

yield关键字自0.45.0起可用（见 optinterpreter.py 的KwargInfo('yield', bool, default=options.DEFAULT_YIELDING, since='0.45.0')，默认值即DEFAULT_YIELDING = False，定义于 options.py）。

其底层实现是父子选项绑定：options.py 的add_project_option()中，当子项目选项yielding且主项目存在相同类型的同名选项时，会把子选项的parent指向主选项（valobj.parent = parent_option，类型不同则跳过）；最终yielding = (parent is not None)。而在读取阶段，options.py 的get_option_and_value_for()中elif option_object.yielding: computed_value = option_object.parent.value正是"返回超级项目值"的直接实现。

内置构建选项概览

除了项目自定义选项外，Meson 还有大量内置选项，分为通用选项（universal options）、基础选项（base options）与编译器选项（compiler options）。要查看当前构建目录下的完整列表，在该构建目录中执行meson configure即可。

内置选项的注册表定义于 options.py：

• BUILTIN_DIR_OPTIONS：目录类选项，如prefix（默认/usr/local，Windows 为C:/）、bindir、libdir（按平台自动检测，交叉编译时可能需要交叉文件paths段修正）、licensedir（默认空，自 1.1.0 起，用于安装依赖清单与许可证）等；
• BUILTIN_CORE_OPTIONS：核心选项，如backend、buildtype、debug、optimization、default_library、warning_level、werror、wrap_mode、auto_features、unity、install_umask（preserve或 0000-0777 八进制）等；
• BUILTIN_OPTIONS_PER_MACHINE：按机器区分的pkg_config_path与cmake_prefix_path；
• COMPILER_BASE_OPTIONS：b_前缀基础选项，如b_lto、b_pch、b_sanitize、b_lundef、b_ndebug、b_vscrt等；
• BUILTIN_DIR_NOPREFIX_OPTIONS：前缀特殊处理映射（如prefix=/usr时sysconfdir默认/etc、localstatedir默认/var）。

两个代表性内置选项的用法：

• Visual Studio 启动项目：backend_startup_project可指定按 F5 执行"Start debugging"时的默认项目，值应与某个可执行目标名一致：

project('my_project', 'c', default_options: ['backend_startup_project=my_exe']) executable('my_exe', ...)

• Ninja 最大链接进程数：backend_max_links可限制 ninja 用于链接的进程数，防止内存受限环境下的链接风暴。

编译器选项（如c_args、cpp_std）与按机器（build.前缀）、按子项目（subp:opt=value）的作用域规则详见 Built-in options 的相关章节。

实战：选项全生命周期的完整链路

把以上知识串起来，一个选项从定义到生效的完整链路如下：

1. 定义：在源码树根目录编写meson.options（旧项目为meson_options.txt），其中只允许option()调用；
2. 解析：Meson 配置阶段由OptionInterpreter.process()（optinterpreter.py）读取文件，mparser解析 AST 后逐个调用func_option()，按类型分发到对应 parser，最终生成UserStringOption/UserBooleanOption/UserComboOption/UserIntegerOption/UserStringArrayOption/UserFeatureOption实例存入OptionStore；文件内容变更通过 SHA1 哈希追踪（coredata.options_files），meson configure时若检测到选项文件更新会自动重载（见 mconf.py）；
3. 读取：构建脚本中get_option('name')经OptionKey定位（OptionKey.from_string()支持subproject:build.opt三段式解析，见 options.py），应用 yield 继承与 augments 覆盖后返回值；
4. 校验：命令行meson configure -Dname=value传入的值经set_option()→validate_value()校验（类型、choices、min/max、弃用映射），非法值直接抛错，合法值持久化到构建目录；
5. 消费：get_option()返回值在meson.build中驱动required、if分支、安装路径等逻辑，最终影响后端生成（ninja / VS / xcode）的构建指令。

通过meson configure（无参数列出、-D修改、subproject:前缀定位子项目选项）、yield（超级项目继承）、deprecated（平滑迁移）、auto_features（打包控制）这套完整机制，Meson 项目可以把"哪些特性启用、依赖装到哪里、按什么标准编译"全部变成可配置、可审计、可随版本演进的显式选项，这也是 Meson 区别于简单构建脚本的核心能力之一。

• 构建工具