From c0a233a5b5f60e5ec3d2fd46e9d472fe6872d222 Mon Sep 17 00:00:00 2001 From: David Allsopp Date: Thu, 22 Apr 2021 14:27:51 +0100 Subject: Update BOOTSTRAP.adoc for changing primitives --- BOOTSTRAP.adoc | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) (limited to 'BOOTSTRAP.adoc') diff --git a/BOOTSTRAP.adoc b/BOOTSTRAP.adoc index e73d01fe62..77604b3cf2 100644 --- a/BOOTSTRAP.adoc +++ b/BOOTSTRAP.adoc @@ -31,8 +31,8 @@ Here is how to perform a change that requires a bootstrap: 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 +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. @@ -53,10 +53,46 @@ This will rebuild runtime/ocamlrun, ocamlc, etc. 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. -- cgit v1.2.1