package ocaml-migrate-parsetree

  1. Overview
  2. Docs
Convert OCaml parsetrees between different versions


Dune Dependency






Deprecated. Please, use Ppxlib instead. More info on

Convert OCaml parsetrees between different versions

This library converts parsetrees, outcometree and ast mappers between different OCaml versions. High-level functions help making PPX rewriters independent of a compiler version.


syntax org:ocamllabs

Published: 17 Jun 2022



Convert OCaml parsetrees between different major versions

This library converts between parsetrees of different OCaml versions.

Supported versions are 4.02, 4.03, 4.04, 4.05, 4.06, 4.07, 4.08, 4.09, 4.10, 4.11, 4.12 and 4.13. For each version, there is a snapshot of the parsetree and conversion functions to the next and/or previous version.


module Ast_{402,403,404,405,406,407,408,409,410,411,412,413} : sig

  (* Version specific copy of AST *)
  module Asttypes
  module Parsetree

  (* Magic numbers used for marshalling *)
  module Config : sig
    val ast_impl_magic_number : string
    val ast_intf_magic_number : string

These embed copies of AST definitions for each supported OCaml major version.

The AST matching the version of the OCaml toolchain will contain equalities relating the copy of types to the definitions from compiler-libs. For instance, when installed with OCaml 4.04.x the type Ast_404.Parsetree.expression is equal to the type Parsetree.expression from the compiler libraries.

Migration modules

For each pair of versions $(n) and $(n+1), the two modules Migrate_parsetree_$(n)_$(n+1) and Migrate_parsetree_$(n+1)_$(n) convert the AST forward and backward.

The forward conversion is total while the backward conversion is partial: when a feature is not available in a previous version of the parsetree, a Migrate_parsetree_def.Migration_error exception is raised detailing the failure case.

Adding a new OCaml version

We use Cinaps to generate boilerplate. You can install it via opam: opam install cinaps.

Add the new version in src/cinaps_helpers/ supported_versions.

Copy the last src/ file to src/ast_<new_version>.ml, then go over the file and update each sub-module by replacing its signature and implementation with the code from the compiler. For the Config sub-module, update the two variables with the values in utils/config.mlp in the compiler source tree.

Once this is done, call:

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

Then diff the src/ and src/ast_<new_version>.ml and go over the diff to make sure the difference are relevant. The ast_... files require some adjustments which should pop up when you do this diff. Port the old adjustments to the new file as required.

Add migration functions. In the commands below, set $OLD and $NEW to the appropriate version numbers, e.g. 408 and 409:

  • Manually compile the asts (ocamlc -c src/ast_{$NEW,$OLD}.ml -I +compiler-libs -I _build/default/src/.migrate_parsetree.objs/byte/)

  • Using tools/gencopy.exe (dune build tools/gencopy.exe), generate copy code to and from previous version:

_build/default/tools/gencopy.exe -I . -I src/ -I +compiler-libs -map Ast_${NEW}:Ast_${OLD} Ast_${NEW}.Parsetree.{expression,pattern,core_type,toplevel_phrase} > src/migrate_${NEW}_${OLD}.ml
_build/default/tools/gencopy.exe -I . -I src/ -I +compiler-libs -map Ast_${OLD}:Ast_${NEW} Ast_${OLD}.Parsetree.{expression,pattern,core_type,toplevel_phrase} > src/migrate_${OLD}_${NEW}.ml
  • Fix the generated code by implementing new cases

TODO: specialize and improve gencopy for these cases

At any time, you can expand boilerplate code by running make cinaps.

Update build system:

  • make sure make cinaps reaches a fixed point :)

  • make should succeed

Dependencies (2)

  1. ocaml >= "4.02.3" & < "5.1"
  2. dune >= "2.3"

Dev Dependencies (1)

  1. cinaps with-test & >= "v0.13.0"

Used by (15)

  1. clangml >= "4.5.0"
  2. elpi >= "1.11.3" & < "1.13.2"
  3. GT >= "0.4.0" & < "0.5.2"
  4. gopcaml-mode >= "0.0.2"
  5. mel >= "0.3.0"
  6. nsq >= "0.5.2"
  7. ocamlformat = "0.17.0"
  8. odoc >= "2.0.0" & < "2.1.0"
  9. pattern >= "0.3.0"
  10. ppx_cstruct >= "6.0.0"
  11. ppx_cstubs >= "0.5.0" & < "0.6.0"
  12. ppx_import = "1.8.0"
  13. ppxlib >= "0.16.0" & < "0.23.0"
  14. scaml = "1.2.0"
  15. tezos-benchmark

Conflicts (1)

  1. base-effects

Innovation. Community. Security.