1 = Bootstrapping the compiler
2
3 This file explains how to bootstrap the OCaml compiler, i.e. how to
4 update the binaries in the link:boot/[] directory.
5
6 A bootstrap is required for example when something changes in the
7 runtime system (the magic number of bytecode executables, the format of
8 bytecode instructions, the set of available primitives) or when the
9 format of .cmi files is modified. In particular, given that the .cmi
10 files contain information related to types, modifying the way a type is
11 represented will modify the format of .cmi files and thus require a
12 bootstrap.
13
14 Here is how to perform a change that requires a bootstrap:
15
16 1. Make sure you start with a clean source tree (e.g. check with
17 `git status`)
18
19 2. Configure your source tree by running:
20
21 ./configure
22
23 3. Bring your system to a stable state. Concretely, this means that the
24 boot/ directory should contain a version of ocamlrun and all the
25 \*.cm* files of the standard library. This stable state can be reached
26 by running
27
28 make world
29 +
30 (Actually, running `make coldstart` should be enough but `make world` is
31 safer. Similarly, `make world.opt` will also bring you to such a stable
32 state but builds more things than actually required.)
33
34 4. Now, and only now, edit the sources. Changes here may include adding,
35 removing or renaming a primitive in the runtime, changing the magic
36 number of bytecode executable files, changing the way types are
37 represented or anything else in the format of .cmi files, etc.
38
39 5. Run:
40
41 make coreall
42 +
43 This will rebuild runtime/ocamlrun, ocamlc, etc.
44
45 6. (optional) The new system can now be tested:
46
47 echo 'let _ = print_string "Hello world!\n"' > foo.ml
48 ./boot/ocamlrun ./ocamlc -I ./stdlib foo.ml
49 ./runtime/ocamlrun a.out
50
51 7. We now know the system works and can thus build the new boot/
52 binaries:
53
54 make bootstrap
55
56 If you notice that this procedure fails for a given change you are
57 trying to implement, please report it so that the procedure can be
58 updated to also cope with your change.
59