Roc 编译器 CLI 参数治理用一张声明式标志表统一 Struct、解析器与 Help 文本【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本文围绕 Roc 仓库中的改进提案文档 cli-declarative-flags.md 展开分析roc命令行工具当前同一套标志被三处独立编码的技术债务并给出一套基于 Zig comptime 的声明式标志表flag table重构方案。读完后你将理解 Roc CLI 参数解析的现有调用链与缺陷证据并掌握如何在不改变任何运行时行为的前提下让新增一个标志变成一张表里的一次编辑。一、问题每个子命令的标志集被编码了三次当前 Roc CLI 的参数解析实现在 cli_args.zig 中。以build子命令为例同一组标志在文件中被独立表达了三次args structBuildArgs 结构体声明了全部标志对应的字段——path、opt、target、output、debug、fuzz、keep_temp、verbose、timings、no_cache、watch、watch_inputs_file、max_threads、wasm_memory、wasm_stack_size等每个字段带注释说明其语义与默认值手写的解析器parseBuild见 cli_args.zig用一长串if/else if链逐个匹配参数布尔标志走mem.eql精确比较带值标志走mem.startsWithgetFlagValue提取--keyvalue最后的兜底分支把未识别参数当作位置参数path手写的 help 字符串isHelpFlag(arg)命中后返回的 help 文本cli_args.zig逐行罗列了--output、--opt、--specialize、--target、--debug、--fuzz……等全部标志及其说明。顶层命令清单也至少重复了两次main_helpcli_args.zig用文本罗列run、install、build、bundle……每个子命令的摘要而 parseCommand 的if (mem.eql(u8, args[0], run)) ...分发链又把这些命令名和对应的parseXxx函数逐一手写了一遍。关键缺陷在于没有任何机制校验解析器接受的标志与help 中列出的标志一致。文档指出的一个现存例证是内部标志--watch-inputs-file它在parseBuild中被解析cli_args.zig但从未出现在 build 的 help 文本里。对内部标志来说这是可接受的行为但它恰好证明了这三份拷贝可以自由地互相不一致。同样的三重编码在check、test、fmt、bundle、unbundle、repl、glue、version、docs、bump、experimental-lsp每个子命令中重复出现——每个parseXxx函数都是局部变量初始化 一长串startsWith/eql链 末尾手动装配 struct的同构模式。二、连带问题默认值与合法取值被二次prose 化除了三重编码本身文档还指出了三类事实被散文复述的隐患默认优化级别写了两次。常量侧default_dev_opt / default_build_opt 分别定义run/test/repl/glue默认.dev、roc build默认.speedprose 侧build 的 help 文本中写着Build mode: speed (default LLVM optimized), ...main_help中又写Execution mode: dev (default, fast compilation), ...。常量改名或调默认值时help 文本不会跟着变。--opt的合法取值写了两次。真正的取值集合是 OptLevel 枚举size、speed、dev、interpreter及其from_str匹配链而 help 字符串里再用散文把同一组值复述一遍。目标平台清单与真正的定义脱节。用户可见的目标清单出现在 help 文本如e.g., x64musl, x64glibc, arm64musl以及 targets_validator.zig 中更完整的带描述清单该文件第 400 余行起还有x64musl, arm64musl - Linux (static, portable)这类分组示例但真正定义目标名称的是 src/target/mod.zig 中的RocTarget枚举。从源码结构看这几处清单彼此独立维护——往RocTarget枚举里新增一个目标不会自动出现在任何 help 文本或校验建议里除非有人记得去改。三、背景仓库已有成功先例只是标志层没跟上值得注意的是Roc 已经用同样的思路解决过目标平台target本身的一致性难题RocTarget是一个枚举自带fromString/toTriple等转换构建系统与 CLI 共同消费这一份定义。标志层之所以没有享受同等待遇纯粹是因为解析器是手写的 if 链。但提案指出现有解析器的形态足够规整——每个子命令的标志只落在三种形状里布尔标志--debug、--keyvalue形式--optspeed和位置参数path。这意味着一张声明式表完全可以同时生成匹配器与 help 文本而不需要改变任何解析语义。四、方案设计四步收敛到单一事实来源1. 每个子命令一张标志表为每个子命令声明一个 comptime 数组条目形状大致为{ long: []const u8, field: []const u8, kind: enum { flag, value, path }, help: ?[]const u8 }其中help为null表示内部标志、刻意不列入 help——--watch-inputs-file这类现状就从碰巧没写变成显式设计决策。配套两个泛型工具parseArgsFor(T, table, args)通过field按field名字把解析结果写入目标 structhelpFor(name, table)直接从同一张表渲染 help 文本。再加一道comptime 双向断言表中每个field必须对应 struct 的真实字段反之每个非内部 struct 字段必须有表条目。缺字段即编译错误。2. 把散文复述的事实改成内插Help 字符串不再手写默认值和取值集合默认优化级别直接引用default_build_opt常量--opt的合法值通过tagName循环枚举OptLevel变体。这样事实只存在于一处help 永远如实反映。3. 生成目标平台清单在RocTarget旁增加一张逐目标元数据表描述、分组归属help 行与 targets_validator.zig 的清单/示例全部从该表渲染。效果是新增一个RocTarget变体但没写元数据直接编译失败——清单从此不可能漏掉或拼错某个目标。4. 单一命令清单parseCommand的分发链与main_help的 Commands 小节从同一张命令表命令名、摘要、parse 函数派生终结顶层命令名被写两遍的现状。特别强调的是不改变解析语义不引入新依赖不改变行为。表驱动后执行的仍是与今天相同的mem.eql/mem.startsWith比较只是比较项由 comptime 从表展开。五、验收标准每一条都必须成立文档给出四条硬性验收标准全部满足才算完成新增一个用户可见标志 表中加一条它能被解析、自动出现在 help 中无需第二次编辑遗漏 struct 字段是编译错误roc build --help等 help 输出与改造前逐字节一致唯一的例外是原文本本来就错了/过时了——且每处此类 diff 都必须在变更说明中被点名任何默认值或--opt取值集合不得再以散文形式出现grep -n default LLVM optimized src/cli结果必须为空在一个试验性构建中往RocTarget加一个变体它必须无需任何 CLI 侧编辑就出现在--targethelp 与校验器的建议里。在性能维度文档的理想态是comptime 表展开产出的运行时比较与手写链完全等价——参数解析成本不变。由于解析每次调用只运行一次验收时只需确认没有可测量的启动开销增量无需追求更快。六、配套测试策略文档规划了三类测试comptime 表↔struct 双向检查本身就是测试——它编译通过即验证了声明一致性无需运行时用例每个子命令的 golden help 测试先固化逐字节一致的承诺之后又充当变更评审的对照面——任何 help diff 都会显式暴露解析器属性测试表中每个条目都能往返round-trip即构造--flagvalue输入后对应 struct 字段被正确设置。这一类模式在仓库现有测试中已有先例如 cli_args.zig 处的parse(gpa, testing.io, [_][]const u8{ build, --watch-inputs-file/tmp/roc-watch-inputs, foo.roc })用例验证内部标志确实被解析进BuildArgs.watch_inputs_file。七、正确性的理想终态与相关提案方案追求的正确性理想可以概括为一句话接受的标志面accepted surface、文档化的标志面documented surface与 struct 是同一份声明——help 不可能再对标志、默认值或目标平台说错话。该提案属于 Roc 仓库projects/small目录下的一组单一事实来源single-sourcing改进计划之一与它配套的是构建侧的同类治理提案 build-and-ci-single-lists.md两者共同的方向是凡是一份事实被多处复述的地方都用 comptime 展开收敛回单一声明点。参考文件文件角色projects/small/cli-declarative-flags.md本提案原文问题、证据、方案、验收标准src/cli/cli_args.zig现有参数解析实现CliArgs联合类型、各子命令 Args struct、parseCommand分发链、main_help与各子命令 help 文本src/cli/targets_validator.zig用户可见目标清单的第二份拷贝所在src/target/mod.zig目标名称的真正定义处RocTarget枚举projects/small/build-and-ci-single-lists.md构建侧的同类 single-sourcing 提案【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Roc 编译器 CLI 参数治理：用一张声明式标志表统一 Struct、解析器与 Help 文本
Roc 编译器 CLI 参数治理用一张声明式标志表统一 Struct、解析器与 Help 文本【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本文围绕 Roc 仓库中的改进提案文档 cli-declarative-flags.md 展开分析roc命令行工具当前同一套标志被三处独立编码的技术债务并给出一套基于 Zig comptime 的声明式标志表flag table重构方案。读完后你将理解 Roc CLI 参数解析的现有调用链与缺陷证据并掌握如何在不改变任何运行时行为的前提下让新增一个标志变成一张表里的一次编辑。一、问题每个子命令的标志集被编码了三次当前 Roc CLI 的参数解析实现在 cli_args.zig 中。以build子命令为例同一组标志在文件中被独立表达了三次args structBuildArgs 结构体声明了全部标志对应的字段——path、opt、target、output、debug、fuzz、keep_temp、verbose、timings、no_cache、watch、watch_inputs_file、max_threads、wasm_memory、wasm_stack_size等每个字段带注释说明其语义与默认值手写的解析器parseBuild见 cli_args.zig用一长串if/else if链逐个匹配参数布尔标志走mem.eql精确比较带值标志走mem.startsWithgetFlagValue提取--keyvalue最后的兜底分支把未识别参数当作位置参数path手写的 help 字符串isHelpFlag(arg)命中后返回的 help 文本cli_args.zig逐行罗列了--output、--opt、--specialize、--target、--debug、--fuzz……等全部标志及其说明。顶层命令清单也至少重复了两次main_helpcli_args.zig用文本罗列run、install、build、bundle……每个子命令的摘要而 parseCommand 的if (mem.eql(u8, args[0], run)) ...分发链又把这些命令名和对应的parseXxx函数逐一手写了一遍。关键缺陷在于没有任何机制校验解析器接受的标志与help 中列出的标志一致。文档指出的一个现存例证是内部标志--watch-inputs-file它在parseBuild中被解析cli_args.zig但从未出现在 build 的 help 文本里。对内部标志来说这是可接受的行为但它恰好证明了这三份拷贝可以自由地互相不一致。同样的三重编码在check、test、fmt、bundle、unbundle、repl、glue、version、docs、bump、experimental-lsp每个子命令中重复出现——每个parseXxx函数都是局部变量初始化 一长串startsWith/eql链 末尾手动装配 struct的同构模式。二、连带问题默认值与合法取值被二次prose 化除了三重编码本身文档还指出了三类事实被散文复述的隐患默认优化级别写了两次。常量侧default_dev_opt / default_build_opt 分别定义run/test/repl/glue默认.dev、roc build默认.speedprose 侧build 的 help 文本中写着Build mode: speed (default LLVM optimized), ...main_help中又写Execution mode: dev (default, fast compilation), ...。常量改名或调默认值时help 文本不会跟着变。--opt的合法取值写了两次。真正的取值集合是 OptLevel 枚举size、speed、dev、interpreter及其from_str匹配链而 help 字符串里再用散文把同一组值复述一遍。目标平台清单与真正的定义脱节。用户可见的目标清单出现在 help 文本如e.g., x64musl, x64glibc, arm64musl以及 targets_validator.zig 中更完整的带描述清单该文件第 400 余行起还有x64musl, arm64musl - Linux (static, portable)这类分组示例但真正定义目标名称的是 src/target/mod.zig 中的RocTarget枚举。从源码结构看这几处清单彼此独立维护——往RocTarget枚举里新增一个目标不会自动出现在任何 help 文本或校验建议里除非有人记得去改。三、背景仓库已有成功先例只是标志层没跟上值得注意的是Roc 已经用同样的思路解决过目标平台target本身的一致性难题RocTarget是一个枚举自带fromString/toTriple等转换构建系统与 CLI 共同消费这一份定义。标志层之所以没有享受同等待遇纯粹是因为解析器是手写的 if 链。但提案指出现有解析器的形态足够规整——每个子命令的标志只落在三种形状里布尔标志--debug、--keyvalue形式--optspeed和位置参数path。这意味着一张声明式表完全可以同时生成匹配器与 help 文本而不需要改变任何解析语义。四、方案设计四步收敛到单一事实来源1. 每个子命令一张标志表为每个子命令声明一个 comptime 数组条目形状大致为{ long: []const u8, field: []const u8, kind: enum { flag, value, path }, help: ?[]const u8 }其中help为null表示内部标志、刻意不列入 help——--watch-inputs-file这类现状就从碰巧没写变成显式设计决策。配套两个泛型工具parseArgsFor(T, table, args)通过field按field名字把解析结果写入目标 structhelpFor(name, table)直接从同一张表渲染 help 文本。再加一道comptime 双向断言表中每个field必须对应 struct 的真实字段反之每个非内部 struct 字段必须有表条目。缺字段即编译错误。2. 把散文复述的事实改成内插Help 字符串不再手写默认值和取值集合默认优化级别直接引用default_build_opt常量--opt的合法值通过tagName循环枚举OptLevel变体。这样事实只存在于一处help 永远如实反映。3. 生成目标平台清单在RocTarget旁增加一张逐目标元数据表描述、分组归属help 行与 targets_validator.zig 的清单/示例全部从该表渲染。效果是新增一个RocTarget变体但没写元数据直接编译失败——清单从此不可能漏掉或拼错某个目标。4. 单一命令清单parseCommand的分发链与main_help的 Commands 小节从同一张命令表命令名、摘要、parse 函数派生终结顶层命令名被写两遍的现状。特别强调的是不改变解析语义不引入新依赖不改变行为。表驱动后执行的仍是与今天相同的mem.eql/mem.startsWith比较只是比较项由 comptime 从表展开。五、验收标准每一条都必须成立文档给出四条硬性验收标准全部满足才算完成新增一个用户可见标志 表中加一条它能被解析、自动出现在 help 中无需第二次编辑遗漏 struct 字段是编译错误roc build --help等 help 输出与改造前逐字节一致唯一的例外是原文本本来就错了/过时了——且每处此类 diff 都必须在变更说明中被点名任何默认值或--opt取值集合不得再以散文形式出现grep -n default LLVM optimized src/cli结果必须为空在一个试验性构建中往RocTarget加一个变体它必须无需任何 CLI 侧编辑就出现在--targethelp 与校验器的建议里。在性能维度文档的理想态是comptime 表展开产出的运行时比较与手写链完全等价——参数解析成本不变。由于解析每次调用只运行一次验收时只需确认没有可测量的启动开销增量无需追求更快。六、配套测试策略文档规划了三类测试comptime 表↔struct 双向检查本身就是测试——它编译通过即验证了声明一致性无需运行时用例每个子命令的 golden help 测试先固化逐字节一致的承诺之后又充当变更评审的对照面——任何 help diff 都会显式暴露解析器属性测试表中每个条目都能往返round-trip即构造--flagvalue输入后对应 struct 字段被正确设置。这一类模式在仓库现有测试中已有先例如 cli_args.zig 处的parse(gpa, testing.io, [_][]const u8{ build, --watch-inputs-file/tmp/roc-watch-inputs, foo.roc })用例验证内部标志确实被解析进BuildArgs.watch_inputs_file。七、正确性的理想终态与相关提案方案追求的正确性理想可以概括为一句话接受的标志面accepted surface、文档化的标志面documented surface与 struct 是同一份声明——help 不可能再对标志、默认值或目标平台说错话。该提案属于 Roc 仓库projects/small目录下的一组单一事实来源single-sourcing改进计划之一与它配套的是构建侧的同类治理提案 build-and-ci-single-lists.md两者共同的方向是凡是一份事实被多处复述的地方都用 comptime 展开收敛回单一声明点。参考文件文件角色projects/small/cli-declarative-flags.md本提案原文问题、证据、方案、验收标准src/cli/cli_args.zig现有参数解析实现CliArgs联合类型、各子命令 Args struct、parseCommand分发链、main_help与各子命令 help 文本src/cli/targets_validator.zig用户可见目标清单的第二份拷贝所在src/target/mod.zig目标名称的真正定义处RocTarget枚举projects/small/build-and-ci-single-lists.md构建侧的同类 single-sourcing 提案【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考