1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
|
== Magic numbers
The magic numbers in `config.common.ml` are included in the header of
compiled files produced by the OCaml compiler. Different kind of files
(cmi, cmo, cmx, cma, executables, etc.) get different magic numbers,
and we also change the magic number whenever we change the format of
the corresponding file.
Note that the `exec_magic_number` value is duplicated as `EXEC_MAGIC`
in `runtime/caml/exec.h` and they must be kept in sync.
This lets the compiler differentiate files that should be valid files
of the kind it expects, and files that are passed by mistake, either
that are not at all valid compiled files, or because they come from
a different compiler version with an incompatible file format.
We say that we "bump" a magic number when we update its version part
in config.common.ml. To bump all magic numbers is to increment the version
of every kind of magic number.
The process for bootstrapping the compiler is covered in
link:../BOOTSTRAP.adoc[BOOTSTRAP.adoc]. There is also a test script in CI which
demonstrates the process in
link:../tools/ci/inria/bootstrap/script[tools/ci/inria/bootstrap].
=== Updating magic numbers
Previously people tried to update magic numbers as infrequently as
possible, to maximize the lifetime of tools supporting only a fixed
version of magic numbers -- so that they would work for as long as the
underlying representation is compatible.
However, it is more dangerous to forget to update a number than to
update it too often. If we update too often, at worst tool authors have
to update their codebase to support more numbers. If we don't update
often enough, tools break with horrible parsing/deserialization errors
and their authors can do nothing to prevent it.
We have thus decided to systematically bump all magic numbers on each
new major release of the compiler. (We don't want to change compiled
file formats in minor releases, so we shouldn't need to bump magic
numbers systematically. If a format change was necessary for
a critical bugfix, then we would still need to bump on a minor
release.)
This should preferably be done just before the first testing release
(the first beta, or the first rc if there is no beta) of the new major
release. We want it to happen after all format-breaking changes have
been included in the development version, but before the version gets
tested on a large scale: this is when tool authors may update their
tools to test the new release, and if you update *after* that you risk
breaking them again without them noticing.
For example, the magic numbers for 4.13 were updated in
dd7927e156b7cb2f9
|
