Function parse_gnu 

pub fn parse_gnu<S: AsRef<OsStr>>(args: &[S]) -> Result<ParseOutcome>

Parses a GNU ld / gold / lld / mold command line.

args includes argv[0], which also selects the flavor when it is a name such as ld64.qld (see select_flavor). Response files are read with std::fs::read; use parse_gnu_with to supply them another way.

The options describe a link run the way the qld binary runs one: LinkOptions::use_process_defaults is applied, so the link map goes to standard output and LD_LIBRARY_PATH and the other variables GNU ld reads are taken from the environment. parse_gnu_with parses the same command line into a hermetic, silent link.

Warnings found while parsing, such as unknown -z keywords, are returned in LinkOptions::warnings for the caller to report.

Errors

Returns Error::Option for an unknown, unsupported or malformed option, Error::Io for an unreadable response file, and Error::Unimplemented for a flavor qld does not parse yet.

Examples found in repository

examples/link_argv.rs (line 35)

fn link(args: &[std::ffi::OsString], diagnostics: &dyn DiagnosticSink) -> qld::Result<()> {
    let options = match qld::parse_gnu(args)? {
        ParseOutcome::Link(options) => options,
        ParseOutcome::Help => {
            print!("{}", qld::args::usage());
            return Ok(());
        }
        ParseOutcome::Version => {
            println!("{}", qld::version_line());
            return Ok(());
        }
    };
    // Parsing does no reporting: warnings such as an unknown `-z` keyword
    // come back in the options, for the caller to emit.
    if !options.no_warnings {
        for warning in &options.warnings {
            diagnostics.emit(Diagnostic::warning(warning.clone()));
        }
    }
    if options.fatal_warnings && !options.warnings.is_empty() {
        return Err(qld::Error::Reported {
            errors: options.warnings.len(),
        });
    }
    qld::link(&options, diagnostics)
}

examples/cancel.rs (line 47)

fn main() -> qld::Result<()> {
    let mut args = std::env::args().skip(1);
    if let Some(limit) = args.next() {
        let limit = Duration::from_millis(limit.parse().unwrap_or(1000));
        let argv: Vec<String> = std::iter::once("ld".to_string()).chain(args).collect();
        let qld::ParseOutcome::Link(options) = qld::parse_gnu(&argv)? else {
            return Ok(());
        };
        let start = Instant::now();
        let result = link_with_deadline(*options, limit);
        match &result {
            Ok(()) => eprintln!("linked in {:?}", start.elapsed()),
            Err(error) if CancelToken::is_cancellation(error) => {
                eprintln!("{error} after {:?}", start.elapsed());
            }
            Err(_) => {}
        }
        return result;
    }

    // Without arguments: link the in-memory demo program twice, once with
    // plenty of time and once cancelled before it starts.
    let mut options = LinkOptions::new();
    options.kind = OutputKind::StaticExecutable;
    options.push_input(
        InputKind::bytes("main.o", objects::main_object()),
        InputAttrs::default(),
    );
    options.push_input(
        InputKind::bytes("answer.o", objects::answer_object(42)),
        InputAttrs::default(),
    );
    let buffer = OutputBuffer::new();
    options.output_buffer = Some(buffer.clone());

    link_with_deadline(options.clone(), Duration::from_secs(10))?;
    println!(
        "with a 10 s deadline: linked {} bytes",
        buffer.take().map_or(0, |b| b.len())
    );

    let token = CancelToken::new();
    token.cancel();
    options.cancel = Some(token);
    match qld::link(&options, &Stderr::new(qld::PROGRAM_NAME)) {
        Err(error) if CancelToken::is_cancellation(&error) => {
            println!(
                "cancelled before it started: {error}; output empty: {}",
                !buffer.is_filled()
            );
        }
        other => println!("unexpected: {other:?}"),
    }
    Ok(())
}

examples/in_memory.rs (line 55)

fn main() -> qld::Result<()> {
    // Object code from a compiler or JIT in the same process.
    let main_o = objects::main_object();
    let answer_o = objects::answer_object(42);

    // 1. Buffers as inputs, the output into a buffer.
    let mut options = LinkOptions::new();
    options.kind = OutputKind::StaticExecutable;
    options.push_input(
        InputKind::bytes("main.o", main_o.clone()),
        InputAttrs::default(),
    );
    options.push_input(
        InputKind::bytes("answer.o", answer_o.clone()),
        InputAttrs::default(),
    );
    let buffer = OutputBuffer::new();
    options.output_buffer = Some(buffer.clone());
    let diagnostics = Collect::new();
    qld::link(&options, &diagnostics)?;
    let first = buffer.take().expect("a successful link fills the buffer");
    report("buffers", &first);

    // 2. A command line whose files live in memory: `main.o`, and
    //    `libanswer.a` in a search directory that does not exist on disk.
    let library = objects::archive(&[("answer.o", &answer_o, &["answer"])]);
    let files = MemoryFiles::new()
        .with("main.o", main_o)
        .with("/virtual/lib/libanswer.a", library);
    let argv = ["ld", "-static", "-L/virtual/lib", "main.o", "-lanswer"];
    let qld::ParseOutcome::Link(options) = qld::parse_gnu(&argv)? else {
        unreachable!("a link command line");
    };
    let mut options = *options;
    options.input_provider = Some(Arc::new(files));
    let buffer = OutputBuffer::new();
    options.output_buffer = Some(buffer.clone());
    qld::link(&options, &diagnostics)?;
    let second = buffer.take().expect("a successful link fills the buffer");
    report("memory files", &second);
    assert_eq!(first, second, "same program either way");

    for diagnostic in diagnostics.take_sorted() {
        eprintln!("{}: {}", diagnostic.severity, diagnostic.message);
    }
    if let Some(path) = std::env::args_os().nth(1) {
        std::fs::write(&path, &first).map_err(|error| qld::Error::io(&path, error))?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))
                .map_err(|error| qld::Error::io(&path, error))?;
        }
        println!("wrote {} (it exits with status 42)", path.to_string_lossy());
    }
    Ok(())
}