Relink: Rust ELF Loader and Runtime/JIT Linker

Relink loads ELF images from files or memory and performs dynamic loading, dependency resolution, relocation, and symbol lookup. It fits plugin systems, JIT and hot-reload flows, isolated link contexts, scan-first layout optimization, kernels, and embedded runtimes when dlopen is too rigid.

Use Cases

• Load plugins, JIT artifacts, or hot-update modules at runtime with custom dependency resolution and symbol scopes.
• Scan dependencies and sections before mapping, then use --emit-relocs to reorder layout, pack hot code, use huge pages, or run custom passes.
• Keep ELF scanning, mapping, and relocation available in no_std, kernel, embedded, or custom mmap environments.
• Scan, rewrite, and load images with different ELF layouts, ABIs, or target architectures.
• Compose shared objects, executable images, and relocatable objects in one loading flow.

What It Loads

• Shared objects / dynamic libraries (ET_DYN)
• Executables and PIE-style images (ET_EXEC, plus executable-style ET_DYN)
• Relocatable object files (ET_REL) when the object feature is enabled
• File-backed or in-memory inputs via &str, String, &[u8], Vec<u8>, ElfFile, and ElfBinary

Use Loader::load() when you want automatic ELF type detection. Use load_dylib(), load_exec(), or load_object() when you want strict type checks.

Core Capabilities

Compared With dlopen

Quick Start

The default feature set is suitable for loading dynamic libraries, executables, and handling TLS:

[dependencies]
elf_loader = "0.15.0"

To enable the common advanced features in one bundle:

[dependencies]
elf_loader = { version = "0.15.1", features = ["full"] }

Load a Dynamic Library and Call a Symbol

use elf_loader::{
    image::{SyntheticModule, SyntheticSymbol},
    Loader, Result,
};

extern "C" fn host_double(value: i32) -> i32 {
    value * 2
}

fn main() -> Result<()> {
    let lib = Loader::new()
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .scope([SyntheticModule::new(
            "__host",
            [SyntheticSymbol::function("host_double", host_double as *const ())],
        )])
        .relocate()?;

    let run = unsafe {
        lib.get::<extern "C" fn(i32) -> i32>("run")
            .expect("symbol `run` not found")
    };
    assert_eq!(run(21), 42);

    Ok(())
}

Loading Paths

Advanced Capability Index

Dynamic link-time layout optimization usually requires the target ELF to retain relocation information, for example by passing -Wl,--emit-relocs to the linker. Scan-first passes can inspect sections, modify data, adjust materialization, and place code, read-only data, writable data, or TLS into different arenas before mapping.

Benchmarks

The table below is a GitHub Actions snapshot, not a universal performance claim. It is meant as a reproducible reference point for the current benchmark suite; run cargo bench on your target environment for numbers that matter to your workload. Full environment details are in actions/runs/25632675040/job/75239090388, and the fixture is the repository's libc -> libb -> liba test chain, not the system C library.

Lower is better for loading. scan_first includes dependency scanning and section-region planning, so it is a planning-path cost rather than a direct dlopen replacement.

Symbol lookup was measured after both loaders had already loaded the fixture chain:

Feature Flags

Notes:

• The default features are tls + libc.
• Compiling with tls is not enough by itself for TLS-using modules. Start from Loader::new().with_default_tls_resolver() or provide your own TLS resolver when loading ELF objects that require TLS relocations.
• load_object() is feature-gated. cargo run --example load_object will fail under the default feature set unless you add --features object.

Examples

The examples/ directory covers the main extension points:

Platform Notes

Legend: ✅ supported, 🟡 basic support, ⏳ pending. Complex section-reorder repair and .o / ET_REL support are currently centered on x86_64 relocation handling; contributions for the other architectures are welcome.

Symbol lookup is name-based and does not perform Rust name mangling for you. Export C ABI symbols when you want stable runtime lookup names.

Contributing

Issues and pull requests are welcome, especially around platform support, examples, and diagnostics. Star the project if it is useful in your work.

License

This project is dual-licensed under either of the following:

• MIT License
• Apache License 2.0

Contributors