arceos-helloworld 0.2.1

A simple helloworld crate (from crates.io) for ArceOS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

# arceos-helloworld

A standalone Hello World application running on [ArceOS](https://github.com/arceos-org/arceos) unikernel, with all dependencies sourced from [crates.io](https://crates.io). No local patches or monorepo required.

## Prerequisites

- **Rust nightly toolchain** (edition 2024)

  ```bash
  rustup install nightly
  rustup default nightly
  ```

- **RISC-V bare-metal target**

  ```bash
  rustup target add riscv64gc-unknown-none-elf
  ```

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

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

  # macOS (Homebrew)
  brew install qemu
  ```

- **rust-objcopy** (from `cargo-binutils`)

  ```bash
  cargo install cargo-binutils
  rustup component add llvm-tools
  ```

## Quick Start

```bash
cargo install cargo-clone
cargo clone 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