arceos-helloworld 0.2.0

A simple helloworld crate (from crates.io) for ArceOS
arceos-helloworld-0.2.0 is not a library.

arceos-helloworld

A standalone Hello World application running on ArceOS unikernel, with all dependencies sourced from crates.io. No local patches or monorepo required.

Prerequisites

  • Rust nightly toolchain (edition 2024)

    rustup install nightly
rustup default nightly

  • RISC-V bare-metal target

    rustup target add riscv64gc-unknown-none-elf

  • QEMU (RISC-V 64-bit system emulator)

    # Ubuntu/Debian
sudo apt install qemu-system-riscv64

# macOS (Homebrew)
brew install qemu

  • rust-objcopy (from cargo-binutils)

    cargo install cargo-binutils
rustup component add llvm-tools

Quick Start

cargo source arceos-helloworld # get source code from crates.io
cd arceos-helloworld
cargo run --release # run

This last single command will:

  1. Fetch all ArceOS crates from crates.io (axstd, axruntime, axhal, etc.)
  2. Build the kernel binary for riscv64gc-unknown-none-elf
  3. Convert the ELF to a raw binary via rust-objcopy
  4. Launch QEMU and boot the kernel

Expected output:

       d8888                            .d88888b.   .d8888b.
      d88888                           d88P" "Y88b d88P  Y88b
     ...
d88P     888 888      "Y8888P  "Y8888   "Y88888P"   "Y8888P"

arch = riscv64
platform = riscv64-qemu-virt
...
smp = 1

Hello, world!

QEMU will automatically exit after printing the message.

Project Structure

app-helloworld/
├── .cargo/
│   └── config.toml    # Build target & QEMU runner configuration
├── src/
│   └── main.rs        # Application entry point
├── build.rs           # Linker script path setup
├── run_qemu.sh        # QEMU launch script (used as Cargo runner)
├── Cargo.toml         # Dependencies (axstd from crates.io)
└── README.md

How It Works

Component Role
axstd ArceOS standard library (replaces Rust's std in no_std environment)
axhal Hardware abstraction layer, generates the linker script at build time
axplat-riscv64-qemu-virt RISC-V QEMU virt board platform support
axruntime Kernel initialization and runtime setup
build.rs Locates the linker script generated by axhal and passes it to the linker
run_qemu.sh Converts ELF to raw binary and launches QEMU
.cargo/config.toml Sets the build target to riscv64gc-unknown-none-elf and registers the QEMU runner

Configuration

The QEMU virtual machine is configured with:

  • Memory: 128 MB
  • CPUs: 1
  • Machine: virt
  • BIOS: default (OpenSBI)

These settings can be adjusted in run_qemu.sh.

License

GPL-3.0-or-later OR Apache-2.0 OR MulanPSL-2.0