The L Compiler Hyperbook

The internals of the L compiler

The L hyperbook describes the internal of the L compiler. More precisely, it is the L compiler, or more precisely a formatted version of its source code. L is written in a semi-literate programming style, meaning that it was written to be read by humans, not only to be executed by computers.

Reading the entire source code of the L compiler sequentially is something you may want to do if you want to learn about the L compiler implementation. For this, the sequential, printed version of the book (not yet published) would suits you. However, if you want to read or re-read only about a specific topic, the present hypertext version is more suitable, because it simplifies selective reading. Thus, the L source code is semi-literate because this documentation appears in the same order than in the source code.

Hierarchical presentation: how to read this book

Unlike a book, the information in the hyperbook not conceived to be presented sequentially, but rather hierarchically. This page represents the top-most level of the hierarchy. As is the case of each level, it presents at the end of the page a table of contents, describing each of its child (eventually with the preferred reading order, and dependencies). If you want more information, you can start reading one of the child. Furthermore, the whole tree is represented in the navigation bar on the left; to explore, click on the ▷ icons (no javascript needed).

The L source code was organized to match this hierarchical presentation; the OCaml module system was great for this purpose. The separation between an interface (.mli) and implementation (.ml) file provide a first level of hierarchy, where the .mli present what a module does, and the .ml how it does it. When the .ml file is simple, or that there would be no presentation gain in writing an interface, only the .ml file is provided.

Further, the source files were splitted recursively into different directories. The idea is that in a directory A/ that contains a directory A/B/, the contents of B/ are not useful to the understanding of A/ (even if some components in A/ may use those in B/). Often a summary of the information in B useful to A/ is given as B.mli (an interface for the whole directory, checked using the Ocaml package system). This splitting was done so as to limit the quantity of information to absorb at each level of the hierarchy.

Work in progress

This hyperbook is still work in progress, but L is quickly approaching version 0.1, where the complete source code of the compiler will be readable in the hyperbook. Any comments or improvement on the hyperbook (as well as on the source code itself) are welcome. You can send me pull requests on github. Future improvements to the hyperbook will include cross-references in and between source file, a dependency diagram of the modules of each level, and a table of contents for each hierarchy level.

Outline of this hierarchy level

If you are interested in the inner working of the compiler, you should start reading compilation_passes.ml, which describes how all the passes of the compiler fit together. The parser, ast, cps and llvm directories represent the successive passes. Last, support contains generic files used by the other passes of the compiler.

License

The hyperbook is extracted from the L source code, and subject to the same open-source license: the Cecill-C license, which is similar to (and compatible with) the LGPL and MPL licenses.



Matthieu Lemerre