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