The bootstrap process

When one makes a change in Camlp4 sources, one must understand how proceeds the bootstrap process. Generally each major change must be split in two parts. The first one is to build a Camlp4 that understands the needed features, the second is to update the Camlp4 in order to use these features. So you can change the grammars specification, the pretty-printers and the code expansion but not directly use these changes.

So to compile camlp4 just type make in the camlp4 directory.

To make this process more realistic one can take a simple example. Suppose that one want to change the EXTEND Gram ... END syntax. This syntax produce function calls like Gram.extend ... The proposed example is to change the name of this function to broaden.

For this trivial example only one working copy of Camlp4 suffices. However in case of a large change my advice is to use two working copies, one for parsing, printing and code generation changes and the other for code change. The two working copies system is needed in order to keep the compilation time reasonable when multiple changes are performed on the first one.

Edit the appropriate file: Camlp4Parsers/Grammar.ml

Find the .extend sequence and replace it by .broaden you can check that this change won't affect your running Camlp4 since it occurs inside a quotation.

Compile this new Camlp4

$ make

In general one change parsers, printers, and code generation until satisfied by what can parse, or generate this version.

Test it

$ cat test.ml

EXTEND Gram expr: [[]]; END

$ ./camlp4of.run pr_o.cmo test.ml

let _ = Gram.extend' (expr : 'expr Gram.Entry.t) (None, [None, None, []])

Propagate the change in the whole Camlp4

Now one should change the extend definition and signature to rename it broaden. In this case this involves the following files:

• Camlp4/Sig/Grammar/Dynamic.mli: The signature for dynamic grammars
• Camlp4/Sig/Grammar/Static.mli: The signature for static grammars
• Camlp4/Struct/Grammar/Static.ml: The structure for dynamic grammars
• Camlp4/Struct/Grammar/Dynamic.ml: The structure for static grammars
• Camlp4/Struct/Grammar/Insert.ml: The real implementation

Bootstrap it

• With one copy:

$ make bootstrap

• With two copies:

$ cp camlp4boot.run /.../second_copy/camlp4/boot/camlp4boot

$ cd /.../second_copy/camlp4

$ make clean all

In case of bootstrap failure

• With one copy (rebuild the previous Camlp4):

$ make restore

$ make

$ edit...

$ make bootstrap

• With two copies:

$ cd /.../first_copy/camlp4

$ edit...

$ make

$ cp camlp4boot.run /.../second_copy/camlp4/boot/camlp4boot

$ cd /.../second_copy/camlp4

$ make

Reach the fix-point

When your first bootstrap reaches the end you must be sure that you reached a fix-point so you must re-run the bootstrap process (with only one copy, the second) until the message "Fixpoint reached, bootstrap succeeded."