asdf-ada

An asdf plugin to manage Ada/GNAT compiler versions seamlessly across projects.

Overview

What is Ada?

Ada is a structured, statically typed, imperative, and object-oriented high-level programming language designed for safety-critical and mission-critical systems. Originally developed in the 1980s for the U.S. Department of Defense, Ada is renowned for:

• Strong typing — Catches errors at compile time rather than runtime

• Built-in concurrency — Native tasking support for parallel programming

• Contract-based programming — Pre/post conditions and type invariants

• Real-time systems support — Deterministic behavior for embedded systems

• Long-term maintainability — Designed for systems with 30+ year lifecycles

Ada is used in aerospace (Boeing, Airbus), defense systems, rail transportation, medical devices, and financial systems where reliability is paramount.

What is asdf?

asdf is a universal version manager that allows you to manage multiple runtime versions with a single CLI tool. Instead of juggling separate version managers for each language, asdf provides one interface to rule them all.

Why asdf-ada?

Managing Ada/GNAT compiler versions traditionally requires manual downloads, environment variable configuration, and careful PATH management. asdf-ada simplifies this by providing:

Feature	Benefit
Version Switching	Switch between GNAT versions instantly per project
Project Isolation	Each project can specify its required Ada version via .tool-versions
Reproducible Builds	Team members and CI/CD pipelines use identical compiler versions
Multiple Distributions	Support for FSF GNAT, GNAT Community, and Alire-managed toolchains
Cross-Platform	Works on Linux, macOS, and Windows (via WSL)

Prerequisites

System Requirements

Platform	Minimum Version	Notes
Linux	Ubuntu 20.04+ / Fedora 35+ / Debian 11+	x86_64 and aarch64 supported
macOS	macOS 11 (Big Sur)+	Intel and Apple Silicon (M1/M2/M3)
Windows	Windows 10+ with WSL2	Native support planned for future releases

Dependencies

Before installing the plugin, ensure you have the following:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y curl git build-essential libc6-dev

# Fedora/RHEL
sudo dnf install -y curl git gcc glibc-devel

# macOS (via Homebrew)
brew install curl git
xcode-select --install  # For build tools

# Arch Linux
sudo pacman -S curl git base-devel

asdf Installation

If you haven’t installed asdf yet:

# Clone asdf
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

# Add to your shell (bash)
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc

# Add to your shell (zsh)
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.zshrc

# Add to your shell (fish)
echo 'source ~/.asdf/asdf.fish' >> ~/.config/fish/config.fish

# Reload your shell
exec $SHELL

Installation

Adding the Plugin

# Add the asdf-ada plugin
asdf plugin add ada https://github.com/hyperpolymath/asdf-ada-plugin.git

# Verify installation
asdf plugin list

Installing Ada/GNAT Versions

# List all available versions
asdf list all ada

# Install a specific version
asdf install ada 14.1.0        # FSF GNAT 14.1.0
asdf install ada community-2021 # GNAT Community 2021
asdf install ada alire-latest   # Latest via Alire

# Install the latest stable version
asdf install ada latest

Setting the Version

# Set global default (used when no local version is specified)
asdf global ada 14.1.0

# Set local version for current project (creates .tool-versions)
asdf local ada 14.1.0

# Set version for current shell session only
asdf shell ada 14.1.0

# Verify the active version
asdf current ada
gnatmake --version

Usage

Project Configuration

Create a .tool-versions file in your project root:

ada 14.1.0

When you cd into the project directory, asdf automatically activates the specified version.

Available Commands

# List installed versions
asdf list ada

# Show current version
asdf current ada

# Uninstall a version
asdf uninstall ada 13.2.0

# Reshim after installing Ada tools (e.g., via Alire)
asdf reshim ada

# Show installation path
asdf where ada 14.1.0

Environment Variables

The plugin respects and sets the following environment variables:

Variable	Description	Default
ASDF_ADA_DISTRIBUTION	Preferred distribution (fsf, community, alire)	fsf
ASDF_ADA_MIRROR	Custom mirror URL for downloads	Official sources
ASDF_ADA_SKIP_VERIFY	Skip checksum verification (true/false)	false
ASDF_ADA_INSTALL_GPRBUILD	Auto-install GPRbuild (true/false)	true

Integration with Build Tools

GPRbuild

# GPRbuild is included with most GNAT installations
gprbuild --version

# Build an Ada project
gprbuild -P my_project.gpr

Alire

Alire is Ada’s package manager. You can use it alongside asdf:

# Install Alire separately or use asdf-managed version
asdf install ada alire-latest

# Initialize an Alire project
alr init my_project
cd my_project
alr build

SPARK Formal Verification

For SPARK Pro users:

# SPARK is included in GNAT Community editions
gnatprove --version

# Run formal verification
gnatprove -P my_project.gpr

Supported Versions

FSF GNAT (GNU Ada)

Official GNU Compiler Collection Ada frontend:

14.1.0, 14.0.0, 13.3.0, 13.2.0, 13.1.0
12.4.0, 12.3.0, 12.2.0, 12.1.0
11.5.0, 11.4.0, 11.3.0, 11.2.0, 11.1.0
10.5.0, 10.4.0, 10.3.0

GNAT Community Edition

AdaCore’s free community releases (discontinued after 2021):

community-2021
community-2020
community-2019

Alire Toolchains

Managed via the Alire package manager:

alire-latest    # Latest available via Alire
alire-native    # Native toolchain via Alire

Configuration

Plugin Configuration File

Create ~/.config/asdf-ada/config for persistent settings:

# Default distribution preference
distribution = fsf

# Download mirror (leave empty for official sources)
mirror =

# Verify checksums (recommended)
verify_checksums = true

# Install GPRbuild automatically
install_gprbuild = true

# Concurrent downloads
parallel_downloads = 4

Platform-Specific Notes

macOS Apple Silicon

Native ARM64 builds are available for GNAT 13.1.0+. For older versions, Rosetta 2 emulation is used automatically.

Linux ARM64

ARM64 builds are provided for: - Raspberry Pi 4/5 (64-bit OS) - AWS Graviton instances - Other aarch64 systems

Windows (WSL2)

# Install WSL2 with Ubuntu
wsl --install -d Ubuntu

# Inside WSL, install asdf and the plugin as normal
# See the Linux installation instructions above

Troubleshooting

Common Issues

1. Version not found when running gnatmake

   Run asdf reshim ada after installation and ensure your shell is properly configured.

2. Download fails with SSL errors

   Ensure ca-certificates is installed: sudo apt-get install ca-certificates

3. "Permission denied" during installation

   Check write permissions for ~/.asdf/installs/ada/

4. Slow downloads

   Set ASDF_ADA_MIRROR to a geographically closer mirror.

Getting Help

1. Check the GitHub Issues for known problems

2. Join the Ada community chat

3. Open a new issue with:

   • Your OS and version

   • asdf version (asdf --version)

   • Plugin version

   • Full error output

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

# Fork and clone
git clone https://github.com/YOUR_USERNAME/asdf-ada-plugin.git
cd asdf-ada-plugin

# Create a feature branch
git checkout -b feature/your-feature-name

# Make changes and test
./scripts/test.sh

# Submit a pull request

Code of Conduct

This project adheres to the Contributor Covenant. Please read our Code of Conduct before participating.

Roadmap

This roadmap outlines the planned development phases for asdf-ada.

Phase 1: Foundation (v0.1.0) [wrench]

Status: 🚧 In Progress

• Core plugin structure following asdf plugin template

• bin/list-all — Fetch available GNAT versions from upstream

• bin/download — Download GNAT releases

• bin/install — Install and configure GNAT toolchain

• bin/latest-stable — Resolve latest stable version

• Basic FSF GNAT support (Linux x86_64)

• README and initial documentation

• GitHub Actions CI/CD pipeline

• Basic test suite using Bats

Phase 2: Multi-Platform Support (v0.2.0) [desktop]

Status: 📋 Planned

• macOS x86_64 support

• macOS ARM64 (Apple Silicon) support

• Linux ARM64 support

• Windows WSL2 documentation and testing

• Checksum verification for all downloads

• Progress indicators during download/install

• Improved error messages and logging

Phase 3: Extended Distribution Support (v0.3.0) [cubes]

Status: 📋 Planned

• GNAT Community Edition support (2019-2021)

• Alire toolchain integration

• AdaCore GNAT Pro stub support (license required)

• Custom mirror configuration

• Version aliases (lts, stable, latest)

• bin/help plugin subcommands

Phase 4: Developer Experience (v0.4.0) [star]

Status: 📋 Planned

• Automatic GPRbuild installation

• GNATcov integration

• SPARK tools inclusion

• Shell completions (bash, zsh, fish)

• Version constraint solving (semver support)

• asdf-ada doctor command for diagnostics

Phase 5: Ecosystem Integration (v0.5.0) [plug]

Status: 📋 Planned

• Alire crate template generation

• VS Code Ada extension compatibility documentation

• GNAT Studio integration notes

• Docker/container image publishing

• CI/CD examples (GitHub Actions, GitLab CI, Jenkins)

• Nix flake support

Phase 6: Enterprise & Polish (v1.0.0) [building]

Status: 🔮 Future

• Stable API with semantic versioning

• Comprehensive test coverage (90%+)

• Full documentation with tutorials

• Offline installation support

• Corporate proxy support

• Signed releases

• Official asdf plugin registry listing

• Community governance model

Future Ideas [lightbulb]

These features are under consideration for post-1.0 releases:

• Cross-compilation toolchains — ARM bare-metal, RISC-V targets

• GNAT-LLVM support — LLVM-based Ada compiler backend

• Version diffing — Show changelog between versions

• Performance profiling integration — GNATbench-like features

• IDE project generation — Templates for various editors

• Dependency caching — Speed up clean installs

• Native Windows support — Without WSL requirement

Mirrors

This repository is mirrored to:

• GitLab

• Codeberg

• Bitbucket

Related Projects

• asdf — The universal version manager

• GNAT Downloads — Official AdaCore downloads

• Alire — Ada/SPARK package manager

• Ada Programming Language — Official Ada resources

• learn.adacore.com — Free Ada/SPARK tutorials

• Awesome Ada — Curated Ada resources

Hyperpolymath asdf Ecosystem

This plugin is part of the Hyperpolymath asdf ecosystem, a layered architecture for managing developer tool versions.

Ecosystem Architecture

                    ┌──────────────────────────┐
                    │  asdf-control-tower      │  ← Layer 3: Presentation
                    │  (docs + dashboard)      │
                    └───────────┬──────────────┘
                                │
┌──────────────────────────┐    │    ┌──────────────────────────┐
│ asdf-ui-plugin           │────┼────│ asdf-plugin-configurator │  ← Layer 2–3
│ (visual UX; planned)     │    │    │ (Rust CLI; config/policy)│
└──────────────────────────┘    │    └──────────────────────────┘
                                │
                    ┌───────────┴───────────┐
                    │ asdf-metaiconic-plugin│  ← Layer 1: Registry
                    │ (registry + schema)   │
                    └───────────┬───────────┘
                                │
     ┌────────────────────────────────────────────────┐
     │  Individual asdf tool plugins (Layer 5)        │
     │                                                │
     │  ★ asdf-ada-plugin  ← YOU ARE HERE             │
     │    asdf-neo4j-plugin                           │
     │    asdf-ghjk                                   │
     │    …(68+ installable plugins)                  │
     └────────────────────────────────────────────────┘

Layer Descriptions

Layer	Component	Purpose
Layer 0	Infrastructure Spine	Multi-forge mirroring, instant-sync, policy constraints (.claude/CLAUDE.md), community docs — present across all repos
Layer 1	asdf-metaiconic-plugin	Canonical metadata registry: registry/plugins.yaml, category definitions, quality metrics, icon/branding standards
Layer 2	asdf-plugin-configurator	Rust CLI for declarative plugin configuration — apply policy to machines/projects, consume registry for validation
Layer 3	asdf-control-tower + asdf-ui-plugin	Human-facing dashboard, documentation hub, visual discovery UI (planned)
Layer 4	Domain Collections	Category "umbrella" plugins (e.g., asdf-security-plugin for curated security toolsets)
Layer 5	Tool Plugins ★	Actual installable units — implements bin/list-all, bin/download, bin/install, bin/latest-stable. This repo (asdf-ada-plugin) lives here.

This Plugin’s Role

asdf-ada-plugin is a Layer 5 tool plugin — the actual "workhorse" that asdf uses to install and manage Ada/GNAT compiler versions. It:

• Implements the asdf plugin contract (bin/list-all, bin/download, bin/install, bin/latest-stable)

• Fetches releases from the GNAT-FSF-builds upstream

• Provides checksum verification, multi-platform support, and robust error handling

• Is indexed by asdf-metaiconic-plugin for ecosystem-wide discovery

• Can be configured via asdf-plugin-configurator for team/project consistency

Ecosystem Links

• asdf-control-tower — Ecosystem documentation hub

• asdf-metaiconic-plugin — Plugin registry and metadata

• asdf-plugin-configurator — Policy enforcement CLI

License

This project is licensed under the GNU Affero General Public License v3.0 or later. See the LICENSE file for details.

SPDX-License-Identifier: AGPL-3.0-or-later

Acknowledgments

• The asdf team for creating the plugin ecosystem

• AdaCore for maintaining GNAT

• The Ada community for keeping the language thriving

• All contributors who help improve this plugin

---

Made with ❤️ for the Ada community

⬆ Back to Top