2. Alire Indexes

There are two key components required to make a crate available to Alire; the crate must be searchable in an index (though this requirement can be temporarily circumvented with pins), and the crate’s source files must be fetchable from an origin. This section describes the index; see Alire Origins for details on crate origins.

2.1. Creating an index

An Alire index is nothing more than a directory containing a collection of release manifest files in a certain directory structure. Full details of the format of an index can be found in the catalog format specification.

An example index accompanies Alire for GNAT Pro (under share/examples/alire/), which is the recommended starting point for a new index.

Alternatively, to create a new index from scratch, create an empty directory at a location of your choice, and add to it a file called index.toml containing one line with the form version = "x.x.x", specifying the index format used. The range of versions Alire is compatible with can be found by running alr version; when creating a new index you should simply use the highest version listed under compatible index versions:.

You will likely also need to add crates for the compiler and GPRbuild (at least one index containing these crates must be configured for alr build to succeed). The example index includes external crates for both of these, which are sufficient for most purposes. It is also possible to provide binary versions through Alire; see the community index’s gnat_* crates and gprbuild crate for more details on how this can be achieved.

2.2. Configuring an index

To start using your new index, run

alr index --add=<path> --name=<name>

where <name> is a human-friendly label that alr will use to refer to it. If you subsequently want to stop using this index, simply run

alr index --del=<name>

It is possible to configure multiple indexes (with any conflicts resolved using a priority order specified by the --before switch). For example, you may wish to configure both a remote index (see remote indexes below) and a local index of your own work-in-progress crates.

2.3. Adding a new crate to an index

In order to add a crate to the index, you must create a suitable manifest file to describe the release, and place this manifest at the appropriate location in the index directory.

The creation of the manifest file is automated through the alr publish command. In the common case where one is working on a local clone of a remote Git repository which contains a crate, simply run alr publish from the crate’s directory. Alternatively, a Git repository can be specified without a local clone using alr publish <URL> <commit>, while a source archive can be specified with alr publish <URL>.

The resulting manifest file must then be copied to the index directory. The alr publish command will provide instructions on the correct location within the index at which to place it.

The newly added crate will become available for use with alr immediately, unless the crate being published contains "provides" definitions, in which case a call to alr index --update-all will be required.

2.4. Remote indexes

You may wish to share an index outside of your local filesystem. Any means of synchronizing the contents of the index directory will suffice, but alr will manage this process automatically if you use a remote Git repository. The requirements for accessing a Git index origin are the same as for a crate origin; see Alire Origins for details.

It is often useful to have other files in the same repository as the index (a README, CI configuration, templates etc.), so the index itself is located in a first-level subdirectory of the repository (conventionally called index/, though alr searches for any directory containing an index.toml file).

Note that if you are starting from the example index, the manifests for the hello and libhello crates must be either removed or changed to point to suitable remote origins, since file:/some/path local filesystem URLs will no longer work correctly. The manifest for the hello_registry crate provides an example of a remote origin - although the url therein should be changed to point to a location from which hello_registry-src.tar.gz (found under share/examples/alire/registry/) can be downloaded.

To start using a remote Git repository as an index, run

alr index --add=<URL> --name=<name>

Note that <URL> can point directly to the remote repository, so no local clone is required.

Changes on the remote index will not take effect until alr performs an index update, either with alr index --update-all, or through a scheduled auto-update (which is performed every 24 hours by default).