Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
talex5 committed May 26, 2020
1 parent c05ad0e commit daed329
Showing 1 changed file with 51 additions and 13 deletions.
64 changes: 51 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ In many situations (e.g. a CI system building in a clean environment, a
project-local opam root, or a duniverse build) this is not necessary, and we
can get a solution much faster by using a different algorithm.

This package uses 0install's (pure OCaml) solver with opam packages.
This package does that by using 0install's (pure OCaml) solver with opam
packages.

# Usage

Expand All @@ -22,7 +23,9 @@ base-bigarray.base base-bytes.base base-threads.base base-unix.base camomile.1.0
[NOTE] Solve took 0.25 s
```

It outputs the set of packages that should be installed (but doesn't install them itself).
Note: the first run may be slow, as the opam library it uses may decide to rebuild its index first.

`opam-0install` outputs the set of packages that should be installed (but doesn't install them itself).
The output is in a format suitable for use as input to `opam`. e.g.

```bash
Expand Down Expand Up @@ -74,23 +77,58 @@ To compare the results, use:

dune exec -- ./test/diff.exe baseline.csv new.csv

# API

The library provides these sub-modules under `Opam_0install`:

- `Solver` is used to create a solver, given an `S.CONTEXT` (source of opam packages).
- `Switch_context` gets packages from the user's opam switch, including any pinned packages.
- `Dir_context` reads the packages directly from a checkout of `opam-repository`.
- `Model` is used internally by `Solver`. It provides the interface needed by 0install.

Example:

```ocaml
let env =
Opam_0install.Dir_context.std_env
~arch:"x86_64"
~os:"linux"
~os_family:"debian"
~os_distribution:"debian"
~os_version:"10"
let context =
Opam_0install.Dir_context.create "/tmp/opam-repository/packages"
~constraints:OpamPackage.Name.Map.empty
~env
module Solver = Opam_0install.Solver.Make(Opam_0install.Dir_context)
let () =
let result = Solver.solve context [OpamPackage.Name.of_string "utop"] in
match result with
| Error e -> print_endline (Solver.diagnostics e)
| Ok selections ->
Solver.packages_of_result selections
|> List.iter (fun pkg -> Printf.printf "- %s\n" (OpamPackage.to_string pkg))
```

# Internals

The core 0install solver does not depend on the rest of 0install and just
provides a functor that can be instantiated with whatever package system you
like (see [Simplifying the Solver With Functors][]).

- The `zi-solver` directory contains a copy of 0install's `solver` directory.
- The `lib` directory applies this to opam.
like (see [Simplifying the Solver With Functors][]). [Zeroinstall_solver.S][]
describes the interface required by the `0install-solver` package.

`zi-solver/s.ml` describes the interface required by `zi-solver`.
`lib/model.ml` maps opam concepts onto 0install ones. It's a little
complicated because 0install doesn't support alternatives in dependencies (e.g.
`ocaml-config` depends on `"ocaml-base-compiler" | "ocaml-variants" |
"ocaml-system"`). The mapping introduces a "virtual" package in these cases
(so `ocaml-config` depends on a virtual package that has three available versions,
with dependencies on the real packages).
`opam-0install` provides an implementation of this interface using opam package
metadata. It's a little complicated because 0install doesn't support
alternatives in dependencies (e.g. `ocaml-config` depends on
`"ocaml-base-compiler" | "ocaml-variants" | "ocaml-system"`). The mapping
introduces a "virtual" package in these cases (so `ocaml-config` depends on a
virtual package that has three available versions, with dependencies on the
real packages).

A virtual package is also created if you specify multiple packages on the command-line.

[Zeroinstall_solver.S]: https://0install.github.io/0install/0install-solver/Zeroinstall_solver/S/index.html
[Simplifying the Solver With Functors]: https://roscidus.com/blog/blog/2014/09/17/simplifying-the-solver-with-functors/

0 comments on commit daed329

Please sign in to comment.