AURA: Ada User Repository Annex

The Ada User Repository Annex (AURA) is a proposed specification for a native Ada source code package management system, developed in lock-step with a reference implementation. This is the official documentation for the Reference Implementation (AURA CLI).

AURA CLI was designed to function as a production-ready, integrated build system with similar capabilities to existing native packaging systems for projects like Rust (cargo), Python (pip), and NodeJS (npm).

AURA CLI has a fully parallelized design for maximum performance on modern systems, and uses all available cores to parse program text, compute dependencies, obtain subsystems, perform configuration, and build projects. Besides having a user-friendly interface, AURA CLI is also designed to work in automated CI/CD pipelines.

Premise

AURA was designed as a hypothetical new Specialized Needs Annex of the Ada Reference Manual (the Ada standard). As such it is not designed to be an exclusively stand-alone tool, but rather as a specific set of behaviors that an Ada compiler could optionally implement 1. The behavior specified by AURA is triggered when the implementation encounters a dependency that it cannot immediately locate. Dependencies are typically specified through standard Ada with clauses, though AURA also specifies a new pragma for the expression of non-Ada dependencies.

The basic idea is that when an AURA implementation encounters a with clause for a library unit of a subsystem it cannot immediately locate, it attempts to retrieve that subsystem from the first available (configured) AURA repository. The AURA reference implementation (“AURA CLI”) parses the context clause of all Ada sources in a project. It then builds a fully dependency graph, and uses this information to compute which subsystems must be obtained, and if those subsystems actually contain the required units.

As a conceptual Specialized Needs Annex, the behavior is well-defined for both compliant and non-compliant compilers. Generally, the attempt to compile an AURA project with a non-compliant compiler may fail, but will never change the meaning of the program text, or the behavior of the compiled program.

See also

Ada Specialized Needs Annexes

The Ada Reference Manual (ARM) is the ISO standardized formal specification for the Ada language, and formally defines how a compliant compiler is required to behave.

The ARM contains a set of Specialized Need Annexes that “define features that are needed by certain application areas”.

See also

Subsystems

Subsystems are both Ada concepts, and (by extension) AURA concepts, as AURA is a conceptual Specialized Needs Annex. Subsystems are essentially any library unit hierarchies rooted by a “top-level” unit. Top-level means a direct child of package Standard.

Subsystems retrieved and configured through AURA are essentially analogues to “packages” or “crates” of other package managers.

Staying true to the Ada philosophy

The best thing is often impractical.
The right thing is usually rejected.
The popular thing is usually wrong.

Package management is fraught with danger. Two poisons conspire: interdependency and versioning.

AURA takes a deliberate, and possibly controversial position that versioning should not be the responsibility of the package manager. Instead, AURA expects versioning and version interdependency to be handled at the level of the repository and/or subsystem. This is done to ensure that AURA’s behaviour is always predictable and that checked-out code never changes without explicit user intervention.

The reference implementation (“AURA CLI”) prominently integrates git, and encourages the use of submodules, branches, or tags to handle repository versioning. The simple subdirectory based repository structure implemented by AURA CLI encourages repository coalescing, where individual subsystems are maintained in their own git repository, allowing coalesced AURA repositories to include them as git submodules, targeting specific commits of each subsystem. Such coalesced repositories can then be versioned as a collection, where integration testing can be applied to all submodules in the repository. Ideally, a project can create its own single point of truth repository to coalesce all project dependencies. This approach, though more work, makes updating of codebases much more reliable, safe, and controlled.

Please see this blog post for a deeper philosophical discussion on the design of AURA.

1

As of yet we have not started any formal proposal to the ARG

2

The Ada Reference Manual clause 10 describes library units and compilation.