Feedback on this post is welcomed on Discuss!

As mentioned in our talk at the OCaml Workshop 2024, we decided to switch to a time-based release cycle (every 6 months), starting with opam 2.3.

As promised, we are very pleased to announce the release of opam 2.3.0, and encourage all users to upgrade. Please read on for installation and upgrade instructions.

Try it!

In case you plan a possible rollback, you may want to first backup your ~/.opam or $env:LOCALAPPDATA\opam directory.

The upgrade instructions are unchanged:

1. Either from binaries: run

For Unix systems

bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh)"

or from PowerShell for Windows systems

Invoke-Expression "& { $(Invoke-RestMethod https://opam.ocaml.org/install.ps1) }"

or download manually from the Github "Releases" page to your PATH.

2. Or from source, manually: see the instructions in the README.

You should then run:

opam init --reinit -ni

Major breaking change: extra-files

When loading a repository, opam now ignores files in packages' files/ directories which aren't listed in the extra-files field of the opam file. This was done to simplify the opam specification where we hope the opam file to be the only thing that you have to look at when reading a package specification. It being optional to list all files in the extra-files: field went against that principle. This change also reduces the surface area for potential file corruption as all extra-files must have checksums.

This is a breaking change and means that if you are using the files/ directory without listing them in the extra-files: field, you need to make sure that all files in that directory are included in the extra-files field. The resulting opam file remains compatible with all previous opam 2.x releases.

If you have an opam repository, you should make sure all files are listed so every packages continues to work without any issue, which can be done automatically using the opam admin update-extrafiles command.

Major changes

• Packages requiring an unsupported version of opam are now marked unavailable, instead of causing a repository error. This means an opam repository can now allow smoother upgrade in the future where some packages can require a newer version of opam without having to fork the repository to upgrade every package to that version as was done for the upgrade from opam 1.2 to 2.0

• Add a new opam list --latests-only option to list only the latest versions of packages. Note that this option respects the order options were given on the command line. For example: --available --latests-only will first list all the available packages, then choose only the latest packages in that set; while --latests-only --available will first list all the latest packages, then only show the ones that are available in that set

• Fix and improve opam install --check, which now checks if the whole dependency tree of the package is installed instead of only the root dependencies

• Add a new --verbose-on option to enable verbose output for specified package names. Thanks to @desumn for this contribution

• Add a new opam switch import --deps-only option to install only the dependencies of the root packages listed in the opam switch export file

• opam switch list-available no longer displays compilers flagged with avoid-version/deprecated unless --all is given, meaning that pre-release or unreleased OCaml packages no longer appear to be the latest version

• opam switch create --repositories now correctly infers --kind=git for URLs ending with .git rather than requiring the git+https:// protocol. This is consistant with other commands such as opam repository add. Thanks to @Keryan-dev for this contribution

• opam switch set-invariant now displays the switch invariant using the same syntax as the --formula flag

• The builtin-0install solver was improved and should now be capable of being your default solver instead of builtin-mccs+glpk. It was previously mostly only suited for automated tasks such as Continuous Integration. If you wish to give it a try, simply calling opam option solver=builtin-0install (call opam option solver= restores the default)

• Most of the unhelpful conflict messages were fixed. (#4373)

• Fix an opam 2.1 regression where the initial pin of a local VCS directory would store untracked and ignored files. Those files would usually be cleaned before building the package, however git submodules would not be cleaned and would cause issues when paired with the new behaviour added in 2.3.0~alpha1 which makes opam error when git submodules fail to update (it was previously a warning). (#5809)

• Fix the value of the arch variable when the current OS is 32bit on a 64bit machine (e.g. Raspberry Pi OS). (#5949)

• opam now fails when git submodules fail to update instead of ignoring the error and just showing a warning

• opam's libraries now compile with OCaml >= 5.0 on Windows

• Fix the installed packages internal cache, which was storing the wrong version of the opam file after a build failure. This could be triggered easily for users with custom repositories with non-populated extra-files. (#6213)

• Several improvements to the pre-built release binaries were made:

  • The Linux binaries are now built on Alpine 3.20
  • The FreeBSD binary is now built on FreeBSD 14.1
  • The OpenBSD binary is now built on OpenBSD 7.6 and loses support for OpenBSD 7.5 and earlier
  • Linux/riscv64 and NetBSD/x86_64 binaries are now available

And many other general, performance and UI improvements were made and bugs were fixed. You can take a look to previous blog posts. API changes and a more detailed description of the changes are listed in:

• the release note for 2.3.0~alpha1
• the release note for 2.3.0~beta1
• the release note for 2.3.0~beta2
• the release note for 2.3.0~rc1
• the release note for 2.3.0

This release also includes PRs improving the documentation and improving and extending the tests.

Please report any issues to the bug-tracker.

We hope you will enjoy the new features of opam 2.3!

Feedback on this post is welcomed on Discuss!

We are pleased to announce the release of opam 2.2.1.

We've fixed a couple of regressions and would like to encourage users of opam 2.2 to upgrade.

Changes

The three main changes are:

• Fixe a regression in opam install --deps-only where the direct dependencies were not set as root packages (spotted in the wild by @rjbou and also reported on Discuss)
• Fix a regression when fetching Git packages where the resulting Git repository could lead to unexpected outputs of Git commands, by disabling shallow clone by default except when fetching opam repositories (#6145)
• Mitigate curl/curl#13845 by falling back from --write-out to --fail if exit code 43 is returned by Curl. In particular, this fixes opam init when run from cmd/PowerShell on Windows 11 23H2 (#6120)

A couple more improvements and additions to the testsuite were made. You can view the full list of changes in the release note.

Try it!

The upgrade instructions are unchanged:

1. Either from binaries: run

For Unix systems

bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.2.1"

or from PowerShell for Windows systems

Invoke-Expression "& { $(Invoke-RestMethod https://opam.ocaml.org/install.ps1) }"

(or via winget upgrade OCaml.opam) or download manually from the Github "Releases" page to your PATH.

2. Or from source, manually: see the instructions in the README.

You should then run:

opam init --reinit -ni

Please report any issues to the bug-tracker.

Happy hacking!

Feedback on this post is welcomed on Discuss!

We are very pleased to announce the release of opam 2.2.0, and encourage all users to upgrade. Please read on for installation and upgrade instructions.

Try it!

In case you plan a possible rollback, you may want to first backup your ~/.opam or $env:LOCALAPPDATA\opam directory.

The upgrade instructions are unchanged:

1. Either from binaries: run

For Unix systems

bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.2.0"

or from PowerShell for Windows systems

Invoke-Expression "& { $(Invoke-RestMethod https://opam.ocaml.org/install.ps1) }"

or download manually from the Github "Releases" page to your PATH.

2. Or from source, manually: see the instructions in the README.

You should then run:

opam init --reinit -ni

Changes

Major change: Windows support

After 8 years' effort, opam and opam-repository now have official native Windows support! A big thank you is due to Andreas Hauptmann (@fdopen), whose WODI and OCaml for Windows projects were for many years the principal downstream way to obtain OCaml on Windows, Jun Furuse (@camlspotter) whose initial experimentation with OPAM from Cygwin formed the basis of opam-repository-mingw, and, most recently, Jonah Beckford (@jonahbeckford) whose DkML distribution kept - and keeps - a full development experience for OCaml available on Windows.

OCaml when used on native Windows requires certain tools from the Unix world which are provided by either Cygwin or MSYS2. We have engineered opam init so that it is possible for a user not to need to worry about this, with opam managing the Unix world, and the user being able to use OCaml from either the Command Prompt or PowerShell. However, for the Unix user coming over to Windows to test their software, it is also possible to have your own Cygwin/MSYS2 installation and use native Windows opam from that. Please see the previous blog post for more information.

There are two "ports" of OCaml on native Windows, referred to by the name of provider of the C compiler. The mingw-w64 port is GCC-based. opam's external dependency (depext) system works for this port (including providing GCC itself), and many packages are already well-supported in opam-repository, thanks to the previous efforts in opam-repository-mingw. The MSVC port is Visual Studio-based. At present, there is less support in this ecosystem for external dependencies, though this is something we expect to work on both in opam-repository and in subsequent opam releases. In particular, it is necessary to install Visual Studio or Visual Studio BuildTools separately, but opam will then automatically find and use the C compiler from Visual Studio.

Major change: opam tree / opam why

opam tree is a new command showing packages and their dependencies with a tree view. It is very helpful to determine which packages bring which dependencies in your installed switch.

$ opam tree cppo
cppo.1.6.9
├── base-unix.base
├── dune.3.8.2 (>= 1.10)
│   ├── base-threads.base
│   ├── base-unix.base [*]
│   └── ocaml.4.14.1 (>= 4.08)
│       ├── ocaml-base-compiler.4.14.1 (>= 4.14.1~ & < 4.14.2~)
│       └── ocaml-config.2 (>= 2)
│           └── ocaml-base-compiler.4.14.1 (>= 4.12.0~) [*]
└── ocaml.4.14.1 (>= 4.02.3) [*]

Reverse-dependencies can also be displayed using the new opam why command. This is useful to examine how dependency versions get constrained.

$ opam why cmdliner
cmdliner.1.2.0
├── (>= 1.1.0) b0.0.0.5
│   └── (= 0.0.5) odig.0.0.9
├── (>= 1.1.0) ocp-browser.1.3.4
├── (>= 1.0.0) ocp-indent.1.8.1
│   └── (>= 1.4.2) ocp-index.1.3.4
│       └── (= version) ocp-browser.1.3.4 [*]
├── (>= 1.1.0) ocp-index.1.3.4 [*]
├── (>= 1.1.0) odig.0.0.9 [*]
├── (>= 1.0.0) odoc.2.2.0
│   └── (>= 2.0.0) odig.0.0.9 [*]
├── (>= 1.1.0) opam-client.2.2.0~alpha
│   ├── (= version) opam.2.2.0~alpha
│   └── (= version) opam-devel.2.2.0~alpha
├── (>= 1.1.0) opam-devel.2.2.0~alpha [*]
├── (>= 0.9.8) opam-installer.2.2.0~alpha
└── user-setup.0.7

Special thanks to @cannorin for contributing this feature.

Major change: with-dev-setup

There is now a way for a project maintainer to share their project development tools: the with-dev-setup dependency flag. It is used in the same way as with-doc and with-test: by adding a {with-dev-setup} filter after a dependency. It will be ignored when installing normally, but it's pulled in when the package is explicitly installed with the --with-dev-setup flag specified on the command line.

For example

opam-version: "2.0"
depends: [
  "ocaml"
  "ocp-indent" {with-dev-setup}
]
build: [make]
install: [make "install"]
post-messages:
[ "Thanks for installing the package"
  "as well as its development setup. It will help with your future contributions" {with-dev-setup} ]

Major change: opam pin --recursive

When pinning a package using opam pin, opam looks for opam files in the root directory only. With recursive pinning, you can now instruct opam to look for .opam files in subdirectories as well, while maintaining the correct relationship between the .opam files and the package root for versioning and build purposes.

Recursive pinning is enabled by the following options to opam pin and opam install:

• With --recursive, opam will look for .opam files recursively in all subdirectories.
• With --subpath <path>, opam will only look for .opam files in the subdirectory <path>.

The two options can be combined: for instance, if your opam packages are stored as a deep hierarchy in the mylib subdirectory of your project you can try opam pin . --recursive --subpath mylib.

These options are useful when dealing with a large monorepo-type repository with many opam libraries spread about.

New Options

• opam switch -, inspired by git switch -, makes opam switch back to the previously selected global switch.

• opam pin --current fixes a package to its current state (disabling pending reinstallations or removals from the repository). The installed package will be pinned to its current installed state, i.e. the pinned opam file is the one installed.

• opam pin remove --all removes all the pinned packages from a switch.

• opam exec --no-switch removes the opam environment when running a command. It is useful when you want to launch a command without opam environment changes.

• opam clean --untracked removes untracked files interactively remaining from previous packages removal.

• opam admin add-constraint <cst> --packages pkg1,pkg2,pkg3 applies the given constraint to a given set of packages

• opam list --base has been renamed into --invariant, reflecting the fact that since opam 2.1 the "base" packages of a switch are instead expressed using a switch invariant.

• opam install --formula <formula> installs a formula instead of a list of packages. This can be useful if you would like to install one package or another one. For example opam install --formula '"extlib" |"extlib-compat"' will install either extlib or extlib-compat depending on what's best for the current switch.

Miscellaneous changes

• The UI now displays a status when extracting an archive or reloading a repository
• Overhauled the implementation of opam env, fixing many corner cases for environment updates and making the reverting of package environment variables precise. As a result, using setenv in an opam file no longer triggers a lint warning.
• Fix parsing pre-opam 2.1.4 switch import files containing extra-files
• Add a new sys-ocaml-system default global eval variable
• Hijack the "%{var?string-if-true:string-if-false-or-undefined}%" syntax to support extending the variables of packages with + in their name (conf-c++ and conf-g++ already exist) using "%{?pgkname:var:}%"
• Fix issues when using fish as shell
• Sandbox: Mark the user temporary directory (as returned by getconf DARWIN_USER_TEMP_DIR) as writable when TMPDIR is not defined on macOS
• Add Warning 69: Warn for new syntax when package name in variable in string interpolation contains several '+' (this is related to the "hijack" item above)
• Add support for Wolfi OS, treating it like Alpine family as it also uses apk
• Sandbox: /tmp is now writable again, restoring POSIX compliance
• Add a new opam admin: new add-extrafiles command to add/check/update the extra-files: field according to the files present in the files/ directory
• Add a new opam lint -W @1..9 syntax to allow marking a set of warnings as errors
• Fix bugs in the handling of the OPAMCURL, OPAMFETCH and OPAMVERBOSE environment variables
• Fix bugs in the handling of the --assume-built argument
• Software Heritage fallbacks is now supported, but is disabled-by-default for now. For more information you can read one of our previous blog post

And many other general and performance improvements were made and bugs were fixed. You can take a look to previous blog posts. API changes and a more detailed description of the changes are listed in:

• the release note for 2.2.0~alpha
• the release note for 2.2.0~alpha2
• the release note for 2.2.0~alpha3
• the release note for 2.2.0~beta1
• the release note for 2.2.0~beta2
• the release note for 2.2.0~beta3
• the release note for 2.2.0~rc1
• the release note for 2.2.0

This release also includes PRs improving the documentation and improving and extending the tests.

Please report any issues to the bug-tracker.

We hope you will enjoy the new features of opam 2.2! 📯

Feedback on this post is welcomed on Discuss!

We are pleased to announce the patch release of opam 2.1.6.

This opam release consists of backported bug fixes and improvements:

• Changes necessary for opam-repository (see ocaml/opam-repository#23789)
  • Warn if GNU patch is not detected when a patch is applied (#5893)
  • Use gpatch by default instead of patch on NetBSD and DragonFlyBSD (#5893)
  • Use gpatch if it exists and is detected as GNU patch when patch is not GNU patch (#5893)
• Better recognize depexts on Gentoo, NetBSD, OpenBSD (#5065)
• Upgrade the vendored dune to 3.14.0 (#5869)
• Fix debug logs showing up regardless of verbosity on macOS 12.7.1 / 13.6.3 / 14.2 and FreeBSD (#5769)

Opam installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.1.6"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

Feedback on this post is welcomed on Discuss!

We are pleased to announce the patch release of opam 2.1.5.

This opam release consists of backported bug & security fixes:

• Security issue: fix opam installing packages without checking their checksum when the local cache is corrupted in some case (#5538), you can find more information there.
• Variables are now expanded in build-env (as for setenv) (#5352)
• Correctly handle empty environment variable additions (#5350)
• Skip empty environment variable additions (#5350)
• Fix passing archive-mirrors field from init config file to config (#5315)
• git, hg: Use the full SHA1 revision instead of just the 8 first characters (#5342)

Opam installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.1.5"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

Feedback on this post is welcomed on Discuss!

We are pleased to announce the minor release of opam 2.1.4.

This opam release consists of backported fixes:

• Make opam able to fully build with OCaml 5.0. dose3 >= 6.1 and base64 >= 3.1.0 are now required (#5357)
• Fix a bug where opam would not output any explanation when a conflict arises when attempting to install a package (#5378)

Opam installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.1.4"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

We are pleased to announce the minor release of opam 2.1.2.

This opam release consists of backported fixes, including:

• Fallback on dnf if yum does not exist on RHEL-based systems (#4825)
• Use --no-depexts in CLI 2.0 mode. This further improves the use of opam 2.1 as a drop-in replacement for opam 2.0 in CI, for example with setup-ocaml in GitHub Actions. (#4908)

Opam installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.1.2"
   

   or download manually from the GitHub "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

Feedback on this post is welcomed on Discuss!

We are pleased to announce the release of opam 2.1.1.

With opam 2.1.1, if you export OPAMCLI=2.0 into your environment then workflows expecting opam 2.0 should now behave even more equivalently.

opam 2.1.1 includes both the fixes in opam 2.0.10.

General fixes:

• Restore support for switch creation with "positional" package arguments and --packages option for CLI version 2.0, e.g. OPAMCLI=2.0 opam switch create . 4.12.0+options --packages=ocaml-option-flambda. In opam 2.1 and later, this syntax remains an error (#4843)
• Fix opam switch set-invariant: default repositories were loaded instead of the switch's repositories selection (#4869)
• Run the sandbox check in a temporary directory (#4783)

Integrated depext support has a few updates:

• Homebrew now has support for casks and full-names (#4800)
• Archlinux now handles virtual package detection (#4833, partially addressing #4759)
• Disable the detection of available packages on RHEL-based distributions. This fixes an issue on RHEL-based distributions where yum list used to detect available and installed packages would wait for user input without showing any output and/or fail in some cases (#4791)

And finally two regressions have been dealt with:

• Regression: avoid calling Unix.environment on load (as a toplevel expression). This regression affected opam's libraries, rather than the binary itself (#4789)
• Regression: handle empty environment variable updates (#4840)

A few issues with the compilation of opam from sources have been fixed as well (e.g. mingw-w64 with g++ 11.2 now works)

Opam installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.1.1"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

Feedback on this post is welcomed on Discuss!

We are pleased to announce the release of opam 2.0.10.

Two subtle fixes are included in opam 2.0.10. These actually affect the ocaml package. Both of these are Heisenbugs - investigating what's going wrong on your system may well have fixed them, they were both found on Windows!

$(opam env --revert) is the reverse of the more familiar $(opam env) but it's effectively called by opam whenever you change switch. It has been wrong since 2.0.0 for the case where several values are added to an environment variable in one setenv update. For example, if a package included a setenv field of the form [PATH += "dir1:dir2"], then this would not be reverted, but [[PATH += "dir1"] [PATH += "dir2"]] would be reverted. As it happens, this bug affects the ocaml package, but it was masked by another setenv update in the same package.

The other fix is also to do with setenv. It can be seen immediately after creating a switch but before any additional packages are installed, as this Dockerfile shows:

FROM ocaml/opam@sha256:244b948376767fe91e2cd5caca3b422b2f8d332f105ef2c8e14fcc9a20b66e25
RUN sudo apt-get install -y ocaml-nox
RUN opam --version
RUN opam switch create show-issue ocaml-system
RUN eval $(opam env) ; echo $CAML_LD_LIBRARY_PATH
RUN opam install conf-which
RUN eval $(opam env) ; echo $CAML_LD_LIBRARY_PATH

Immediately after switch creation, $CAML_LD_LIBRARY_PATH was set to /home/opam/.opam/show-issue/lib/stublibs:, rather than /home/opam/.opam/show-issue/lib/stublibs:/usr/local/lib/ocaml/4.08.1/stublibs:/usr/lib/ocaml/stublibs

Opam installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.0.10"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

Feedback on this post is welcomed on Discuss!

We are happy to announce the release of opam 2.1.0.

Many new features made it in (see the pre-release changelogs or release notes for the details), but here are a few highlights.

What's New in opam 2.1?

• Integration of system dependencies (formerly the opam-depext plugin), increasing their reliability as it integrates the solving step
• Creation of lock files for reproducible installations (formerly the opam-lock plugin)
• Switch invariants, replacing the "base packages" in opam 2.0 and allowing for easier compiler upgrades
• Improved options configuration (see the new option and expanded var subcommands)
• CLI versioning, allowing cleaner deprecations for opam now and also improvements to semantics in future without breaking backwards-compatibility
• opam root readability by newer and older versions, even if the format changed
• Performance improvements to opam-update, conflict messages, and many other areas

Seamless Integration of System Dependencies Handling (a.k.a. "depexts")

Opam has long included the ability to install system dependencies automatically via the depext plugin. This plugin has been promoted to a native feature of opam 2.1.0 onwards, giving the following benefits:

• You no longer have to remember to run opam depext, as opam always checks depexts (there are options to disable this or automate it for CI use). Installation of an opam package in a CI system is now as easy as opam install ., without having to do the dance of opam pin add -n/depext/install. Just one command now for the common case!
• The solver is only called once, which both saves time and also stabilises the behaviour of opam in cases where the solver result is not stable. It was possible to get one package solution for the opam depext stage and a different solution for the opam install stage, resulting in some depexts missing.
• Opam now has full knowledge of depexts, which means that packages can be automatically selected based on whether a system package is already installed. For example, if you have neither MariaDB nor MySQL dev libraries installed, opam install mysql will offer to install conf-mysql and mysql, but if you have the MariaDB dev libraries installed, opam will offer to install conf-mariadb and mysql.

Hint: You can set OPAMCONFIRMLEVEL=unsafe-yes or --confirm-level=unsafe-yes to launch non interactive system package commands.

opam Lock Files and Reproducibility

When opam was first released, it had the mission of gathering together scattered OCaml source code to build a community repository. As time marches on, the size of the opam repository has grown tremendously to over 3000 unique packages with over 19500 unique versions. Opam looks at all these packages and is designed to solve for the best constraints for a given package, so your project can keep up with releases of your dependencies.

While this works well for libraries, we need a different strategy for projects that need to test and ship using a fixed set of dependencies. To satisfy this use case, opam 2.0.0 shipped with support for using project.opam.locked files. These are normal opam files but with exact versions of dependencies. The lock file can be used as simply as opam install . --locked to have a reproducible package installation.

With opam 2.1.0, the creation of lock files is also now integrated into the client:

• opam lock will create a .locked file for your current switch and project, that you can check into the repository.
• opam switch create . --locked can be used by users to reproduce your dependencies in a fresh switch.

This lets a project simultaneously keep up with the latest dependencies (without lock files) while providing a stricter set for projects that need it (with lock files).

Hint: You can export the full configuration of a switch with opam switch export new options, --full to have all packages metadata included, and --freeze to freeze all VCS to their current commit.

Switch Invariants

In opam 2.0, when a switch is created the packages selected are put into the “base” of the switch. These packages are not normally considered for upgrade, in order to ease pressure on opam's solver. This was a much bigger concern early on in opam 2.0's development, but it is less of a problem with the default mccs solver.

However, it's a problem for system compilers. opam would detect that your system compiler version had changed, but it's unable to upgrade the ocaml-system package, unless you went through a slightly convoluted process with --unlock-base.

In opam 2.1, base packages have been replaced by switch invariants. The switch invariant is a package formula which must be satisfied on every upgrade and install. All existing switches' base packages could just be expressed as package1 & package2 & package3, etc., but opam 2.1 recognises many existing patterns and simplifies them. Therefore, in most cases, the invariant will be "ocaml-base-compiler" {= "4.11.1"}, etc. This means that opam switch create my_switch ocaml-system now creates a switch invariant of "ocaml-system" rather than a specific version of the ocaml-system package. If your system OCaml package is updated, opam upgrade will seamlessly switch to the new package.

This also allows you to have switches which automatically install new point releases of OCaml. For example:

opam switch create ocaml-4.11 --formula='"ocaml-base-compiler" {>= "4.11.0" & < "4.12.0~"}' --repos=old=git+https://github.com/ocaml/opam-repository#a11299d81591
opam install utop

Creates a switch with OCaml 4.11.0 (the --repos= was just to select a version of opam-repository from before 4.11.1 was released). Now issue:

opam repo set-url old git+https://github.com/ocaml/opam-repository
opam upgrade

Opam 2.1 will automatically offer to upgrade OCaml 4.11.1 along with a rebuild of the switch. There's not yet a clean CLI for specifying the formula, but we intend to iterate further on this with future opam releases so that there is an easier way of saying “install OCaml 4.11.x."

Hint: You can set up a default invariant that will apply for all new switches, via a specific opamrc. The default one is ocaml >= 4.05.0

Configuring opam From the Command Line

Configuring opam is not a simple task: you need to use an opamrc at init stage, hack global/switch config file, or use opam config var for additional variables. To ease that step, and permit a more consistent opam config tweaking, a new command was added : opam option.

For example:

• opam option download-jobs gives the global download-jobs value (as it exists only in global configuration)
• opam option jobs=6 --global will set the number of parallel build jobs opam is allowed to run (along with the associated jobs variable)
• opam option depext-run-commands=false disables the use of sudo for handling system dependencies. It will be replaced by a prompt to run the installation commands
• opam option depext-bypass=m4 --global bypasses m4 system package check globally, while opam option depext-bypass=m4 --switch myswitch will only bypass it in the selected switch.

The command opam var is extended with the same format, acting on switch and global variables.

Hint: to revert your changes use opam option <field>=, it will take its default value.

CLI Versioning

A new --cli switch was added to the first beta release, but it's only now that it's being widely used. Opam is a complex enough system that sometimes bug fixes need to change the semantics of some commands. For example:

• opam show --file needed to change behaviour
• The addition of new controls for setting global variables means that the opam config was becoming cluttered and some things want to move to opam var
• opam switch install 4.11.1 still works in opam 2.0, but it's really an opam 1.2.2 syntax.

Changing the CLI is exceptionally painful since it can break scripts and tools which themselves need to drive opam. CLI versioning is our attempt to solve this. The feature is inspired by the (lang dune ...) stanza in dune-project files, which has allowed the Dune project to rename variables and alter semantics without requiring every single package using Dune to upgrade their dune files on each release.

Now you can specify which version of opam you expected the command to be run against. In day-to-day use of opam at the terminal, you wouldn't specify it, so you'll get the latest version of the CLI. For example: opam var --global is the same as opam var --cli=2.1 --global. However, if you issue opam var --cli=2.0 --global, you will have told it that --global was added in 2.1, so it's not available to you. You can see similar things with the renaming of opam upgrade --unlock-base to opam upgrade --update-invariant.

The intention is that --cli should be used in scripts, user guides (e.g., blog posts), and in software which calls opam. The only decision you have to take is the oldest version of opam which you need to support. If your script is using a new opam 2.1 feature (for example, opam switch create --formula=) then you simply don't support opam 2.0. If you need to support opam 2.0, then you can't use --formula and should use --packages instead. Opam 2.0 does not have the --cli option, so for opam 2.0 instead of --cli=2.0 you should set the environment variable OPAMCLI to 2.0. As with all opam command line switches, OPAMCLI is simply the equivalent of --cli, which opam 2.1 will pick-up but opam 2.0 will quietly ignore (and, as with other options, the command line takes precedence over the environment).

Note that opam 2.1 sets OPAMCLI=2.0 when building packages, so on the rare instances where you need to use the opam command in a package build: command (or in your build system), you must specify --cli=2.1 if you're using new features.

Since 2.1.0~rc2, CLI versioning applies to opam environment variables. The previous behaviour was to ignore unknown or wrongly set environment variables. Now you will have a warning to let you know that the environment variable won't be handled by this version of opam.

To ensure not breaking compatibility of some widely used deprecated options, a default CLI is introduced: when no CLI is specified, those deprecated options are accepted. It concerns opam exec and opam var subcommands.

There's even more detail on this feature in our wiki. We're hoping that this feature will make it much easier in future releases for opam to make required changes and improvements to the CLI without breaking existing setups and tools.

Note: For opam libraries users, since 2.1 environment variable are no more loaded by the libraries, only by opam client. You need to load them explicitly.

opam root Portability

opam root format changes during opam's life cycle. New fields are added or removed, and new files are added. An older opam version sometimes can no longer read an upgraded or newly created opam root. opam root format has been updated to allow new versions of opam to indicate that the root may still be read by older versions of the opam libraries. A plugin compiled against the 2.0.9 opam libraries will therefore be able to read information about an opam 2.1 root (plugins and tools compiled against 2.0.8 are unable to load opam 2.1.0 roots). It is a read-only best effort access, any attempt to modify the opam root fails.

Hint: for opam libraries users, you can safely load states with OpamStateConfig load functions.

Tremendous thanks to all involved people, who've developed, tested & retested, helped with issue reports, comments, feedback, etc...

Try It!

In case you plan a possible rollback, you may want to first backup your ~/.opam directory.

The upgrade instructions are unchanged:

1. Either from binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.1.0"
   

   or download manually from the GitHub "Releases" page to your PATH.

2. Or from source, manually: see the instructions in the README.

You should then run:

opam init --reinit -ni

Feedback on this post is welcomed on Discuss!

We are pleased to announce the minor release of opam 2.0.9.

This new version contains some back-ported fixes.

New features

• Back-ported ability to load upgraded roots read-only; allows applications compiled with opam-state 2.0.9 to load a root which has been upgraded to opam 2.1 [#4636]
• macOS sandbox now supports OPAM_USER_PATH_RO for adding a custom read-only directory to the sandbox [#4589, #4609]
• OPAMROOT and OPAMSWITCH now reflect the --root and --switch parameters in the package build [#4668]
• When built with opam-file-format 2.1.3+, opam-format 2.0.x displays better errors for newer opam files [#4394]

Bug fixes

• Linux sandbox now mounts host $TMPDIR read-only, then sets the sandbox $TMPDIR to a new separate tmpfs. Hardcoded /tmp access no longer works if TMPDIR points to another directory [#4589]
• Stop clobbering DUNE_CACHE in the sandbox script [#4535, fixing ocaml/dune#4166]
• Ctrl-C now correctly terminates builds with bubblewrap; sandbox now requires bubblewrap 0.1.8 or later [#4400]
• Linux sandbox script no longer makes PWD read-write on remove actions [#4589]
• Lint W59 and E60 no longer trigger for packages flagged conf [#4549]
• Reduce the length of temporary file names for pin caching to ease pressure on Windows [#4590]
• Security: correct quoting of arguments when removing switches [#4707]
• Stop advertising the removed option --compiler when creating local switches [#4718]
• Pinning no longer fails if the archive's opam file is malformed [#4580]
• Fish: stop using deprecated ^ syntax to fix support for Fish 3.3.0+ [#4736]

Installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.0.9"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

We are pleased to announce the minor release of opam 2.0.8.

This new version contains some backported fixes:

• Critical for fish users! Don't add . to PATH. [#4078]
• Fix sandbox script for newer ccache versions. [#4079 and #4087]
• Fix sandbox crash when ~/.cache is a symlink. [#4068]
• User modifications to the sandbox script are no longer overwritten by opam init. [#4020 & #4092]
• macOS sandbox script always mounts /tmp read-write, regardless of TMPDIR [#3742, addressing ocaml/opam-repository#13339]
• pre- and post-session hooks can now print to the console [#4359]
• Switch-specific pre/post sessions hooks are now actually run [#4472]
• Standalone opam-installer now correctly builds from sources [#4173]
• Fix arch variable detection when using 32bit mode on ARM64 and i486 [#4462]

A more complete release note is available.

Installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.0.8"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com, and published in discuss.ocaml.org. Please head to the latter for the comments!

We are pleased to announce the minor release of opam 2.0.7.

This new version contains backported small fixes:

• Escape Windows paths on manpages [#4129 @AltGr @rjbou]
• Fix opam installer opam file [#4058 @rjbou]
• Fix various warnings [#4132 @rjbou @AltGr - fix #4100]
• Fix dune 2.5.0 promote-install-files duplication [#4132 @rjbou]

Installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.0.7"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com. Please head to the latter for the comments!

We are pleased to announce the minor release of opam 2.0.6.

• Don't remove git cache objects that may be used [#3831 @AltGr]
• Don't include .gitattributes in index.tar.gz [#3873 @dra27]
• Update FAQ uri [#3941 @dra27]
• Lock: add warning in case of missing locked file [#3939 @rjbou]
• Directory tracking: fix cached entries retrieving with precise tracking [#4038 @hannesm]
• Build:
  • Add sanity checks [#3934 @dra27]
  • Build man pages using dune [#3902 ]
  • Add patch and bunzip check for make cold [#4006 @rjbou - fix #3842]
• Shell:
  • fish: add colon for fish manpath [#3886 @rjbou - fix #3878]
• Sandbox:
  • Add dune cache as rw [#4019 @rjbou - fix #4012]
  • Do not fail if $HOME/.ccache is missing [#3957 @mseri]
• opam-devel file: avoid copying extraneous files in opam-devel example [#3999 @maroneze]

As sandbox scripts have been updated, don't forget to run opam init --reinit -ni to update yours.

Note: To homogenise macOS name on system detection, we decided to keep macos, and convert darwin to macos in opam. For the moment, to not break jobs & CIs, we keep uploading darwin & macos binaries, but from the 2.1.0 release, only macos ones will be kept.

Installation instructions (unchanged):

1. From binaries: run

   bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh) --version 2.0.6"
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com. Please head to the latter for the comments!

We are pleased to announce the minor release of opam 2.0.5.

This new version contains build update and small fixes:

• Bump src_ext Dune to 1.6.3, allows compilation with OCaml 4.08.0. [#3887 @dra27]
• Support Dune 1.7.0 and later [#3888 @dra27 - fix #3870]
• Bump the ocaml_mccs lib-ext, to include latest changes [#3896 @AltGr]
• Fix cppo detection in configure [#3917 @dra27]
• Read jobs variable from OpamStateConfig [#3916 @dra27]
• Linting:
  • add check upstream option [#3758 @rjbou]
  • add warning for with-test in run-test field [#3765, #3860 @rjbou]
  • fix misleading doc filter warning [#3871 @rjbou]
• Fix typos [#3891 @dra27, @mehdid]

Note: To homogenise macOS name on system detection, we decided to keep macos, and convert darwin to macos in opam. For the moment, to not break jobs & CIs, we keep uploading darwin & macos binaries, but from the 2.1.0 release, only macos ones will be kept.

Installation instructions (unchanged):

1. From binaries: run

   sh <(curl -sL https://opam.ocaml.org/install.sh)
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com. Please head to the latter for the comments!

We are pleased to announce the release of opam 2.0.4.

This new version contains some backported fixes:

• Sandboxing on macOS: considering the possibility that TMPDIR is unset [#3597 @herbelin - fix #3576]
• display: Fix opam config var display, aligned on opam config list [#3723 @rjbou - rel. #3717]
• pin:
  • update source of (version) pinned directory [#3726 @rjbou - #3651]
  • fix --ignore-pin-depends with autopin [#3736 @AltGr]
  • fix pinnings not installing/upgrading already pinned packages (introduced in 2.0.2) [#3800 @AltGr]
• opam clean: Ignore errors trying to remove directories [#3732 @kit-ty-kate]
• remove wrong "mismatched extra-files" warning [#3744 @rjbou]
• urls: fix hg opam 1.2 url parsing [#3754 @rjbou]
• lint: update message of warning 47, to avoid confusion because of missing synopsis field internally inferred from descr [#3753 @rjbou - fix #3738]
• system:
  • lock & signals: don't interrupt at non terminal signals [#3541 @rjbou]
  • shell: fix fish manpath setting [#3728 @gregory-nisbet]
  • git: use diff.noprefix=false config argument to overwrite user defined configuration [#3788 @rjbou, #3628 @Blaisorblade - fix #3627]
• dirtrack: fix precise tracking mode [#3796 @rjbou]
• fix some mispellings [#3731 @MisterDA]
• CI enhancement & fixes [#3706 @dra27, #3748 @rjbou, #3801 @rjbou]

Note: To homogenise macOS name on system detection, we decided to keep macos, and convert darwin to macos in opam. For the moment, to not break jobs & CIs, we keep uploading darwin & macos binaries, but from the 2.1.0 release, only macos ones will be kept.

Installation instructions (unchanged):

1. From binaries: run

   sh <(curl -sL https://opam.ocaml.org/install.sh)
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com. Please head to the latter for the comments!

We are pleased to announce the release of opam 2.0.3.

This new version contains some backported fixes:

• Fix manpage remaining $ (OPAMBESTEFFORT)
• Fix OPAMROOTISOK handling
• Regenerate missing environment file

Installation instructions (unchanged):

1. From binaries: run

   sh <(curl -sL https://opam.ocaml.org/install.sh)
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new major version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com. Please head to the latter for the comments!

We are pleased to announce the release of opam 2.0.2.

As sandbox scripts have been updated, don't forget to run opam init --reinit -ni to update yours.

This new version contains mainly backported fixes:

• Doc:
  • update man page
  • add message for deprecated options
  • reinsert removed ones to print a deprecated message instead of fail (e.g. --alias-of)
  • deprecate no-aspcud
• Pin:
  • on pinning, rebuild updated pin-depends packages reliably
  • include descr & url files on pinning 1.2 opam files
• Sandbox:
  • handle symlinks in bubblewrap for system directories such as /bin or /lib (#3661). Fixes sandboxing on some distributions such as CentOS 7 and Arch Linux.
  • allow use of unix domain sockets on macOS (#3659)
  • change one-line conditional to if statement which was incompatible with set -e
  • make /var readonly instead of empty and rw
• Path: resolve default opam root path
• System: suffix .out for read_command_output stdout files
• Locked: check consistency with opam file when reading lock file to suggest regeneration message
• Show: remove pin depends messages
• Cudf: Fix closure computation in the presence of cycles to have a complete graph if a cycle is present in the graph (typically ocaml-base-compiler ⇄ ocaml)
• List: Fix some cases of listing coinstallable packages
• Format upgrade: extract archived source files of version-pinned packages
• Core: add is_archive in OpamSystem and OpamFilename
• Init: don't fail if empty compiler given
• Lint: fix light_uninstall flag for error 52
• Build: partial port to dune
• Update cold compiler to 4.07.1

Installation instructions (unchanged):

1. From binaries: run

   sh <(curl -sL https://opam.ocaml.org/install.sh)
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new minor version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com. Please head to the latter for the comments!

We are pleased to announce the release of opam 2.0.1.

This new version contains mainly backported fixes, some platform-specific:

• Cold boot for MacOS/CentOS/Alpine
• Install checksum validation on MacOS
• Archive extraction for OpenBSD now defaults to using gtar
• Fix compilation of mccs on MacOS and Nix platforms
• Do not use GNU-sed specific features in the release Makefile, to fix build on OpenBSD/FreeBSD
• Cleaning to enable reproducible builds
• Update configure scripts

And some opam specific:

• git: fix git fetch by sha1 for git < 2.14
• linting: add test variable warning and empty description error
• upgrade: convert pinned but not installed opam files
• error reporting: more comprehensible error message for tar extraction, and upgrade of git-url compilers
• opam show: upgrade given local files
• list: as opam 2.0.0 list doesn't return non-zero code if list is empty, add --silent option for a silent output and returns 1 if list is empty

Installation instructions (unchanged):

1. From binaries: run

   sh <(curl -sL https://opam.ocaml.org/install.sh)
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new major version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com. Please head to the latter for the comments!

We are happy to announce the final release of opam 2.0.0.

A few weeks ago, we released a last release candidate to be later promoted to 2.0.0, synchronised with the opam package repository upgrade.

You are encouraged to update as soon as you see fit, to continue to get package updates: opam 2.0.0 supports the older formats, and 1.2.2 will no longer get regular updates. See the Upgrade Guide for details about the new features and changes.

The website opam.ocaml.org has been updated, with the full 2.0.0 documentation pages. You can still find the documentation for the previous versions in the corresponding menu.

Package maintainers should be aware of the following:

• the master branch of the opam package repository is now in the 2.0.0 format
• package submissions must accordingly be made in the 2.0.0 format, or using the new version of opam-publish (2.0.0)
• anything that was merged into the repository in 1.2 format has been automatically updated to the 2.0.0 format
• the 1.2 format repository has been forked to its own branch, and will only be updated for critical fixes

For custom repositories, the advice remains the same.

Installation instructions (unchanged):

1. From binaries: run

   sh <(curl -sL https://opam.ocaml.org/install.sh)
   

   or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed.

2. From source, using opam:

   opam update; opam install opam-devel
   

   (then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni to enable sandboxing if you had version 2.0.0~rc manually installed)

3. From source, manually: see the instructions in the README.

We hope you enjoy this new major version, and remain open to bug reports and suggestions.

NOTE: this article is cross-posted on opam.ocaml.org and ocamlpro.com. Please head to the latter for the comments!

opam-lib 1.3

The package for opam-lib version 1.3 has just been released in the official opam repository. There is no release of opam with version 1.3, but this is an intermediate version of the library that retains compatibility of the file formats with 1.2.2.

The purpose of this release is twofold:

• provide some fixes and enhancements over opam-lib 1.2.2. For example, 1.3 has an enhanced lint function
• be a step towards migration to opam-lib 2.0.

This version is compatible with the current stable release of opam (1.2.2), but dependencies have been updated so that you are not (e.g.) stuck on an old version of ocamlgraph.

Therefore, I encourage all maintainers of tools based on opam-lib to migrate to 1.3.

The respective APIs are available in HTML for 1.2 and 1.3.

A note on plugins: when you write opam-related tools, remember that by setting flags: plugin in their definition and installing a binary named opam-toolname, you will enable the users to install package toolname and run your tool with a single opam toolname command.

Architectural changes

If you need to migrate from 1.2 to 1.3, these tips may help:

• there are now 6 different ocamlfind sub-libraries instead of just 4: format contains the handlers for opam types and file formats, has been split out from the core library, while state handles the state of a given opam root and switch and has been split from the client library.

• OpamMisc is gone and moved into the better organised OpamStd, with submodules for String, List, etc.

• OpamGlobals is gone too, and its contents have been moved to:

  • OpamConsole for the printing, logging, and shell interface handling part
  • OpamXxxConfig modules for each of the libraries for handling the global configuration variables. You should call the respective init functions, with the options you want to set, for proper initialisation of the lib options (and handling the OPAMXXX environment variables)

• OpamPath.Repository is now OpamRepositoryPath, and part of the repository sub-library.

opam-lib 2.0 ?

The development version of the opam-lib (2.0~alpha5 as of writing) is already available on opam. The name has been changed to provide a finer granularity, so it can actually be installed concurrently -- but be careful not to confuse the ocamlfind package names (opam-lib.format for 1.3 vs opam-format for 2.0).

The provided packages are:

• opam-file-format: now separated from the opam source tree, this has no dependencies and can be used to parse and print the raw opam syntax.
• opam-core: the basic toolbox used by opam, which actually doesn't include the opam specific part. Includes a tiny extra stdlib, the engine for running a graph of processes in parallel, some system handling functions, etc. Depends on ocamlgraph and re only.
• opam-format: defines opam data types and their file i/o functions. Depends just on the two above.
• opam-solver: opam's interface with the dose3 library and external solvers.
• opam-repository: fetching repositories and package sources from all handled remote types.
• opam-state: handling of the opam states, at the global, repository and switch levels.
• opam-client: the client library, providing the top-level operations (installing packages...), and CLI.
• opam-devel: this packages the development version of the opam tool itself, for bootstrapping. You can install it safely as it doesn't install the new opam in the PATH.

The new API can be also be browsed ; please get in touch if you have trouble migrating.

OPAM 1.2.2 has just been released. This fixes a few issues over 1.2.1 and brings a couple of improvements, in particular better use of the solver to keep the installation as up-to-date as possible even when the latest version of a package can not be installed.

Upgrade from 1.2.1 (or earlier)

See the normal installation instructions: you should generally pick up the packages from the same origin as you did for the last version -- possibly switching from the official repository packages to the ones we provide for your distribution, in case the former are lagging behind.

There are no changes in repository format, and you can roll back to earlier versions in the 1.2 branch if needed.

Improvements

• Conflict messages now report the original version constraints without translation, and they have been made more concise in some cases
• Some new opam lint checks, opam lint now numbers its warnings and may provide script-friendly output
• Feature to automatically install plugins, e.g. opam depext will prompt to install depext if available and not already installed
• Priority to newer versions even when the latest can't be installed (with a recent solver only. Before, all non-latest versions were equivalent to the solver)
• Added opam list --resolve to list a consistent installation scenario
• Be cool by default on errors in OPAM files, these don't concern end-users and packagers and CI now have opam lint to check them.

Fixes

• OSX: state cache got broken in 1.2.1, which could induce longer startup times. This is now fixed
• opam config report has been fixed to report the external solver properly
• --dry-run --verbose properly outputs all commands that would be run again
• Providing a simple path to an aspcud executable as external solver (through options or environment) works again, for backwards-compatibility
• Fixed a fd leak on solver calls (thanks Ivan Gotovchits)
• opam list now returns 0 when no packages match but no pattern was supplied, which is more helpful in scripts relying on it to check dependencies.

OPAM 1.2.1 has just been released. This patch version brings a number of fixes and improvements over 1.2.0, without breaking compatibility.

Upgrade from 1.2.0 (or earlier)

See the normal installation instructions: you should generally pick up the packages from the same origin as you did for the last version -- possibly switching from the official repository packages to the ones we provide for your distribution, in case the former are lagging behind.

What's new

No huge new features in this point release -- which means you can roll back to 1.2.0 in case of problems -- but lots going on under the hood, and quite a few visible changes nonetheless:

• The engine that processes package builds and other commands in parallel has been rewritten. You'll notice the cool new display but it's also much more reliable and efficient. Make sure to set jobs: to a value greater than 1 in ~/.opam/config in case you updated from an older version.
• The install/upgrade/downgrade/remove/reinstall actions are also processed in a better way: the consequences of a failed actions are minimised, when it used to abort the full command.
• When using version control to pin a package to a local directory without specifying a branch, only the tracked files are used by OPAM, but their changes don't need to be checked in. This was found to be the most convenient compromise.
• Sources used for several OPAM packages may use <name>.opam files for package pinning. URLs of the form git+ssh:// or hg+https:// are now allowed.
• opam lint has been vastly improved.

... and much more

There is also a new manual documenting the file and repository formats.

Fixes

See the changelog for a summary or closed issues in the bug-tracker for an overview.

Experimental features

These are mostly improvements to the file formats. You are welcome to use them, but they won't be accepted into the official repository until the next release.

• New field features: in opam files, to help with ./configure scripts and documenting the specific features enabled in a given build. See the original proposal and the section in the new manual
• The "filter" language in opam files is now well defined, and documented in the manual. In particular, undefined variables are consistently handled, as well as conversions between string and boolean values, with new syntax for converting bools to strings.
• New package flag "verbose" in opam files, that outputs the package's build script to stdout
• New field libexec: in <name>.install files, to install into the package's lib dir with the execution bit set.
• Compilers can now be defined without source nor build instructions, and the base packages defined in the packages: field are now resolved and then locked. In practice, this means that repository maintainers can move the compiler itself to a package, giving a lot more flexibility.

We are very proud to announce the availability of OPAM 1.2.0.

Upgrade from 1.1

Simply follow the usual instructions, using your preferred method (package from your distribution, binary, source, etc.) as documented on the homepage.

NOTE: There are small changes to the internal repository format (~/.opam). It will be transparently updated on first run, but in case you might want to go back and have anything precious there, you're advised to back it up.

Usability

Lot of work has been put into providing a cleaner interface, with helpful behaviour and messages in case of errors.

The documentation pages also have been largely rewritten for consistency and clarity.

New features

This is just the top of the list:

• A extended and versatile opam pin command. See the Simplified packaging workflow
• More expressive queries, see for example opam source
• New metadata fields, including source repositories, bug-trackers, and finer control of package behaviour
• An opam lint command to check the quality of packages

For more detail, see the announcement for the beta, the full changelog, and the bug-tracker.

Package format

The package format has been extended to the benefit of both packagers and users. The repository already accepts packages in the 1.2 format, and this won't affect 1.1 users as a rewrite is done on the server for compatibility with 1.1.

If you are hosting a repository, you may be interested in these administration scripts to quickly take advantage of the new features or retain compatibility.

Most package managers support some pin functionality to ensure that a given package remains at a particular version without being upgraded. The stable OPAM 1.1 already supported this by allowing any existing package to be pinned to a target, which could be a specific released version, a local filesystem path, or a remote version-controlled repository.

However, the OPAM 1.1 pinning workflow only lets you pin packages that already exist in your OPAM repositories. To declare a new package, you had to go through creating a local repository, registering it in OPAM, and adding your package definition there. That workflow, while reasonably clear, required the user to know about the repository format and the configuration of an internal repository in OPAM before actually getting to writing a package. Besides, you were on your own for writing the package definition, and the edit-test loop wasn't as friendly as it could have been.

A natural, simpler workflow emerged from allowing users to pin new package names that don't yet exist in an OPAM repository:

1. choose a name for your new package
2. opam pin add in the development source tree
3. the package is created on-the-fly and registered locally.

To make it even easier, OPAM can now interactively help you write the package definition, and you can test your updates with a single command. This blog post explains this new OPAM 1.2 functionality in more detail; you may also want to check out the new Packaging tutorial relying on this workflow.

From source to package

For illustration purposes in this post I'll use a tiny tool that I wrote some time ago and never released: ocp-reloc. It's a simple binary that fixes up the headers of OCaml bytecode files to make them relocatable, which I'd like to release into the public OPAM repository.

"opam pin add"

The command opam pin add <name> <target> pins package <name> to <target>. We're interested in pinning the ocp-reloc package name to the project's source directory.

cd ocp-reloc
opam pin add ocp-reloc .

If ocp-reloc were an existing package, the metadata would be fetched from the package description in the OPAM repositories. Since the package doesn't yet exist, OPAM 1.2 will instead prompt for on-the-fly creation:

Package ocp-reloc does not exist, create as a NEW package ? [Y/n] y
ocp-reloc is now path-pinned to ~/src/ocp-reloc

NOTE: if you are using beta4, you may get a version-control-pin instead, because we added auto-detection of version-controlled repos. This turned out to be confusing (issue #1582), because your changes wouldn't be reflected until you commit, so this has been reverted in favor of a warning. Add the --kind path option to make sure that you get a path-pin.

OPAM Package Template

Now your package still needs some kind of definition for OPAM to acknowledge it; that's where templates kick in, the above triggering an editor with a pre-filled opam file that you just have to complete. This not only saves time in looking up the documentation, it also helps getting consistent package definitions, reduces errors, and promotes filling in optional but recommended fields (homepage, etc.).

opam-version: "1.2"
name: "ocp-reloc"
version: "0.1"
maintainer: "Louis Gesbert <louis.gesbert@ocamlpro.com>"
authors: "Louis Gesbert <louis.gesbert@ocamlpro.com>"
homepage: ""
bug-reports: ""
license: ""
build: [
  ["./configure" "--prefix=%{prefix}%"]
  [make]
]
install: [make "install"]
remove: ["ocamlfind" "remove" "ocp-reloc"]
depends: "ocamlfind" {build}

After adding some details (most importantly the dependencies and build instructions), I can just save and exit. Much like other system tools such as visudo, it checks for syntax errors immediately:

[ERROR] File "/home/lg/.opam/4.01.0/overlay/ocp-reloc/opam", line 13, character 35-36: '.' is not a valid token.
Errors in /home/lg/.opam/4.01.0/overlay/ocp-reloc/opam, retry editing ? [Y/n]

Installation

You probably want to try your brand new package right away, so OPAM's default action is to try and install it (unless you specified -n):

ocp-reloc needs to be installed.
The following actions will be performed:
 - install   cmdliner.0.9.5                        [required by ocp-reloc]
 - install   ocp-reloc.0.1*
=== 1 to install ===
Do you want to continue ? [Y/n]

I usually don't get it working the first time around, but opam pin edit ocp-reloc and opam install ocp-reloc -v can be used to edit and retry until it does.

Package Updates

How do you keep working on your project as you edit the source code, now that you are installing through OPAM? This is as simple as:

opam upgrade ocp-reloc

This will pick up changes from your source repository and reinstall any packages that are dependent on ocp-reloc as well, if any.

So far, we've been dealing with the metadata locally used by your OPAM installation, but you'll probably want to share this among developers of your project even if you're not releasing anything yet. OPAM takes care of this by prompting you to save the opam file back to your source tree, where you can commit it directly into your code repository.

cd ocp-reloc
git add opam
git commit -m 'Add OPAM metadata'
git push

Publishing your New Package

The above information is sufficient to use OPAM locally to integrate new code into an OPAM installation. Let's look at how other developers can share this metadata.

Picking up your development package

If another developer wants to pick up ocp-reloc, they can directly use your existing metadata by cloning a copy of your repository and issuing their own pin.

git clone git://github.com/OCamlPro/ocp-reloc.git
opam pin add ocp-reloc/

Even specifying the package name is optional since this is documented in ocp-reloc/opam. They can start hacking, and if needed use opam pin edit to amend the opam file too. No need for a repository, no need to share anything more than a versioned opam file within your project.

Cloning already existing packages

We have been focusing on an unreleased package, but the same functionality is also of great help in handling existing packages, whether you need to quickly hack into them or are just curious. Let's consider how to modify the omd Markdown library.

opam source omd --pin
cd omd.0.9.7
...patch...
opam upgrade omd

The new opam source command will clone the source code of the library you specify, and the --pin option will also pin it locally to ensure it is used in preference to all other versions. This will also take care of recompiling any installed packages that are dependent on omd using your patched version so that you notice any issues right away.

There's a new OPAM field available in 1.2 called dev-repo. If you specify this in your metadata, you can directly pin to the upstream repository via opam source --dev-repo --pin.

If the upstream repository for the package contains an opam file, that file will be picked up in preference to the one from the OPAM repository as soon as you pin the package. The idea is to have:

• a development opam file that is versioned along with your source code (and thus accurately tracks the latest dependencies for your package).
• a release opam file that is published on the OPAM repository and can be updated independently without making a new release of the source code.

How to get from the former to the latter will be the subject of another post! In the meantime, all users of the beta are welcome to share their experience and thoughts on the new workflow on the bug tracker.

We are proud to announce that OPAM 1.1.1 has just been released.

This minor release features mostly stability and UI/doc improvements over OPAM 1.1.0, but also focuses on improving the API and tools to be a better base for the platform (functions for opam-doc, interface with tools like opamfu and opam-installer). Lots of bigger changes are in the works, and will be merged progressively after this release.

Installing

Installation instructions are available on the wiki.

Note that some packages may take a few days until they get out of the pipeline. If you're eager to get 1.1.1, either use our binary installer or compile from source.

The 'official' package repository is now hosted at opam.ocaml.org, synchronised with the Git repository at http://github.com/ocaml/opam-repository, where you can contribute new packages descriptions. Those are under a CC0 license, a.k.a. public domain, to ensure they will always belong to the community.

Thanks to all of you who have helped build this repository and made OPAM such a success.

After a while staged as RC, we are proud to announce the final release of OPAM 1.1.0!

Thanks again to those who have helped testing and fixing the last few issues.

Important note

The repository format has been improved with incompatible new features; to account for this, the new repository is now hosted at [opam.ocaml.org][], and the legacy repository at [opam.ocamlpro.com][] is kept to support OPAM 1.0 installations, but is unlikely to benefit from many package updates. Migration to [opam.ocaml.org][] will be done automatically as soon as you upgrade your OPAM version.

You're still free, of course, to use any third-party repositories instead or in addition.

Installing

NOTE: When switching from 1.0, the internal state will need to be upgraded. THIS PROCESS CANNOT BE REVERTED. We have tried hard to make it fault- resistant, but failures might happen. In case you have precious data in your ~/.opam folder, it is advised to backup that folder before you upgrade to 1.1.0.

Using the binary installer:

• download and run http://www.ocamlpro.com/pub/opam_installer.sh

Using the .deb packages from Anil's PPA (binaries are [currently syncing][1]): add-apt-repository ppa:avsm/ppa apt-get update sudo apt-get install opam

For OSX users, the homebrew package will be updated shortly.

or build it from sources at :

• http://www.ocamlpro.com/pub/opam-full-1.1.0.tar.gz
• https://github.com/ocaml/opam/releases/tag/1.1.0

For those who haven't been paying attention

OPAM is a source-based package manager for OCaml. It supports multiple simultaneous compiler installations, flexible package constraints, and a Git-friendly development workflow. OPAM is edited and maintained by OCamlPro, with continuous support from OCamlLabs and the community at large (including its main industrial users such as Jane-Street and Citrix).

The 'official' package repository is now hosted at [opam.ocaml.org][], synchronised with the Git repository at [http://github.com/ocaml/opam-repository][repo], where you can contribute new packages descriptions. Those are under a CC0 license, a.k.a. public domain, to ensure they will always belong to the community.

Thanks to all of you who have helped build this repository and made OPAM such a success.

I am very happy to announce the first official release of OPAM!

Many of you already know and use OPAM so I won't be long. Please read http://www.ocamlpro.com/blog/2013/01/17/opam-beta.html for a longer description.

1.0.0 fixes many bugs and add few new features to the previously announced beta-release.

The most visible new feature, which should be useful for beginners with OCaml and OPAM, is an auto-configuration tool. This tool easily enables all the features of OPAM (auto-completion, fix the loading of scripts for the toplevel, opam-switch-eval alias, etc). This tool runs interactively on each opam init invocation. If you don't like OPAM to change your configuration files, use opam init --no-setup. If you trust the tool blindly, use opam init --auto-setup. You can later review the setup by doing opam config setup --list and call the tool again using opam config setup (and you can of course manually edit your ~/.profile (or ~/.zshrc for zsh users), ~/.ocamlinit and ~/.opam/opam-init/*).

Please report:

• Bug reports and feature requests for the OPAM tool: http://github.com/OCamlPro/opam/issues
• Packaging issues or requests for a new packages: http://github.com/OCamlPro/opam-repository/issues
• General queries to: https://lists.ocaml.org/listinfo/platform
• More specific queries about the internals of OPAM to: https://lists.ocaml.org/listinfo/opam-devel

Install

Packages for Debian and OSX (at least homebrew) should follow shortly and I'm looking for volunteers to create and maintain rpm packages. The binary installer is up-to-date for Linux and Darwin 64-bit architectures, the 32-bit version for Linux should arrive shortly.

If you want to build from sources, the full archive (including dependencies) is available here:

http://www.ocamlpro.com/pub/opam-full-latest.tar.gz

Upgrade

If you are upgrading from 0.9.* you won't have anything special to do apart installing the new binary. You can then update your package metadata by running opam update. If you want to use the auto-setup feature, remove the "eval opam config env line you have previously added in your ~/.profile and run opam config setup --all.

So everything should be fine. But you never know ... so if something goes horribly wrong in the upgrade process (of if your are upgrading from an old version of OPAM) you can still trash your ~/.opam, manually remove what OPAM added in your ~/.profile (~/.zshrc for zsh users) and ~/.ocamlinit, and start again from scratch.

Random stats

Great success on github. Thanks everybody for the great contributions!

https://github.com/OCamlPro/opam: +2000 commits, 26 contributors https://github.com/OCamlPro/opam-repository: +1700 commits, 75 contributors, 370+ packages

on http://opam.ocamlpro.com/ +400 unique visitor per week, 15k 'opam update' per week +1300 unique visitor per month, 55k 'opam update' per month 3815 unique visitor since the alpha release