1 link:parsetree.mli[Parsetree] and link:asttypes.mli[Asttypes]::
2 Parsetree is an Abstract Syntax Tree (AST) representation of OCaml
3 source code. It is well annotated with examples and is a recommended
4 read before any further exploration of the compiler.
5
6 link:location.mli[Location]:: This module contains utilities
7 related to locations and error handling. In particular, it contains
8 handlers that are used for all the error reporting in the compiler.
9
10 link:parser.mly[parser.mly]:: This file contains the grammar used to
11 generated the parser -- using the
12 link:http://gallium.inria.fr/~fpottier/menhir/[menhir] parser
13 generator, which is an external tool that you need to install if you
14 wish to modify the parser.
15
16 === Working on the parser grammar
17
18 To avoid depending on an external tool, the compiler build system does
19 not rebuild the parser from the source grammar link:parser.mly[] each
20 time. It works from a versioned copy of the generated parser stored
21 in the `boot/menhir` subdirectory.
22
23 If you change link:parser.mly[], you need to run the `promote-menhir`
24 target of the root Makefile to rebuild the compiler parser. See
25 link:../Makefile.menhir[] for the details of the various
26 Menhir-related targets and their use.
27
28 ==== Testing the grammar
29
30 The root Makefile contains a `build-all-asts` target that will build,
31 for each source `.ml` or `.mli` file in the repository, a `.ml.ast` or
32 `.mli.ast` file describing the parsed abstract syntax tree (AST) in
33 `-dparsetree` format.
34 This rule is rather slow to run, and can safely be run in parallel, so
35 we recommend using `-j` (without a number) to maximize parallelism:
36
37 ----
38 make -j build-all-asts
39 ----
40
41 Finally, the 'list-all-asts' target lists all such '.ast' files.
42
43 This is intended to be used to test parser changes, in particular
44 those that should not modify the parsed AST at all:
45
46 1. Before performing any changes, build all AST files and add them to
47 the git index (`make list-all-asts | xargs git add`).
48
49 2. Perform any parser change of interest.
50
51 3. To test your changes, build AST files again; `git diff` will show
52 any change to an AST file.
53
54 4. Before committing any change, remember to remove the `.ast` files
55 from your index (using `git reset HEAD`), and maybe remove them
56 completely (unless you plan to check further changes).
57
58 ----
59 # save pre-change ASTs
60 make -j build-all-asts
61 make list-all-asts | xargs git add
62
63 # do your parser changes
64 # ...
65 make promote-menhir
66
67 # compare new ASTs
68 make -j build-all-asts
69 git diff # shows any .ml.ast difference
70
71 # remove AST files from the index
72 make list-all-asts | xargs git reset HEAD
73
74 # remove the files (if no further parser change planned)
75 make list-all-asts | xargs rm
76 ----
77