qld 0.1.1

//! The `qld` command-line linker.
//!
//! This binary is a thin wrapper: it selects a command-line flavor, parses
//! argv and calls [`qld::link`]. Everything it can do is available through
//! the library too, except `--fork`, which is about the process itself.
//!
//! # `--fork`
//!
//! On Unix, `qld` links in a child process by default (`--fork`, as mold
//! and wild do) so that it can return as soon as the output is complete.
//! A large link then spends a while freeing memory and unmapping its inputs
//! (150 ms for a 1.2 GiB output with debug information), and the build
//! does not have to wait for that. `--no-fork` links in the `qld` process
//! itself, as do `--help`, `--version`, and every library call.
//!
//! The child is this executable started again (no `fork()` without
//! `unsafe`), found in the environment variable `QLD_FORK_CHILD`, which
//! holds the parent's process ID so that a `qld` started further down (by
//! an LTO plugin's subprocess, say) does not take itself for the child. The
//! child parses the same argv, links with a
//! [`qld::args::OutputCompleteHook`] and, when the output is complete,
//! sends its exit status to the parent, which exits with it. See [`fork`]
//! for the channels and the failure modes.
//!
//! # Allocator tuning
//!
//! On glibc the binary widens two `malloc` thresholds at startup; see
//! [`tune_allocator`]. The library does not, because a library call runs
//! inside someone else's process.

use std::ffi::OsString;
use std::process::ExitCode;
use std::sync::Arc;

use qld::args::{OutputCompleteHook, ParseOutcome};
use qld::diag::{Diagnostic, DiagnosticSink, Stderr};

fn main() -> ExitCode {
    tune_allocator();
    let args: Vec<OsString> = std::env::args_os().collect();
    #[cfg(unix)]
    if let Some(child) = fork::Child::from_env() {
        let code = run(&args, Launch::Child(child));
        // A failed link, or a backend that finished without the hook
        // (cannot happen with `qld::link`, which runs it on success).
        child.notify(code);
        return ExitCode::from(code);
    }
    ExitCode::from(run(&args, Launch::MayFork))
}

/// Widens glibc's `malloc` thresholds for a linker's allocation profile.
///
/// A link allocates a few hundred megabytes in a burst and frees all of it
/// at exit. With the defaults, each thread's arena grows 128 KiB at a time
/// — every growth an `mprotect` that takes the address space's lock for
/// writing — and `free` hands memory straight back to the kernel, which
/// faults it in again on the next allocation. A clang link makes about
/// 12,000 `mprotect` calls and 80,000 page faults that way, and spends
/// three to four times as long in the kernel at 16 threads as at one.
///
/// `M_TOP_PAD` (64 MiB) is how much extra each `sbrk`/arena growth asks
/// for, and `M_TRIM_THRESHOLD` (128 MiB) how much free space at the top an
/// arena keeps before returning it. Both only raise the high-water mark of
/// memory a process that is about to exit holds; peak RSS is unchanged
/// because the pages are never touched. Measured on a clang link: 224 ms
/// down to 180 on a loaded machine, 151 to 148 on a quiet one.
///
/// This is the binary's own tuning. It is deliberately not in the library,
/// where `qld::link` runs inside a caller's process whose allocator
/// settings are the caller's to choose. It is also not
/// `glibc.malloc.hugetlb`, which is 7× slower when memory is tight and the
/// kernel has to compact.
///
/// Nothing depends on it succeeding: `mallopt` returning 0 (not a glibc, or
/// a parameter it does not know) only leaves the defaults in place.
#[cfg(all(unix, target_env = "gnu"))]
fn tune_allocator() {
    /// `M_TRIM_THRESHOLD` in glibc's `malloc.h`.
    const M_TRIM_THRESHOLD: i32 = -1;
    /// `M_TOP_PAD` in glibc's `malloc.h`.
    const M_TOP_PAD: i32 = -2;

    unsafe extern "C" {
        fn mallopt(param: i32, value: i32) -> i32;
    }

    // SAFETY: `int mallopt(int, int)` is glibc's, declared here with that
    // signature, and it is linked in already because this target's std
    // allocates through it. It takes no pointers and reads nothing of
    // ours: it stores two integers in glibc's own tuning state. Calling it
    // before any thread is started also keeps it away from the one case
    // glibc documents as undefined, a concurrent allocation. The result (0
    // if the parameter is not known) is ignored: the defaults then stay.
    unsafe {
        mallopt(M_TOP_PAD, 64 * 1024 * 1024);
        mallopt(M_TRIM_THRESHOLD, 128 * 1024 * 1024);
    }
}

/// Does nothing off glibc, where there is nothing to tune.
#[cfg(not(all(unix, target_env = "gnu")))]
fn tune_allocator() {}

/// How [`run`] links.
enum Launch {
    /// In a child process if `--fork` is in effect and supported, else here.
    MayFork,
    /// Here, as the child process of `--fork`, telling the parent once the
    /// output is complete.
    #[cfg(unix)]
    Child(fork::Child),
}

/// Runs the command line and returns the exit status, after reporting any
/// error.
fn run(args: &[OsString], launch: Launch) -> u8 {
    let diagnostics = Arc::new(Stderr::new(qld::PROGRAM_NAME));
    // The sink buffers so that it can sort by `Diagnostic::order`. As the
    // child of `--fork`, everything it holds has to reach the relayed
    // stderr before the parent is told the link is done, because being told
    // ends the relay.
    let hook = match launch {
        Launch::MayFork => None,
        #[cfg(unix)]
        Launch::Child(child) => {
            let sink = Arc::clone(&diagnostics);
            Some(OutputCompleteHook::new(move || {
                sink.flush();
                // The status the parent exits with, and only the first
                // `notify` counts, so it has to be the real one here. The
                // output is complete, so the link succeeded; what is left
                // is `--fatal-warnings`, which promotes warnings to errors
                // inside the sink without stopping the link, and
                // `--noinhibit-exec`, which writes the output anyway.
                child.notify(u8::from(sink.error_count() != 0));
            }))
        }
    };
    let result = run_link(args, hook, &diagnostics);
    diagnostics.flush();
    match result {
        // `--fatal-warnings` turns link-time warnings into errors inside the
        // sink, which the backends do not see.
        Ok(code) if diagnostics.error_count() == 0 => code,
        Ok(_) => 1,
        // Every error was printed above; GNU ld and lld add no summary.
        Err(qld::Error::Reported { .. }) => 1,
        Err(error) => {
            eprintln!("{}: error: {error}", qld::PROGRAM_NAME);
            1
        }
    }
}

fn run_link(
    args: &[OsString],
    hook: Option<OutputCompleteHook>,
    diagnostics: &Stderr,
) -> qld::Result<u8> {
    let mut options = match qld::parse_gnu(args)? {
        ParseOutcome::Help => {
            print!("{}", qld::args::usage());
            return Ok(0);
        }
        ParseOutcome::Version => {
            println!("{}", qld::version_line());
            return Ok(0);
        }
        ParseOutcome::Link(options) => options,
    };
    // `--color-diagnostics`, `--error-limit`, `--fatal-warnings` and `-w`.
    diagnostics.configure(&options);
    match hook {
        None => {
            #[cfg(unix)]
            if options.fork
                && fork::allowed(args, &options)
                && let Some(code) = fork::link_in_child(args)
            {
                return Ok(code);
            }
        }
        Some(hook) => options.on_output_complete = Some(hook),
    }
    // GNU ld exits inside the plugin's fatal callback; plugins can
    // misbehave if the linker returns instead. Library callers get
    // an error (see LinkOptions::exit_on_plugin_fatal).
    options.exit_on_plugin_fatal = true;
    // `-w` drops these and `--fatal-warnings` turns them into errors, both
    // in the sink; `run` fails the link when any error reached it.
    for warning in &options.warnings {
        diagnostics.emit(Diagnostic::warning(warning.clone()));
    }
    qld::link(&options, diagnostics)?;
    Ok(0)
}

/// `--fork`: running the link in a child process.
///
/// # Channels
///
/// - **Status**: the child's stdin is one end of a Unix socket pair. The
///   child writes one byte, its exit status, once the output is complete
///   (or when it is about to exit after a failure); the parent reads it
///   and exits with it. The parent shuts down its sending side at once, so
///   anything in the child that reads stdin sees end of file.
/// - **stdout and stderr**: a caller reading a pipe (`ninja`, `make -O`,
///   `$(...)`, a test harness) waits for end of file, which would only
///   come when the child exits. So a stream that is a pipe or a socket is
///   relayed: the child gets a socket, a thread in the parent copies it to
///   the real stream, and the child shuts its sockets down when it reports
///   its status. If stdout and stderr are the same pipe (`2>&1`), the
///   child gets one socket for both, which keeps their relative order.
///   Terminals, files and `/dev/null` are passed to the child as they are:
///   nobody waits for their end of file.
/// - Everything else (the environment, the working directory, other open
///   file descriptors such as a `make` jobserver's, the process group,
///   ignored signals) is inherited as by any child process. The child gets
///   the same `argv[0]`, so flavor selection is unchanged.
///
/// # Failure modes
///
/// - The child cannot be started, or a relay thread cannot be: the link
///   runs in the parent.
/// - The child exits or dies before reporting (a crash, a plugin's fatal
///   error, which exits the process as GNU ld does, a signal): the status
///   socket reaches end of file, the parent waits for the child, and exits
///   with its status, or with 128 + the signal number after an error
///   message if it was killed.
/// - The child reports only after the output file is in place under its
///   final name, the link map is written, stdout is flushed and LTO
///   plugins are cleaned up (`-plugin-save-temps` keeps their files as
///   without `--fork`), so a command started after `qld` returns sees the
///   complete output.
/// - A signal sent to the process group (Ctrl-C in a terminal, `ninja` or
///   `timeout` stopping a job) reaches both processes. A signal sent to the
///   parent alone lets the child finish the link on its own, as with mold
///   and wild.
/// - Paths under `/dev/` or `/proc/` on the command line (`-o /dev/stdout`,
///   an input read from `/dev/stdin`) name the parent's standard streams,
///   which the child does not have: such links run in the parent.
#[cfg(unix)]
mod fork {
    use std::ffi::OsString;
    use std::fs::File;
    use std::io::{self, Read, Write};
    use std::net::Shutdown;
    use std::os::fd::{AsFd, BorrowedFd, OwnedFd};
    use std::os::unix::fs::{FileTypeExt, MetadataExt};
    use std::os::unix::net::UnixStream;
    use std::os::unix::process::{CommandExt, ExitStatusExt};
    use std::path::PathBuf;
    use std::process::{Command, ExitStatus, Stdio};
    use std::sync::atomic::{AtomicBool, Ordering};
    use std::thread::JoinHandle;

    use qld::LinkOptions;

    /// Set in the child's environment: `PID:FLAGS`, the parent's process ID
    /// and which streams are relayed (`o` for stdout, `e` for stderr).
    const ENV: &str = "QLD_FORK_CHILD";

    /// Whether a link may run in a child process: see "Failure modes" in
    /// the [module documentation](self).
    pub fn allowed(args: &[OsString], options: &LinkOptions) -> bool {
        let paths = [Some(options.output_path()), options.map_file.clone()];
        !args
            .iter()
            .any(|arg| names_system_path(arg.as_encoded_bytes()))
            && !paths
                .iter()
                .flatten()
                .any(|path| path.starts_with("/dev") || path.starts_with("/proc"))
    }

    /// Whether an argument names a path under `/dev/` or `/proc/`: as a
    /// whole (`/dev/stdin`), as an option's value (`-o/dev/stdout`,
    /// `--output=/dev/stdout`), or as a response file (`@/dev/stdin`).
    /// `/home/me/dev/out.o` does not count.
    fn names_system_path(arg: &[u8]) -> bool {
        [&b"/dev/"[..], b"/proc/"].iter().any(|dir| {
            (0..arg.len()).any(|at| {
                let (before, rest) = arg.split_at(at);
                rest.starts_with(dir)
                    && (before.is_empty()
                        || before.ends_with(b"=")
                        || before.ends_with(b"@")
                        || (before.starts_with(b"-") && !before.contains(&b'/')))
            })
        })
    }

    /// A standard stream of the parent, as the child gets it.
    struct Stream {
        /// A pipe or socket, relayed through a socket.
        relay: bool,
        /// Device and inode, to recognize stdout and stderr as one file.
        id: (u64, u64),
    }

    impl Stream {
        fn of(fd: BorrowedFd<'_>) -> Option<Self> {
            let metadata = File::from(fd.try_clone_to_owned().ok()?).metadata().ok()?;
            let kind = metadata.file_type();
            Some(Self {
                relay: kind.is_fifo() || kind.is_socket(),
                id: (metadata.dev(), metadata.ino()),
            })
        }
    }

    /// Runs the link in a child process and returns the exit status the
    /// parent should exit with, or `None` if no child could be started
    /// (the caller then links in this process).
    pub fn link_in_child(args: &[OsString]) -> Option<u8> {
        let stdout = Stream::of(io::stdout().as_fd())?;
        let stderr = Stream::of(io::stderr().as_fd())?;
        let shared = stdout.relay && stderr.relay && stdout.id == stderr.id;
        let (status, status_child) = UnixStream::pair().ok()?;

        let mut command = Command::new(program()?);
        if let Some(arg0) = args.first() {
            command.arg0(arg0);
        }
        command
            .args(args.iter().skip(1))
            .env(
                ENV,
                format!(
                    "{}:{}{}",
                    std::process::id(),
                    if stdout.relay { "o" } else { "" },
                    if stderr.relay { "e" } else { "" }
                ),
            )
            .stdin(Stdio::from(OwnedFd::from(status_child)));

        // Relay threads start before the child, so that a child is never
        // left writing to a socket nobody reads.
        let mut relays = Vec::new();
        if stdout.relay {
            let child = relay(io::stdout().as_fd(), &mut relays)?;
            if shared {
                command.stderr(Stdio::from(OwnedFd::from(child.try_clone().ok()?)));
            }
            command.stdout(Stdio::from(OwnedFd::from(child)));
        }
        if stderr.relay && !shared {
            let child = relay(io::stderr().as_fd(), &mut relays)?;
            command.stderr(Stdio::from(OwnedFd::from(child)));
        }

        let spawned = command.spawn();
        // Close the parent's copies of the child's ends, so that the relays
        // and the status socket see end of file when the child is done.
        drop(command);
        let Ok(mut child) = spawned else {
            join(relays);
            return None;
        };
        let _ = status.shutdown(Shutdown::Write);

        let reported = read_status(&status);
        join(relays);
        Some(match reported {
            Some(code) => code,
            None => exit_code(child.wait()),
        })
    }

    /// The executable to start: this one.
    fn program() -> Option<PathBuf> {
        let path = std::env::current_exe().ok()?;
        // If the file at that path was replaced since this process started
        // (qld linking a new qld over itself), `/proc/self/exe` still names
        // this executable. It is not the first choice because the child's
        // process name would be `exe`.
        #[cfg(any(target_os = "linux", target_os = "android"))]
        {
            let id = |path: &std::path::Path| {
                std::fs::metadata(path)
                    .ok()
                    .map(|metadata| (metadata.dev(), metadata.ino()))
            };
            let proc = PathBuf::from("/proc/self/exe");
            if let Some(this) = id(&proc)
                && id(&path) != Some(this)
            {
                return Some(proc);
            }
        }
        Some(path)
    }

    /// Starts a thread that copies a new socket to `target` until end of
    /// file, and returns the child's end of the socket.
    fn relay(target: BorrowedFd<'_>, relays: &mut Vec<JoinHandle<()>>) -> Option<UnixStream> {
        let mut target = File::from(target.try_clone_to_owned().ok()?);
        let (mut source, child) = UnixStream::pair().ok()?;
        let thread = std::thread::Builder::new()
            .name("qld-relay".into())
            .spawn(move || {
                let mut buffer = vec![0u8; 64 << 10];
                loop {
                    match source.read(&mut buffer) {
                        Ok(0) => return,
                        Ok(n) => {
                            // If the real stream is gone, stop reading: the
                            // child then gets the same write error it would
                            // have got without `--fork`.
                            if target.write_all(buffer.get(..n).unwrap_or(&[])).is_err() {
                                return;
                            }
                        }
                        Err(error) if error.kind() == io::ErrorKind::Interrupted => {}
                        Err(_) => return,
                    }
                }
            })
            .ok()?;
        relays.push(thread);
        Some(child)
    }

    fn join(relays: Vec<JoinHandle<()>>) {
        for relay in relays {
            let _ = relay.join();
        }
    }

    /// The status byte the child sent, or `None` at end of file.
    fn read_status(mut status: &UnixStream) -> Option<u8> {
        let mut byte = [0u8; 1];
        loop {
            match status.read(&mut byte) {
                Ok(1) => return Some(byte[0]),
                Err(error) if error.kind() == io::ErrorKind::Interrupted => {}
                Ok(_) | Err(_) => return None,
            }
        }
    }

    /// The exit status for a child that exited without reporting.
    fn exit_code(status: io::Result<ExitStatus>) -> u8 {
        let program = qld::PROGRAM_NAME;
        match status {
            Ok(status) => {
                if let Some(code) = status.code() {
                    return u8::try_from(code & 0xff).unwrap_or(1);
                }
                let Some(signal) = status.signal() else {
                    return 1;
                };
                let core = if status.core_dumped() {
                    " (core dumped)"
                } else {
                    ""
                };
                eprintln!("{program}: error: the link process was killed by signal {signal}{core}");
                u8::try_from(signal.saturating_add(128)).unwrap_or(1)
            }
            Err(error) => {
                eprintln!("{program}: error: cannot wait for the link process: {error}");
                1
            }
        }
    }

    /// The child side: this process was started by [`link_in_child`].
    #[derive(Clone, Copy)]
    pub struct Child {
        relay_stdout: bool,
        relay_stderr: bool,
    }

    impl Child {
        /// `Some` if this process is the child of a `qld` parent.
        pub fn from_env() -> Option<Self> {
            let value = std::env::var(ENV).ok()?;
            let (pid, flags) = value.split_once(':')?;
            if pid.parse::<u32>().ok()? != std::os::unix::process::parent_id() {
                return None;
            }
            // The status socket; anything else means the variable was not
            // set for this process.
            let stdin = File::from(io::stdin().as_fd().try_clone_to_owned().ok()?);
            if !stdin.metadata().ok()?.file_type().is_socket() {
                return None;
            }
            Some(Self {
                relay_stdout: flags.contains('o'),
                relay_stderr: flags.contains('e'),
            })
        }

        /// Sends the exit status to the parent, after flushing stdout and
        /// ending the relayed streams. Only the first call does anything:
        /// nothing may be printed after it.
        pub fn notify(self, code: u8) {
            static SENT: AtomicBool = AtomicBool::new(false);
            if SENT.swap(true, Ordering::AcqRel) {
                return;
            }
            let _ = io::stdout().flush();
            let _ = io::stderr().flush();
            if self.relay_stdout {
                shut_down(io::stdout().as_fd());
            }
            if self.relay_stderr {
                shut_down(io::stderr().as_fd());
            }
            if let Ok(fd) = io::stdin().as_fd().try_clone_to_owned() {
                let _ = UnixStream::from(fd).write_all(&[code]);
            }
        }
    }

    /// Ends the parent's relay of a stream: shutting the socket down (not
    /// just closing this descriptor) also ends it for copies of it, such
    /// as plugin subprocesses', and for the descriptor itself.
    fn shut_down(fd: BorrowedFd<'_>) {
        if let Ok(fd) = fd.try_clone_to_owned() {
            let _ = UnixStream::from(fd).shutdown(Shutdown::Write);
        }
    }

    #[cfg(test)]
    mod tests {
        use super::names_system_path;

        #[test]
        fn system_paths_in_arguments() {
            for arg in [
                "/dev/stdout",
                "/proc/self/fd/1",
                "-o/dev/stdout",
                "--output=/dev/stdout",
                "-Map=/dev/stderr",
                "@/dev/stdin",
                "-T/dev/stdin",
            ] {
                assert!(names_system_path(arg.as_bytes()), "{arg}");
            }
            for arg in [
                "/home/me/dev/out",
                "-L/home/me/dev/lib",
                "--output=/home/me/proc/a.out",
                "dev/stdout",
                "-lproc",
                "",
            ] {
                assert!(!names_system_path(arg.as_bytes()), "{arg}");
            }
        }
    }
}