# Define distribution and installation

Type: grilling
Status: resolved
Blocked by: 10, 13
Parent: [Find the ASPL MVP specification](../map.md)

## Question

What versioning, release archive, checksum, install location, upgrade and uninstall instructions, glibc compatibility floor, and licensing notices must the ASPL website provide for the single Linux executable?

## Answer

ASPL publishes one immutable release archive for the x86-64 glibc target. The website defaults to a user-owned manual installation of the single `aspl` executable, verifies the archive before extraction, and keeps every old release available for exact rollback. It provides no installer, package-manager repository, automatic updater, or separately installed runtime.

### Versions and support

The current public MVP version is `0.1.1`. ASPL follows [Semantic Versioning 2.0.0](https://semver.org/) and prints the exact release version as `aspl 0.1.1` through the CLI contract from [Define the CLI and build behavior](13-define-cli-and-build-behavior.md).

During the `0.y.z` series:

- every release states whether it preserves accepted ASPL source and documented CLI invocation compatibility within its minor line;
- a pre-1.0 release may make incompatible source, CLI, private bytecode, or native-packaging changes and must name them in its release notes; and
- native programs built by an older release remain independent executables. They do not require the matching or current `aspl` installation to run.

Each published archive, checksum file, license set, release page, and release note is immutable. A corrected build receives a new version. The project never replaces bytes under an existing version or filename.

Only the newest release receives fixes during the pre-1.0 MVP. The website marks it as recommended and labels all older releases as archived. Archived releases and their checksums and notices remain downloadable. The MVP promises no security-support duration, automatic update check, update service, or silent redirection from an old version to new bytes.

### Native host contract

The release supports baseline x86-64 Linux with glibc 2.34 or later. It uses no instruction-set extension beyond baseline x86-64. The release build fixes that choice with an equivalent of `-march=x86-64 -mtune=generic`, uses a controlled glibc 2.34 build environment or sysroot, and fails release validation if the executable requires any `GLIBC_*` symbol version newer than `GLIBC_2.34`.

Musl systems, including an ordinary Alpine Linux installation, are unsupported. Other architectures and non-Linux systems are also unsupported. The normative promise is the architecture, operating-system family, libc family, and glibc floor rather than a list of distributions.

The download page tells users to run:

~~~sh
uname -m
getconf GNU_LIBC_VERSION
~~~

The supported results are `x86_64` and `glibc 2.34` or a later glibc version. A failure to report GNU libc does not qualify as a supported host.

A release may list RHEL 9, Ubuntu 22.04, and Debian 12 as tested examples only when that release's clean-system tests passed on them. RHEL 9 supplies glibc 2.34, Ubuntu 22.04 supplies glibc 2.35, and Debian 12 supplies glibc 2.36. These versions justify the floor but do not turn the examples into separate compatibility contracts:

- [RHEL 9.0 system toolchain](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/pdf/9.0_release_notes/distribution)
- [Ubuntu 22.04 `libc6`](https://packages.ubuntu.com/jammy/libc6)
- [Ubuntu release lifecycle](https://ubuntu.com/about/release-cycle)
- [Debian 12 `libc6`](https://packages.debian.org/en/bookworm/libc6)

### Release archive and checksum

Version `0.1.1` uses this exact archive name:

~~~text
aspl-0.1.1-x86_64-linux-gnu.tar.xz
~~~

The version component changes for later releases; the target component remains `x86_64-linux-gnu` while this is the only distributed target. The archive extracts into one directory named `aspl-0.1.1-x86_64-linux-gnu`. That directory contains exactly:

~~~text
aspl
LICENSE-MIT
LICENSE-APACHE
~~~

The directory and `aspl` have mode `0755`. License and notice files have mode `0644`. Entries are regular files, except for the containing directory; the archive contains no symlinks, hard links, absolute paths, parent traversal, installer, README, or runtime directory. If incorporated material requires notices, the same directory also contains `THIRD-PARTY-NOTICES` with mode `0644`. The file is absent when no notice is required.

Every version has its own release directory on the website. Beside the archive it contains a GNU-compatible file named `SHA256SUMS` with exactly one line: the archive's lowercase 64-digit SHA-256 digest, two ASCII spaces, the exact archive filename, and a final line feed. The digest covers the complete compressed archive, including its executable and notices. The website also renders the exact digest and archive byte size next to the download link.

The verification command is:

~~~sh
sha256sum --check SHA256SUMS
~~~

It must report the exact archive filename followed by `OK`. The page calls SHA-256 an integrity check, not proof of publisher identity. Cryptographic release signing and its required key-custody policy are outside the MVP.

### First installation

The Arabic and English installation pages render the real current version into every filename and command. They do not publish placeholders. After the user downloads the archive and `SHA256SUMS` into the same directory, the default user-owned flow for version `0.1.1` is:

~~~sh
sha256sum --check SHA256SUMS
tar -xJf aspl-0.1.1-x86_64-linux-gnu.tar.xz
./aspl-0.1.1-x86_64-linux-gnu/aspl --version
install -d "$HOME/.local/bin"
install -m 0755 aspl-0.1.1-x86_64-linux-gnu/aspl "$HOME/.local/bin/aspl"
command -v aspl
aspl --version
aspl check hello.aspl
~~~

Both version commands must print `aspl 0.1.1`. A successful `aspl check hello.aspl` is silent and returns status `0`. The page supplies the exact bilingual-documentation example as `hello.aspl`, states that expected result, and links next to the documented `run` and `build` workflows.

If `command -v aspl` does not resolve to `$HOME/.local/bin/aspl`, the page first offers this change for the current POSIX-compatible shell:

~~~sh
export PATH="$HOME/.local/bin:$PATH"
~~~

It then gives shell-specific instructions for adding `$HOME/.local/bin` to the user's startup configuration. It tells the user which file to edit and which line to add, but it never edits a shell file or appends a line automatically. Fish instructions use `fish_add_path`. After starting a new shell, the user reruns `command -v aspl` and `aspl --version`.

The optional administrator-managed flow replaces the two `install` commands with:

~~~sh
sudo install -m 0755 aspl-0.1.1-x86_64-linux-gnu/aspl /usr/local/bin/aspl
~~~

The page warns users to choose one installation location. They must inspect `command -v aspl` after installation so an older executable elsewhere on `PATH` does not mask the selected copy. The default path never requires `sudo`.

### Upgrade, rollback, and uninstall

An upgrade repeats the host check, download, SHA-256 verification, extraction, and extracted `--version` check for the new release before replacing the installed file with the same `install -m 0755` command. The website performs no automatic update and the executable does not contact the website.

A rollback follows the identical procedure with a chosen archived version. The user downloads that version's archive and checksum from its immutable release page, verifies both, checks the extracted version, and replaces the installed executable. ASPL creates no automatic backup. Users may retain downloaded archives for offline rollback; the instructions never delete them.

The user-owned uninstall command is:

~~~sh
rm -- "$HOME/.local/bin/aspl"
~~~

The administrator-managed uninstall command is:

~~~sh
sudo rm -- /usr/local/bin/aspl
~~~

Uninstall removes only the selected executable. It does not edit `PATH`, shell configuration, source files, generated native programs, or downloaded release archives. The page tells users to check `command -v aspl` afterward to detect another installed copy.

### License presentation

ASPL is available under either MIT or Apache-2.0 at the recipient's choice. `LICENSE-MIT` and `LICENSE-APACHE` contain the complete license texts and use `Copyright (c) 2026 ASPL contributors` where a copyright line belongs. The website states the dual-license choice beside the archive and links both complete texts from every release page.

An Apache `NOTICE` file is not created for ASPL itself. If incorporated third-party material requires attribution or another notice, the release includes `THIRD-PARTY-NOTICES`, links it beside the licenses, and treats its presence and contents as part of the immutable archive. Contributor build and release-production instructions live outside the user installation flow.