Reason 内置的 OCaml Migrate Parsetree（vendored-omp）：跨 OCaml 版本解析与 PPX 迁移的完整指南

• 编程语言
• 编译器

本篇技术指南围绕 reason 仓库中内置的 vendored-omp（即 ocaml-migrate-parsetree，OMP）展开，讲解它在 OCaml 4.08~4.14 与 5.0~5.6 各主版本之间转换解析树（parsetree）的核心机制、迁移模块体系、PPX 驱动（Driver）注册与自定义构建流程，以及如何为仓库添加新的 OCaml 版本支持。读完本文，你将掌握 OMP 的 Ast 版本化快照结构、前向/后向迁移的语义差异、Migrate_parsetree.Versions的类型级版本抽象，以及如何在-ppx场景下构建独立的组合式 PPX 驱动。

为什么 reason 需要 vendored 一份 OMP

ocaml-migrate-parsetree（OMP）是一个在不同 OCaml 主版本之间转换解析树的库。OCaml 编译器每个主版本都可能调整Parsetree、Asttypes、Outcometree等 AST 类型定义，而 PPX 重写器（rewriter）编译一次之后，若直接绑定compiler-libs的 AST 类型，则只能在配套的编译器版本上运行。OMP 的做法是：为每个受支持的 OCaml 主版本保存一份 AST 快照，并提供相邻版本之间的双向转换函数，从而让 PPX 重写器"写一次、跨版本运行"。

在 reason 仓库中，这一库以src/vendored-omp/目录的形式被整体内置（vendored），并在 dune 中以reason.ocaml-migrate-parsetree的公开名称打包。从构建配置看，它依赖ppxlib.astlib，通过tools/pp.exe对源文件做预处理，并以config/gen.ml根据当前ocaml_version动态生成ast-version与compiler-functions-file两个构建产物，从而选择正确的compiler-functions/下的兼容层（如 ge_52.ml）。这意味着该目录是 reason 解析器（src/reason-parser）在不同 OCaml 版本上保持行为一致的地基。

Asts：每个 OCaml 主版本一份 AST 快照

OMP 的核心思想是"版本化 AST 定义"。对每个支持的版本，src/vendored-omp/src/下都有一个独立的ast_XXX.ml文件——从ast_408.ml、ast_409.ml直到ast_56.ml，与 README 声明支持的 OCaml 4.08~4.14、5.0~5.6 一一对应。每个快照模块的公开结构如下（摘自 README）：

module Ast_VERSION : sig (* 这两个模块在不同编译器版本间没有变化，直接复用 compiler-libs 的版本 *) module Location = Location module Longident = Longident (* 版本特定的 AST 副本 *) module Asttypes module Parsetree module Outcometree (* 实现 PPX 时有用的其他模块。 Docstrings 和 Ast_mapper 只保留通用定义： 内部状态已被移除。 同时，抽象类型（如 Docstring.docstring）的相等性会丢失。 *) module Docstrings module Ast_helper module Ast_mapper (* 用于 marshalling 的魔法数字 *) module Config : sig val ast_impl_magic_number : string val ast_intf_magic_number : string end end

其中Location与Longident直接复用compiler-libs，因为它们在不同编译器版本之间保持稳定；Asttypes、Parsetree、Outcometree则是逐版本的深层拷贝。一个关键设计是：与当前工具链版本匹配的那个 AST 模块，会与compiler-libs中的类型建立相等关系。例如在 OCaml 4.14.x 上安装时，Ast_414.Parsetree中的类型就与compiler-libs的Parsetree类型相等，从而既能在当前版本上零开销互操作，又能在其他版本上通过迁移函数自由转换。Docstrings与Ast_mapper在版本化时剥离了全局状态，这会影响使用Ast_mapper作为 driver 时的重写器注册方式（详见下文 Driver 一节）。

Migration modules：相邻版本间的双向转换

对每一对相邻版本$(n)与$(n+1)，仓库中都生成了一对模块：

• Migrate_parsetree_$(n)_$(n+1)：前向转换；
• Migrate_parsetree_$(n+1)_$(n)：后向转换。

在源码中，这类模块通常只是简单地把_migrate生成文件的内容 include 进来，例如 migrate_parsetree_408_409.ml：

include Migrate_parsetree_408_409_migrate

真正的工作量在migrate_parsetree_XXX_YYY_migrate.ml文件中，它们是字段级（field-by-field）的深拷贝函数。以 migrate_parsetree_408_409_migrate.ml 为例，可以看到诸如copy_out_type_extension、copy_out_phrase、copy_out_sig_item等递归函数，逐个字段地把Ast_408.Outcometree的值搬到Ast_409.Outcometree：

let rec copy_out_type_extension : Ast_408.Outcometree.out_type_extension -> Ast_409.Outcometree.out_type_extension = fun { Ast_408.Outcometree.otyext_name = otyext_name; ... } -> { Ast_409.Outcometree.otyext_name = otyext_name; Ast_409.Outcometree.otyext_params = (List.map (fun x -> x) otyext_params); ... }

这类代码的初始骨架由仓库自带的 gencopy.exe 自动生成，随后由维护者手工补充版本差异分支。

前向全量、后向部分：Migration_error

README 明确指出一个重要的语义不对称性：

• 前向转换是全量（total）的：把旧版本 AST 升到新版本总是可行的；
• 后向转换是部分（partial）的：当目标旧版本中不存在某个语法特性时，会抛出Migrate_parsetree_def.Migration_error异常。

这些"缺失特性"的完整清单定义在 migrate_parsetree_def.ml 的missing_feature变体类型中，每个变体都标注了它从哪个版本引入。下表摘录代表性条目：

migrate_parsetree_def.ml还提供了两个辅助函数：missing_feature_description把变体转成可读文本（如 "let operators"），missing_feature_minimal_version给出引入版本（如 "OCaml 4.08"）。最终错误消息形如"let operators are not supported before OCaml 4.08"，并且通过Printexc.register_printer注册了格式化器，使得异常在被打印时自动附带文件位置（文件名、行号、字符区间）。因此，任何调用迁移函数（无论是Migrate_40x_40y的函数还是migrate_functions记录的字段）的地方都可能抛出Migration_error，只有后向迁移才是部分的——这是写 PPX 时必须铭记的边界。

Migrate_parsetree_versions：类型层面的版本抽象

相邻版本模块只解决"两个已知版本之间"的转换。当 PPX 需要面对任意版本（例如把当前编译器的 AST 迁到 4.04）时，就轮到Migrate_parsetree_versions出场。README 与 migrate_parsetree_versions.mli 描述了这套机制：

• module type Ast：列出每个版本被抽象的所有 AST 类型；
• module type OCaml_version：在模块层面表示一个 OCaml 版本，包含Ast子模块、整数version、字符串string_version以及用于动态恢复类型相等性的witnesses；
• 具体实例：OCaml_408、OCaml_409、…、OCaml_56以及对应的值ocaml_408、ocaml_409、…（第一公民值，便于在类型层面携带版本）；
• OCaml_current/ocaml_current：指向当前编译器版本（即与compiler-libs兼容的版本），在 migrate_parsetree_versions.ml 末尾由module OCaml_current = OCaml_OCAML_VERSION定义；
• Convert函子：接收两个OCaml_version模块，产出两者之间的copy_*函数集；
• migrate函数：接收两个版本值，返回migration_functions记录（含copy_out_value、copy_out_type等每个 AST 类型的拷贝函数）；
• 附带migration_identity（同版本迁移是无操作）与migration_compose（迁移可组合），以及compare_ocaml_version用于比较任意两个版本。

从实现看（migrate_parsetree_versions.ml），各版本实例通过Make_witness函子生成，其中migration_info是可变记录，保存next_version与previous_version；随后用一连串Register_migration (OCaml_X) (OCaml_Y) (Migrate_parsetree_X_Y) (Migrate_parsetree_Y_X)把相邻版本串成一条迁移链。migrate函数正是沿着这条链逐跳组合出任意两个版本之间的完整迁移函数：先比较版本号决定方向（Next或Previous），再migration_compose拼接中间跳。all_versions : (module OCaml_version) list则列出了全部 14 个受支持版本。

值得注意的一个细节：版本实例中version的取值规则定义在 cinaps_helpers.ml 的version_number中——4.08记为408，而5.1记为510（version < 100时乘 10），所以OCaml_51.version = 510，保证数值比较与版本先后一致。该文件的supported_versions列表正是整个库所支持版本集合的单一事实来源，全部 14 个版本为：4.08~4.14 与 5.0~5.6。

附带的 Parse 与 Ast_io

MANUAL（MANUAL.md）补充了两个实操模块：

• Parse：接口与compiler-libs的Parse相似，但解析函数把 OCaml 版本作为第一个参数。它用当前发行版的 OCaml 解析器解析源码，再把结果 AST 迁移到请求的版本——因此这些解析函数同样可能抛出Migration_error；
• Ast_io：实现跨版本的 AST（反）序列化，可以读写不同编译器版本的二进制实现/接口文件，并把它们与对应的Versions.OCaml_version模块打包在一起。MANUAL 也提醒：marshalling 格式并不保证跨版本稳定。

Driver：从 AST mapper 到可运行的 PPX 二进制

有了 AST 快照与迁移函数，只能操作解析树，还差"把它变成能跑起来的 PPX 二进制"这一步。这正是Migrate_parsetree.Driver的职责：注册一个或多个 AST 重写器，然后生成一个统一驱动。README 强调，把多个重写器合并进单一 driver 的最大好处是快——尤其在大量使用 PPX 时能显著加速编译（原文："it can speed up compilation a lot"）。

传统注册方式与新版接口

MANUAL 指出，传统上 mapper 通过Ast_mapper.register或Ast_mapper.run_main注册到全局状态，而版本化的模块移除了注册接口。若坚持使用compiler-libs的Ast_mapper，必须先迁移版本：

(* 假设 rewriter 针对 OCaml 4.04 parsetree 编写 *) let migration = Versions.migrate Versions.ocaml_404 Versions.ocaml_current let () = (* 引用未被遮蔽的 mapper *) Compiler_libs.Ast_mapper.register (fun args -> migration.copy_mapper (my_mapper args))

新版接口则把状态显式化，PPX 重写器可访问三类信息：

• 编译器配置：Driver.config，快照了编译器 API 保证设置的少量设置项；
• Cookies：Driver.cookies、get_cookies、set_cookies，跨版本工作；
• 命令行参数：注册 mapper 时提供Arg模块风格的参数规格。

重写器不再接收任意的参数列表，一切通过规格进行；重写器名字与参数键的冲突是错误——一个重写器只能注册一次，每个键只能使用一次。注册示例（摘自 MANUAL.md）：

open Ast_404 (* 目标 4.04 parsetree *) (* 重写器设置 *) let foo_config : string option ref = ref None let set_foo bar = foo_config := Some bar let reset_args () = foo_config := None let args = [ ("-foo", Arg.String set_foo, "<bar> Foo value to use in the rewriter") ] (* 重写器实现 *) let my_rewriter config cookies = let foo = match !foo_config with | None -> raise (Arg.Bad "-foo is mandatory") | Some foo -> foo in {Ast_mapper.default_mapper with ...} (* 注册 *) let () = Driver.register ~name:"hello_world" ~reset_args ~args Versions.ocaml_404 my_rewriter

最小 driver 与运行方式

注册只是第一步，要产出可运行二进制还需要"跑起来"：

• Driver.run_as_ast_mapper：适合作为Ast_mapper.run_main（甚至Ast_mapper.register）的参数，是一个会依次应用所有已注册 mapper 的"元 mapper"；
• Driver.run_as_ppx_rewriter：等价于调用Ast_mapper.run_main Driver.run_as_ast_mapper。

执行顺序的设计目标是最小化重写次数：重写器按版本排序、低版本在前；目标版本相同的重写器按注册顺序应用。

Driver.run_main作为入口点可以构建自定义/独立重写器：独立重写器不依赖 OCaml 编译器即可重写源文件或保存处理后的 AST（运行./myrewriter --help可查看全部选项）；当第一个参数是--as-ppx时，它表现为普通 PPX，适用于-ppx（即ocamlc -ppx "./myrewriter --as-ppx"）。README 给出了三种使用形态：

• ./ppx file.ml：打印转换后的代码；
• ocamlc -pp './ppx --as-pp' ...：作为预处理程序使用；
• ocamlc -ppx './ppx --as-ppx' ...：作为-ppx重写器使用。

用 ocamlfind 构建自定义 driver

README 给出了用 ocamlfind 把多个 PPX 库链接成单一 driver 的命令——关键是把ocaml-migrate-parsetree.driver-main包放在最后链接：

ocamlfind ocamlopt -predicates ppx_driver -o ppx -linkpkg \ -package ppx_sexp_conv -package ppx_bin_prot \ -package ocaml-migrate-parsetree.driver-main

通常基于 OMP 的重写器应以合适的-linkall选项构建单个库；若某个库缺少该选项导致重写器没有被链接进来，可以在链接自定义 driver 时补传-linkall。MANUAL 还补充了更一般的形式：

ocamlfind ocamlopt -linkpkg -package rewriter1,rewriter2,... \ -package ocaml-migrate-parsetree.driver-main -o myrewriter

其目的正是"把项目里用到的所有 PPX 链接进一个专用二进制，以降低重写开销"。

findlib META 规范

MANUAL 专门强调了两处写META文件时的注意事项：

1. 独立--as-ppx重写器：如果重写器以独立形式发布，必须在 META 中显式传入--as-ppx参数：

   -ppx = "./my_ppx" +ppx = "./my_ppx --as-ppx"

   只要 PPX 命令行以./开头，findlib 就会把路径展开为绝对路径。

2. ppxopt 中传参：由于重写器用Arg模块声明参数，匿名参数不再被允许。原本的匿名参数需要改成带名字的参数：

   -ppxopt = "my_ppx,./bar" +ppxopt = "my_ppx,-foo,./bar"

   参数以逗号分隔，逗号保证文件名展开仍然发生。

此外，MANUAL 给出了"可链接 PPX 重写器"的发布约定：一个包若采用Driver.register注册重写器但不做实际重写（不传-ppx ...），就可供项目把所有 PPX 链接进自定义 driver。通过两个 findlib 谓词区分使用场景：

• custom_ppx：正在构建自定义 ppx driver，此刻不应做重写（不要传-ppx ...）；
• ppx_driver：正在构建自己的 driver，注册应使用Driver.register。

链接示例：

$ ocamlfind opt -o my_driver -linkpkg -predicates custom_ppx,ppx_driver \ -package ppx_tools_versioned.metaquot_402 \ -package ocaml-migrate-parsetree.driver-main

一个 META 示例：

version = "1.0" description = "dummy ppx" requires = "ocaml-migrate-parsetree" ppx(-custom_ppx,-ppx_driver) = "./ppx_dummy --as-ppx" archive(byte,ppx_driver) = "ppx_dummy.cma" archive(native,ppx_driver) = "ppx_dummy.cmxa"

即：未定义custom_ppx时执行重写；定义了ppx_driver时链接ppx_dummy目标文件。

在 rewriter 中与 compiler-libs 打交道

MANUAL 的 Troubleshooting 部分提供了两个高频坑的解法：

• 访问被遮蔽的 compiler-libs 模块：Ast_40x会遮蔽同名模块，OMP 提供Compiler_libs模块，重新导出所有可能被遮蔽的compiler-libs模块（实现见 reason_omp.ml 中的module Compiler_libs，包括Location、Longident、Parsetree、Docstrings、Ast_helper、Ast_mapper）。

• 类型错误：由于抽象，rewriter 内部的值与compiler-libs定义的类型无关。例如不能直接Pprintast.core_type打印类型，而要先取迁移记录再提升：

  (* 假设 rewriter 针对 OCaml 4.04 parsetree 编写 *) let migration = Versions.migrate Versions.ocaml_404 Versions.ocaml_current let print_core_type fmt typ = Pprintast.core_type fmt (migration.copy_core_type typ)

另外，结合本仓库的顶层组织 reason_omp.ml，可以看到所有子模块如何被汇总成一个整洁的公开接口：Def（错误定义）、全部Ast_XXX快照、全部Migrate_XXX_YYY迁移模块、Versions、OCaml_current、Convert以及Compiler_libs。这也正是外部代码open之后拿到的 API 全景。

开发：为仓库添加一个新的 OCaml 版本

README 的 Development 一节完整描述了新增版本的流程。这套流程大量依赖 Cinaps 生成样板代码，可先通过 opam 安装：opam install cinaps ocamlformat。

具体步骤（结合源码对应文件整理）：

1. 登记新版本：在 cinaps_helpers.ml 的supported_versions列表中加入新版本（如("57", "5.7")）。该列表驱动migrate_parsetree_versions.ml、reason_omp.ml等文件中的(*$ ... $*)代码块，由 cinaps 展开成具体的版本模块与迁移注册。

2. 创建 AST 快照：复制最后一个src/ast_xxx.ml为src/ast_<new_version>.ml，逐个子模块地把签名与实现替换为编译器源码中的对应代码；Config子模块的两个魔法数字（ast_impl_magic_number、ast_intf_magic_number）取自编译器源码树中的utils/config.mlp。

3. 运行特殊注释工具：

   $ dune exec tools/add_special_comments.exe src/ast_<new_version>.ml

   add_special_comments.ml 会在类型定义后插入(*IF_CURRENT = ... *)形式的注释，用于标记哪些类型定义与当前编译器版本一致，从而在特定版本上建立类型相等关系。

4. diff 检查：diffsrc/ast_xxx.ml与src/ast_<new_version>.ml，逐个确认差异是合理的，并把旧文件中手工调整过的部分移植到新文件。

5. 生成迁移函数：

   • 手工编译 AST（ocamlc -c src/ast_{NEW,OLD}.ml -I +compiler-libs ...）；
   • 构建并使用 gencopy.exe 生成往返复制代码（示例假设前一版本是 408）：

   _build/default/tools/gencopy.exe -I . -I src/ -I +compiler-libs \ -map Ast_409:Ast_408 Ast_409.Parsetree.{expression,expr,pattern,pat,core_type,typ,toplevel_phrase} \ Ast_409.Outcometree.{out_phrase,out_type_extension} \ > src/migrate_parsetree_409_408_migrate.ml _build/default/tools/gencopy.exe -I . -I src/ -I +compiler-libs \ -map Ast_408:Ast_409 Ast_408.Parsetree.{expression,expr,pattern,pat,core_type,typ,toplevel_phrase} \ Ast_408.Outcometree.{out_phrase,out_type_extension} \ > src/migrate_parsetree_408_409_migrate.ml

   gencopy 的注释（tools/gencopy.ml 头部）说明它的作用是"生成把一个类型深拷贝到另一模块中相同类型的代码，作为迁移代码的首个版本，之后手工修补以完成真正的迁移"；

   • 修补生成代码，为版本差异实现新 case；
   • 迁移函子有特定命名要求，对照Migrate_parsetree_versions接口检查。

6. 添加 mapper 提升函数：在migrate_parsetree_NEW_408.ml与migrate_parsetree_408_NEW.ml中 include 对应的_migrate模块并定义copy_mapper函数（参考既有Migrate_parsetree_40x_40y）。

7. 展开样板并构建：随时运行make cinaps展开样板；最后确保make cinaps达到不动点且make构建成功。仓库内置的 Makefile 提供all（dune build @install）、test（dune runtest）、cinaps、clean等目标，其中cinaps目标通过dune build --root ../.. @src/vendored-omp/src/cinaps --auto-promote自动回写生成文件。

迁移部分性的实际保障

README 结尾（与 MANUAL 的 Troubleshooting 呼应）讨论了"迁移是部分函数"这一限制的实际影响：只有当你使用了"目标版本中不存在的 OCaml 构造"时才会出问题。一个关键推论是：新编译器版本发布时，既有代码通常能立即工作——因为新特性尚未被使用。这正是帮助新编译器版本平稳落地（opam switch 更新后立即可用）的核心用例。未来 OMP 可能允许把不支持的特性改写成扩展（extensions）或属性（attributes），只要重写器 opt-in，且最终到达编译器时所有扩展都已消失即可（例如 4.04 文件可用 4.02 重写器改写，但 4.02 文件不能用引入内联记录的 4.04 PPX 改写）。

小结

vendored-omp 为 reason 提供了一套完整的"解析树版本化基础设施"：14 份 AST 快照（4.08~4.14、5.0~5.6）保证每个主版本都有可引用的类型定义；相邻版本双向迁移模块与Migrate_parsetree_versions的迁移链组合，让任意两个版本之间的转换在类型层面可控；Driver注册与 findlib 约定则把这一切落地为可组合、可链接的 PPX 二进制。无论是想在 reason 生态内编写跨版本 PPX、还是为仓库贡献新的 OCaml 版本支持，都可以从本文梳理的文件路径与源码入手：先读 README 与 MANUAL 建立全貌，再对照 migrate_parsetree_versions.ml、migrate_parsetree_def.ml 与 cinaps_helpers.ml 深入实现细节。

• 编程语言
• 编译器