ALR

ALIRE: Ada LIbrary REpository.

A catalog of ready-to-use Ada libraries plus a command-line tool (alr) to obtain, compile, and incorporate them into your own projects. It aims to fulfill a similar role to Rust’s cargo or OCaml’s opam.

Caveat emptor

Documentation at this time is minimal. Expect further efforts in this direction until this warning is removed.

TL;DR

Available for Debian stable / Ubuntu >=17.10 / macOS

alr is undergoing frequent changes in preparation for a first publicly announced beta. Hence, the current recommendation is to run the latest master branch version, and double-check in case of problems that no new PRs have been merged since your last compiled version.

To install run the following as user in a terminal, or see below for more details:

If running on macOS, export OS=macOS
git clone --recursive https://github.com/alire-project/alire.git
cd alire
gprbuild -j0 -p -P alr_env

After a succesful build, you will have a bin/alr executable that you can put in your path if desired.

To see available crates per platform/compiler, see the alire-crates-ci companion repository.

Design principles

alr is tailored to userspace, in a similar way to Python’s virtualenv. A project or workspace will contain all its dependencies.

At this time some projects require platform packages. In this case the user will be asked to authorize a sudo installation through the platform package manager.

Properties and dependencies of projects are managed through a TOML file. This file exists locally for working copies of projects, and the Alire community index stores the files corresponding to its projects.

The complete build environment is set up with another file generated by alr for every project: a GNAT aggregate project that specifies the paths of necessary dependencies, thus freeing the user from concerns about installation paths. The user simply adds the used projects to its own project GPR file with their simple name.

Supported platforms

Alire requires a recent Ada 2012 compiler. In practice, this currently means GNAT GPL 2017 or GNAT FSF 7.2 onward. The continuous integration checks are run against Debian stable, Ubuntu LTS and the latest GNAT Community edition.

Note that, for projects that require platform-provided Ada libraries (such as Debian’s GtkAda), the platform compiler will be used automatically, so even having GPL 2017 in older platforms some projects may be unavailable due to missing dependencies.

Installation

At present, only the latest master version is recommended. To obtain it you need to perform a manual clone and build:

If running on macOS, export OS=macOS
git clone --recursive https://github.com/alire-project/alire.git
cd alire
gprbuild -j0 -p -P alr_env

The executable will be found in bin/alr.

First steps

The following miniguide shows how to obtain and compile already packaged projects, and create your own. First, create or enter into some folder where you don’t mind that new project folders are created by the alr tool

Run alr without arguments to get a summary of available commands.

Run alr --help for global options about verbosity.

Run alr help <command> for more details about a command.

Downloading, compiling and running an executable project

Obtaining an executable project already cataloged in Alire is straightforward. We’ll demonstrate it with the hello project which is a plain “Hello, world!” application (or you can use the hangman or eagle_lander projects as funnier alternatives).

Follow these steps:

Issue alr get hello
Enter the new folder you’ll find under your current directory: cd hello*
Build and run the project with alr run. This will compile and then launch the resulting executable.

As a shorthand, you can use alr get --compile hello to get and compile the program in one step.

Creating a new project

Alire allows you to initialize an empty GNAT binary or library project with ease:

Issue alr init --bin myproj (you can use –lib for a library project).
Enter the folder: cd myproj
Check that it builds: alr compile
Run it: alr run

Dependencies and upgrading

Alire keeps track of a project dependencies in the file ./alire/project_name.toml file of your project. You may check the one just created in the previous example.

This file can be managed through alr:

alr with project_name adds a dependency. You can immediately ‘with’ its GPR project files and packages in your code.
alr with --del project_name removes a dependency.
alr with --from yourproject.gpr reads the given GPR file and adds dependencies specified in comments as alr invocations. For example:
```
  with "xstrings"; -- alr with xstrings
  project My_Project is
```

Alternatively you can edit the file (example in the works) to add dependencies and then issue:

alr update, which will fetch any additional dependencies in your project.

Finding available projects

For quick listing of projects and its description you can use the list command:

alr list [substring]

There’s also a search command which provides more details:

alr search <substring> will look for substring in project names.
alr search --list will list the whole catalog.

Even more details are obtained with:

alr show <project>

This last command will show generic information. To see the one that specifically applies to your platform:

alr show --native <project>

Troubleshooting

By default alr is quite terse and will hide the output of subprocesses, mostly reporting in case of failure. If you hit any problem, increasing verbosity (-v or even -vv) is usually enough to get an idea of the root of the problem. Additionally, -d will show tracebacks of exceptions.

Running tests

alr comes with a test suite for self-checks. See the instructions in the README of the testsuite folder.

Additionally, you can test in batch the building of crates in your platform with the alr test command. (See alr test --help output for instructions.)

ALR