3. Alire Origins

In order to use a crate as a dependency, alr must be able to fetch the crate’s source files from an origin. The most common kinds of origin are Git repositories and source archives.

3.1. Git repositories

Crates and indexes can be fetched as clones of Git repositories, over either HTTP or SSH.

Repositories are cloned and updated by calling out to the system’s git command, so git must be configured with any credentials required to authenticate with a private origin. This means either Git-over-SSH (see your SSH client’s documentation), or HTTPS with git’s credential handling (documented here). As a general rule, if a git clone or git fetch on a crate/index origin succeeds, then so will any corresponding updates with alr.

The main consideration when using such repositories with Alire is ensuring that the correct form of URL is used. It must be apparent to alr that the URL refers to a Git repository (which can be disambiguated with a git+ prefix), and git must be able to infer which protocol should be used (documented here). It is therefore recommended that URLs use only the schemes git+https:// or git+ssh:// as appropriate.

Repositories on the local filesystem can be specified with the form git+file:/some/path, though this is not recommended except as a temporary arrangement for testing purposes.

3.2. Source archives

Crates (but not indexes) can also be fetched as an archive file (either tarball or Zip) containing the relevant sources. alr simply requires some means of downloading this file from a URL to a local filesystem location.

The command used to fetch such files is specified by the settings key origins.archive.download_cmd. By default alr uses the command curl ${URL} -L -s -o ${DEST}, which does not attempt any form of user authentication, but this can be changed to any equivalent alternative which implements a desired authentication scheme. The command should download the file to ${DEST} (the full file path, not a directory), and must not pollute the containing directory with other files.

The simplest way to enable user authentication is to configure the server to accept HTTP Basic authentication and supply curl with the switch --netrc (or equivalently -n), which instructs it to scan the .netrc file in the user’s home directory and attempt to authenticate with any credentials found there (see man curl and man netrc for more detail). This is achieved by invoking

alr settings --set --global origins.archive.download_cmd 'curl ${URL} -n -L -s -o ${DEST}'

Note that most terminals will perform substitutions on double-quoted strings containing ${SOMETHING}, so it is important to enclose the value in single-quotes.

If you wish to use a .wgetrc configuration file instead, the equivalent wget command is 'wget ${URL} -q -O ${DEST}'.

3.2.1. Using a fetch script

The origins.archive.download_cmd setting only accepts a simple space-separated command, with no scripting functionality. If this is not sufficient, you can write more complex logic (or commands with arguments containing spaces) to a separate script, for instance by setting the value to 'python /path/to/my_script.py ${URL} ${DEST}'.

In fact, while alr will only recognise a URL as a remote archive if it has an HTTP scheme and ends with a known archive extension (e.g. .tgz), there are no restrictions on the remainder of the URL or how it is interpreted. In more complex cases it is therefore possible to encode any relevant information in the URL under a domain you control (which needn’t necessarily exist) and have the script parse this URL to determine how to fetch the archive. See share/examples/alire/fetch-script/ for an example of how this might be done.

4. Example: using a fetch script and a custom registry

Assuming you have already installed alr in the directory $PREFIX, the following steps will guide you through the process of configuring alr to use a fetch script and a registry. We’ll base this on the examples packaged together with Alire, namely:

  • the example index, which contains a few crates;

  • in particular the crate hello_registry, the origin of which is a tarball meant to be retrieved from a registry;

  • the example fetch script;

  • the example registry, which contains the tarball for hello_registry.

(Note: if you would like to try these steps without changing your global Alire configuration, you could create a blank directory and start each command with alr -s <directory>, to tell Alire to use this directory to contain the settings for this session.)

Let’s first tell alr to use the example index:

alr index --add $PREFIX/share/examples/alire/index/ --name example_index

Alire will now have access to all the crates in this index. Let’s now configure alr to use the example fetch script. This is done with

alr settings --global --set origins.archive.download_cmd "python $PREFIX/share/examples/alire/fetch-script/alr_download_helper.py \${URL} \${DEST}"

The fetch script is a simple Python program which will work this way:

  • If the variable ALIRE_LOCAL_FOLDER is set, and points to an existing directory, the script will first attempt to get the file from this directory.

  • Otherwise, it will call wget to download the file from the given URL. If the environment variable ALIRE_WGET_HEADER is set, it will be used as the header for the wget command.

For the purposes of our example, we don’t want to set up a bona fide registry, so let’s set the environment variable ALIRE_LOCAL_FOLDER to point to the directory containing the archive:

export ALIRE_LOCAL_FOLDER=$PREFIX/share/examples/alire/registry

You should now be set to use all the elements in this example: you can now fetch and run the hello_registry crate with:

alr get hello_registry
cd hello_registry*
alr run