Skip to content

About

Rust native application template for the Xila embedded operating system

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

Xila Native Rust app template — A Rust starter for your first native Xila application.

Documentation · Community

Build a small no_std Rust application for the Xila embedded OS. The starter prints a greeting and its arguments to stdout. Pass --fail as the first argument to print a diagnostic to stderr and return status 1. A normal run returns 0, and a stream write failure returns 2. The build produces a plain static-PIE ELF.

Requirements

Use an x86-64 Linux host with Git, Rustup, mise and Python 3 available to uv. Rustup selects the pinned nightly and installs rust-src, the target libraries and the lint tools from rust-toolchain.toml. The first build needs network access to fetch the toolchain, the pinned Core revision and Cargo dependencies. The guest build uses Rustup's bundled rust-lld.

Create your application

  1. Select Use this template on GitHub and clone your new repository, or clone this repository directly.
  2. Set the package name in Cargo.toml and run cargo generate-lockfile.
  3. Edit src/main.rs to implement your application.
  4. Replace the README header, .github/brand/ assets and README footer with your project's own material. Update the copyright holder in LICENSE for your own work and retain the template's MIT notice as required.

Build and check

Review the mise configuration before trusting it.

mise trust
mise run build
mise run check

The default output is target/x86_64-unknown-linux-gnu/release/hello. The filename follows the Cargo binary name. Set XILA_SDK_TARGET for both tasks to select another target.

XILA_SDK_TARGET=thumbv7em-none-eabihf mise run build
XILA_SDK_TARGET=thumbv7em-none-eabihf mise run check
Target Xila platform
x86_64-unknown-linux-gnu Linux x86-64 host loader
thumbv7em-none-eabihf Arm Cortex-M4F, hard float
riscv32imac-unknown-none-elf RV32IMAC, soft float

cargo xila-build and cargo xila-clippy enable the guest feature and apply .cargo/guest.toml. Cargo resolves that config path relative to the current directory, so run the aliases from the repository root (from a subdirectory they fail to read the file). Always pass --target with one of the targets above: without it, the guest linker options also apply to host build scripts, and the build fails at link time.

cargo xila-build --locked --release --target thumbv7em-none-eabihf
cargo xila-clippy --locked --release --target thumbv7em-none-eabihf -- -D warnings

Cargo's nightly build-std rebuilds core, alloc and compiler_builtins as position-independent code. Nightly also lets xila-sys/link forward the linker script and target arguments to the application. Keep the host test build separate with cargo test --locked and cargo clippy --locked --all-targets, which use the normal host sysroot without the guest feature. The ELF checker finds Core through locked Cargo metadata, so it checks against the same ABI revision used for the build. That needs xila-sys from a Git checkout of Core (a git dependency, or a [patch] entry pointing at a Core clone); a path or vendored copy has no checker next to it and mise run check reports that. The checker also fails when the rust-toolchain.toml channel differs from the nightly_version of Core at the pinned revision.

Editor setup

mod guest only exists with the guest feature, so rust-analyzer shows it as inactive by default. The repository ships .vscode/settings.json with "rust-analyzer.cargo.features": ["guest"]. In another editor, set the same option (rust-analyzer.cargo.features = ["guest"]). The host sysroot is enough for analysis: cargo clippy --locked --all-targets --features guest works without the guest sysroot. Real guest builds still go through cargo xila-build.

Run through Core's host loader

No released Xila build runs native executables yet. Platform support is tracked in xila-project/platforms#115. Today the x86-64 ELF runs through Core's host loader tests, which install the ELF in a test filesystem and launch it with the Xila ABI.

In a separate Core checkout at the revision pinned in Cargo.toml, add this test to libraries/executable/tests/sdk.rs. It uses the SDK test's existing setup, install and launch helpers.

#[task::test]
async fn runs_native_rust_template() {
    let (context, parent) = setup().await;
    let image = std::fs::read(std::env::var_os("XILA_TEMPLATE_ELF").unwrap()).unwrap();
    let path = "/hello";
    install(context.virtual_file_system, parent, path, &image).await;

    let (status, stdout, stderr) = launch(context, parent, path, "hello", &["world"]).await;
    assert_eq!(status, 0);
    assert_eq!(stdout, b"Hello from Rust on Xila!\narg: world\n");
    assert!(stderr.is_empty());
}

From that Core checkout, set the ELF path and run the focused test with Core's host prerequisites. Use Core's ci:packages-host mise task on Debian or Ubuntu, and install the Rust version from Core's mise.toml with Rustup.

XILA_TEMPLATE_ELF=/absolute/path/to/this/template/target/x86_64-unknown-linux-gnu/release/hello \
  cargo +1.97.0 test --locked -p xila-executable --features native-dev --test sdk -- runs_native_rust_template --exact

Update the SDK pin

Review a revision on Core's main and put its full SHA in the xila-sys rev in Cargo.toml. Set channel in rust-toolchain.toml to the nightly_version from that same revision's mise.toml.

Regenerate Cargo.lock, then build and check all targets before committing the pin. Fix any reported failure before proceeding.

cargo generate-lockfile
for target in x86_64-unknown-linux-gnu thumbv7em-none-eabihf riscv32imac-unknown-none-elf; do
  XILA_SDK_TARGET="$target" mise run build &&
    XILA_SDK_TARGET="$target" mise run check || break
done

Nanobom

To publish vulnerability reports, create a Nanobom project named after the lowercased GitHub repository. Set the Actions secret NANOBOM_TOKEN to its upload token and the Actions variable NANOBOM_ENABLED to true. For your own server or organization, set the Actions variables NANOBOM_URL and NANOBOM_ORGANIZATION to match the project. You can add the project's public badge to this README.

License

This template is released under the MIT License, except for the .github/brand/ header assets, which are covered by their own notice.


Part of Xila · Repositories · Community

Special thanks to Martin Legand for generously designing the Xila logo.

About

Rust native application template for the Xila embedded operating system

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages