This document covers most of the common OPAM features. If you're looking for a +quick introduction, check the Basic Usage tutorial first.
+If you are a developper and want to get a project packaged or change an existing +package, see the step-by-step packaging guide
+The full documentation is available inline, using
+opam --help
+opam <command> --helpThis document is intended as a quicker overview, use the above to dig into the +details.
+OPAM needs to initialise its internal state in a ~/.opam directory to work.
+This command can also take care of installing a version of OCaml if needed.
To operate as expected, some variables need to be set in your environment. You +will be prompted to update your configuration, and given instructions on how +to proceed manually if you decline.
+This command synchronises OPAM's database with the package repositories. The
+lists of available packages and their details are stored into
+~/.opam/repo/<name>. Remember to run this regularly if you want to keep
+up-to-date, or if you are having trouble with a package.
There are three useful commands for that:
+opam list List installed packages, or packages matching a patternopam search Search in package descriptionsopam show Print details on a given package.This command installs packages along with all their dependencies. You can +specify one or several packages, along with version constraints. E.g:
+opam install lwt
+opam install ocp-indent ocp-index.1.0.2
+opam install "ocamlfind>=1.4.0"Will attempt to upgrade the installed packages to their newest versions. You
+should run it after opam update, and may use opam pin to prevent specific
+packages from being upgraded.
This command enables the user to have several installations on disk, each with +their own prefix, set of installed packages, and OCaml version. Use cases +include having to work or test with different OCaml versions, keeping separate +development environments for specific projects, etc.
+Use opam switch <version> to switch to a different OCaml version, or opam
+switch <name> --alias-of <version> to name the new switch as you like. Don't
+forget to run the advertised eval $(opam config env) to update your PATH
+accordingly.
Creating a new switch requires re-compiling OCaml, unless you make it an alias +of the "system" switch, relying on the global OCaml installation.
+There are a bunch of specific or experimental OCaml compiler definitions on the
+official repository, list them all with opan switch list --all.
This command allows to pin a package to a specific version, but in fact, as you +know if you've read the Packaging guide, it can do much more.
+The syntax is
+opam pin add <package name> <target>Where <target> may be a version, but also a local path, an http address or
+even a git, mercurial or darcs URL. The package will be kept up-to-date with its
+origin on opam update and when explicitely mentionned in a command, so that
+you can simply run opam upgrade <package name> to re-compile it from its
+upstream. If the upstream includes OPAM metadata, that will be used as well.
opam pin add camlpdf 1.7 # version pin
+opam pin add camlpdf ~/src/camlpdf # path
+opam pin add opam-lib https://github.com/ocaml/opam.git#1.2 # specific branch or commit
+opam pin add opam-lib --dev-repo # upstream repositoryThis can be used in conjunction with opam source to start and hack an existing
+package before you know it:
opam source <package> --dev-repo --pin
+cd <package>; hack hack hack;
+opam upgrade <package>OPAM is configured by default to use the community's software repository at
+opam.ocaml.org, but this can easily be
+changed at opam init time or later.
opam repo add <name> <address> will make OPAM use the definitions of any
+package versions defined at <address>, falling back to the previously defined
+repositories for those which aren't defined. The <address> may point to an
+http, local or version-controlled repository.
Defining your own repository, either locally or online, is quite easy: you can
+start off by cloning the official
+repository if you intend it as a
+replacement, or just create a new directory with packages and compilers
+sub-directories. See the packaging guide if you need help on
+the package format.
If your repository is going to be served over HTTP, you should generate an index
+using the opam-admin tool.
This short tutorial covers the very basic use cases to get you started with +OPAM. A more lengthy introduction can be found in the +Advanced Usage guide.
+opam initThis will create the ~/.opam directory, within which packages will be
+installed and where OPAM will store its data.
The following commands will enable you to obtain information on available +packages:
+opam list -a # List all available packages
+opam search QUERY # List packages with QUERY in their name or description
+opam show PACKAGE # Display information about PACKAGEYou may prefer to browse them online. If you
+find a package there but not on your computer, either it has been recently added
+and you should simply run opam update, or it's not available on your system or
+OCaml version -- opam install PACKAGE should give you the reason.
The two commands you will probably use the most with OPAM are:
+opam update # Update the packages database
+opam install PACKAGE # Download, build and install the latest version of PACKAGEYou may want to regularly issue these commands to keep your packages up-to-date:
+opam update # Update the packages database
+opam upgrade # Re-install packages that were updated since last upgradeIf you need more details and options, OPAM is self-documented through
+opam --helpTo learn how to use more advanced features of OPAM (package pinning, multiple +repositories, multiple compilers...), move on to the Advanced +Usage guide, or the Packaging tutorial.
diff --git a/doc/tutorials/Basic_Usage.pdf b/doc/tutorials/Basic_Usage.pdf deleted file mode 100644 index 0eaed819ae5..00000000000 Binary files a/doc/tutorials/Basic_Usage.pdf and /dev/null differ diff --git a/doc/tutorials/Developing.pdf b/doc/tutorials/Developing.pdf deleted file mode 100644 index 17d7ba26060..00000000000 Binary files a/doc/tutorials/Developing.pdf and /dev/null differ diff --git a/doc/tutorials/FAQ.html b/doc/tutorials/FAQ.html new file mode 100644 index 00000000000..ddad4029175 --- /dev/null +++ b/doc/tutorials/FAQ.html @@ -0,0 +1,121 @@ +See the Quick install guide.
+OPAM has git-like, hierarchical manpages. Try opam --help for a starting point.
Get started with OPAM packages by reading the Packaging Howto.
+See the details on the file formats and more in the Developper +Guide +(pdf).
+OPAM is designed to be run strictly as user (non-root), and apart for the
+explicit options provided during opam init, only writes within ~/.opam (and
+/tmp). This directory -- the default "OPAM root" -- contains configuration,
+various internal data, a cache of downloaded archives, and your OCaml
+installations.
opam init need to add stuff to my init scripts / why is eval $(opam config env) needed ?You need two things when you install OPAM packages: to have their libraries +accessible, and to access binary programs. To provide those, OPAM needs to setup +a few ocaml-related environment variables, and to prepend to your PATH variable.
+Of course, you may choose not to let OPAM change anything at opam init, and
+run eval $(opam config env) yourself whenever you will be needing it.
An ocaml installation and a set of installed packages within an OPAM
+installation. This can be used to keep different OCaml versions side-by-side, or
+different sets of packages. See the related
+section in the Advanced usage manual and
+opam switch --help. The "prefix" for a given installation is simply
+~/.opam/<switch-name>.
A switch is either based on a system-wide OCaml installation, or on a local +installation. In the former case, OPAM will need to recompile all packages when +your system compiler changes. In the latter case, OCaml will be downloaded and +compiled on creation of the switch.
+Yes. Use one of:
+eval $(opam config env --switch <switch>) # for the current shell
+opam config exec --switch <switch> <command> # for one commandThis only affects the environment.
+Yes. Use:
+opam switch export file.export # from the previous switch
+opam switch <new switch>
+opam switch import file.exportOPAM might fail if you had packages installed that are not compatible with the
+OCaml version in your new switch. In that case, you'll need to remove them from
+the file.export file by hand (the format is straight-forward, one line per
+package).
ocamlfind remove / fiddled with the installed packages and OPAM is out of sync. Help !Don't panic. OPAM assumes it's controlling what's below ~/.opam/<switch>, but
+there are several ways you can recover:
opam remove --force will attempt to uninstall even if not registered as
+ installed. Then opam installopam reinstall will try to remove an installed package, but go on to
+ re-installing even if that fails.opam switch reinstallopam install|remove --fake. This is not
+ recommended though, as your manual install may not be exactly equivalent to
+ the one expected by other OPAM packages, and OPAM may later on trigger
+ reinstallations or upgrades of the package. Don't complain if you mess up your
+ installation using this! If you want to control how a package is installed or
+ modify it, the right way is opam pin.1GB of memory should be all you need. It was reported that you may run into +problems with 512MB of RAM and no swap. Of course, software packages themselves +may be more greedy.
+They probably depend on system, non-OCaml libraries: you'll need to install them +using your system package manager (apt-get, yum, pacman, homebrew, etc.). If you +have no idea what the missing system package might be:
+opam list <package> --externalFirst of all, you should make sure your repositories are up-to-date:
+opam updateIf this isn't enough, or if you get the checksum errors while running opam
+init, this could be caused by a badly configured proxy cache that is serving
+stale files. To clear your proxy cache, you can use wget --no-cache
+<remote-file> and retry.
As a last resort, you can bypass the checksum checks using --no-checksums.
opam upgrade PACKAGES, opam
+ install 'PACKAGE>=VERSION' PACKAGE..., etc.)Bug reports and feature requests for the OPAM tool should be reported on +OPAM's issue-tracker.
+Packaging issues or requests for a new package can be reported on the +official repository's +issue-tracker.
+General queries for both the tool and the packages can be addressed on the +OCaml-platform mailing-list and +insights and evolution of OPAM internals can discussed on the OPAM-devel +mailing-list.
+You may also try IRC channel #opam on Freenode.
Create a local package from the current directory
+$ opam pin add <name> .Get a local copy of an existing package and install from there
+$ opam source <package> --pinGet it back to normal
+$ opam pin remove <package>Publish to the OPAM repository:
+opam, descr and url files to packages/<pkgname>/<pkgname>.<version>An OPAM package is basically just a bunch of data on a software project:
+This document will go through a simple way to get it in the right format, whether +you are packaging your own project or someone else's. It's not a complete guide +to the opam file format.
+We'll be assuming that you have a working OPAM installation. If not, please +first read the quick install guide.
+Let's start from the root directory of your project source, typically obtained +from a version-controlled repository or from a tarball.
+$ wget https://.../project.tar.gz && tar xvzf project.tar.gz
+# Or
+$ git clone git://.../project.git
+...
+$ cd projectOPAM 1.2 provides a feature that allows you to register packages locally, +without the need for them to exist in a repository. We call this pinning, +because it is an extension of the very common feature that allows to pin a +package to a specific version number in other package managers.
+So let's create a package pinned to the current directory. We just need to +choose a name and issue the command:
+$ opam pin add <project> . -n(-n tells OPAM to not try and install just yet, we'll get to it later)
At this stage, OPAM will be looking for metadata for the package <project>, on
+its repository and in the source directory. Not finding any, it will open an
+editor with a pre-filled template for your package's opam file. It's best to
+keep the project's README file open at this stage, as it should contain the
+information we're interested in, only in a less normalised format.
opam-version: "1.2"
+maintainer: "Name <email>"
+author: "Name <email>"
+name: "project"
+version: "0.1"
+homepage: ""
+bug-reports: ""
+license: ""
+build: [
+ ["./configure" "--prefix=%{prefix}%"]
+ [make]
+]
+install: [make "install"]
+remove: ["ocamlfind" "remove" "project"]
+depends: "ocamlfind"The opam-version, maintainer and version fields are mandatory ; you should
+remove the others rather than leave them empty.
maintainer for now, so give a way to contact you in
+ case your package needs maintenance.build field, that tells OPAM how to compile the
+ project. Each element of the list is a single command in square brackets,
+ containing arguments either as a string ("./configure") or a variable name
+ (make, defined by default to point at the chosen "make" command -- think
+ $(MAKE) in Makefiles). %{prefix}% is another syntax to replace variables
+ within strings.install is similar to build, but tells OPAM how to install. This is indeed
+ install: [ [make "install"] ], but the extra square brackets are optional
+ when there is a single element, just add them if you need more than one
+ command.remove is similar to build and install, but tells OPAM how to uninstall.depends should be a list of existing OPAM package names that your package
+ relies on to build and run. You'll be guaranteed those are there when you
+ execute the build instructions, and won't be changed or removed while your
+ package is installed.A few other fields are available, but that should be enough to get started. Like
+install and remove, most fields may contain lists in square brackets rather
+than a single element: maintainer, author, homepage, bug-reports,
+license and depends.
One you save and quit, OPAM will syntax-check and let you edit again in case of +errors.
+The best test is to let OPAM attempt to install your just created package. As +for any package, you do it by hand with:
+$ opam install <project> --verboseAt this point, OPAM will get a snapshot of the project, resolve its dependencies
+and propose a course of actions for the install. Let it go and see if your
+project installs successfully ; it's a good idea to use --verbose as it will
+make OPAM print the output of the externals commands, in particular the ones in
+the build instructions.
You can now check that everything is installed as expected. Do also check that
+opam remove <project> works properly.
If you need to change anything, simply do
+opam pin edit <project>to get back to editing the opam file. Manually editing the opam file in
+your source tree also works.
So far, so good ! You may have missed dependencies in case they were already +installed on your system, but that will be checked automatically by the +continuous integration system when you attempt to publish your package to the +OPAM repository, so don't worry.
+There are still two things missing for a complete package.
+An appealing description. Put it in a simple utf-8 text file named descr.
+ Like for git commits, the first line is a short summary, and a longer text may
+ follow.
An URL where OPAM may download the project source for the release. If your
+ project is hosted on github, pushing TAG will automatically provide
+ https://github.com/me/project/archive/TAG.zip. This shoud be put in
+ an url file, with a format similar to that of opam:
archive: "https://address/of/project.1.0.tar.gz"
+checksum: "3ffed1987a040024076c08f4a7af9b21"The checksum is a simple md5 of the archive, which you can obtain with:
+curl -L "https://address/of/project.1.0.tar.gz" | md5sumThat's it !
+Publishing is currently handled through Github, using the pull-request +mechanism. If you're not familiar with it, it is a fancy way to:
+Here is how to do it from scratch:
+Go to https://github.com/ocaml/opam-repository and hit the Fork button on
+ the top right corner (you may be asked to login or register)
Get the clone URL on the right, and, from the shell, run git clone <url>
+ to get your local copy
Now we'll add the new package description (opam, descr and url files)
+ into opam-repository/packages/<project>/<project>.<version>/ and make that
+ a git commit:
$ cd opam-repository/packages
+$ mkdir -p <project>/<project>.<version>
+$ cp <project-src>/opam <project>/<project>.<version>
+$ cp <path-to>/url <path-to>/descr <project>/<project>.<version>
+$ git add <project>
+$ git commit -m "Added new fancy <project>.<version>"Sending that back to github is just a matter of running git push
Back to the web interface, refresh, hit the Pull request button, check your
+ changes and confirm;
Wait for feedback !
+Don't forget to opam pin remove <project> once your project is on the
+repository, if you don't want to continue using your local version. Remember
+that as long as the package is pinned, OPAM will use the metadata found in its
+source if any, but otherwise only what is in the OPAM repository matters. Use
+git pin list to list all currently pinned packages.
You may skip the first step and pin to a remote version-controlled + repository directly, using for example
+$ opam pin add <project> git://github.com/me/project.gitOPAM will propose to save your opam file back to your source, but if you want
+ to take a peek at the internal version it's at
+ ~/.opam/<switch>/overlay/<project>/. You may also check it with opam show
+ --raw.
You can set OPAM to use your local clone of the repository with
+$ opam repository add my-dev-repo path/to/opam-repositoryDon't forget to opam pin remove <project>, and test your changes to the repo
+directly. You'll also need to opam update my-dev-repo each time to keep OPAM
+in sync (opam update synches all repos, this will be faster).
Pins can also be used to try out experimental changes to a project with
+ minimal effort: you can pin to a git repository and even to a specific branch,
+ tag or hash by adding #BRANCH to the target. So say you want to try out
+ Joe's GitHub pull-request present on his branch new-feature on his fork of
+ project, just do
$ opam pin project git://github.com/Joe/project.git#new-featureand OPAM will use that to get the source (and possibly updated metadata) of +the package; this works with any branch of any git repo, it's not github +specific.
+We've been focusing on git above, but OPAM can handle darcs and mercurial
+ repositories too, using darcs:// and hg://.
The opam files can express much more than what was shown above. Without getting +into too much details, here are some of the most useful features:
+Version constraints: an optional version constraint can be added after any
+ package name in depends: simply write "package" {>= "3.2"}. Warning,
+ versions are strings too, don't forget the quotes.
Formulas: depends are by default a conjunction (all of them are required),
+ but you can use the logical "and" & and "or" | operators, and even group
+ with parens. The same is true for version constraints: ("pkg1" & "pkg2") |
+ "pkg3" {>= "3.2" & != "3.7"}.
Build depends: you may add the key build in front of the version
+ constraints, e.g. "package" {build & >= "3.2"}, to indicate that there is no
+ run-time dependency to this package: it is required but won't trigger rebuilds
+ of your package when changed.
OS and OCaml constraints: The available field is a formula that
+ determines your package availability based on the os, OCaml version or other
+ constraints. For example:
available: [ os != "darwin" | ocaml-version >= "4.00" ]Conflicts: some packages just can't coexist. The conflicts field is a
+ list of packages, with optional version constraints.
Optional dependencies: they change the way your package builds, but are
+ not mandatory. The depopts field is a simple list of package names. If you
+ require specific versions, add a conflicts field with the ones that won't
+ work.
Variables: you can get a list of predefined variables that you can use in
+ your opam rules with opam config list.
Filters: full commands, or single commands arguments, may need to be + omitted depending on the environment. This uses the same optional argument + syntax as above, postfix curly braces, with boolean conditions:
+["./configure" "--with-foo" {ocaml-version > "3.12"} "--prefix=%{prefix}%"]
+[make "byte"] { !ocaml-native }
+[make "native"] { ocaml-native }For more, see the +OPAM Developer's Manual
diff --git a/doc/tutorials/Packaging.pdf b/doc/tutorials/Packaging.pdf deleted file mode 100644 index d733ea8303a..00000000000 Binary files a/doc/tutorials/Packaging.pdf and /dev/null differ diff --git a/doc/tutorials/Quick_Install.html b/doc/tutorials/Quick_Install.html new file mode 100644 index 00000000000..d53b16476c1 --- /dev/null +++ b/doc/tutorials/Quick_Install.html @@ -0,0 +1,76 @@ ++Notice
OPAM 1.2.0 is just being released. It may take a few days before the binary +packages make it to your distribution, we'll keep updating as it goes. If you +don't want to wait:
++
+- +
+- +
or use the binary installer.
+
This page describes how to install and configure OPAM.
+For further help on how to use OPAM, either read
+opam --help or move on to the Basic Usage guide.
You can use the OPAM package of your distribution if +available. Here is a list of supported distributions:
+The opam and opam-git packages are available in the AUR. Replace opam with opam-git in the following instruction to get the development version:
yaourt -S opamBinary packages of OPAM 1.1.1 are available for the testing and unstable distributions. Wheezy users are left with the options of compiling from source, pinning the packages from the testing repository, requesting a backport from Debian, or using our binary installer below.
+apt-get install opamSimply install the dev-ocaml/opam package: cave resolve -x dev-ocaml/opam.
+You might need to add the ::ocaml-unofficial repository first: cave resolve -x repository/ocaml-unofficial.
The opam package for Mageia can be installed with the command:
+urpmi opamOPAM packages for homebrew and MacPorts are available:
+brew install opam # using Homebrew on OSX Mavericks
+brew install opam --without-aspcud # using Homebrew on OSX Mountain Lion (or lower)
+port install opam # using MacPortSee also howto setup Emacs.app for opam usage.
+add-apt-repository ppa:avsm/ppa
+apt-get update
+apt-get install ocaml opamThere are also PPAs available that are pinned to specific revisions of OCaml and OPAM to help with automated testing.
+If the command add-apt-repository is not available, you can install the package python-software-properties with apt-get install python-software-properties. Alternatively, you may manually edit the file /etc/apt/sources.list to add the PPA for your Ubuntu release.
OCaml 4.01.0 and OPAM 1.1.1 are included in Ubuntu Trusty's universe repository, so just install them as normal.
apt-get update
+apt-get install ocaml ocaml-native-compilers camlp4-extra opamPre-compiled versions for most common architectures and OSes are available on the Github "releases" page. We also provide a very simple installer script that will automatically download the right version for you, put it in your binary directory and initialize it.
+Download opam_installer.sh and run it as follows:
+sh <path to>/opam_installer.sh /usr/local/binYou can also specify which version of OCaml you want to install:
+sh ./opam_installer.sh /usr/local/bin 3.12.1 # Install the latest OPAM and OCaml 3.12.1
+sh ./opam_installer.sh /usr/local/bin system # Install the latest OPAM using the system compiler (if any)Sources of the latest stable version of OPAM are available on Github:
+ + +You can also download the full archives, including OPAM dependencies:
+Follow the instructions in README.md to get OPAM built and installed from
+there.
ocamlbrew is a script that can bootstrap an OCaml environment including OPAM, from source. This option does not require an existing OCaml installation, or a pre-compiled OPAM binary for your platform. To bootstrap a new OCaml environment including OPAM, make sure that you have the necessary pre-requisites installed to run ocamlbrew, and then run:
+curl -kL https://raw.github.com/hcarty/ocamlbrew/master/ocamlbrew-install | env OCAMLBREW_FLAGS="-r" bashA 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.
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.
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 packageschanged : the number of packages modifiedremoved : the number of packages removednotuptodate : the number of packages that are not at their latest versionFor 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.
+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 wich are not at their latest version, and then reduce the changes to a minimum.
This is 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
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 opam uses a different default value -removed,-changed,-notuptodate that tries to minimise changes to the system. It can be set using the environment variable OPAMCRITERIA
Recent versions of opam allow to specify your 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 issueing 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:
opam upgrade --criteria="-changed"You can also use the OPAMCRITERIA and OPAMUPGRADECRITERIA environment variables to specify your preferences (for example, adding your preferred settings to a shell profile). If both variables are set, upgrades are controlled by OPAMUPGRADECRITERIA, while OPAMCRITERIA applies to all other commands.
+If only OPAMCRITERIA is set, it applies to all commands. If only OPAMUPGRADECRITERIA is set, it applies to upgrade commands only, while all other commands are controlled by the opam internal default preferences.
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 external dependency solvers for package managers, that communicate with the package manager front-end via the CUDF format.
+We have now several CUDF-compatible solvers, developed by a variety of research teams during the MISC competitions run yearly from 2010 to 2012:
Each of these competitions led to improving the preferences language, by allowing the user progressively more flexibility.
+As of today, the preferences language described in the previous section, which corresponds to the one used in the 2010 competition, should be supported by all external solvers, but if you happen to use as external solver one of the entrants of the 2012 competition, like recent versions of aspcud, then you have access to a more sophisticated set of preferences, described in the 2012 MISC competition rules.
+For example, 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 aspcud solver supports this extended language starting from its version 1.8.0, which unfortunately is not the version shipped by default with Ubuntu precise or Debian Wheezy.
Starting from version 1.9.0, aspcud adds support for three extra selectors, that are particularly useful to perform local upgrades. Here they are:
installrequest is the set of packages in the solution that satisfy the requirements mentioned in the install: part of a CUDF requestupgraderequest is the set of packages in the solution that satisfy the requirements mentioned in the upgrade: part of a CUDF requestrequest is the union of the above twoUsing this extended set of package selector, it is now finally possible to specify user preferences that describe optimisations to be applied only to the packages explicitly mentioned in the request. For example, -notuptodate(request),-count(changed) would find a solution that tries to bring all packages mentioned in the request to their latest version, while leaving all the rest as untouched as possible.
And if we have added to each package a priority value, we could also play with preferences like +sum(upgraderequest,priority),-count(changed) to get the packages mentioned in the upgrade request to the version with the highest possible priority, while leaving all the rest as untouched as possible.
For portability reasons, opam also embarks an ad-hoc solver module that is built by wrapping a set of heuristics around the code of the SAT-solver which is used in the Dose Library for detecting broken packages. This solver module has no support for user preferences, and is not able to manage correctly large package repositories: it is highly recommended that you install an external CUDF solver (aspcud is the one best supported today).
Thanks to support from Irill, it is now possible to use an external solver for opam on any platform, over the network. See the CUDF solver farm for instructions.
+The latest version of the solver is on the farm, so you can use the full preferences language with it.