rucc_sysroot/

artifact.rs

//! What this release pins: one sysroot artifact per target, by URL and by hash.
//!
//! Design: `spec/cross-compile/13-distribution.md` section 13.2, which says every downloaded
//! artifact has a hash pinned in the rucc release, checked before use, with a mismatch being a hard
//! failure and no flag to get past it. Section 13.8 divides the work in three and the other two are
//! written: `rucc_driver::fetch` moves the bytes with a program the machine already has, and
//! `rucc_driver::install` decides whether what arrived is the right tree. This is the third, which
//! is the statement of what the right one is, and it is the half that makes the other two mean
//! anything.
//!
//! # Why it is here rather than with the two halves that use it
//!
//! Because it is read by something that cannot depend on the driver. The distribution manifest of
//! section 13.5 is generated by a build tool, the same way `docs/TARGETS.md` and `tests/link-lines`
//! are, and what it says about a target is what this table says plus what [`crate::Wall`] says. A
//! build tool that pulled in the whole driver to read three strings would be a layer violation
//! dressed up as convenience. It sits well here for a second reason as well: a pin is a fact about
//! a sysroot, which is what this crate is for, and the fetch and the install are what a driver does
//! with one.
//!
//! # Why the table is in the binary
//!
//! Because a hash that travels with the artifact is not a pin, and a hash in a file beside the
//! compiler is a hash whoever replaces the artifact can replace too. The release is the authority
//! for what an artifact of that release is, so the table is compiled into the release, which also
//! means an upgrade can change a URL without anything on the machine having to be told.
//!
//! It is a table rather than a computed URL for the same reason. A name built out of a version and
//! a tuple looks tidier and quietly says that every target's artifact is at a predictable address
//! forever, which is a promise about somebody else's file server. A row per target costs three
//! strings and says only what is true.
//!
//! # What is in it
//!
//! Fifteen rows, which are the three windows-gnu targets, four musl ones and eight glibc ones. For windows-gnu,
//! `bin/mingw-headers` in `tamnd/rucc-cross` installs mingw-w64 14.0.0's headers, `bin/mingw-runtime`
//! builds the runtime and the import libraries into the `lib` directory beside them, `bin/artifact`
//! packs the tree, and the release `sysroots-2026-09-21` is where the files are. The archives are
//! 15.2 MiB for x86_64, 14.8 MiB for i686 and 12.5 MiB for aarch64, installing to 134 MB, 128 MB and
//! 113 MB. The header half is the same 1702 files in all three, because mingw-w64 has no per
//! architecture split and [`crate::Sysroot::splits_by_arch`] says so, and the `lib` half is what
//! differs.
//!
//! For musl, `bin/sysroot` builds musl 1.2.5 for x86_64, aarch64, riscv64 and armv7 hard float, and
//! the release `sysroots-2026-09-23` has the four archives, each about 2 MiB and installing to between
//! 7 and 13 MB. They hold musl's headers and its static libraries and start files, and not the Linux
//! uapi headers, which are [`KERNEL_HEADERS`] and fetched once for every Linux target. Both runs that
//! produced them, on two machines, packed the same bytes.
//!
//! For glibc, `bin/glibc-sysroot` puts together the merged header tree of every pinned release from
//! 2.28 to 2.44 with glibc 2.44's start files and `libc_nonshared.a`, for x86_64, i686, aarch64,
//! armv7 hard float, riscv64, powerpc64le, s390x and loongarch64, and the release
//! `sysroots-2026-09-24b` has the eight archives, each under 600 KB. The seven whose ABI has a glibc
//! older than 2.33 also carry `libc_nonshared_stat.a`, the `stat` family those releases kept in
//! `libc_nonshared.a`, which [`crate::link::LinkLine::glibc`] adds for a pin before 2.33. There is no `libc.so` in them,
//! because the driver writes the stubs itself, and one archive serves every release of its target,
//! which is [`pinned_for_target`]. server2 and server3 built them from separate inputs and packed
//! the same bytes.
//!
//! Every other target is still unpublished, which is a statement about producers rather than about
//! this table: `--fetch` of one says so by name, and the day a tree for it is published is the day a
//! row for it is added here. The rows that are here are the first thing `--fetch` has ever had
//! anything to move, so they are also what the fetch and the install are tested against.

use std::path::{Path, PathBuf};

use rucc_tuple::{Env, Os, TargetTuple};

/// One artifact: the sysroot for one target, as this release pins it.
///
/// Or the kernel header tree, which is [`KERNEL_HEADERS`] and the one artifact that is not any
/// target's.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Pinned {
    /// The target it is the sysroot for, in the spelling that names its directory under the cache,
    /// or `kernel-headers` for the tree every Linux target shares, which is that tree's directory.
    pub tuple: &'static str,
    /// Where to get it. Handed to a downloader as it stands, and nothing here builds it out of
    /// parts.
    pub url: &'static str,
    /// The sha256 of the archive, lowercase hex, which is what the bytes that arrive are held to.
    pub sha256: &'static str,
}

impl Pinned {
    /// The name to write the archive under, which is the last component of the URL.
    ///
    /// The URL's own name rather than one built out of the tuple, so that the file on disk is the
    /// file the server served and a person comparing the two is comparing names as well as bytes.
    #[must_use]
    pub fn file_name(&self) -> &'static str {
        self.url.rsplit('/').next().unwrap_or(self.url)
    }

    /// Where in the cache the archive is kept.
    ///
    /// Under the cache rather than in a temporary directory, because a machine with no downloader is
    /// told this exact path and a second `--fetch` carries on from the check, which is section 13.8's
    /// answer for a host that cannot reach the network at all. It is kept after the install for the
    /// same reason and for one more: a fetch of a target that is already installed then moves
    /// nothing and says so.
    ///
    /// The directory in front of the name is the first twelve characters of the hash, and it is
    /// there because the name alone does not say which artifact this is. Two releases of a sysroot
    /// for one target have the same file name, so a cache that kept the name alone would hold last
    /// release's archive under the name this release wants, and a fetch refuses a file that does not
    /// match rather than downloading over the top of it. That refusal is right for a file somebody
    /// placed by hand and wrong for one we put there ourselves, so the fix is to stop the collision
    /// rather than to soften the check. The hash is what has to change when the bytes change, so it
    /// is the thing that separates them.
    #[must_use]
    pub fn archive_in(&self, cache: &Path) -> PathBuf {
        cache.join("downloads").join(&self.sha256[..12]).join(self.file_name())
    }
}

/// Every artifact this release pins, in tuple order.
///
/// A row is three strings and the test below says what they have to be. The order is the tuple's
/// rather than the order they were published in, so that a row is found by reading down the column
/// and two releases of this file diff as what changed between them.
pub const PINNED: &[Pinned] = &[
    Pinned {
        tuple: "aarch64-linux-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-24b/rucc-sysroot-aarch64-linux-gnu.tar.gz",
        sha256: "7a3e54260de1a07d00c7b6a1d8c4a3868367885d4aa96351b804a3a4c14e1a3c",
    },
    Pinned {
        tuple: "aarch64-linux-musl",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-23/rucc-sysroot-aarch64-linux-musl.tar.gz",
        sha256: "098c24c0c27d264dceaee76141f0933845dcc8a7c3a4b473954987f731fecde5",
    },
    Pinned {
        tuple: "aarch64-windows-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-21/rucc-sysroot-aarch64-windows-gnu.tar.gz",
        sha256: "cc6be4263b09a475895d9054bb4b096d837010b7e5ed25ebc8934accccd5258e",
    },
    Pinned {
        tuple: "armv7-linux-gnueabihf",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-24b/rucc-sysroot-armv7-linux-gnueabihf.tar.gz",
        sha256: "f96e369bdbe1013a2d8d162fce9fb83444835098c606f5e200f181db63ab011f",
    },
    Pinned {
        tuple: "armv7-linux-musleabihf",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-23/rucc-sysroot-armv7-linux-musleabihf.tar.gz",
        sha256: "645ceef60e0302b260ad804569243c3470f7545f1b135a143f9b7ec8408b6f78",
    },
    Pinned {
        tuple: "i686-linux-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-24b/rucc-sysroot-i686-linux-gnu.tar.gz",
        sha256: "6860bcb60e2079d7ba40f29d8ce6344da202affe0a0f9462d12652bff773d513",
    },
    Pinned {
        tuple: "i686-windows-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-21/rucc-sysroot-i686-windows-gnu.tar.gz",
        sha256: "296de7554f57d308c00b405c145eb314886e1e28ff8507aa6e7b34e7e4def7f1",
    },
    Pinned {
        tuple: "loongarch64-linux-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-24b/rucc-sysroot-loongarch64-linux-gnu.tar.gz",
        sha256: "67e0565d9acc6a768dd2ad6318fab716c34bcbfaeb005398e38d4ca8d7f5c3c2",
    },
    Pinned {
        tuple: "powerpc64le-linux-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-24b/rucc-sysroot-powerpc64le-linux-gnu.tar.gz",
        sha256: "c5262070d3de6f6a91d6df9ee0acf32088d7d03720ce2bb650cae1f865d2ba05",
    },
    Pinned {
        tuple: "riscv64-linux-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-24b/rucc-sysroot-riscv64-linux-gnu.tar.gz",
        sha256: "6157fb51fb66fac4fedfe5233d0a2857bcce346cd8f376c595db558e0470c42f",
    },
    Pinned {
        tuple: "riscv64-linux-musl",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-23/rucc-sysroot-riscv64-linux-musl.tar.gz",
        sha256: "00fc00f996d0a9a3de1cabd95840d423de1562ed5345dd5c47f1bf89b30f0b99",
    },
    Pinned {
        tuple: "s390x-linux-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-24b/rucc-sysroot-s390x-linux-gnu.tar.gz",
        sha256: "ac73fa903ef8816f2eebb35d106bcf6aabdc3e5c22e94646af196df8d5615b56",
    },
    Pinned {
        tuple: "x86_64-linux-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-24b/rucc-sysroot-x86_64-linux-gnu.tar.gz",
        sha256: "a951b219c641ee0b17e228adc8e43f36eaa70ee255d3c6f7717ec39c41e8b5b8",
    },
    Pinned {
        tuple: "x86_64-linux-musl",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-23/rucc-sysroot-x86_64-linux-musl.tar.gz",
        sha256: "93b42df66c0a7547c3e96cd5512267790df1ca0227a0000ba4f1808eb214c376",
    },
    Pinned {
        tuple: "x86_64-windows-gnu",
        url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-21/rucc-sysroot-x86_64-windows-gnu.tar.gz",
        sha256: "2f1e34ea0ad3e1ae8be08c054c61030e0a916053e194916f4045e08dcfd69545",
    },
];

/// The Linux uapi header tree, which every Linux target reads beside its own sysroot.
///
/// One archive rather than a part of each Linux sysroot, for the reason [`crate::Kernel`] gives
/// about the directory: the tree is the same for every Linux row except a small `asm/` per
/// architecture, so a copy in every sysroot would be the same eleven megabytes once per target.
/// `bin/kernel-headers` in `tamnd/rucc-cross` produces it and `bin/artifact kernel-headers` packs it,
/// and `--fetch` of a Linux target installs it after the sysroot when it is not there already.
pub const KERNEL_HEADERS: Pinned = Pinned {
    tuple: "kernel-headers",
    url: "https://github.com/tamnd/rucc-cross/releases/download/sysroots-2026-09-23/rucc-kernel-headers.tar.gz",
    sha256: "e96934f553df19d6bdbb6804f1b52d079adc4bea10a819d51eda5bc4ec584f2d",
};

/// The artifact this release pins for `tuple`, if it pins one.
///
/// The canonical spelling is what a row is named by, so the caller parses what the user wrote and
/// asks with the tuple's own text rather than with theirs.
#[must_use]
pub fn pinned_for(tuple: &str) -> Option<&'static Pinned> {
    look(PINNED, tuple)
}

/// The artifact this release pins for a target, which for a glibc tuple that names a release is the
/// one for the same tuple without it.
///
/// One glibc sysroot serves every release, because the headers in it pick the release with
/// `__GLIBC_MINOR__` and the libraries a link reads are the stubs the driver writes for the release
/// asked for. So `x86_64-linux-gnu.2.28` and `x86_64-linux-gnu` fetch the same archive, and it is
/// installed under the pinned spelling because that is the directory the compiler reads.
#[must_use]
pub fn pinned_for_target(target: TargetTuple) -> Option<&'static Pinned> {
    pinned_for(&target.to_canonical_string())
        .or_else(|| pinned_for(&glibc_base(target)?.to_canonical_string()))
}

/// The same glibc target with its release left off, or [`None`] for a target that is not glibc or
/// names no release.
///
/// What [`pinned_for_target`] looks a pinned release up under, and what the install accepts as the
/// target of an archive fetched for one.
#[must_use]
pub fn glibc_base(target: TargetTuple) -> Option<TargetTuple> {
    if target.os() != Os::Linux || target.env() != Env::Gnu {
        return None;
    }
    target.env_version()?;
    let mut base = TargetTuple::builder(target.arch(), target.os())
        .sub_arch(target.sub_arch())
        .endian(target.endian())
        .data_model(target.data_model())
        .env(target.env())
        .abi(target.abi());
    if let Some(version) = target.os_version() {
        base = base.os_version(version);
    }
    base.build().ok()
}

/// Every target this release pins an artifact for, for a message that has to say what there is.
#[must_use]
pub fn pinned_targets() -> Vec<&'static str> {
    PINNED.iter().map(|what| what.tuple).collect()
}

/// The same lookup over a table that is passed in, so what the lookup does is tested against rows
/// that are written for it rather than against whatever [`PINNED`] happens to hold this release.
fn look<'a>(table: &'a [Pinned], tuple: &str) -> Option<&'a Pinned> {
    table.iter().find(|what| what.tuple == tuple)
}

#[cfg(test)]
mod tests {
    use std::path::PathBuf;

    use super::*;

    #[test]
    fn a_pinned_glibc_release_shares_the_artifact_of_its_tuple() {
        let tuple = |spelling: &str| spelling.parse::<TargetTuple>().expect("a tuple");
        let base = glibc_base(tuple("x86_64-linux-gnu.2.28")).expect("glibc with a release");
        assert_eq!(base.to_canonical_string(), "x86_64-linux-gnu");
        let arm = glibc_base(tuple("armv7-linux-gnu.2.31eabihf")).expect("glibc with a release");
        assert_eq!(arm.to_canonical_string(), "armv7-linux-gnueabihf");
        // No release, or not glibc, is nothing to fall back to.
        assert_eq!(glibc_base(tuple("x86_64-linux-gnu")), None);
        assert_eq!(glibc_base(tuple("x86_64-linux-musl")), None);
        // And a musl row is still found under its own name.
        assert_eq!(
            pinned_for_target(tuple("x86_64-linux-musl")).map(|what| what.tuple),
            Some("x86_64-linux-musl")
        );
    }

    /// A table with rows in it, which is what [`PINNED`] will look like.
    const TABLE: &[Pinned] = &[
        Pinned {
            tuple: "aarch64-linux-musl",
            url: "https://example.invalid/rucc-sysroot-aarch64-linux-musl.tar.gz",
            sha256: "1111111111111111111111111111111111111111111111111111111111111111",
        },
        Pinned {
            tuple: "x86_64-linux-musl",
            url: "https://example.invalid/rucc-sysroot-x86_64-linux-musl.tar.gz",
            sha256: "2222222222222222222222222222222222222222222222222222222222222222",
        },
    ];

    #[test]
    fn a_target_the_table_names_is_found_and_one_it_does_not_is_not() {
        let found = look(TABLE, "x86_64-linux-musl").expect("the table has that one");
        assert_eq!(found.sha256, TABLE[1].sha256);
        assert_eq!(look(TABLE, "riscv64-linux-gnu"), None);
    }

    /// A tuple that starts with one the table has is a different target and not a match.
    #[test]
    fn a_longer_tuple_is_not_the_row_it_begins_with() {
        assert_eq!(look(TABLE, "x86_64-linux-musl.1.2.5"), None);
        assert_eq!(look(TABLE, "x86_64-linux"), None);
    }

    #[test]
    fn the_archive_is_named_by_the_url_and_kept_under_the_cache() {
        let what = TABLE[0];
        assert_eq!(what.file_name(), "rucc-sysroot-aarch64-linux-musl.tar.gz");
        assert_eq!(
            what.archive_in(&PathBuf::from("/tmp/cache")),
            PathBuf::from(
                "/tmp/cache/downloads/111111111111/rucc-sysroot-aarch64-linux-musl.tar.gz"
            )
        );
    }

    /// Two releases of the sysroot for one target have the same file name, and the cache has to keep
    /// them apart, because a fetch refuses a file under the artifact's name that is not the artifact.
    #[test]
    fn two_releases_of_one_target_are_not_the_same_path() {
        let cache = PathBuf::from("/tmp/cache");
        let old = TABLE[0];
        let new = Pinned { sha256: TABLE[1].sha256, ..old };
        assert_eq!(old.file_name(), new.file_name());
        assert_ne!(old.archive_in(&cache), new.archive_in(&cache));
    }

    /// What every row of [`PINNED`] has to be.
    ///
    /// Left as a test rather than as a comment above the table, because the day somebody adds a row
    /// is the day the rules stop being obvious, and a pasted hash with a capital letter in it or a
    /// tuple spelled the way the URL spells it would otherwise be found by a user.
    #[test]
    fn every_row_is_a_target_a_url_and_a_hash() {
        for what in PINNED {
            let tuple: TargetTuple =
                what.tuple.parse().unwrap_or_else(|why| panic!("{}: {why}", what.tuple));
            assert_eq!(
                tuple.to_canonical_string(),
                what.tuple,
                "a row is named by the canonical spelling, because that is what names the \
                 directory the tree is installed at"
            );
            assert!(what.url.starts_with("https://"), "{}: {}", what.tuple, what.url);
            // A query string or a fragment would make the file name something other than the last
            // component of the URL, which is the one thing the name is read out of.
            assert!(!what.url.contains('?') && !what.url.contains('#'), "{}", what.url);
            assert!(!what.file_name().is_empty(), "{} ends with a separator", what.url);
            assert_eq!(what.sha256.len(), 64, "{}: {}", what.tuple, what.sha256);
            assert!(
                what.sha256.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)),
                "{}: {} is not lowercase hex, and the check compares text",
                what.tuple,
                what.sha256
            );
        }
        let mut sorted: Vec<&str> = pinned_targets();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted, pinned_targets(), "the rows are in tuple order and each target once");
    }

    /// The kernel tree's row is held to the same rules as a target's, except that its name is the
    /// directory it is installed at rather than a tuple.
    #[test]
    fn the_kernel_tree_is_a_url_and_a_hash_and_no_target_is_called_that() {
        let what = KERNEL_HEADERS;
        assert!(what.url.starts_with("https://"), "{}", what.url);
        assert!(!what.url.contains('?') && !what.url.contains('#'), "{}", what.url);
        assert_eq!(what.file_name(), "rucc-kernel-headers.tar.gz");
        assert_eq!(what.sha256.len(), 64, "{}", what.sha256);
        assert!(
            what.sha256.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)),
            "{} is not lowercase hex",
            what.sha256
        );
        assert_eq!(pinned_for(what.tuple), None);
    }
}