A unikernel operating system written in Rust.
RuxOS was inspired by Unikraft and ArceOS
π§ Working In Progress. See RuxOS Book for more information.
Example applications can be found in the apps/ directory. All applications must at least depend on the following modules, while other modules are optional:
The currently supported applications and programming languages, as well as their dependent modules and features, are shown in the following table:
App | Extra modules | Enabled features | Description |
---|---|---|---|
display | axalloc, ruxdisplay | alloc, paging, display | Graphic/GUI test |
shell | axalloc, ruxdriver, ruxfs | alloc, paging, fs | A simple shell that responds to filesystem operations |
App | Enabled features | Description |
---|---|---|
helloworld | A minimal app that just prints a string by C | |
envtest | alloc, paging | An environment variable test |
memtest | alloc, paging | Dynamic memory allocation test by C |
filetest | alloc, paging, fs, blkfs | File system operation test |
httpclient | alloc, paging, net | A simple client that sends an HTTP request and then prints the response by C |
httpserver | alloc, paging, net | A multi-threaded HTTP server that serves a static web page by C |
udpserver | alloc, paging, net | A simple UDP server that send back original message |
systime | rtc | A simple test for real time clock module |
basic | alloc, paging, multitask, irq | A simple test for basic pthread-related API in C standard library |
parallel | alloc, paging, multitask | Parallel computing test to test synchronization by C |
pipe | alloc, paging, multitask, pipe | A test for pipe API |
sleep | alloc, paging, multitask, irq | Thread sleeping test |
tsd | alloc, paging, multitask, irq | A test for pthread-key related API |
dl | paging, alloc, irq, musl, multitask, fs, pipe, poll, rtc, signal, virtio-9p | An example for dynamically loading apps |
libc-bench | alloc, multitask, fs, musl | A standard libc test for musl libc integration |
sqlite3 | alloc, paging, fs, fp_simd, blkfs | A simple test for Sqlite3 API |
iperf | alloc, paging, net, fs, blkfs, select, fp_simd | A network performance test tool |
redis | alloc, paging, fp_simd, irq, multitask, fs, blkfs, net, pipe, epoll, poll, virtio-9p, rtc | Redis server on Ruxos |
cpp | alloc, paging, irq, multitask, fs, random-hw | C++ benchmark |
nginx | alloc, paging, fp_simd, irq, multitask, fs, blkfs, net, pipe, epoll, poll, select, rtc, signal | Run Nginx as web server |
wamr | alloc, paging, fp_simd, irq, multitask, fs, virtio-9p, signal, smp | Wasm runtime |
Language | Description |
---|---|
C | Run C apps by RuxOS ruxlibc or standard musl libc supported by ruxmusl. Evaluated by libc-bench. |
C++ | Run C++ apps by c++ static library provided by musl libc. Passed c++ benchmark. Evaluated by c++ benchmark. |
Perl | Run Perl standard library by musl libc. Evaluated by Perl benchmark. |
Python | Run Python apps by dynamically loading Python modules. Evaluated by Python benchmark. |
Rust | Run Rust standard library by modifying Rust std source. Evaluated by Rust tests. |
Install cargo-binutils to use rust-objcopy
and rust-objdump
tools:
cargo install cargo-binutils
Install libclang-dev
:
sudo apt install libclang-dev
Download&Install cross-musl-based toolchains
:
# download
wget https://musl.cc/aarch64-linux-musl-cross.tgz
wget https://musl.cc/riscv64-linux-musl-cross.tgz
wget https://musl.cc/x86_64-linux-musl-cross.tgz
# install
tar zxf aarch64-linux-musl-cross.tgz
tar zxf riscv64-linux-musl-cross.tgz
tar zxf x86_64-linux-musl-cross.tgz
# exec below command in bash OR add below info in ~/.bashrc
export PATH=`pwd`/x86_64-linux-musl-cross/bin:`pwd`/aarch64-linux-musl-cross/bin:`pwd`/riscv64-linux-musl-cross/bin:$PATH
# in ruxos directory
make A=path/to/app ARCH=<arch> LOG=<log>
Where <arch>
should be one of riscv64
, aarch64
οΌx86_64
.
<log>
should be one of off
, error
, warn
, info
, debug
, trace
.
path/to/app
is the relative path to the example application.
More arguments and targets can be found in Makefile.
For example, to run the shell on qemu-system-aarch64
:
make A=apps/fs/shell ARCH=aarch64 LOG=info run BLK=y
Note that the BLK=y
argument is required to enable the block device in QEMU. These arguments (NET
, GRAPHIC
, etc.) only take effect at runtime not build time.
Create a new rust package with no_std
and no_main
environment.
Add axstd
dependency and features to enable to Cargo.toml
:
[dependencies]
axstd = { path = "/path/to/ruxos/ulib/axstd", features = ["..."] }
Call library functions from axstd
in your code, just like the Rust std library.
Build your application with RuxOS, by running the make
command in the application directory:
# in app directory
make -C /path/to/ruxos A=$(pwd) ARCH=<arch> run
# more args: LOG=<log> SMP=<smp> NET=[y|n] ...
All arguments and targets are the same as above.
Create axbuild.mk
and features.txt
in your project:
app/
βββ foo.c
βββ bar.c
βββ axbuild.mk # optional, if there is only one `main.c`
βββ features.txt # optional, if only use default features
Add build targets to axbuild.mk
, add features to enable to features.txt
(see this example):
# in axbuild.mk
app-objs := foo.o bar.o
# in features.txt
alloc
paging
net
Build your application with RuxOS, by running the make
command in the application directory:
# in app directory
make -C /path/to/ruxos A=$(pwd) ARCH=<arch> run
# more args: LOG=<log> SMP=<smp> NET=[y|n] ...
Set the PLATFORM
variable when run make
:
# Build helloworld for raspi4
make PLATFORM=aarch64-raspi4 A=apps/helloworld
You may also need to select the corrsponding device drivers by setting the FEATURES
variable:
# Build the shell app for raspi4, and use the SD card driver
make PLATFORM=aarch64-raspi4 A=apps/fs/shell FEATURES=driver-bcm2835-sdhci
# Build Redis for the bare-metal x86_64 platform, and use the ixgbe and ramdisk driver
make PLATFORM=x86_64-pc-oslab A=apps/c/redis FEATURES=driver-ixgbe,driver-ramdisk SMP=4
A convient tool to run RuxOS applications by concise command. See RuxGo-Book for more information.