1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
link:parsetree.mli[Parsetree] and link:asttypes.mli[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.
link:location.mli[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.
link:parser.mly[parser.mly]:: This file contains the grammar used to
generated the parser -- using the
link:http://gallium.inria.fr/~fpottier/menhir/[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 link:parser.mly[] each
time. It works from a versioned copy of the generated parser stored
in the `boot/menhir` subdirectory.
If you change link:parser.mly[], you need to run the `promote-menhir`
target of the root Makefile to rebuild the compiler parser. See
link:../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
----
|
