Skip to main content

Rust System Vitals (Experimental)

View source on GitHub

This guide walks you through building and running the Rust system vitals reference on Avocado OS. The app cross-compiles a Rust binary that reads system stats from /proc and logs structured JSON to the journal.

Prerequisites​

  • macOS 10.12+ or Linux (Ubuntu 22.04+, Fedora 39+)
  • Docker Desktop installed and running
  • The latest version of the Avocado CLI

For hardware targets, you will also need:

  • Your target device and any required accessories (SD card, USB cable, serial console adapter)
  • See the Support Matrix for your target's requirements

Initialize​

Clone the reference or initialize a new project from it:

avocado init --reference rust-vitals rust-app
cd rust-app

To target specific hardware instead of the default, pass --target:

avocado init --reference rust-vitals --target raspberrypi5 rust-app
cd rust-app

Install​

Install the SDK toolchain, extension dependencies, and runtime packages:

avocado install -f

This pulls the SDK container image and installs the Rust cross-compilation toolchain: nativesdk-rust, nativesdk-cargo, packagegroup-rust-cross-canadian-avocado-<target>, and target libraries libstd-rs and libstd-rs-dev.

Build​

Build the extensions and assemble the runtime image:

avocado build

The build step runs rust-compile.sh inside the SDK container, which:

  1. Discovers the Rust target triple from RUST_TARGET_PATH (e.g., x86_64-avocado-linux-gnu)
  2. Clears SDK-injected RUSTFLAGS to avoid conflicts
  3. Generates .cargo/config.toml with the correct --sysroot and linker flags
  4. Runs cargo build --release --target $RUST_TARGET

Then rust-install.sh locates the cross-compiled binary and copies it to /usr/bin/ref_rust in the extension sysroot.

Deploy​

QEMU​

For QEMU targets, provision and boot the VM:

avocado provision -r dev
avocado sdk run -iE vm dev

SD card targets (Raspberry Pi, Seeed reTerminal, NXP, STMicroelectronics)​

Insert your SD card and provision:

avocado provision -r dev --profile sd

Insert the SD card into the device and apply power.

USB flash targets (OnLogic)​

avocado provision -r dev --profile usb

NVIDIA Jetson​

avocado provision -r dev --profile tegraflash

Follow the USB disconnect/reconnect prompts during the flash process.

Verify​

Log in as root with an empty password. The service starts automatically on boot.

Check the service is running:

systemctl status ref-rust
journalctl -u ref-rust -f

You should see output like:

{"hostname":"avocado-qemux86-64","uptime":42,"mem_total_kb":977972,"mem_free_kb":821488,"load_1m":"0.12"}

Customize​

Edit the Rust source​

Modify ref-rust/src/main.rs to change the vitals collected or the output format.

Add Cargo dependencies​

Edit ref-rust/Cargo.toml:

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Rebuild after changes​

After any change, rebuild and reprovision:

avocado build
avocado provision -r dev