arceos-helloworld

A standalone Hello World application running on ArceOS unikernel, with all dependencies sourced from crates.io. Supports multiple architectures via cargo xtask.

Supported Architectures

Prerequisites

• Rust nightly toolchain (edition 2024)

  rustup install nightly
  rustup default nightly
  

• Bare-metal targets (install the ones you need)

  rustup target add riscv64gc-unknown-none-elf
  rustup target add aarch64-unknown-none-softfloat
  rustup target add x86_64-unknown-none
  rustup target add loongarch64-unknown-none
  

• QEMU (install the emulators for your target architectures)

  # Ubuntu/Debian
  sudo apt install qemu-system-riscv64 qemu-system-aarch64 \
                   qemu-system-x86 qemu-system-loongarch64  # OR qemu-systrem-misc
  
  # macOS (Homebrew)
  brew install qemu
  

• rust-objcopy (from cargo-binutils, required for non-x86_64 targets)

  cargo install cargo-binutils
  rustup component add llvm-tools
  

Quick Start

# install cargo-clone sub-command
cargo install cargo-clone 
# get source code of arceos-helloworld crate from crates.io
cargo clone arceos-helloworld
# into crate dir
cd arceos-helloworld
# Build and run on RISC-V 64 QEMU (default)
cargo xtask run

# Build and run on other architectures
cargo xtask run --arch aarch64
cargo xtask run --arch x86_64
cargo xtask run --arch loongarch64

# Build only (no QEMU)
cargo xtask build --arch riscv64
cargo xtask build --arch aarch64

Expected output (riscv64 example):

       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       # cargo xtask alias & AX_CONFIG_PATH
├── xtask/
│   ├── Cargo.toml        # xtask build tool (clap CLI)
│   └── src/
│       └── main.rs       # build/run subcommand implementation
├── configs/
│   ├── riscv64.toml      # Platform config for RISC-V 64 QEMU virt
│   ├── aarch64.toml      # Platform config for AArch64 QEMU virt
│   ├── x86_64.toml       # Platform config for x86-64 PC
│   └── loongarch64.toml  # Platform config for LoongArch64 QEMU virt
├── src/
│   └── main.rs           # Application entry point
├── build.rs              # Linker script path setup (auto-detects arch)
├── Cargo.toml            # Dependencies (axstd from crates.io)
└── README.md

How It Works

The cargo xtask pattern uses a host-native helper crate (xtask/) to orchestrate cross-compilation and QEMU execution:

1. cargo xtask build --arch <ARCH>

   • Copies configs/<ARCH>.toml to .axconfig.toml (platform configuration)
   • Runs cargo build --release --target <TARGET>
   • build.rs auto-detects the architecture and locates the correct linker script

2. cargo xtask run --arch <ARCH>

   • Performs the build step above
   • Converts ELF to raw binary via rust-objcopy (except x86_64 which uses ELF directly)
   • Launches the appropriate QEMU emulator with architecture-specific flags

Key Components

License

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