External Solvers

Resolving package installations in the presence of dependencies and conflicts is known to be an NP-complete problem. Thankfully, a big effort has already been put into solving it efficiently:

The opam package manager is an instance of the approach described in the article "A modular package manager architecture", which was one of the outcomes of the Mancoosi research project. This architecture relies on dependency solvers for package managers, that communicate with the package manager front-end via the CUDF format.

Installation and compatibility

As of 2.0.0, opam comes with a CUDF solver built-in by default, so unless you have specifically compiled without it, you shouldn't have to be worried about installing an external solver. However, these are still supported, and can be useful in some specific cases. An external solver can be chosen over the built-in one using the --solver command-line argument, the $OPAMEXTERNALSOLVER environment variable, or the solver: field in the ~/.opam/config file. If no solver was built in or selected, opam will detect the availability of aspcud, packup or mccs commands on your system and use one automatically.

The following CUDF solvers have been tested:

• aspcud (recommended solution until opam 1.2.2)
• packup
• mccs (a modified version of which is now being used as the built-in solver)
• p2Cudf, which can be downloaded here and used with the configuration string java -jar <jarfile-location> -obj %{criteria}% %{input}% %{output}%.

These have been developed by a variety of research teams during the MISC competitions run yearly from 2010 to 2012.

Specifying user Preferences for the External Solvers

A fundamental distinguishing feature of the opam package manager is the fact that it is designed to reuse state-of-the-art dependency solving technology that gives the users the possibility to express their preferences regarding the operations to be performed during an installation, instead of being bound to an hard-coded strategy. This section provides basic documentation on this feature, and its usage.

What are user preferences for installations, and why are they important?

When you request the installation of some packages, say p1...pn, opam has a lot to do: it needs to look at all the packages already installed on your machine, find all packages available from the repositories, consider your request, and then come up with a set of actions to be performed to satisfy your request.

Unfortunately, there are a lot of assumptions hidden in your mind when you tell opam that you want p1...pn installed: should it choose the latest version of the p1...pn? That seems a sensible thing to do, but sometimes installing a recent version of a package p may lead to downgrading or removing another package q, which is something you might not want. What should opam do in this case? Remove q to get the latest p, or keep q and get the most recent p that is compatible with it? Well, the answer is: it depends! It depends on what you really want, and different users may have different points of view.

User preferences, supported by CUDF-compatible solvers, are the means you can use to make the assumptions in your mind explicit and known to the solver used by opam, so that the actions performed on your machine correspond to your personalised needs.

How do I express my preferences?

Preferences are expressed using a simple language built by prefixing a little set of combinators with the - (minus) or + (plus) operators. The most useful combinators are the following ones:

• new : the number of new packages
• changed : the number of packages modified
• removed : the number of packages removed
• notuptodate : the number of packages that are not at their latest version

For example, the preference -removed tells the solver that among all possible ways of satisfying your request, it should choose one that minimises the number of packages removed.

These combinators can be combined in a comma separated sequence, that is treated in lexicographic order by the solver.

Default preferences for an upgrade

For example, the preference -removed,-notuptodate,-changed tells the solver that after ensuring that removals are minimised, it should look for a solution that minimises also the number of packages which are not at their latest version, and then reduce the changes to a minimum.

This is close to the default preference setting used by opam when you perform an update or an upgrade, and in practice it tries to bring all your packages to the latest version available, as far as this does not implies removing too many packages. It can be set using the environment variable OPAMUPGRADECRITERIA, or the solver-upgrade-criteria: configuration field.

Default preferences for an install

When you request to install a (set of) package(s), in general you do not expect to see all your existing packages updated, and this is why in this case it is preferable to use a different value -removed,-changed,-notuptodate that tries to minimise changes to the system. It can be set using the environment variable OPAMCRITERIA, or the solver-criteria: configuration field.

Specifying preferences for opam

opam allows one to specify criteria on the command line, using the --criteria option, that will apply only to the current command. For example, if you are a very conservative user, you might try issuing the following command:

opam install --criteria="-removed,-changed" ...

This can also be used for some tricks: if for example you want to repair your set of installed packages, you can use the opam upgrade command without specifying a preference for newer versions in the criteria (although you may prefer to run opam upgrade --fixup in this case):

opam upgrade --criteria="-changed"

Yes, there are different versions of the user preference language

The different editions of the MISC competition led to improving the preferences language, by allowing the user progressively more flexibility. Recent solvers give access to a more sophisticated set of preferences, described in the 2012 MISC competition rules. For example, using aspcud >=1.8.0, you could use

-count(removed),-count(down),-sum(solution,installedsize),-notuptodate(solution),-count(changed)

to instruct a solver to minimise downgrades, and mininise the installed size, among other criteria.

The default criteria used by opam use a custom CUDF property version-lag that gives a monotonic measure of the "age" of packages, by counting the number of newer revisions of the package. They can be seen using the opam config report command:

# install-criteria  -removed,-count[version-lag,request],-count[version-lag,changed],-changed
# upgrade-criteria  -removed,-count[version-lag,solution],-new

Notice that these criteria are written for the built-in solver which, being derived from mccs, uses a slightly different syntax for the criteria: the -sum(subset,property) criterion should be written -count[property,subset] instead. We also make use of the request subset here, which applies only to the packages that were part of the user request, and was introduced in aspcud 1.9.0 and is not part of the official mccs release.