From the OCaml Labs wiki
Jump to: navigation, search


OPAM is a source-based package manager for OCaml. It supports multiple simultaneous compiler installations, flexible package constraints, and a Git-friendly development workflow.

Related Pages[edit]



Using OPAM[edit]

Package Lifecycle[edit]

OPAM allows you to manage the lifecycle of your packages: including update, examine, install and upgrade.

  • Update: opam update This command will update the locally-saved states of your repositories to make sure you have access to the last updates from them.
  • Examine:
    • opam list This will display as many lines as there are packages available, and each line displays the name of the package, its version if it is installed, and a short description.
    • opam search This will display something similar to opam list except for it is only going to display available packages whose name or description match the string you declare.
    • opam info This will display information about the package you declare. This information includes the installed version if the package is installed, all available versions that can be installed, and the full description of the package.
  • Install: opam install If the package to be installed has no dependencies or if all its dependencies are already installed, then OPAM will install it without further ado. Otherwise, it will print a summary of the actions that are going to be performed, and you will be asked if it should continue.

Optional dependencies will not be installed by default, but opam install will take advantage of them if they are already installed while installing a package that optionally depends on them. OPAM will also track optional dependencies. This means that while installing a new package, OPAM will check if any already installed package optionally depends on the package to be installed, and will recompile such packages and all their forward dependencies.

  • Upgrade: After running opam update, it is possible that some packages that you installed got updated upstream, and it is now possible to upgrade them on your system. Use opam upgrade to upgrade your packages. The dependency solver will be called to make sure the upgrade is possible, that is, that most packages can get upgraded. OPAM will select the the best upgrade scenario and display a summary of what will be done during the upgrade.

Multiple Compiler Support[edit]

OPAM has the ability to install and use different OCaml compilers. This functionality is useful if you need to use different compilers on the same computer, and will make it very easy to switch between different compiler versions. This functionality is driven by the opam switch command. Using opam switch --help will give you the full documentation.

  • opam switch list will display a list of the available compilers. The first section is a list of installed compilers on this computer. It contains at least system, which is not a compiler installed by opam but the compiler that was used to compile opam in the first place.
  • opam switch 4.00.0 will make opam to switch to OCaml 4.00.0. If opam did not install it already, it will do so now. The first opam switch therefore takes the time it needs for your system to compile OCaml 4.00.0.
  • opam switch remove <version> will just delete an opam-installed compiler from your system, freeing some disk space.

After switching to another compiler, opam will ask you to update your environment by running eval opam config env.

Compiler copies under an alias[edit]

opam switch install <alias> --alias-of <version> is useful if you want to use two instances of the same compiler.

Replicating the state of one compiler to another

Useful if you want to have the ability to fork a given compiler.

opam switch <version>
opam switch export -f universe_for_<version>
opam switch <other-version>
opam switch import -f universe_for_<version>

Version pinning[edit]

opam pin <package> </local/path> uses the content of /local/path to compile package. opam pin remove <package> to unpin.

Handling repositories[edit]

OPAM supports using multiple repositories at the same time, and supports multiple repository backends as well. Currently supported backends are HTTP, rsync, and git.

These three backends should be sufficient to access most repositories. Additional backends can be added without much effort because of the modularized interface, basically, adding a backend means just implementing a module matching the REPOSITORY signature.

From repositories, OPAM makes a global index of all available packages. This means that if two repositories export the same package, OPAM will download it from a random one (in practice, from the last added repository). You can change that by editing ~/.opam/repo/index and moving the repository you want to use in the beginning of each package line you want to install from this repository.

Adding your own packages[edit]

Put your packages in a private repository and then add this repository in order to be able to install these packages the same way you install public OPAM packages.

Current Projects[edit]

Opam local - March 2016

The opam local project's goal is to enable developers to create isolated development and testing environments for their OPAM packages. By associating a switch with a directory via the opam local create command, other opam commands will recognize they are in a directory sandbox and override the globally-configured switch. This causes commands that modify switch state (e.g., opam install, opam pin, etc.) to be isolated to the switch associated to the directory in which they're executed, leaving the gobal OPAM state, as well as other local sandboxes, unchanged. In addition, developers can access development lifecycle events defined in their project's OPAM files via the opam package [build|test|doc] commands. There are outstanding pull requests to the OPAM package that include these features, awaiting review.


OPAM 1.2 - October 2014

OPAM 1.2 features a streamlined workflow to improve the day-to-day development experience, as well as numerous performance and reliability improvements.

  • An extended and versatile opam pin command, described here
  • More expressive queries over the package database, and opam source to quickly clone packages
  • New metadata fields for describing source repositories, bug-trackers, and finer control of package behaviour
  • An opam lint command to check the quality of packages

OPAM 1.1 - October 2013

Since the release of OPAM 1.0, we've steadily been fixing bugs that have been reported from the wider userbase. The release has actually been remarkably stable, and most of the issues are around the constraint solver (which tackles an NP-complete problem with cunning heuristics). There's also been quite a bit of work on improving portability and integration with the operating system via more interactive initialisation.

The big purpose behind the next release, though, is to improve support for large-scale continuous integration and testing of the packages contained within the repository. Jane Street, for example, is now issuing weekly releases of their Core standard library suite. Testing these manually across Linux, FreeBSD, MacOS X and several CPU architectures (x86, x86_64, ARM, Macppc) is both tedious and error-prone, and so we'd like to automate the process.

OPAM doesn't need many changes to support this testing, but there is more package metadata being added to facilitate the process, and tools such as oasis2opam help automate this by looking inside the packages themselves. The whole of OPAM is exported as a library so that third-party packages can interface with the OPAM repository without changing OPAM itself. This is exactly what the OCamlot project does.

OPAM 1.0 - March 2013

The goal of the first version of OPAM was to get something released that would provide basic package management facilities to the community, but also be designed with distributed open-source design in mind. To that end, OPAM 1.0 supports a remotes mechanism which lets you combine local development trees with other people's remote Git or Darcs repositories. Whenever opam update is run, all the remotes are refreshed and merged, letting you subscribe to other people's compilers and package trees.

This first version is build-system agnostic in the interests of compatibility with the large existing body of third party external source code, and so can't do much in the way of advanced manipulation of the packages.

OPAM 1.0 has been a great success. Since its release, there have been hundreds of external contributions from the community, and over 500 packages are now contained within the main package repository!