Skip to content

2019 Nov Beta

Jump to bottom
Alejandro R Mosteo edited this page Nov 14, 2019 · 4 revisions

About the Alire Nov-2019 Beta

Greetings, and thank you for your interest. This document intends to serve as a short introduction and guide for testers of the alr tool during the 0.8 release (first invited beta).

Introduction

Alire intends to fill the role of package managers in other languages like OCaml/opam, Rust/cargo, Python/pip, etc.

  • We use "Alire" to refer to the whole project, and "alr" for the command-line tool.

  • alr is a "project package manager", as described in the Universal Package Manager page, as opposed to "system package managers". With alr you have an isolated working environment for every project you create or "check out".

  • We borrow the 'crate' name from Rust to refer to a project available in alire, and avoid confusion with GNAT projects (*.gpr files) and Ada package keyword. A crate describes one or more releases, with every release having a semantic version. A release contains all sources and project files necessary to build it, and use it (in the case of libraries).

Expectations from beta testers

For this beta, our scope primarily is:

  • Identifying shortcomings and bugs in the use cases already supported.

  • Identifying missing functionality for a bare-minimum complete 1.0 release.

  • Identifying new use cases for the Ada open source world that may have been missed.

Providing feedback

Alire is quite young and our manpower is very limited, so please be understanding if you find rough spots or do not feel enough responsiveness from the team. Suggested ways to submit feedback are:

  • For informal or open-ended discussion, chat through gitter.

  • For specific problems, open or reply to issues in the alire repository. Please ensure that you are using the latest version from master before opening an issue.

If your problem is not evident, you can help us by including a full log (passing -vv -d to alr) and the output of:

  1. git show (ran in the alire source folder from which you compile alr).
  2. alr index --list
  3. alr version

Use cases

The following use cases were envisioned during the creation or alire. You can try any of them, see where the current implementation falls short, and point other use cases that we may have missed.

More in-depth guides for these use cases will be provided as time permits.

Ada newcomer wanting to try some Ada application

In this use case, the user simply wants to retrieve a release, and compile and run a main executable.

  • Commands: alr get, alr run
  • Example: $ alr get --compile hangman && cd hangman* && alr run

Ada newcomers exploring the language and looking for popular libraries

In this case, the user is considered inexperienced with Ada, and may want help with all steps from project creation to inclusion of libraries.

  • Commands: init, compile, run, list, search, with
  • Example: see README from this section onward.

Ada developers wanting to reuse Ada libraries in their own projects

A seasoned Ada programmer wants to start using Alire to manage dependencies of their own projects. Projects may be new or already existing.

  • Commands: init, compile, run, with
  • Examples:
    • For basic use in new projects: see previous use case.
    • Adding Alire support to an existing (executable) project:
      1. Enter your sources: $ cd <project root>
      2. Make the project Alire-aware: $ alr init --bin --in-place <name>
        • <name> must match the name.gpr build file or manual tinkering will be necessary.
        • --lib should be used instead of --bin for library projects.
      3. Test compilation: $ alr compile
        • See previous comment about name.gpr
      4. Test execution: $ alr run.
        • The executable name must be <name> or manual tinkering will be necessary. It can be located in any subfolder.
    • Adding dependencies after the project is Alire-aware: see README from this section onward.
      • Alire takes care of relative paths to project files. All "withs" in a project file should use just the simple_name.gpr without path.

Ada developers wanting to publish their Ada libraries/programs for the benefit of the community

In this use case, an Ada programmer wants to make available its library in the community Alire catalog.

  • Commands: init, publish
  • Minimal information (to be enhanced shortly):
    • Releases should be available online as an immutable tarball or zipball.
      • Its SHA512 hash will be used for integrity validation.
    • alr publish --hash <URL> can be used to obtain the integrity hash.
    • A crate description file in TOML format must be submitted as a Pull Request to the alire-index repository.
      • See its specification for details, or check other crates (e.g., libhello) in the given repository for examples.
      • Each crate has a maintainer (GitHub username) which is used to automatically approve subsequent PRs to the same crate.
        • This is work in progress, still unimplemented.

Caveats and Known Issues

Crate TOML format

The format described in catalog-format-spec.rst may change or get extended as we work towards the first stable release. Current crates in the index are maintained by Alire developers; if you submit new crates we would like for you to take charge of maintaining them, understanding that during this beta period that may involve (hopefully infrequent) updates.

Related issue: #234

Linux-only

At present development is chiefly done in Ubuntu LTS Linux. After PR #228 is merged, the codebase will compile and testing on Windows will be able to proceed. Help would be greatly appreciated in this area.

During CI tests, the Ubuntu LTS, Debian stable, and GNAT Community Edition compiler versions are tested.

Related issues: #3, #217

Manual publishing

Our objective is to simplify/automate the publishing process as much as possible, but currently crate submission/updating is entirely a manual affair.

Related issue: #227

Native crates

We denominate "native crates" those that wrap packages provided by the OS package manager: apt in Debian/Ubuntu and similar. These are used to jumpstart support for complex dependencies like GtkAda, AdaCurses...

There is limited support for some native crates in Debian/Ubuntu only at present. This support is based on flawed ideas and is to be reworked. Currently, these crates are not required for dependency resolution.

In regard to this beta run:

  • Native crates, when failing or unsupported, require the user to externally make available its contents (manually installing the library, or installing the OS package they refer to). Otherwise, dependent crates will likely fail to compile.

  • Issues with native crates, as long as they are not breaking, are not important since the whole support is going to change, and need not be reported.

  • No new native crates are to be submitted for inclusion until the new system is in place.

Related issue: #65

Website

The Alire website is Jekyll-based, and regenerated every 24h. Suggestions for improvement can also be submitted. Issues are centralized in the alire repository and should be submitted there.

Crate/Project nomenclature.

Initially, crates were named projects through the codebase. The reason was to avoid the usual "package", given its specific Ada meaning. Later, to avoid confusion with gprbuild projects, also ubiquitous in open-source Ada, they were renamed as crates.

If you go digging through the codebase you will find still many references to projects. These are intended to be refactored at some point and need not confuse you; they are simply crates.

Related issue: #113

FAQ

We'll add here common questions received during this testing period.

Clone this wiki locally