Skip to content

Latest commit

 

History

History
76 lines (57 loc) · 2.63 KB

HACKING.adoc

File metadata and controls

76 lines (57 loc) · 2.63 KB
Raw
Parsetree and Asttypes

Parsetree is an Abstract Syntax Tree (AST) representation of OCaml source code. It is well annotated with examples and is a recommended read before any further exploration of the compiler.

Location

This module contains utilities related to locations and error handling. In particular, it contains handlers that are used for all the error reporting in the compiler.

parser.mly

This file contains the grammar used to generated the parser — using the menhir parser generator, which is an external tool that you need to install if you wish to modify the parser.

Working on the parser grammar

To avoid depending on an external tool, the compiler build system does not rebuild the parser from the source grammar parser.mly each time. It works from a versioned copy of the generated parser stored in the boot/menhir subdirectory.

If you change parser.mly, you need to run the promote-menhir target of the root Makefile to rebuild the compiler parser. See ../Makefile.menhir for the details of the various Menhir-related targets and their use.

Testing the grammar

The root Makefile contains a build-all-asts target that will build, for each source .ml or .mli file in the repository, a .ml.ast or .mli.ast file describing the parsed abstract syntax tree (AST) in -dparsetree format. This rule is rather slow to run, and can safely be run in parallel, so we recommend using -j (without a number) to maximize parallelism:

make -j build-all-asts

Finally, the 'list-all-asts' target lists all such '.ast' files.

This is intended to be used to test parser changes, in particular those that should not modify the parsed AST at all:

  1. Before performing any changes, build all AST files and add them to the git index (make list-all-asts | xargs git add).

  2. Perform any parser change of interest.

  3. To test your changes, build AST files again; git diff will show any change to an AST file.

  4. Before committing any change, remember to remove the .ast files from your index (using git reset HEAD), and maybe remove them completely (unless you plan to check further changes).

# save pre-change ASTs
make -j build-all-asts
make list-all-asts | xargs git add

# do your parser changes
# ...
make promote-menhir

# compare new ASTs
make -j build-all-asts
git diff # shows any .ml.ast difference

# remove AST files from the index
make list-all-asts | xargs git reset HEAD

# remove the files (if no further parser change planned)
make list-all-asts | xargs rm