Struct Linker 

pub struct Linker { /* private fields */ }

A configured linker: a base address and an optional entry point.

Linker is the configurable form of link. Set the address the image is laid out from with base_address and the symbol execution starts at with entry, then call link. The defaults — base address 0, no entry point — are what the free link function uses, so reach for Linker only when you need to change one of them.

A linker holds no per-link state, so one instance links many sets of objects.

Examples

use linker_lang::{Linker, Object};

let mut obj = Object::new("o");
obj.section(".text", [0u8; 16]);
obj.define("_start", ".text", 0);

let image = Linker::new()
    .base_address(0x40_0000)
    .entry("_start")
    .link(&[obj])
    .expect("the entry point is defined");

assert_eq!(image.symbol("_start"), Some(0x40_0000));
assert_eq!(image.entry(), Some(0x40_0000));

Implementations

impl Linker

pub fn new() -> Self

Creates a linker with the default configuration: base address 0 and no entry point. Equivalent to Linker::default().

pub const fn base_address(self, address: u64) -> Self

Sets the address the first output section is placed at; later sections follow it.

Every resolved symbol address is relative to this base, so a non-zero base shifts the whole image — useful when the image will be loaded at a known address.

Examples

use linker_lang::{Linker, Object};

let mut obj = Object::new("o");
obj.section(".text", [0u8; 4]);
obj.define("f", ".text", 0);

let image = Linker::new().base_address(0x1000).link(&[obj]).unwrap();
assert_eq!(image.symbol("f"), Some(0x1000));

pub fn entry(self, symbol: impl Into<String>) -> Self

Sets the symbol whose address becomes the image’s entry.

The symbol must be defined by one of the linked objects; if it is not, the link fails with LinkError::UndefinedEntry. Without this, the image has no entry point.

Examples

use linker_lang::{Linker, Object};

let mut obj = Object::new("o");
obj.section(".text", [0u8; 4]);
obj.define("main", ".text", 0);

let image = Linker::new().entry("main").link(&[obj]).unwrap();
assert_eq!(image.entry(), Some(0));

pub fn link(&self, objects: &[Object]) -> Result<Image, LinkError>

Links objects into an Image.

The objects’ sections are merged by name, every symbol is resolved to an address, and every relocation is patched. The objects are consumed by reference and not modified.

Errors

Returns a LinkError if a symbol is defined twice, a relocation or the entry point names a symbol no object defines, a symbol or relocation names a section its object never created, a relocation’s slot runs past its section or its address does not fit the relocation width, or the laid-out image would exceed the address space.

Examples

use linker_lang::{Linker, Object, Width};

let mut code = Object::new("code");
code.section(".text", [0u8; 8]);
code.define("handler", ".text", 0);

let mut table = Object::new("table");
table.section(".data", [0u8; 8]);
table.relocate(".data", 0, "handler", Width::U64, 0);

let image = Linker::new().link(&[code, table]).unwrap();
let slot = image.section(".data").unwrap().data();
assert_eq!(u64::from_le_bytes(slot.try_into().unwrap()), 0); // patched with handler's address

Trait Implementations

impl Clone for Linker

fn clone(&self) -> Linker

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Linker

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

Formats the value using the given formatter.

impl Default for Linker

fn default() -> Linker

Returns the “default value” for a type.

impl Eq for Linker

impl PartialEq for Linker

fn eq(&self, other: &Linker) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Linker