Relink: Rust ELF Loader and Runtime Linker

Relink is a highly customizable, high-performance Rust ELF loading and runtime linking library. It can load .so files, executables, and object files from disk or memory, then resolve dependencies, apply relocations, and look up symbols. It also exposes observer hooks for load, relocation, symbol binding, and lifecycle events.

When To Use It

• Load plugins, JIT artifacts, or hot-reload modules at runtime.
• Control DT_NEEDED dependencies, symbol scopes, or relocation handling yourself.
• Track or customize load, relocation, symbol binding, and init/fini flow through observer hooks.
• Load ELF from memory, or plug in your own mmap or memory-management backend.
• Scan dependencies and sections first, then reorder layout, pack hot code, use huge pages, or run custom handling.
• Load relocatable ELF files such as .o / .ko.
• Keep ELF loading available in no_std, kernels, embedded systems, or non-standard runtimes.

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, for example .o / .ko)

Compared With dlopen

Quick Start

The default feature set is full. It includes the libc backend, relocatable-object loading, and the built-in native lazy binder:

[dependencies]
elf_loader = "0.17.0"

For a smaller build, disable default features and opt in only to what you need:

[dependencies]
elf_loader = { version = "0.17.0", default-features = false, features = ["libc"] }

Use Linker to Load Dependencies

use elf_loader::{
    LinkContext, Linker, Result,
    input::PathBuf,
    linker::SearchPathResolver,
    runtime::DomainId,
};

const LINKER: Linker = Linker::new();

fn main() -> Result<()> {
    let root = PathBuf::from("path/to/plugin.so");
    let mut context = LinkContext::<()>::new(DomainId::PROCESS);
    let mut resolver = SearchPathResolver::new();
    resolver.push_rpath();
    resolver.push_runpath();

    let loaded = LINKER
        .resolver(resolver)
        .run()
        .load(&mut context, root)?;

    let run = unsafe {
        context
            .module(loaded.root())?
            .get::<extern "C" fn() -> i32>("run")
            .expect("symbol `run` not found")
    };
    let _ = run();
    drop(loaded.release(&mut context)?);

    Ok(())
}

Benchmarks

The table below is a GitHub Actions performance snapshot. Use it only as a reference for the current test suite. Full environment details are in actions/runs/25632675040/job/75239090388. The fixture is the repository's leaf -> middle -> base test chain.

Lower is better for loading. scan_first includes dependency scanning and section planning, so it is not a direct dlopen replacement.

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

Feature Flags

Notes:

• TLS relocation and DefaultTlsResolver are always available; custom runtimes can provide their own resolver.
• Call Loader::with_default_tls_resolver() when native modules use TLS; Loader::new() starts with no TLS runtime.
• Custom LazyBinder implementations are always available; lazy-binding only adds NativeLazyBinder.
• Relocator::new() uses eager binding until a binder is configured with lazy_binder().
• The default feature set is full, equivalent to lazy-binding + object + libc.
• load_object() is still controlled by the object feature. Default builds include it; with --no-default-features, enable it explicitly.

Platform Support

Legend: ✅ supported, 🔧 basic support, 🚧 pending. Section-reorder repair is currently available on x86_64; .o / ET_REL relocation is available on x86_64 and riscv64. Contributions for the other architectures are welcome.

Xtensa currently supports dynamic relocation, but not lazy binding or TLS relocations.

Contributing

Issues and pull requests are welcome. 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