Introduction

Preprocessing in OCaml

The OCaml language does not feature a first class macro system, that is, there is no official part of the OCaml language that will be executed at compile time in order to generate or alter the source code. The preprocessing is thus left to external programs, written by the community, and specialized for their own tasks. However, without a unification framework, the following issues would arise:

• Difficulty in using several preprocessors, with incompatibility or composition issues,
• Duplication of code and efforts on the different preprocessors,
• Performance loss with many phases (parsing, pretty-printing, ...) being executed multiple times.

ppxlib

The goal of ppxlib is to provide this unifying framework. It sits in between the OCaml compiler and toolchain, and the PPX authors, providing an API for them. One could sum up the ppxlib features as:

• It deals with all boilerplate such as parsing the input, output the rewritten output, generate an executable, ...
• It generates a single executable for multiple transformations, dealing itself with possible composition issues,
• It integrates well with Dune and Merlin,
• It provides a more stable API than the compiler for manipulating the AST,
• A single PPX codebase works on every OCaml version of the AST,
• It defines restricted rewriters whose semantic ensure better confidence for the user and better compositional semantics,
• It provides many helpers to pattern-match and generate AST nodes, traverse the AST.

This guide

This guide is separated into several parts.

First, we focus on the driver that performs the AST transformations: how it is generated, executed, and more importantly what it does exactly, from migrating the AST, to the different rewriting phases it goes through.

After that, we explain the different kinds of transformations that ppxlib supports, and how to register them to the driver. This section only describes the transformations and their properties, not how to actually manipulate the AST.

The part where we discuss how to manipulate the AST is split in three pages: generating AST nodes to generate OCaml code, destructing AST nodes to extract information and act differently depending on what is extracted, and traversing the AST to use fold, iter and map on the AST. This code-manipulation part explains both using the modules Ast_builder, Ast_pattern and the ppxlib's PPX Metaquot.

We finally discuss several good practices, such as how to properly report errors, how to test your PPX, or how to migrate from other PPX libraries such as OMP and ppx_deriving.

We end by including some examples, which you can also find in the examples folder of ppxlib's repository.

PPXs and ppxlib history

The preprocessing history of OCaml started long before ppxlib. However, this section is not yet written. You can find more information in these ressources: 1 2 3 4 5. You can also contribute to the ppxlib documentation by opening a pull request in the repository.