Skip to content

Latest commit

 

History

History
62 lines (45 loc) · 2.25 KB

BOOTSTRAP.adoc

File metadata and controls

62 lines (45 loc) · 2.25 KB
Raw

Bootstrapping the compiler

This file explains how to bootstrap the OCaml compiler, i.e. how to update the binaries in the 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.