Struct LinkOptions 

#[non_exhaustive]
pub struct LinkOptions {

    pub flavor: Flavor,
    pub target: Option<Target>,
    pub endian: Option<Endianness>,
    pub output: Option<PathBuf>,
    pub output_format: Option<OutputFormat>,
    pub kind: OutputKind,
    pub inputs: Vec<InputSpec>,
    pub search_paths: Vec<PathBuf>,
    pub nostdlib: bool,
    pub sysroot: Option<PathBuf>,
    pub default_script: Option<PathBuf>,
    pub entry: Option<String>,
    pub soname: Option<String>,
    pub dynamic_linker: Option<PathBuf>,
    pub no_dynamic_linker: bool,
    pub rpaths: Vec<PathBuf>,
    pub rpath_links: Vec<PathBuf>,
    pub new_dtags: Option<bool>,
    pub undefined: Vec<String>,
    pub undefined_glob: Vec<String>,
    pub require_defined: Vec<String>,
    pub defsym: Vec<(String, String)>,
    pub wrap: Vec<String>,
    pub init: Option<String>,
    pub fini: Option<String>,
    pub auxiliary: Vec<String>,
    pub filter: Vec<String>,
    pub gc_sections: bool,
    pub print_gc_sections: bool,
    pub gc_keep_exported: bool,
    pub why_live: Vec<String>,
    pub icf: IcfMode,
    pub print_icf_sections: bool,
    pub keep_unique: Vec<String>,
    pub ignore_data_address_equality: bool,
    pub ignore_function_address_equality: bool,
    pub strip: StripMode,
    pub discard: DiscardMode,
    pub retain_symbols_file: Option<PathBuf>,
    pub build_id: BuildId,
    pub hash_style: HashStyle,
    pub eh_frame_hdr: bool,
    pub export_dynamic: bool,
    pub export_dynamic_symbols: Vec<String>,
    pub export_dynamic_symbol_lists: Vec<PathBuf>,
    pub dynamic_lists: Vec<PathBuf>,
    pub dynamic_list_data: bool,
    pub dynamic_list_cpp_new: bool,
    pub dynamic_list_cpp_typeinfo: bool,
    pub exclude_libs: Vec<String>,
    pub version_scripts: Vec<PathBuf>,
    pub undefined_version: Option<bool>,
    pub default_symver: bool,
    pub symbolic: SymbolicMode,
    pub no_undefined: Option<bool>,
    pub allow_shlib_undefined: Option<bool>,
    pub unresolved_symbols: Option<UnresolvedSymbols>,
    pub warn_unresolved_symbols: bool,
    pub ignore_unresolved_symbols: Vec<String>,
    pub allow_multiple_definition: bool,
    pub warn_common: bool,
    pub warn_backrefs: bool,
    pub warn_backrefs_exclude: Vec<String>,
    pub warn_textrel: bool,
    pub error_textrel: bool,
    pub bind_now: bool,
    pub relro: bool,
    pub separate_code: Option<SeparateCode>,
    pub rosegment: Option<bool>,
    pub exec_stack: ExecStack,
    pub gnu_stack: bool,
    pub stack_size: Option<u64>,
    pub max_page_size: Option<u64>,
    pub common_page_size: Option<u64>,
    pub copy_relocs: bool,
    pub combine_relocs: bool,
    pub pack_relative_relocs: bool,
    pub gnu_tls_tag: bool,
    pub gnu2_tls_tag: bool,
    pub apply_dynamic_relocs: bool,
    pub dynamic_flags: DynamicFlags,
    pub start_stop_gc: Option<bool>,
    pub start_stop_visibility: Option<Visibility>,
    pub keep_text_section_prefix: bool,
    pub dynamic_undefined_weak: Option<bool>,
    pub extern_protected_data: bool,
    pub mark_plt: bool,
    pub section_header: bool,
    pub memory_seal: bool,
    pub dead_reloc_in_nonalloc: Vec<(String, u64)>,
    pub x86: X86Features,
    pub fix_cortex_a53_843419: bool,
    pub aarch64: Aarch64Features,
    pub spare_dynamic_tags: Option<u64>,
    pub emit_relocs: bool,
    pub define_common: bool,
    pub magic: MagicMode,
    pub relax: bool,
    pub merge_exidx_entries: bool,
    pub relax_gp: bool,
    pub image_base: Option<u64>,
    pub section_starts: Vec<(String, u64)>,
    pub text_segment: Option<u64>,
    pub rodata_segment: Option<u64>,
    pub ldata_segment: Option<u64>,
    pub orphan_handling: OrphanHandling,
    pub sort_section: SortSection,
    pub compress_debug_sections: DebugCompression,
    pub package_metadata: Option<String>,
    pub symbol_ordering_file: Option<PathBuf>,
    pub no_warn_symbol_ordering: bool,
    pub call_graph_profile_sort: Option<CallGraphSort>,
    pub call_graph_ordering_file: Option<PathBuf>,
    pub print_symbol_order: Option<PathBuf>,
    pub gdb_index: bool,
    pub s390_pgste: bool,
    pub debug_names: bool,
    pub separate_debug_file: Option<Option<PathBuf>>,
    pub dependency_file: Option<PathBuf>,
    pub dependent_libraries: bool,
    pub optimize: u8,
    pub threads: Option<usize>,
    pub map_file: Option<PathBuf>,
    pub print_map: bool,
    pub cref: bool,
    pub trace: bool,
    pub trace_symbols: Vec<String>,
    pub verbose: bool,
    pub demangle: bool,
    pub fatal_warnings: bool,
    pub no_warnings: bool,
    pub error_limit: Option<u64>,
    pub color: ColorChoice,
    pub noinhibit_exec: bool,
    pub pe: PeArgs,
    pub darwin: DarwinArgs,
    pub plugins: Vec<(PathBuf, Vec<String>)>,
    pub plugin_save_temps: bool,
    pub exit_on_plugin_fatal: bool,
    pub fork: bool,
    pub on_output_complete: Option<OutputCompleteHook>,
    pub input_provider: Option<Arc<dyn InputProvider>>,
    pub output_buffer: Option<OutputBuffer>,
    pub cancel: Option<CancelToken>,
    pub map_output: Option<TextOutput>,
    pub timing: Option<TextOutput>,
    pub env_run_path: Vec<PathBuf>,
    pub env_library_path: Vec<PathBuf>,
    pub zero_ar_date: bool,
    pub output_backing: Option<OutputBacking>,
    pub ignored: Vec<OsString>,
    pub warnings: Vec<String>,
}

Everything a link is configured by.

Construct one with LinkOptions::new and the builder methods, or parse argv with crate::args::parse_gnu.

Fields typed Option<bool> distinguish “not given” (None, meaning the target’s or output kind’s default applies) from an explicit choice.

LinkOptions::default is LinkOptions::new: both describe the link GNU ld performs when the command line says nothing, so the ten options GNU ld has on by default (-z relro, --demangle, --relax, …) are on in both.

The struct is #[non_exhaustive]: qld adds fields as it implements more options, so build one with LinkOptions::new and assign the fields you need.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

flavor: Flavor

Command-line dialect this was parsed from.

target: Option<Target>

Target, when it was given explicitly (-m). Otherwise it is inferred from the first object input.

endian: Option<Endianness>

Endianness forced with -EB / -EL.

output: Option<PathBuf>

Output path (-o). None means the flavor’s default (a.out).

output_format: Option<OutputFormat>

Output format (--oformat), such as binary or elf64-x86-64.

kind: OutputKind

What kind of output to produce.

inputs: Vec<InputSpec>

Inputs, in command-line order.

search_paths: Vec<PathBuf>

Library search paths (-L), in order.

nostdlib: bool

-nostdlib: ignore SEARCH_DIR commands in linker scripts.

sysroot: Option<PathBuf>

--sysroot.

default_script: Option<PathBuf>

--default-script / -dT: used when no -T script is given.

entry: Option<String>

Entry point (-e).

soname: Option<String>

-soname / -install_name.

dynamic_linker: Option<PathBuf>

Program interpreter (--dynamic-linker).

no_dynamic_linker: bool

--no-dynamic-linker: omit PT_INTERP (used for static PIE).

rpaths: Vec<PathBuf>

-rpath entries, in order.

rpath_links: Vec<PathBuf>

-rpath-link entries, in order.

new_dtags: Option<bool>

--enable-new-dtags (Some(true), DT_RUNPATH) or --disable-new-dtags (Some(false), DT_RPATH).

undefined: Vec<String>

Symbols required to be defined (-u, --undefined).

undefined_glob: Vec<String>

--undefined-glob patterns.

require_defined: Vec<String>

--require-defined symbols: like -u, but an error if undefined.

defsym: Vec<(String, String)>

--defsym assignments, in order.

wrap: Vec<String>

--wrap symbols.

init: Option<String>

-init symbol (DT_INIT).

fini: Option<String>

-fini symbol (DT_FINI).

auxiliary: Vec<String>

-f / --auxiliary names (DT_AUXILIARY).

filter: Vec<String>

-F / --filter names (DT_FILTER).

gc_sections: bool

Remove unreferenced sections (--gc-sections).

print_gc_sections: bool

--print-gc-sections.

gc_keep_exported: bool

--gc-keep-exported: exported symbols are GC roots.

why_live: Vec<String>

--why-live symbol patterns.

icf: IcfMode

Identical code folding (--icf).

print_icf_sections: bool

--print-icf-sections.

keep_unique: Vec<String>

--keep-unique symbols, never folded by ICF.

ignore_data_address_equality: bool

--ignore-data-address-equality.

ignore_function_address_equality: bool

--ignore-function-address-equality.

strip: StripMode

Strip level.

discard: DiscardMode

Local symbol discarding (-x, -X, --discard-none).

retain_symbols_file: Option<PathBuf>

--retain-symbols-file.

build_id: BuildId

Build ID generation.

hash_style: HashStyle

Dynamic symbol hash tables to emit.

eh_frame_hdr: bool

--eh-frame-hdr: create .eh_frame_hdr and PT_GNU_EH_FRAME.

export_dynamic: bool

Export all symbols from an executable (--export-dynamic).

export_dynamic_symbols: Vec<String>

--export-dynamic-symbol patterns.

export_dynamic_symbol_lists: Vec<PathBuf>

--export-dynamic-symbol-list files.

dynamic_lists: Vec<PathBuf>

--dynamic-list files.

dynamic_list_data: bool

--dynamic-list-data: add every defined data symbol to the dynamic list.

dynamic_list_cpp_new: bool

--dynamic-list-cpp-new: add operator new and operator delete to the dynamic list.

dynamic_list_cpp_typeinfo: bool

--dynamic-list-cpp-typeinfo: add the C++ type information symbols to the dynamic list.

exclude_libs: Vec<String>

--exclude-libs archive names (ALL is kept as a name).

version_scripts: Vec<PathBuf>

--version-script files.

undefined_version: Option<bool>

--undefined-version (Some(true)) or --no-undefined-version (Some(false)).

default_symver: bool

--default-symver: version exported symbols with the soname.

symbolic: SymbolicMode

-Bsymbolic and variants.

no_undefined: Option<bool>

--no-undefined / -z defs (Some(true)) or -z undefs (Some(false)): whether undefined symbols in regular objects are errors even for shared output.

allow_shlib_undefined: Option<bool>

--allow-shlib-undefined (Some(true)) or --no-allow-shlib-undefined (Some(false)).

unresolved_symbols: Option<UnresolvedSymbols>

--unresolved-symbols=.

warn_unresolved_symbols: bool

--warn-unresolved-symbols: report unresolved symbols as warnings.

ignore_unresolved_symbols: Vec<String>

--ignore-unresolved-symbol names.

allow_multiple_definition: bool

--allow-multiple-definition / -z muldefs.

warn_common: bool

--warn-common.

warn_backrefs: bool

--warn-backrefs.

warn_backrefs_exclude: Vec<String>

--warn-backrefs-exclude patterns.

warn_textrel: bool

--warn-textrel: warn when the output needs DT_TEXTREL.

error_textrel: bool

-z text: make DT_TEXTREL an error.

bind_now: bool

Resolve all dynamic symbols at load time (-z now).

relro: bool

-z relro (default) / -z norelro.

separate_code: Option<SeparateCode>

-z separate-code and friends. None means the target default.

rosegment: Option<bool>

--rosegment (Some(true)) / --no-rosegment (Some(false)).

exec_stack: ExecStack

-z execstack / -z noexecstack.

gnu_stack: bool

-z nognustack clears this: omit PT_GNU_STACK.

stack_size: Option<u64>

-z stack-size=: the PT_GNU_STACK size.

max_page_size: Option<u64>

-z max-page-size=.

common_page_size: Option<u64>

-z common-page-size=.

copy_relocs: bool

-z copyreloc (default) / -z nocopyreloc.

combine_relocs: bool

-z combreloc (default) / -z nocombreloc.

pack_relative_relocs: bool

-z pack-relative-relocs or --pack-dyn-relocs=relr: emit DT_RELR.

gnu_tls_tag: bool

--gnu-tls-tag (default) / --no-gnu-tls-tag: add the GLIBC_ABI_GNU_TLS version dependency to an output that keeps GNU general-dynamic or local-dynamic TLS, when a needed library defines that version.

gnu2_tls_tag: bool

--gnu2-tls-tag (default) / --no-gnu2-tls-tag: the same for GLIBC_ABI_GNU2_TLS and TLS descriptors.

apply_dynamic_relocs: bool

--apply-dynamic-relocs: also write addends into the output.

dynamic_flags: DynamicFlags

DT_FLAGS / DT_FLAGS_1 bits from -z keywords.

start_stop_gc: Option<bool>

-z start-stop-gc (Some(true)) / -z nostart-stop-gc.

start_stop_visibility: Option<Visibility>

-z start-stop-visibility=. None when the keyword was not given, which leaves the linker’s own default.

keep_text_section_prefix: bool

-z keep-text-section-prefix.

dynamic_undefined_weak: Option<bool>

-z dynamic-undefined-weak (Some(true)) / -z nodynamic-undefined-weak.

extern_protected_data: bool

-z noextern-protected-data clears this.

mark_plt: bool

-z mark-plt.

section_header: bool

-z sectionheader (default) / -z nosectionheader.

memory_seal: bool

-z memory-seal.

dead_reloc_in_nonalloc: Vec<(String, u64)>

-z dead-reloc-in-nonalloc=<glob>=<value> rules, in command-line order: the value written for a relocation in a non-allocated section whose name matches the glob, when its target section was discarded. Later rules take precedence.

x86: X86Features

x86 CET and ISA-level options.

fix_cortex_a53_843419: bool

--fix-cortex-a53-843419.

aarch64: Aarch64Features

AArch64 BTI, PAC and erratum options.

spare_dynamic_tags: Option<u64>

--spare-dynamic-tags.

emit_relocs: bool

-q / --emit-relocs: keep relocations in the output.

define_common: bool

-d, -dc, -dp: allocate common symbols even for -r.

magic: MagicMode

-n / -N.

relax: bool

--relax (default) / --no-relax.

merge_exidx_entries: bool

Arm --merge-exidx-entries (default) / --no-merge-exidx-entries: drop .ARM.exidx entries that repeat the one before.

relax_gp: bool

RISC-V --relax-gp: relax absolute accesses within 2 KiB of __global_pointer$ to gp-relative ones (off by default, as in lld).

image_base: Option<u64>

--image-base.

section_starts: Vec<(String, u64)>

--section-start, -Ttext, -Tdata, -Tbss: section addresses, in order.

text_segment: Option<u64>

-Ttext-segment.

rodata_segment: Option<u64>

-Trodata-segment.

ldata_segment: Option<u64>

-Tldata-segment.

orphan_handling: OrphanHandling

--orphan-handling=.

sort_section: SortSection

--sort-section=.

compress_debug_sections: DebugCompression

--compress-debug-sections=.

package_metadata: Option<String>

--package-metadata=: contents of .note.package.

symbol_ordering_file: Option<PathBuf>

--symbol-ordering-file: order input sections by the symbols listed in this file (lld).

no_warn_symbol_ordering: bool

--no-warn-symbol-ordering: do not warn about symbols of the ordering file that cannot be ordered.

call_graph_profile_sort: Option<CallGraphSort>

--call-graph-profile-sort=: how to order sections by call graph profile. None when not given: qld then orders only with --call-graph-ordering-file (lld also sorts by default when an input has a .llvm.call-graph-profile section).

call_graph_ordering_file: Option<PathBuf>

--call-graph-ordering-file: call graph edges (from to weight).

print_symbol_order: Option<PathBuf>

--print-symbol-order=: write the symbol order the call graph sort chose to this file.

gdb_index: bool

--gdb-index: write a .gdb_index section.

s390_pgste: bool

--s390-pgste: add an empty PT_S390_PGSTE segment, which tells the Linux kernel to allocate page tables with the guest storage extension (s390x only).

debug_names: bool

--debug-names: write a merged .debug_names section.

separate_debug_file: Option<Option<PathBuf>>

--separate-debug-file[=FILE]: write the debug sections to FILE (Some(None): the output path plus .dbg) and link it from the output with .gnu_debuglink, as mold does.

dependency_file: Option<PathBuf>

--dependency-file.

dependent_libraries: bool

--dependent-libraries (default) / --no-dependent-libraries.

optimize: u8

Optimization level (-O).

threads: Option<usize>

Thread count (--threads). Some(n) runs the link in a pool of n threads that crate::link creates for it.

None, the default, leaves the choice to the format driver: the ELF driver sizes a pool from the input (small links run faster on few threads), at most 16 threads and at most the available parallelism. Called inside a rayon pool of your own (rayon::ThreadPool::install), a link with None runs in that pool and creates none, however large it is.

map_file: Option<PathBuf>

Write a link map to this path (-Map).

print_map: bool

-M / --print-map: write the link map to stdout.

cref: bool

--cref: add a cross-reference table to the map.

trace: bool

-t / --trace: print each input file as it is processed.

trace_symbols: Vec<String>

-y / --trace-symbol names.

verbose: bool

--verbose.

demangle: bool

Demangle symbol names in diagnostics (--demangle, on by default).

fatal_warnings: bool

--fatal-warnings.

no_warnings: bool

-w / --no-warnings.

error_limit: Option<u64>

--error-limit. Some(0) means no limit.

color: ColorChoice

--color-diagnostics.

noinhibit_exec: bool

--noinhibit-exec: write the output even after errors.

pe: PeArgs

The PE/COFF options of GNU ld’s MinGW emulations. Only PE links read them.

darwin: DarwinArgs

The Apple ld64 options that have no GNU equivalent. Only Mach-O links read them.

plugins: Vec<(PathBuf, Vec<String>)>

LTO plugin paths (-plugin) and their options (-plugin-opt).

plugin_save_temps: bool

-plugin-save-temps: keep the files an LTO plugin generates.

exit_on_plugin_fatal: bool

Exit the process when an LTO plugin reports a fatal error, as GNU ld does. The qld binary sets this; library callers get an error instead, and accept that a plugin may not expect to be called again.

fork: bool

--fork (the default) / --no-fork: whether the qld binary runs the link in a child process and returns as soon as the output is complete, leaving the child to free memory and unmap the inputs. Only the binary reads it (on Unix); the library never forks.

on_output_complete: Option<OutputCompleteHook>

Called once when a successful link’s output is complete; see OutputCompleteHook. None by default. The qld binary sets it in the child process of --fork to let its parent exit early.

input_provider: Option<Arc<dyn InputProvider>>

Files that exist only in memory, looked up by path before the file system: inputs named by path, -l libraries found in the search directories, INPUT/GROUP entries of input scripts, and thin archive members. None by default (only the file system). See MemoryFiles and InputProvider.

The ELF driver uses it. Files read outside the input list (-T scripts, version scripts, dynamic lists) still come from the file system; so do all inputs of PE and Mach-O links.

output_buffer: Option<OutputBuffer>

Hand the output image to this buffer instead of writing the output file; see OutputBuffer. None by default.

cancel: Option<CancelToken>

Stop the link with an error once this token is cancelled; see CancelToken. None by default.

map_output: Option<TextOutput>

Receives the link map of -M / --print-map, and the --cref table when no -Map file was named. None by default, which drops that text: a library link writes nothing to the process’s standard output. See LinkOptions::use_process_defaults.

timing: Option<TextOutput>

Receives one line per pipeline stage with the time it took, the way QLD_TIMING asks the qld binary for. None by default, which measures nothing. See LinkOptions::use_process_defaults.

env_run_path: Vec<PathBuf>

LD_RUN_PATH, split into directories: searched for the dependencies of shared libraries when no -rpath was given, as GNU ld does. Empty by default; a library link reads no environment of its own. See LinkOptions::use_process_defaults.

env_library_path: Vec<PathBuf>

LD_LIBRARY_PATH, split into directories: searched for the dependencies of shared libraries, as GNU ld does. Empty by default. See LinkOptions::use_process_defaults.

zero_ar_date: bool

Record zero modification times in a Mach-O debug map, for reproducible output; ZERO_AR_DATE in the environment asks ld64, lld and the qld binary for it. Off by default. See LinkOptions::use_process_defaults.

output_backing: Option<OutputBacking>

How the output image is held while it is written. None, the default, leaves the choice to the writer; QLD_OUTPUT_BACKING sets it for the qld binary. See LinkOptions::use_process_defaults.

ignored: Vec<OsString>

Options that were recognized but have no effect yet, kept so that --verbose and tests can report them.

warnings: Vec<String>

Warnings produced while parsing the command line (for example an unknown -z keyword), in command-line order. The driver emits them to its diagnostic sink.

Implementations

impl LinkOptions

pub fn new() -> Self

Creates the options of a link whose command line said nothing: every field at the default GNU ld uses.

Examples found in repository

examples/rayon_pool.rs (line 23)

fn link(value: u8) -> qld::Result<Vec<u8>> {
    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(value)),
        InputAttrs::default(),
    );
    let buffer = OutputBuffer::new();
    options.output_buffer = Some(buffer.clone());
    qld::link(&options, &Collect::new())?;
    buffer
        .take()
        .ok_or_else(|| qld::Error::Internal("no output".into()))
}

examples/custom_sink.rs (line 91)

fn main() {
    // `main.o` calls `answer`, which nothing defines.
    let mut options = LinkOptions::new();
    options.kind = OutputKind::StaticExecutable;
    options.output_buffer = Some(OutputBuffer::new());
    options.push_input(
        InputKind::bytes("main.o", objects::main_object()),
        InputAttrs::default(),
    );

    let sink = JsonLines::default();
    let result = qld::link(&options, &sink);
    print!("{}", sink.render());
    match result {
        Ok(()) => println!("linked"),
        Err(qld::Error::Reported { errors }) => {
            println!("the link failed with {errors} error(s) reported above");
        }
        Err(error) => println!("the link failed: {error}"),
    }
}

examples/link_map.rs (line 24)

fn main() -> qld::Result<()> {
    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(),
    );

    // `-M` and `--cref`, into a string instead of standard output.
    options.print_map = true;
    options.cref = true;
    let map = Arc::new(Mutex::new(String::new()));
    let collected = Arc::clone(&map);
    options.map_output = Some(TextOutput::new(move |text| {
        collected.lock().unwrap().push_str(text);
    }));

    let image = qld::link_to_memory(&options, &Collect::new())?;
    let map = map.lock().unwrap();
    println!("linked {} bytes, {} of map", image.len(), map.len());
    for line in map.lines().take(8) {
        println!("  {line}");
    }

    // What the same options would take from the process, if asked.
    let mut as_the_binary = options.clone();
    as_the_binary.use_process_defaults();
    println!(
        "\nhermetic: map_output {}, LD_LIBRARY_PATH {} entries, timing {}",
        if options.map_output.is_some() {
            "set by this program"
        } else {
            "unset"
        },
        options.env_library_path.len(),
        if options.timing.is_some() {
            "on"
        } else {
            "off"
        },
    );
    println!(
        "as the binary: LD_LIBRARY_PATH {} entries, timing {}",
        as_the_binary.env_library_path.len(),
        if as_the_binary.timing.is_some() {
            "on"
        } else {
            "off"
        },
    );
    Ok(())
}

examples/cancel.rs (line 64)

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 31)

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(())
}

pub fn use_process_defaults(&mut self)

Makes these options describe a link run the way the qld binary runs one, by taking from the process what a library link must be told explicitly.

Nothing else in qld reads the environment or writes to standard output or standard error, so a LinkOptions that never went through this method describes a hermetic, silent link. parse_gnu and parse_darwin call it, because they parse a command line the way the binary does; parse_gnu_with, parse_darwin_with and LinkOptions::new do not.

It sets:

• map_output to standard output, where GNU ld writes the map of -M and a --cref table with no -Map file;
• timing to standard error when QLD_TIMING is set in the environment;
• env_run_path from LD_RUN_PATH and env_library_path from LD_LIBRARY_PATH, which GNU ld also searches;
• zero_ar_date from ZERO_AR_DATE, which ld64 and lld also read;
• output_backing from QLD_OUTPUT_BACKING, a benchmarking knob.

Examples found in repository

examples/link_map.rs (line 53)

fn main() -> qld::Result<()> {
    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(),
    );

    // `-M` and `--cref`, into a string instead of standard output.
    options.print_map = true;
    options.cref = true;
    let map = Arc::new(Mutex::new(String::new()));
    let collected = Arc::clone(&map);
    options.map_output = Some(TextOutput::new(move |text| {
        collected.lock().unwrap().push_str(text);
    }));

    let image = qld::link_to_memory(&options, &Collect::new())?;
    let map = map.lock().unwrap();
    println!("linked {} bytes, {} of map", image.len(), map.len());
    for line in map.lines().take(8) {
        println!("  {line}");
    }

    // What the same options would take from the process, if asked.
    let mut as_the_binary = options.clone();
    as_the_binary.use_process_defaults();
    println!(
        "\nhermetic: map_output {}, LD_LIBRARY_PATH {} entries, timing {}",
        if options.map_output.is_some() {
            "set by this program"
        } else {
            "unset"
        },
        options.env_library_path.len(),
        if options.timing.is_some() {
            "on"
        } else {
            "off"
        },
    );
    println!(
        "as the binary: LD_LIBRARY_PATH {} entries, timing {}",
        as_the_binary.env_library_path.len(),
        if as_the_binary.timing.is_some() {
            "on"
        } else {
            "off"
        },
    );
    Ok(())
}

pub fn output_complete(&self)

Runs the on_output_complete hook, if there is one and it has not run yet.

Link drivers call this once the output of a successful link is complete, and crate::link calls it before returning Ok for drivers that did not.

pub fn check_cancelled(&self) -> Result<()>

Returns an error if the link was cancelled through LinkOptions::cancel. Link drivers call this between stages.

Errors

CancelToken::error once the token is cancelled.

pub fn output_path(&self) -> PathBuf

Returns the output path, or the flavor’s default.

pub fn is_pic(&self) -> bool

Whether the output is position-independent.

pub fn is_dynamic(&self) -> bool

Whether the output links against shared libraries at run time.

pub fn push_input(&mut self, kind: InputKind, attrs: InputAttrs)

Appends an input with the given attributes.

Examples found in repository

examples/rayon_pool.rs (lines 25-28)

fn link(value: u8) -> qld::Result<Vec<u8>> {
    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(value)),
        InputAttrs::default(),
    );
    let buffer = OutputBuffer::new();
    options.output_buffer = Some(buffer.clone());
    qld::link(&options, &Collect::new())?;
    buffer
        .take()
        .ok_or_else(|| qld::Error::Internal("no output".into()))
}

examples/custom_sink.rs (lines 94-97)

fn main() {
    // `main.o` calls `answer`, which nothing defines.
    let mut options = LinkOptions::new();
    options.kind = OutputKind::StaticExecutable;
    options.output_buffer = Some(OutputBuffer::new());
    options.push_input(
        InputKind::bytes("main.o", objects::main_object()),
        InputAttrs::default(),
    );

    let sink = JsonLines::default();
    let result = qld::link(&options, &sink);
    print!("{}", sink.render());
    match result {
        Ok(()) => println!("linked"),
        Err(qld::Error::Reported { errors }) => {
            println!("the link failed with {errors} error(s) reported above");
        }
        Err(error) => println!("the link failed: {error}"),
    }
}

examples/link_map.rs (lines 26-29)

fn main() -> qld::Result<()> {
    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(),
    );

    // `-M` and `--cref`, into a string instead of standard output.
    options.print_map = true;
    options.cref = true;
    let map = Arc::new(Mutex::new(String::new()));
    let collected = Arc::clone(&map);
    options.map_output = Some(TextOutput::new(move |text| {
        collected.lock().unwrap().push_str(text);
    }));

    let image = qld::link_to_memory(&options, &Collect::new())?;
    let map = map.lock().unwrap();
    println!("linked {} bytes, {} of map", image.len(), map.len());
    for line in map.lines().take(8) {
        println!("  {line}");
    }

    // What the same options would take from the process, if asked.
    let mut as_the_binary = options.clone();
    as_the_binary.use_process_defaults();
    println!(
        "\nhermetic: map_output {}, LD_LIBRARY_PATH {} entries, timing {}",
        if options.map_output.is_some() {
            "set by this program"
        } else {
            "unset"
        },
        options.env_library_path.len(),
        if options.timing.is_some() {
            "on"
        } else {
            "off"
        },
    );
    println!(
        "as the binary: LD_LIBRARY_PATH {} entries, timing {}",
        as_the_binary.env_library_path.len(),
        if as_the_binary.timing.is_some() {
            "on"
        } else {
            "off"
        },
    );
    Ok(())
}

examples/cancel.rs (lines 66-69)

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 (lines 33-36)

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(())
}

pub fn resolve_sysroot(&self, path: &Path) -> PathBuf

Resolves a path that may start with = or $SYSROOT against LinkOptions::sysroot, as GNU ld does for -L, -T, -rpath-link and script INPUTs.

Paths without the prefix are returned unchanged. When there is no sysroot the prefix is simply removed. This is a pure string operation; it does not touch the file system.

Trait Implementations

impl Clone for LinkOptions

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LinkOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LinkOptions

fn default() -> Self

Identical to LinkOptions::new.