Rust programs

terse build hello.rs builds a Rust program with rustc and the runtime terse.rs (programs/lib/rust), built into terse. This article says what it runs, what the runtime gives, what things cost, and how to build a larger program with cargo. programs/hello-rs/hello.rs is the hello program in Rust.

A program

A Rust program is a #![no_std], #![no_main] crate root that names its main function with terse::entry!:

#![no_std]
#![no_main]
use terse::*;
entry!(main);

fn main() {
    term_puts("Hello from Rust\n");
    loop {
        wait_frame();
    }
}

What it runs

rustc --edition 2024 --target riscv32imc-unknown-none-elf \
    -C opt-level=s -Cpanic=abort --remap-path-prefix=<lib>/= \
    --crate-type rlib --crate-name terse \
    -o <tmp>/libterse.rlib <lib>/terse.rs
rustc --edition 2024 --target riscv32imc-unknown-none-elf \
    -C opt-level=s -Cpanic=abort --remap-path-prefix=<lib>/= \
    -C lto -C strip=debuginfo --crate-type bin \
    --crate-name hello -C link-arg=-T<lib>/terse.ld \
    --extern terse=<tmp>/libterse.rlib -o out.elf hello.rs

then the ROM and terse pack as for C (see "Building a program").

FlagWhy
--edition 2024rustc's own default is the 2015 edition
--target riscv32imc-unknown-none-elfRust's target for exactly RV32IMC with no operating system (core and alloc, no std)
-C opt-level=ssmall code, as -Os for C
-Cpanic=abortno unwinding: a panic goes straight to the runtime's panic handler
--remap-path-prefix=<lib>/=panic messages name terse.rs, not the temporary directory, so the same source gives the same image
--crate-type rlib --crate-name tersethe runtime is an ordinary library crate, used as terse
-C ltolink-time optimisation across the program, the runtime and core: about 12% smaller for hello
-C strip=debuginfocore comes with debug information; it never reaches the ROM, but it makes the ELF file large
-C link-arg=-T<lib>/terse.ldthe same memory map as C; rustc links with rust-lld and passes --gc-sections itself
--extern terse=...the runtime, so the program can say use terse::*;

The runtime, terse.rs

One file, about 590 lines, the counterpart of crt0.S, terse.h and terse.c for the program profile:

The devices outside the program profile (content, the page, sound, the 3D display, machines) are not in the runtime; reach their calls with call and the numbers of the call table (The Terse32 machine; terse.h has them all).

What things cost

Measured with rustc 1.100 and clang 23:

ProgramROM
hello in assembly, hello.S898 bytes
hello in C, hello.c1,288 bytes
hello in Rust, hello.rs1,716 bytes
terse new starter: C, Rust, assembly347, 229, 123 bytes
Rust, one write! of two integersabout 1.9 KiB in all
Rust, one f32 formatted with {:.3}about 23 KiB in all

A larger program with cargo

For several crates, or crates from crates.io that support no_std, use cargo with the runtime as a path dependency. The files, with terse.rs and terse.ld from terse build --write-lib:

game/Cargo.toml
game/.cargo/config.toml
game/terse-rt/Cargo.toml   package "terse", lib path terse.rs
game/terse-rt/terse.rs
game/terse.ld
game/src/main.rs           #![no_std] #![no_main] ...

Cargo.toml:

[package]
name = "game"
version = "0.1.0"
edition = "2024"

[dependencies]
terse = { path = "terse-rt" }

[profile.release]
opt-level = "s"
lto = true
panic = "abort"
debug = false

[profile.dev]
panic = "abort"

.cargo/config.toml:

[build]
target = "riscv32imc-unknown-none-elf"

[target.riscv32imc-unknown-none-elf]
rustflags = ["-C", "link-arg=-Tterse.ld"]

Then:

cargo build --release
llvm-objcopy -O binary \
    target/riscv32imc-unknown-none-elf/release/game game.bin
terse pack --rom game.bin --title game --ram-pages 4 \
    --device 2:0 --device 3:0 -o game.terse

The linker script's path is relative to the package's root, where cargo runs the linker. This gives the same ROM as terse build for the same source (checked with hello.rs). A debug build (opt-level = 0) works but is far larger and slower: 11,701 bytes of ROM for hello instead of 1,716, and a larger program may not fit in 128 KiB of ROM or in a frame's budget.

Next: Building by hand, and other languages.