eyra 0.15.2

Rust programs written entirely in Rust
Documentation

Eyra is a package that supports building Rust programs implemented entirely in Rust.

It uses Origin for program and thread startup and shutdown, and c-gull for ABI-compatible libc functions.

Quick start

Check out this hello world example.

In detail

Eyra needs three things. First, a Cargo.toml dependency:

[dependencies]
eyra = "<current-version>"

The next step is to add an extern crate:

extern crate eyra;

fn main() {
    println!("Hello, world!");
}

This tells Rust that Eyra is actually used and the libraries should actually be linked in.

And finally, a build.rs file to add -nostartfiles to the link flags to disable the host startup code, so that Eyra can provide its own. build.rs:

fn main() {
    println!("cargo:rustc-link-arg=-nostartfiles");
}

With these three steps, this crate prints "Hello, world!". And under the covers, it uses Origin to start and stop the program, c-ward to handle libc calls from std, and rustix to do the printing, so it's completely implemented in Rust.

Optional logging

Eyra has a log feature to enable Rust log tracing of program and thread startup and shutdown, and an env_logger feature to install env_logger as the logger, which can be enabled in Cargo.toml:

[dependencies]
eyra = { version = "<current-version>", features = ["log", "env_logger"] }

With this, and setting the RUST_LOG environment variable to "trace", the hello world program output like this:

[TRACE origin::program] Program started
[TRACE origin::thread] Main Thread[Pid(51383)] initialized
[TRACE origin::program] Calling `.init_array`-registered function `0x55e86306bb80(1, 0x7ffd0f76aad8, 0x7ffd0f76aae8)`
[TRACE origin::program] Calling `origin_main(1, 0x7ffd0f76aad8, 0x7ffd0f76aae8)`
Hello, world!
[TRACE origin::program] `origin_main` returned `0`
[TRACE origin::thread] Thread[51383] calling `at_thread_exit`-registered function
[TRACE origin::thread] Thread[51383] calling `at_thread_exit`-registered function
[TRACE origin::program] Program exiting

Background

Eyra is similar to Mustang and uses the same underlying code, but instead of using a custom target and -Z build-std, Eyra just needs users to add -nostartfiles to their link line, such as via build.rs in the example.

Like Mustang, Eyra currently runs on Rust Nightly on Linux on x86-64, x86, aarch64, and riscv64. It aims to support all Linux versions supported by Rust, though at this time it's only tested on relatively recent versions. It's complete enough to run: