rucc_sysroot/

link.rs

//! The start files, the libraries and the loader for one target's link.
//!
//! Design: `spec/cross-compile/08-sysroots.md` section 8.2 and `spec/cross-compile/11-linking.md`.
//!
//! What is here is what has to be linked, in what order, and which loader will start the result.
//! How that is spelled for a particular linker is [`crate::argv`], which is the division
//! `spec/cross-compile/11-linking.md` draws: the files are a fact about the target and the flags are
//! a fact about the linker.
//!
//! # Why musl is first
//!
//! `spec/cross-compile/09-libc-stubs.md` section 9.3 is the argument. musl exercises the header
//! tree, the search paths, the start files, the compiler runtime and the link line, and it does
//! that without symbol versioning and without stub generation, which are the two hardest pieces of
//! the glibc path. If a musl cross link works end to end then the pipeline is right and what is
//! left for M9.5 is the glibc specific parts rather than the shape of the thing.
//!
//! # Why the line has three parts and not one
//!
//! `crtn.o` goes after the libraries and `crti.o` goes before them, because between them they open
//! and close the `.init` and `.fini` sections and anything contributing to those has to land in the
//! middle. A link line that is one list gets this wrong in a way that produces a binary which links,
//! runs, and does not run its static constructors, so the three parts are three fields here rather
//! than a comment on an ordering somebody has to preserve.

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

use rucc_tuple::{Abi, Arch, DataModel, Endian, Env, ObjectFormat, Os, TargetTuple, Version};

use crate::layout::Sysroot;

/// How the program is linked, which decides the first start file and the flags.
///
/// The glibc release that moved the `stat` family out of `libc_nonshared.a` and into `libc.so.6`.
const STAT_IN_LIBC: Version = Version::new(2, 33);

/// Five cases rather than two booleans for static and position independent, because the two are not
/// independent and the start file is a different file in four of the five. A pair of flags would
/// admit a sixth combination, a shared object that is not position independent, which is not a thing
/// any of these linkers will produce.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum LinkMode {
    /// Everything in the binary, no interpreter, no relocation at load. The default for musl, and
    /// the mode `spec/cross-compile/02-the-goal.md`'s exit criterion names.
    #[default]
    Static,
    /// Static, and position independent, so the loader may place it anywhere. A different first
    /// start file, because the program has to relocate itself before `main` and `rcrt1.o` is what
    /// does that.
    StaticPie,
    /// Against the shared libc, position independent, with the libc's loader named in the program
    /// header. What every distribution builds today and what `-pie` asks for.
    Dynamic,
    /// Against the shared libc, at a fixed address, which is `-no-pie`.
    ///
    /// The same link as [`LinkMode::Dynamic`] with a different start file, because the reference to
    /// `main` in `crt1.o` is an absolute one and the reference in `Scrt1.o` is not. Build systems
    /// that pass `-no-pie` are usually doing it because something in them takes the address of a
    /// function and compares it, and they get the file that matches.
    DynamicNoPie,
    /// A shared object rather than a program, which is `-shared`.
    ///
    /// No start file at all, since nothing starts a shared object and it has no `main` to be
    /// started at, and no loader named either: the program that loads this one carries that.
    Shared,
}

impl LinkMode {
    /// Whether the result is linked against a shared libc, which decides whether a loader is named.
    #[must_use]
    pub const fn is_dynamic(self) -> bool {
        matches!(self, LinkMode::Dynamic | LinkMode::DynamicNoPie | LinkMode::Shared)
    }

    /// Whether the result may be placed anywhere in memory.
    #[must_use]
    pub const fn is_pie(self) -> bool {
        matches!(self, LinkMode::StaticPie | LinkMode::Dynamic | LinkMode::Shared)
    }
}

/// What a produced sysroot holds for a target's C library.
///
/// Four cases, from `spec/cross-compile/08-sysroots.md` section 8.2's table, and the line differs
/// between them in what goes on it rather than in how it is spelled. The table has seven rows and two
/// of those are legal walls rather than technical ones, so what is left is these four.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Libc {
    /// Nothing, which is the freestanding row: the nine compiler headers and no link inputs at all.
    /// Our runtime is still there, because an architecture without a division instruction needs it
    /// whether there is a libc or not.
    None,
    /// A real static archive, which today means musl built from source. The only row where the code
    /// behind the names is present, so the only row a static link can use.
    Archive,
    /// A generated stub shared object: the names the platform's libc exports and none of the code.
    /// glibc is the row this was written for, and bionic, the BSDs and illumos take the same shape
    /// for the same reason, which is that their libc is a shared object on the target machine and a
    /// list of names is enough to link against one.
    Stub,
    /// A set of import libraries, which is what the same idea is called in COFF.
    ///
    /// Windows is the row this is, and it is a separate case from [`Libc::Stub`] rather than a
    /// spelling of it, for two reasons that both show up on the line. The container is different: a
    /// Windows program links against an archive of tiny objects per DLL rather than against one
    /// shared object, which is `spec/cross-compile/09-libc-stubs.md` section 9.4 and what
    /// `rucc_stub::coff` writes. And the C library is not one file: the msvcrt import library,
    /// mingw-w64's own `libmingwex.a` and `libmoldname.a`, and the Win32 libraries a CRT calls into
    /// are all on the line, where a glibc line has one `libc.so` on it.
    ///
    /// A static link against this is not refused, which is the other difference. On Windows the C
    /// library is a DLL on every machine and always has been, so `-static` there is a statement
    /// about our libraries and mingw-w64's rather than about the CRT, and a program linked that way
    /// runs. That is why the refusal in [`crate::argv::argv`] is about [`Libc::Stub`] by name.
    Import,
}

/// Which of the four cases this target is.
///
/// Asked in two places, which is why it is a function rather than a `match` in each: [`LinkLine`]
/// uses it to pick the files and [`crate::argv::argv`] uses it to refuse a static link against a
/// stub. Two copies of this rule would be two rules.
///
/// The format is asked before the environment, because what holds a libc's names is a property of
/// the object format and `Env::Gnu` means mingw-w64 on a Windows target and glibc on a Linux one.
#[must_use]
pub fn libc(target: TargetTuple) -> Libc {
    match (target.os(), target.env()) {
        (Os::None, _) => Libc::None,
        _ if target.object_format() == ObjectFormat::Coff => Libc::Import,
        // wasi-libc is musl with the system interface replaced by WASI calls, and it is a real
        // static archive in the same way. There is no shared form of it to stub.
        (Os::Wasi, _) => Libc::Archive,
        (_, Env::Musl) => Libc::Archive,
        _ => Libc::Stub,
    }
}

/// Which of Microsoft's two C runtimes a program in the MSVC environment is linked against.
///
/// `cl.exe` spells the choice `/MT` and `/MD`, and here it is `-fms-runtime-lib=static` and
/// `-fms-runtime-lib=dll`, which is clang's spelling. Two sets of libraries and two macros: the
/// headers read `_MT` for both and `_DLL` only for the second, and that is how a header knows its
/// functions are imported from a DLL rather than linked into the program.
///
/// The static one is the default, which is the opposite of `cl.exe`, and the reason is the machine
/// the program is copied to. The universal CRT is part of Windows 10 and later, but the Visual C++
/// runtime is not: `vcruntime140.dll` arrives with the redistributable, and a program linked `/MD`
/// on a machine that never installed it does not start. A program linked `/MT` carries both and
/// starts anywhere, which is what the mingw-w64 rows give without being asked.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Crt {
    /// `/MT`: `libcmt.lib`, `libucrt.lib` and `libvcruntime.lib`, all three linked into the
    /// program.
    #[default]
    Static,
    /// `/MD`: `msvcrt.lib`, `ucrt.lib` and `vcruntime.lib`, which are import libraries for
    /// `ucrtbase.dll` and `vcruntime140.dll` with the startup code in the first of them.
    Dll,
}

/// Our own runtime library, which every one of the three lines below carries.
///
/// Named once because three callers ask about it by name: the line that puts it on,
/// [`crate::argv::argv`] when `-fno-builtins-lib` asks for it to be left off, and the driver that
/// goes looking for the file. A second spelling of the name anywhere is a flag that stops working
/// the day the first one is renamed.
///
/// Where the file is, is not this crate's answer and used to be. Every line below named it inside
/// the sysroot, as `sysroot.lib().join(BUILTINS)`, and nothing ever put it there: it is this
/// compiler's own output for the target rather than anything the platform ships, `cargo xtask
/// builtins` writes it beside the compiler, and a sysroot fetched from a release will never hold
/// it. So the lines take the path from whoever built them, which is the driver, and this constant
/// is the name alone. tamnd/rucc#1514.
pub const BUILTINS: &str = "librucc_builtins.a";

/// Our runtime as a list, which is what every line below puts at the end of its libraries.
///
/// One function rather than the same `into_iter` at four call sites, and it takes the whole answer
/// rather than a path so that a line reads the same whether the file was found or not.
fn ours(builtins: Option<&Path>) -> Vec<PathBuf> {
    builtins.map(Path::to_path_buf).into_iter().collect()
}

/// The inputs to a link, in the three groups a linker needs them in.
///
/// Paths rather than strings, and no flags at all, because
/// `spec/cross-compile/11-linking.md` owns which linker is invoked and how its arguments are
/// spelled and [`crate::argv`] is where that happens. What is here is what has to be linked and in
/// what order, which is a target fact and the same fact whichever linker reads it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LinkLine {
    /// The start files, before the user's objects.
    pub start: Vec<PathBuf>,
    /// The libraries, after the user's objects.
    pub libraries: Vec<PathBuf>,
    /// The end files, after the libraries.
    pub end: Vec<PathBuf>,
}

impl LinkLine {
    /// The line for a link against this sysroot, whichever libc the target names.
    ///
    /// The dispatch rather than the line, and it is [`libc`] that decides: a real archive, a stub
    /// shared object, or nothing. The three methods below are the three answers. A target whose
    /// sysroot we do not produce yet still gets the right shape, because the shape follows from
    /// whether the libc on the target machine is an archive or a shared object and that is known
    /// before any of it is built.
    ///
    /// The runtime is a path from the caller rather than a name joined onto the sysroot, and
    /// [`None`] means it is not on this machine and the line goes without it. Whether that is worth
    /// refusing over is the driver's question, since the driver is what knows whether it looked.
    #[must_use]
    pub fn for_target(sysroot: &Sysroot, mode: LinkMode, builtins: Option<&Path>) -> Self {
        match libc(sysroot.target()) {
            Libc::None => LinkLine::freestanding(builtins),
            Libc::Archive if sysroot.target().os() == Os::Wasi => {
                LinkLine::wasi(sysroot, false, builtins)
            }
            Libc::Archive => LinkLine::musl(sysroot, mode, builtins),
            Libc::Stub => LinkLine::glibc(sysroot, mode, builtins),
            Libc::Import if sysroot.target().env() == Env::Msvc => {
                LinkLine::msvc(Crt::Static, builtins)
            }
            Libc::Import => LinkLine::mingw(sysroot, mode, builtins),
        }
    }

    /// The line for a freestanding link against this sysroot, which is our runtime and nothing else.
    ///
    /// Section 8.2's first row: nine compiler headers and no link inputs. There is no `crt1.o`,
    /// because nothing here decides what runs before `main` or whether there is a `main` at all, and
    /// no `crti.o` or `crtn.o`, because those come from a libc too. A kernel or a bootloader brings
    /// its own start file and says so with `-nostartfiles`, which it would have to pass anyway.
    ///
    /// `librucc_builtins.a` stays, because it is ours rather than the platform's.
    /// `spec/cross-compile/10-runtime.md` is the argument: an architecture with no division
    /// instruction needs `__divti3` whether there is a libc in the picture or not, and freestanding
    /// code that does 64-bit arithmetic on a 32-bit target reaches it without asking.
    ///
    /// The mode is not a parameter because it changes nothing here. Every difference between the
    /// modes is a start file and there are none. Neither is the sysroot, now that the one file on
    /// this line is not in it: a freestanding link reads headers out of a sysroot and links nothing
    /// out of one.
    #[must_use]
    pub fn freestanding(builtins: Option<&Path>) -> Self {
        LinkLine { start: Vec::new(), libraries: ours(builtins), end: Vec::new() }
    }

    /// The line for a musl link against this sysroot.
    ///
    /// `crt1.o` runs before `main` and calls it. `crti.o` and `crtn.o` are the prologue and the
    /// epilogue of the `.init` and `.fini` sections, which is why one is at the front and the other
    /// is at the very back. `libc.a` carries musl's whole C library, and `librucc_builtins.a`
    /// carries the operations the architecture does not have an instruction for, which
    /// `spec/cross-compile/10-runtime.md` says has to be ours rather than the platform's.
    ///
    /// The builtins go after `libc.a` because musl calls some of them, and an archive that is
    /// searched before the thing that needs it contributes nothing.
    ///
    /// `libc.a` on every mode including the dynamic ones, because what a musl sysroot here holds is
    /// musl built static: section 9.3 takes musl first precisely because one tarball built one way
    /// exercises the whole pipeline, and a shared musl is a second build of it that buys nothing
    /// until somebody asks for a dynamically linked musl program.
    #[must_use]
    pub fn musl(sysroot: &Sysroot, mode: LinkMode, builtins: Option<&Path>) -> Self {
        let lib = sysroot.lib();
        let mut libraries = vec![lib.join("libc.a")];
        libraries.extend(ours(builtins));
        LinkLine { start: start_files(&lib, mode), libraries, end: vec![lib.join("crtn.o")] }
    }

    /// The line for a WASI link against this sysroot, which is a command unless `reactor` says
    /// that it is a reactor.
    ///
    /// One start file and no end file. A wasm module has no `.init` section for `crti.o` and
    /// `crtn.o` to open and close: the linker writes `__wasm_call_ctors` from the init functions of
    /// the objects, and the start file calls it. `crt1-command.o` has `_start`, which runs the
    /// constructors, then `main` through `__main_void`, then the destructors, and then exits with
    /// the status. `crt1-reactor.o` has `_initialize`, which runs the constructors and nothing
    /// more, for a module whose host calls its exports after that. The mode does not change the
    /// line, because a wasm module is one kind of image: there is no loader, no interpreter and no
    /// address to place it at.
    ///
    /// `libc.a` is wasi-libc whole, `libm` included, as on musl. Our runtime goes after it for the
    /// same reason as on musl, which is that wasi-libc calls `__multf3` and its friends for `long
    /// double`. tamnd/rucc#2864.
    ///
    /// `libsetjmp.a` comes before `libc.a`. It has `__wasm_setjmp`, `__wasm_setjmp_test`,
    /// `__wasm_longjmp` and the tag `__c_longjmp`, which the code that rucc writes for a call of
    /// `setjmp` or `longjmp` refers to. wasm-ld takes a member of an archive only for a symbol that
    /// is undefined, so a program with no `setjmp` gets nothing from it, and it is always on the
    /// line. clang puts it there only for `-lsetjmp`. tamnd/rucc#2865.
    #[must_use]
    pub fn wasi(sysroot: &Sysroot, reactor: bool, builtins: Option<&Path>) -> Self {
        let lib = sysroot.lib();
        let start = if reactor { "crt1-reactor.o" } else { "crt1-command.o" };
        let mut libraries = vec![lib.join("libsetjmp.a"), lib.join("libc.a")];
        libraries.extend(ours(builtins));
        LinkLine { start: vec![lib.join(start)], libraries, end: Vec::new() }
    }

    /// The line for a link against a generated stub, which is glibc and every other hosted libc that
    /// is not musl.
    ///
    /// Named for glibc because glibc is the case `spec/cross-compile/09-libc-stubs.md` is written
    /// about and the hard one. bionic, the BSDs and illumos reach the same line for the same reason:
    /// their libc is a shared object on the target machine, so a list of the names it exports is
    /// enough to link against it, and that is what `rucc-stub` produces. The paragraphs below about
    /// `libc_nonshared.a` and `libm` are glibc's own.
    ///
    /// The same start files as musl's and different libraries. A stub libc is linked against
    /// dynamically, so what goes on the line is the `libc.so` `rucc-stub` wrote into
    /// [`Sysroot::stubs`] rather than an archive, and the version nodes in it are what make a
    /// program built here run on an older machine. The driver writes it before the link, cut at
    /// the release the tuple names, and the directory is on the line as a `-L` too so that `-lm`
    /// and `-lpthread` find their stubs there.
    ///
    /// `libc_nonshared.a` comes next and out of the sysroot. glibc's own `libc.so` is a linker
    /// script naming `libc.so.6`, `libc_nonshared.a` and the loader as a group, and that archive
    /// holds real compiled objects: `atexit`, `__stack_chk_fail_local` on i386, and the `stat`
    /// family on releases before 2.33. None of it can be written from a description, because a
    /// stub is a list of names and these are bodies, so it is built from glibc's sources and
    /// fetched with the start files. It goes after the stub because what is in it calls into
    /// libc, which is the order glibc's script gives them. It is glibc's alone, so bionic and the
    /// BSDs get the stub and nothing between it and our runtime.
    ///
    /// The archive in the sysroot is 2.44's, and 2.44's has no `stat` in it, because 2.33 moved the
    /// family into `libc.so.6`. A target pinned before 2.33 gets `libc_nonshared_stat.a` after it,
    /// which rucc-cross builds the way 2.32 built those ten functions, each a call to `__xstat` or
    /// one of its siblings. Without it a program that calls `stat` links at -O2, where the old
    /// headers inline the call, and not at -O0. A target with no pin is the newest release and
    /// does not get it.
    ///
    /// The loader comes last, as in glibc's script. `ld.so` in the stubs is a script with the
    /// loader's stub inside `AS_NEEDED`, so a program gets the loader in `DT_NEEDED` only when it
    /// uses one of its names. On AArch64, Arm, RISC-V and LoongArch the stack protector reads
    /// `__stack_chk_guard`, and the loader exports it there.
    ///
    /// `libm.so` is not on the line, and that is a decision. glibc's `libm` is real code and a
    /// program that wants it passes `-lm`, which every build system that does arithmetic already
    /// does, so putting it on every line would record a dependency the program does not have.
    ///
    /// A static glibc link is not one of these: there is no `libc.a` in a sysroot whose libc is a
    /// stub, because a stub is a list of names and a static link needs bodies.
    /// [`crate::argv::argv`] refuses that combination by name rather than producing this line with
    /// `-static` in front of it.
    #[must_use]
    pub fn glibc(sysroot: &Sysroot, mode: LinkMode, builtins: Option<&Path>) -> Self {
        let lib = sysroot.lib();
        let mut libraries = vec![sysroot.stubs().join("libc.so")];
        if sysroot.target().env() == Env::Gnu {
            libraries.push(lib.join("libc_nonshared.a"));
            let version = sysroot.target().env_version();
            if version.is_some_and(|version| !version.at_least(STAT_IN_LIBC)) {
                libraries.push(lib.join("libc_nonshared_stat.a"));
            }
            libraries.push(sysroot.stubs().join("ld.so"));
        }
        libraries.extend(ours(builtins));
        LinkLine { start: start_files(&lib, mode), libraries, end: vec![lib.join("crtn.o")] }
    }

    /// The line for a mingw-w64 link against this sysroot.
    ///
    /// One start file and no end file, which is the first thing that is different from every ELF
    /// line above. `crt2.o` runs before `main` and calls it, `dllcrt2.o` is its counterpart for a
    /// DLL, and there is no `crti.o` and no `crtn.o` because PE has no `.init` and `.fini` sections
    /// for a pair of files to open and close. What those two bracket on ELF is done on Windows by a
    /// table of pointers in the `.CRT$XC` sections, which the linker sorts by section name, so the
    /// ordering problem the three groups exist for does not arise here.
    ///
    /// `crtbegin.o` and `crtend.o` are deliberately absent. They are GCC's files rather than
    /// mingw-w64's, they bracket GCC's own list of constructors, and a toolchain that is not GCC
    /// writes that list the way the platform writes it instead. Ours is not written yet: a mingw
    /// link runs `main` and does not run a file scope constructor, which is a known gap that belongs
    /// with the sysroot build rather than with the line, and the gap is in the codegen for the
    /// format rather than here.
    ///
    /// The libraries are a set rather than one file, because the C library on Windows is several
    /// DLLs and the CRT calls into the system ones. `libmingw32.a` holds the start code `crt2.o`
    /// calls, `libmoldname.a` is the layer that gives the old unprefixed spellings of the names
    /// Microsoft deprecated, `libmingwex.a` is everything C requires that the CRT does not have, and
    /// `libmsvcrt.a` is the import library for the CRT itself. Then the four Win32 libraries that
    /// mingw-w64's own code calls into, which are on the line for the same reason they are on gcc's:
    /// a program that uses none of them directly still reaches `kernel32` through `malloc`.
    ///
    /// `libmsvcrt.a` is the right name for either CRT, which is why nothing here asks the sysroot
    /// which one it has. mingw-w64 installs it as a copy of the default runtime's import library, so
    /// in the UCRT sysroot this compiler fetches it is `libucrt.a` and names the `api-ms-win-crt-*`
    /// API sets, and in a `-msvcrt` sysroot it names `msvcrt.dll`. gcc's spec says `-lmsvcrt` on a
    /// UCRT toolchain for the same reason, so the line follows the sysroot without being told.
    ///
    /// `-pthread` adds `-lpthread` after the objects, as on every other target, and the sysroot's
    /// `libpthread.a` is winpthreads, built static so the program needs no `libwinpthread-1.dll`.
    /// It is not on this line otherwise. A gcc built with the posix thread model lists it for every
    /// program, and a program that asked for no threads has nothing to take from it.
    ///
    /// The order is the one a single pass linker needs, which is GNU ld's PE port: a library after
    /// everything that calls into it. `librucc_builtins.a` is last for the reason it is last on the
    /// musl line, which is that the things before it call it and it calls none of them. lld's COFF
    /// linker resolves archives to a fixed point and does not care about any of this, and writing
    /// the line for the stricter of the two is what makes one line serve both.
    #[must_use]
    pub fn mingw(sysroot: &Sysroot, mode: LinkMode, builtins: Option<&Path>) -> Self {
        let lib = sysroot.lib();
        let start = match mode {
            LinkMode::Shared => "dllcrt2.o",
            _ => "crt2.o",
        };
        let theirs = [
            "libmingw32.a",
            "libmoldname.a",
            "libmingwex.a",
            "libmsvcrt.a",
            "libadvapi32.a",
            "libshell32.a",
            "libuser32.a",
            "libkernel32.a",
        ];
        let mut libraries: Vec<PathBuf> = theirs.iter().map(|name| lib.join(name)).collect();
        libraries.extend(ours(builtins));
        LinkLine { start: vec![lib.join(start)], libraries, end: Vec::new() }
    }

    /// The line for a program in Microsoft's environment, linked against the CRT `crt` names.
    ///
    /// No start file, because the one Microsoft ships is not a file of its own. `mainCRTStartup` is
    /// a member of `libcmt.lib`, or of `msvcrt.lib` for the other runtime, and the linker picks it
    /// as the entry point because the program defines `main`, so the start of the program is left
    /// to the CRT the way `cl.exe` leaves it. The mode is not a parameter for the same reason: a
    /// DLL is started by `_DllMainCRTStartup`, which is in the same libraries.
    ///
    /// Names rather than paths, which is where this differs from every other line here. The tree
    /// keeps the CRT in `crt/lib` and the SDK's libraries in two directories of `sdk/lib`, and
    /// [`crate::argv`] names those directories to the linker, which is how `lld-link` and
    /// `link.exe` both look for a library and how a `-L` of the user's own gets in front of ours.
    ///
    /// `kernel32.lib` because the CRT calls into it and says so only in a directive, and
    /// `oldnames.lib` because it is what makes `open` and `strdup` mean `_open` and `_strdup`,
    /// which a C program written for anything but Windows calls by the old names. Ours goes last,
    /// the same as on the mingw-w64 line, so that the CRT answers for everything it has.
    #[must_use]
    pub fn msvc(crt: Crt, builtins: Option<&Path>) -> Self {
        let theirs = match crt {
            Crt::Static => ["libcmt.lib", "libucrt.lib", "libvcruntime.lib"],
            Crt::Dll => ["msvcrt.lib", "ucrt.lib", "vcruntime.lib"],
        };
        let mut libraries: Vec<PathBuf> = theirs.iter().map(PathBuf::from).collect();
        libraries.push(PathBuf::from("kernel32.lib"));
        libraries.push(PathBuf::from("oldnames.lib"));
        libraries.extend(ours(builtins));
        LinkLine { start: Vec::new(), libraries, end: Vec::new() }
    }

    /// Every input, in the order they reach the linker, with the caller's objects in the middle.
    ///
    /// The one function that knows the whole order, so that a caller cannot assemble the three
    /// groups in the wrong sequence.
    #[must_use]
    pub fn with_objects(&self, objects: &[PathBuf]) -> Vec<PathBuf> {
        let mut all = self.start.clone();
        all.extend_from_slice(objects);
        all.extend(self.libraries.iter().cloned());
        all.extend(self.end.iter().cloned());
        all
    }
}

/// The start files for one mode, in the order they go on the line.
///
/// Two files, and which the first one is says how the reference to `main` inside it is written.
/// `crt1.o` refers to it absolutely, `Scrt1.o` through the global offset table so that a loader may
/// place the program anywhere, and `rcrt1.o` does that and relocates the program itself before
/// `main` runs, which is what a static position independent executable needs because there is no
/// loader to do it. A shared object has none of them.
///
/// `crti.o` is always second and `crtn.o` is always last, which is [`LinkLine`]'s three groups
/// rather than anything here.
fn start_files(lib: &Path, mode: LinkMode) -> Vec<PathBuf> {
    let first = match mode {
        LinkMode::Static | LinkMode::DynamicNoPie => Some("crt1.o"),
        LinkMode::StaticPie => Some("rcrt1.o"),
        LinkMode::Dynamic => Some("Scrt1.o"),
        LinkMode::Shared => None,
    };
    first.map(|name| lib.join(name)).into_iter().chain([lib.join("crti.o")]).collect()
}

/// The absolute path the target's loader is installed at, or [`None`] for a target that has none.
///
/// The libc picks the table and the architecture picks the row. [`None`] is the right answer for
/// three different reasons: a freestanding target has no libc, WASI has no loader of this kind at
/// all, and Darwin and Windows have one whose path is not written on the link line.
#[must_use]
pub fn loader(target: TargetTuple) -> Option<&'static str> {
    match (target.os(), target.env()) {
        (Os::Linux, Env::Musl) => Some(musl_loader(target)),
        (Os::Linux, Env::Gnu) => Some(glibc_loader(target)),
        // Bionic's is one path per word size and not one per architecture, because Android fixes
        // the filesystem layout rather than leaving it to the port.
        (Os::Linux, Env::Android) => Some(match target.pointer_width() {
            64 => "/system/bin/linker64",
            _ => "/system/bin/linker",
        }),
        _ => None,
    }
}

/// The absolute path musl's loader is installed at on the target.
///
/// It goes in the program header of a dynamically linked binary, so it is a string about the target
/// machine's filesystem and not about ours, and it has to be right without anything to check it
/// against at link time. A wrong one produces a binary that the kernel refuses to start with a
/// message about a missing file that is on nobody's disk.
///
/// 32-bit ARM is the row with two answers, because musl names the hard float and soft float builds
/// differently and they are not interchangeable. PowerPC is the other row with two, and there the
/// endianness picks, because musl treats the two byte orders as separate ports.
#[must_use]
pub fn musl_loader(target: TargetTuple) -> &'static str {
    match target.arch() {
        Arch::X86_64 => match target.data_model() {
            DataModel::Ilp32On64 => "/lib/ld-musl-x32.so.1",
            _ => "/lib/ld-musl-x86_64.so.1",
        },
        Arch::X86 => "/lib/ld-musl-i386.so.1",
        Arch::Aarch64 | Arch::Arm64Ec => "/lib/ld-musl-aarch64.so.1",
        Arch::Arm => match target.resolved_abi() {
            Abi::DoubleFloat => "/lib/ld-musl-armhf.so.1",
            _ => "/lib/ld-musl-arm.so.1",
        },
        Arch::Riscv64 => "/lib/ld-musl-riscv64.so.1",
        Arch::Riscv32 => "/lib/ld-musl-riscv32.so.1",
        Arch::S390x => "/lib/ld-musl-s390x.so.1",
        Arch::PowerPc64 => match target.endian() {
            Endian::Little => "/lib/ld-musl-powerpc64le.so.1",
            Endian::Big => "/lib/ld-musl-powerpc64.so.1",
        },
        Arch::LoongArch64 => "/lib/ld-musl-loongarch64.so.1",
        // musl has no wasm port and wasm has no loader. The caller that gets here asked for a
        // dynamic musl link on a target with neither, which is a driver bug rather than a user
        // one, and a path that cannot exist is a better report than a plausible wrong one.
        Arch::Wasm32 => "/lib/ld-musl-none.so.1",
    }
}

/// The absolute path glibc's loader is installed at on the target.
///
/// A different table from musl's and not a different spelling of it. musl names every loader after
/// the architecture in one directory; glibc's names come from each port's history, so three of them
/// are called `ld64.so` with a number that means something different per architecture, two are in
/// `/lib64` rather than `/lib`, and i386's carries no architecture in its name at all because it was
/// the only one when it was named.
///
/// The rows with more than one answer are the ones where the loader and the program have to agree
/// about register usage. 32-bit ARM has the hard float and soft float split, RISC-V and LoongArch
/// spell the float ABI and the data model into the name, and AArch64 has a byte order in it.
/// Getting one wrong produces a binary the kernel will not start, with a message about a missing
/// file, and it is a string nothing at link time can check.
#[must_use]
pub fn glibc_loader(target: TargetTuple) -> &'static str {
    let narrow = target.data_model() == DataModel::Ilp32On64;
    let hard = matches!(target.resolved_abi(), Abi::DoubleFloat);
    match target.arch() {
        Arch::X86_64 if narrow => "/libx32/ld-linux-x32.so.2",
        Arch::X86_64 => "/lib64/ld-linux-x86-64.so.2",
        Arch::X86 => "/lib/ld-linux.so.2",
        Arch::Aarch64 | Arch::Arm64Ec => match (target.endian(), narrow) {
            (Endian::Little, false) => "/lib/ld-linux-aarch64.so.1",
            (Endian::Little, true) => "/lib/ld-linux-aarch64_ilp32.so.1",
            (Endian::Big, false) => "/lib/ld-linux-aarch64_be.so.1",
            (Endian::Big, true) => "/lib/ld-linux-aarch64_be_ilp32.so.1",
        },
        // The one row where the number differs rather than the name. ARM's loader went to 3 when
        // EABI replaced OABI, and the hard float build is a separate file because passing a double
        // in a float register is not compatible with passing it in a pair of integer ones.
        Arch::Arm if hard => "/lib/ld-linux-armhf.so.3",
        Arch::Arm => "/lib/ld-linux.so.3",
        Arch::Riscv64 if hard => "/lib/ld-linux-riscv64-lp64d.so.1",
        Arch::Riscv64 => "/lib/ld-linux-riscv64-lp64.so.1",
        Arch::Riscv32 if hard => "/lib/ld-linux-riscv32-ilp32d.so.1",
        Arch::Riscv32 => "/lib/ld-linux-riscv32-ilp32.so.1",
        // `ld64` here means 64-bit z/Architecture and the 1 is glibc's ABI version for the port,
        // which is not the 2 on PowerPC's file of the same name. It is in `/lib` and PowerPC's is in
        // `/lib64`, so the two rows have nothing in common but the stem.
        Arch::S390x => "/lib/ld64.so.1",
        // ELFv2, both byte orders, which is the only PowerPC ABI
        // `spec/cross-compile/06-abis.md` admits. The ELFv1 big-endian world uses `ld64.so.1` and
        // is out of scope, so a wrong answer here is impossible rather than merely unlikely.
        Arch::PowerPc64 => "/lib64/ld64.so.2",
        Arch::LoongArch64 if hard => "/lib64/ld-linux-loongarch-lp64d.so.1",
        Arch::LoongArch64 => "/lib64/ld-linux-loongarch-lp64s.so.1",
        // There is no glibc for wasm and no loader for it either. Same reasoning as the musl table
        // above: a path nothing will ever open beats a plausible one.
        Arch::Wasm32 => "/lib/ld-linux-wasm32.so.1",
    }
}