Commands

You can use opam-bin to list all available commands, and opam-bin COMMAND --help for usage of a specific command.

opam-bin clean

Clear the log, remove all packages and archives from the cache and store (internal repository), and call opam update to synchronize opam:

$ opam bin clean

You can limit the cleaning by adding these arguments:

  • all: clean everything as described above

  • log: clean only the internal log ($OPAMROOT/plugins/opam-bin/opam-bin.log)

  • store: clean only the store (packages and archives) and call opam update

For example:

$ opam bin clean log

opam-bin config

Configure options from the command line. opam-bin options are stored in $OPAMROOT/plugins/opam-bin/config.

To display most options:

$ opam bin config
opam-bin 0.9.2 by OCamlPro SAS <contact@ocamlpro.com>
Current options (from /home/user/.opam/plugins/opam-bin/config):
  base_url : /change-this-option
  rsync_url : None
  patches_url : file:///home/user/GIT/relocation-patches
  title : Repository of Binary Packages
  enabled : true
  create_enabled : true
  share_enabled: false
  all_switches : true
  version : 1
  switches :
  protected_switches :

To display arguments that can be used to change the options:

$ opam bin config --help

Here are some common arguments:

  • --enable/--disable: when disabled, opam-bin will neither patch sources, nor create new binary archives, nor re-use cached ones.

  • --enable-create/--disable-create: can be used to enable/disable creation of new binary archives. When disabled, existing binary archives will still be used when possible

  • --enable-share/--disable-share: can be used to enable/disable sharing of file between switches using hard links. opam-bin uses an heuristic to decide which files should be shared. In particular, it will try not to share files that could be modified, like configuration files.

  • --base-url URL: the base url that will be used when creating opam files to specify from where the binary archive should be downloaded. For example, if you specify https://x/y, the urls in the opam files will look like https://x/y/archives/package.version.tar.gz

    Note that, when this argument is used, opam-bin will automatically modify all the existing opam files in $OPAMROOT/plugins/opam-bin/store/repo to use the new URLs, so this argument can be used after creating the packages to relocate them.

  • --patches-url URL: the URL specifying the location of the patches to make packages relocatable. It can be an archive over https (https://), a Git repository (git@) or a local directory (file://).

    Default is https://www.typerex.org/opam-bin/relocation-patches.tar.gz.

opam-bin help

Display help about opam-bin and its sub-commands:

$ opam bin --help

opam-bin info

Display information on binary packages that have been created by last opam commands:

$ ./opam-bin info
Info on binary packages:
2020/09/14:18:57:25: base-threads.base binary package created
2020/09/14:18:57:25: base-bigarray.base binary package created
2020/09/14:18:57:25: base-unix.base binary package created
2020/09/14:18:58:37: ocaml-base-compiler.4.10.0 binary package created
2020/09/14:18:58:37: ocaml-config.1 binary package created
2020/09/14:18:58:37: ocaml.4.10.0 binary package created
2020/09/14:19:02:03: base-threads.base binary package installed from cache
2020/09/14:19:02:03: base-bigarray.base binary package installed from cache
2020/09/14:19:02:03: base-unix.base binary package installed from cache
2020/09/14:19:02:06: ocaml-base-compiler.4.10.0 binary package installed from cache
2020/09/14:19:02:06: ocaml-config.1 binary package installed from cache
2020/09/14:19:02:06: ocaml.4.10.0 binary package installed from cache

The --tail argument can be used to monitor the log during calls to opam. The file containing the information is called $OPAMROOT/plugins/opam-bin/opam-bin.info.

opam-bin install

Install opam-bin in opam. It performs the following steps:

  • Install the binary of opam bin in opam to be used as a plugin and for hooks ($OPAMROOT/plugins/opam-bin/opam-bin.exe with a link from $OPAMROOT/plugins/bin/opam-bin)

  • Install hooks to call opam-bin while building, installing and removing packages (modify $OPAMROOT/config)

  • Install the internal repository of opam-bin as a repository, called local-bin, where opam can lookup packages. The internal repo is $OPAMROOT/plugins/opam-bin/store/repo

  • Download and extract the set of relocation patches

All these actions can be called indiviually using the following arguments, respectivelly: exe, hooks, repos, patches.

For example, to install a newly built version of opam-bin, you can just use:

$ ./opam-bin install exe

If you want opam-bin to re-download its set of patches because a new version is available:

$ opam bin install patches

opam-bin list

List binary packages created on this computer:

$ opam bin list

opam-bin pull

Pull binary packages from the remote server specified by the rsync_url option (set by opam bin config --rsync-url URL).

This command will copy all files from the URL specified in option rsync_url to the opam-bin store ($OPAMROOT/plugins/opam-bin/store/). Since no --delete option is given to rsync, the new content will be added over the existing content. It may be useful to use opam bin clean store before to get rid of existing content if you don’t want a merge.

opam-bin push

Push binary packages to the remote server, specified by the rsync_url option (set by opam bin config --rsync-url URL):

$ opam bin push

It will perform the following actions:

  • Generate an HTML index (index.html) and an opam index (index.tar.gz) in every repository present in the store ($OPAMROOT/plugins/opam-bin/store/* where a sub-dir packages exists)

  • Copy the files from the store to the remote server, adding the --delete option to rsync to get rid of former files if necessary.

If the --merge argument is provided:

$ opam bin push --merge

the index files are not generated and the --delete option is not passed to rsync, resulting in a merge of the stores. You may have to call opam admin index on the remote server for the opam index to take into account the new packages.

The --local-only argument can be provided to only generate the index and not copy the files:

$ opam bin push --local-only

Finally, you can extract a set of packages from the current repository ($OPAMROOT/plugins/opam-bin/store/repo) that are compatible with a binary package (i.e. not conflicting with it or its dependencies), using --extract NAME:PACKAGE.VERSION:

$ opam bin push --extract 4.07.1:ocaml-base-compiler.4.07.1

will generate a new repository $OPAMROOT/plugins/opam-bin/store/4.07.1 containing only the packages compatible with the binary packages with prefix ocaml-base-compiler.4.07.1 (resulting in this example in a repository containing only 4.07.1 packages). Index files will be generated too. A later call to opam bin push will push all the store, including the archives and all the repositories.

opam-bin share

Share files passed as arguments. Sharing is performed by replacing these files by hard links to identical files in the sharing cache located at $OPAMROOT/plugins/opam-bin/share/.

This command behaves identically to what happens when sharing is enabled in the configuration. It can be used to share an opam switch that was created before activating the option.

Sharing is only efficient to save disk space when binary packages are used. Otherwise, building from sources often generates different binary files, that cannot be shared.

The --rec option can be used to pass directories to the command, that will iterate on their content.

opam-bin uninstall

Un-install opam-bin hooks from opam config. Note that it does not currently remove the local-bin directory, so you may have to do it yourself if you want to:

$ opam bin uninstall
$ opam remote remove --all --set-default local-bin

OPAM Hooks

  • opam-bin pre-build: Check the sources before building the package to decide whether to use an existing binary package

  • opam-bin wrap-build: Exec or not build commands

  • opam-bin pre-install: Install cached binary archives if available

  • opam-bin wrap-install Exec or not install commands

  • opam-bin post-install: Create a binary archive from installed built artefacts

  • opam-bin pre-remove: Remove binary install artefacts