You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: src_ext/HACKING.md
+10-13
Original file line number
Diff line number
Diff line change
@@ -6,36 +6,33 @@ Files related to the dependency vendoring are kept in the `src_ext` directory. T
6
6
-`shell/bootstrap-ocaml.sh` - assembles an OCaml compiler in `bootstrap/`
7
7
-`shell/re-patch.sh` - when run from the `src_ext/` directory, normalises all the patch files (eliminating git-specific features, etc.)
8
8
9
-
## lib-ext and lib-pkg
9
+
## Mode of operation
10
10
11
-
There are two modes of operation. `lib-ext` uses Dune vendoring and assembles the dependencies of opam in subdirectories of `src_ext/`, allowing Dune to build them with opam. In this mode, only the `opam` binary can then be installed: the libraries are not installable (as with all Dune vendoring with libraries). `lib-pkg` installs the libraries to a given compiler using either `dune install` (for dependencies which use Dune) or `ocamlfind install` for any others. This mode is typically used to install dependencies to the compiler built in `bootstrap/` by `shell/bootstrap-ocaml.sh`. In `lib-pkg`, the dependency's preferred build system is used, in `lib-ext`, the package must use Dune.
11
+
We use Dune vendoring and assembles the dependencies of opam in subdirectories of `src_ext/`, allowing Dune to build them with opam. Only the `opam` binary can then be installed: the libraries are not installable (as with all Dune vendoring with libraries).
12
12
13
13
## Patching
14
14
15
-
Package sources have patches applied from two places. For package `foo`, the patches in `src_ext/foo.common` and then patches in `src_ext/foo` (for `lib-ext` mode) or `src_ext/foo.pkg` (for `lib-pkg` mode) are applied (within those directories, patches apply in the order returned by shell globbing). Patches placed here are either to back-port the package to an older version of OCaml than upstream supports, or to back-port a fix from an unreleased version of package.
15
+
Package sources have patches applied from two places. For package `foo`, the patches in `src_ext/foo` are applied (within those directories, patches apply in the order returned by shell globbing). Patches placed here are either to back-port the package to an older version of OCaml than upstream supports, or to back-port a fix from an unreleased version of package.
16
16
17
-
In `lib-ext` mode, `dune` files can be dropped into the extracted package sources, after patching, by creating a file named `src_ext/dune-foo`. If the package needs dropping in a subdirectory, then these can be appended to the filename, using `-` instead of `/`. For example, `src_ext/dune-foo-src-lib` will be copied to `src/lib/dune` when package `foo` is extracted.
17
+
`dune` files can be dropped into the extracted package sources, after patching, by creating a file named `src_ext/dune-foo`. If the package needs dropping in a subdirectory, then these can be appended to the filename, using `-` instead of `/`. For example, `src_ext/dune-foo-src-lib` will be copied to `src/lib/dune` when package `foo` is extracted.
18
18
19
19
Finally, `src_ext/Makefile` provides an opportunity for package-specific commands to be run by adding specific commands to the `.stamp` targets. See, for example, the horrors in [f721385](https://github.com/ocaml/opam/commit/f721385).
20
20
21
21
## Updating the dependencies
22
22
23
-
`src_ext/update-sources.sh` will attempt to use repository data from your current opam switch to automatically update `src_ext/Makefile.sources`. For some packages, the script may make the wrong determination (e.g. cudf 0.9, where opam's sources stick with the original gforge source archive), so the changes suggested should be reviewed carefully! After updating the dependencies, it's important to check that the patches still work. These can be triggered manually with `make clone` (for `lib-ext`) or `make clone-pkg` (for `lib-pkg`). If a patch no longer applies, it needs to be updated or replaced (e.g. by rebasing a git commit and using `git format-patch` or by manually applying the changes to a clean worktree and using `diff -Naur`, etc.). Once the patches are correct and `make clone` is working, run `../shell/re-patch.sh` to normalise the patches. This script will apply the patches as given and then regenerate them using `diff`.
23
+
`src_ext/update-sources.sh` will attempt to use repository data from your current opam switch to automatically update `src_ext/Makefile.sources`. For some packages, the script may make the wrong determination (e.g. cudf 0.9, where opam's sources stick with the original gforge source archive), so the changes suggested should be reviewed carefully! After updating the dependencies, it's important to check that the patches still work. These can be triggered manually with `make clone`. If a patch no longer applies, it needs to be updated or replaced (e.g. by rebasing a git commit and using `git format-patch` or by manually applying the changes to a clean worktree and using `diff -Naur`, etc.). Once the patches are correct and `make clone` is working, run `../shell/re-patch.sh` to normalise the patches. This script will apply the patches as given and then regenerate them using `diff`.
24
24
25
25
## Dune and mccs
26
26
27
-
The Dune vendored dependency is a special case: firstly, in lib-ext mode it's optional and secondly the package is called `dune-local`. The name avoids conflict with a directory called `dune` (which Dune itself can't cope with). mccs is also a special case, because it's optional in lib-ext mode.
27
+
The Dune vendored dependency is a special case: firstly, it's optional and secondly the package is called `dune-local`. The name avoids conflict with a directory called `dune` (which Dune itself can't cope with). mccs is also a special case, because it's optional.
28
28
29
29
## Adding a new dependency
30
30
31
-
1. Add the tarball information to `src_ext/Makefile.sources`. If the package is used in `lib-ext` mode, define `URL_package` and `MD5_package`. If the same package is used in `lib-pkg` mode, add `$(call PKG_SAME,package)`, otherwise define `URL_PKG_package` and `MD5_PKG_package`. If a package is only used in `lib-pkg` mode, don't define`URL_package` and `MD5_package`.
32
-
2. Add `package` to `SRC_EXTS`or `PKG_EXTS in `src_ext/Makefile`.
33
-
3. Put any requires patches in `src_ext/patches/` (in `package.common/` for both modes, `package/` for `lib-ext` mode and `package.pkg/` for `lib-pkg` mode).
31
+
1. Add the tarball information to `src_ext/Makefile.sources`. Define`URL_package` and `MD5_package`.
32
+
2. Add `package` to `SRC_EXTS` in `src_ext/Makefile`.
33
+
3. Put any requires patches in `src_ext/patches/` (in `package/`).
34
34
4. If the package's build system is not Dune, create `src_ext/dune-package`. The build system `touch`es `package.opam` when assembling the sources.
35
-
5. Add a `package.pkgbuild:` entry to `src_ext/Makefile.packages` containing the dependencies of `package`.
36
-
6. Add a `package-pkg-build:` target with the build steps for building and installing `package`. Various utility variables are available in `src_ext/Makefile.packages`, in particular `$(OCAMLBIN)` is the compiler's `bin` directory and `$(SITELIB)` is the ocamlfind library root (effectively `%{lib}%` in opam) and `$(OCAMLROOT)` is the actual prefix of the compiler's installation.
37
35
38
36
## Testing
39
37
40
-
* For `lib-pkg` mode: run `make compiler`, backup `bootstrap` directory, and run `make lib-pkg`
41
-
* For `lib-ext` mode: run `./configure --with-vendored-deps`, then `make`
38
+
run `./configure --with-vendored-deps`, then `make`
0 commit comments