diff --git a/doc/explanation/package-management.md b/doc/explanation/package-management.md index 72dcb37500d4..8671a62151b7 100644 --- a/doc/explanation/package-management.md +++ b/doc/explanation/package-management.md @@ -65,16 +65,17 @@ supported. ## Locking -Given the list of the project's transitive dependencies and their version +Given the list of the project's dependencies and their version constraints, the next steps are: -1. Figure out a version for each dependency that satisifies the constraints +1. Find the transitive dependencies and figure out a version for each + dependency that satisifies the constraints 2. For each dependency, download it, build it, and make it available to the project -In `opam`, `opam install` does both of these. +In opam, `opam install` does both of these. -In `dune`, these are separate steps: the first one is `dune pkg lock`, and the +In Dune, these are separate steps: the first one is `dune pkg lock`, and the second one happens implicitly as part of [building](#building). The idea of doing the first step and recording it for later is popular in other @@ -91,13 +92,13 @@ always requires a set of locked packages. In the most general sense, a package lock is just a set of specific packages and their versions to be installed. -A Dune lock file extends this to a directory (a "lock directory") with files that describe the -dependencies. It includes the package's name and version. Unlike many other -package managers, the files include a lot of other information as well, such as -the location of the source archives to download (since there is no central -location for all archives), the build instructions (since each package can use -its own way of building), and additional metadata like the system packages it -depends upon. +A Dune lock file extends this to a directory (a "lock directory") with files +that describe the dependencies. It includes the package's name and version. +Unlike many other package managers, the files include a lot of other +information as well, such as the location of the source archives to download +(since there is no central location for all archives), the build instructions +(since each package can use its own way of building), and additional metadata +like the system packages it depends upon. The information is stored in a directory (`dune.lock` by default) as separate files, to reduce potential merge conflicts and simplify code review. Storing @@ -137,8 +138,8 @@ repository can be used by specifying a commit hash. Dune defines two repositories by default: -* `upstream` refers to the default branch of `opam-repository`, which - contains all the publicly released packages. +* `upstream` refers to the default branch of `opam-repository`, which contains + all the publicly released packages. * `overlay` refers to [opam-overlay](https://github.com/ocaml-dune/opam-overlays), which defines packages patched to work with package management. The long-term goal is to @@ -148,14 +149,14 @@ Dune defines two repositories by default: ### Solving -After Dune has retrieved the constraints and the set of possible packages, it -is necessary to determine which packages and versions should be selected for -the package lock. +After Dune has read the constraints and loaded set of candidate packages, it is +necessary to determine which packages and versions should be selected for the +package lock. To do so, Dune uses [`opam-0install-solver`](https://github.com/ocaml-opam/opam-0install-solver), -which is a variant of the [`0install`](https://github.com/0install/0install) solver to find solutions for opam -packages. +which is a variant of the [`0install`](https://github.com/0install/0install) +solver to find solutions for opam packages. Contrary to opam, the Dune solver always starts from a blank slate; it assumes nothing is installed and everything needs to be installed. This has the @@ -181,8 +182,8 @@ in a later step. ## Building When building, Dune will read the information from the lock directory and set -up rules for the packages. Check {doc}`/explanation/mental-model` for -details about rules. +up rules for the packages. Check {doc}`/explanation/mental-model` for details +about rules. The rules that the package management sets up include: @@ -217,9 +218,14 @@ installed in and expect this path to remain the same. Dune builds packages in a sandbox location, and after the build has finished, it moves the files to the actual destination. -There are several reasons for building packages in a sandbox. On one hand it enables building without messing -up the current state, and on the other hand it allows for caching artifacts -across projects. +:::{note} +Unlike opam, Dune at the moment does not wrap the build in sandboxing tools +like [Bubblewrap](https://github.com/containers/bubblewrap). +::: + +There are several reasons for building packages in a sandbox. On one hand it +enables building without messing up the current state, and on the other hand it +allows for caching artifacts across projects. To comply with these restrictions the usual solution is to use relative paths, as Dune guarantees that packages installed into different sections are