this repo has no description
anil.recoil.org
1## Ppx_deriving becomes an optional dependency of ppx_type_conv
2
3There are two ways of using the `ppx_sexp_conv` ppx rewriter:
4
5- the legacy way, with:
6 ```
7 $ ocamlfind ocamlc -package ppx_sexp_conv ...
8 ```
9
10- the new way, with a driver. Since the v0.9.0 version of
11 `ppx_sexp_conv` one can use either the `ocaml-migrate-parsetree`
12 driver or `ppx_driver`. Before v0.9.0 one could only use
13 `ppx_driver`
14
15Using the legacy way requires using `ppx_deriving`. `ppx_deriving`
16used to be a hard dependency of `ppx_sexp_conv` through
17`ppx_type_conv`. Since v0.9.0 it is an optional one. As a result
18pacakges building using the legacy way must declare an explicit
19dependency on `ppx_deriving`.
20
21Many packages didn't at the time `ppx_sexp_conv` v0.9.0 was
22released. To fix builds failure, a `ppx_deriving` dependency was added
23to all packages depending on `ppx_sexp_conv` but not `ppx_deriving`.
24
25## Split build and install steps (2016-05-18)
26
27The opam tool has been separating the "build" and "install" steps of packages
28since version 1.2.2, but historically packages could only define a "build:"
29field in their metadata, that did both steps. There are many usages and tools
30that can benefit from the split (like tracking of installed files without losing
31build parallelism), and it is cleaner overall.
32
33To upgrade older packages that didn't make the move yet, an heuristic has been
34applied to automatically do the split. It's in the
35[admin-scripts/split-install.ml](https://github.com/ocaml/opam/blob/ce8605e0572335beb7f9ae04713c9cc8048cf707/admin-scripts/split_install.ml)
36script and simply reads commands from the end, detecting calls to `install`,
37`cp` to appropriate destinations, and commands mentioning `install`.
38
39The main invariant to respect is that the `build` stage should never write
40outside of its build directory and the temp dir, while the `install` stage
41should be as fast as possible. So in case of doubt, it is better to put
42everything in `install:` instead (but we don't do that automatically, since many
43correct packages only have `build:` and a `.install` file, which we can't detect
44from the metadata alone).
45
46In turn, opam guarantees that `install` and `remove` commands are never run
47concurrently.
48
49Please remember to correctly split the two stages from now on, as advised by
50`opam lint`; tools to check the invariants are being put in place.
51
52## Camlp4 syntax extensions split from Jane Street packages (2016-01-11)
53
54Jane Street packages no longer support camlp4 after the 113.09.00
55series.
56
57For Jane Street packages that contain both a library and a camlp4
58syntax extension, the latter is extracted to its own package.
59
60The following table summarize the changes:
61
62Package | Old findlib name of syntax | New camlp4-only package | version
63------------|----------------------------|-------------------------|----------
64sexplib | sexplib.syntax | pa\_sexp\_conv | 113.00.00
65bin\_prot | bin\_prot.syntax | pa\_bin\_prot | 113.00.00
66typerep | typerep.syntax | pa\_typerep\_conv | 113.00.00
67fieldslib | fieldslib.syntax | pa\_fields\_conv | 113.00.00
68variantslib | variantslib.syntax | pa\_variants\_conv | 109.15.03
69
70### Upgrading
71
72For the long term it is recommended to switch to the corresponding ppx
73alternative (replace the pa\_ prefix by ppx\_ to get the ppx package
74name).
75
76Until then packages that are using one of the camlp4 syntax extension
77must upgrade their build system to refer to the new package
78name. Simply replace the name in the second column by the one in the
79third column.
80
81Running the following shell command on the sources should do:
82
83 sed -ri 's/\<sexplib\.syntax\>/pa_sexp_conv/g;
84 s/\<bin_prot\.syntax\>/pa_bin_prot/g;
85 s/\<typerep\.syntax\>/pa_typerep_conv/g;
86 s/\<fieldslib\.syntax\>/pa_fields_conv/g;
87 s/\<variantslib\.syntax\>/pa_variants_conv/g' \
88 `ag -l .`
89
90The new dependency must also be added to the opam file.
91
92### Automatic upgrade of the opam-repository
93
94To avoid the opam-repository being in a inconsistent state once the
95camlp4-free Jane Street packages are released, the following automatic
96change is applied to the
97[opam repository](https://github.com/ocaml/opam-repository):
98
99```
100for js_pkg in "sexplib" "bin_prot" "type_conv" "variantslib" "fieldslib":
101 for pkg in all_packages():
102 if pkg depends on js_pkg and "type_conv":
103 pkg.add_constraint(js_pkg < next-version-of(js_pkg))
104```
105
106This is an over-approximation as some package might not use the syntax
107extension at all.
108
109Following this automatic change maintainers should:
110
111- just remove the constraint if the package doesn't use the syntax extension
112- do a new release that depend on the new camlp4-only package