63 lines
2.3 KiB
Plaintext
63 lines
2.3 KiB
Plaintext
= Bootstrapping the compiler
|
|
|
|
This file explains how to bootstrap the OCaml compiler, i.e. how to
|
|
update the binaries in the link:boot/[] directory.
|
|
|
|
A bootstrap is required for example when something changes in the
|
|
runtime system (the magic number of bytecode executables, the format of
|
|
bytecode instructions, the set of available primitives) or when the
|
|
format of OCaml compilation object files like .cmi files is modified. In
|
|
particular, given that the .cmi files contain information related to
|
|
types, modifying the way a type is represented will modify the format
|
|
of .cmi files and thus require a bootstrap.
|
|
|
|
Here is how to perform a change that requires a bootstrap:
|
|
|
|
1. Make sure you start with a clean source tree (e.g. check with
|
|
`git status`)
|
|
|
|
2. Configure your source tree by running:
|
|
|
|
./configure
|
|
|
|
3. Bring your system to a stable state. Concretely, this means that the
|
|
boot/ directory should contain a version of ocamlrun and all the
|
|
\*.cm* files of the standard library. This stable state can be reached
|
|
by running
|
|
|
|
make world
|
|
+
|
|
(Actually, running `make coldstart` should be enough but `make world` is
|
|
safer. Similarly, `make world.opt` will also bring you to such a stable
|
|
state but builds more things than actually required.)
|
|
|
|
4. Now, and only now, edit the sources. Changes here may include adding,
|
|
removing or renaming a primitive in the runtime, changing the magic
|
|
number of bytecode executable files, changing the way types are
|
|
represented or anything else in the format of .cmi files, etc.
|
|
|
|
5. Run:
|
|
|
|
make coreall
|
|
+
|
|
This will rebuild runtime/ocamlrun, ocamlc, etc.
|
|
|
|
6. (optional) The new system can now be tested:
|
|
|
|
echo 'let _ = print_string "Hello world!\n"' > foo.ml
|
|
./boot/ocamlrun ./ocamlc -I ./stdlib foo.ml
|
|
./runtime/ocamlrun a.out
|
|
|
|
7. We now know the system works and can thus build the new boot/
|
|
binaries:
|
|
|
|
make bootstrap
|
|
|
|
If you notice that this procedure fails for a given change you are
|
|
trying to implement, please report it so that the procedure can be
|
|
updated to also cope with your change.
|
|
|
|
If you want to upstream your changes, indicate in the message of the
|
|
commit that the changes need a bootstrap. Perform the bootstrap and
|
|
commit the result of the bootstrap separately, after that commit.
|