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
//!
//! Seven rows, which are the three windows-gnu targets and four musl 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.
//!
//! 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};

/// 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-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-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-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: "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: "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)
}

/// 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 rucc_tuple::TargetTuple;

    use super::*;

    /// 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);
    }
}