Skip to content

Latest commit

 

History

History
122 lines (81 loc) · 3.88 KB

BOOTSTRAP.adoc

File metadata and controls

122 lines (81 loc) · 3.88 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 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

Problems

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.

Upstreaming

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.

Adding, removing and renaming primitives

Primitives can be added without having to bootstrap, however it is necessary to repeat make coldstart in order to use your new primitive in the standard library.

There are five steps to renaming a primitive:

  1. Rename the primitive and its uses

  2. Create a temporary stub with the old primitive’s name. This stub simply passes its arguments on to the new primitive:

    CAMLprim value caml_old_primitive(value a1, value a2) {
  return caml_new_primitive(a1, a2);
}

  3. Deal with the addition of the new primitive:

    make coldstart

  4. Ensure the system still works:

    make coreall

  5. Now remove the old primitive stub and issue:

    make bootstrap

It is desirable for bootstraps to be easily repeatable, so you should commit changes after step 4.

To remove a primitive:

  1. Start with a working build of the compiler eg ./configure && make world

  2. Remove uses of the primitive, but not the primitive itself. Then ensure the system still works:

    make coreall

  3. Then, and only then, remove the primitive, and run:

    make coreall
make bootstrap

Bootstrap test script

A script is provided (and used on Inria’s continuous integration infrastructure) to make sure the bootstrap works. This script implements the bootstrap procedure described above and performs two changes to the compiler: it updates the magic numbers and removes a primitive from the runtime. It then makes sure the bootstrap still works after these changes. This script can be run locally as follows:

OCAML_ARCH=linux ./tools/ci/inria/bootstrap