Add Asterinas NixOS to README and the Book
This commit is contained in:
Tate, Hongliang Tian
Tate, Hongliang Tian
parent
cf0ae116b0
commit
55c1aa7d40
40
README.md
40
README.md
|
|
@ -52,37 +52,57 @@ we are steadfastly progressing towards this goal.
|
|||
Over the course of 2024,
|
||||
we significantly enhanced Asterinas's maturity,
|
||||
as detailed in [our end-year report](https://asterinas.github.io/2025/01/20/asterinas-in-2024.html).
|
||||
By the end of 2025,
|
||||
we plan to launch [Asterinas NixOS](https://asterinas.github.io/book/rfcs/0002-asterinas-nixos.html),
|
||||
the first distribution for Asterinas.
|
||||
This release will mark Asterinas reaching the Minimum Viable Product (MVP) milestone.
|
||||
In December 2025,
|
||||
we launched [Asterinas NixOS](https://asterinas.github.io/book/distro/index.html),
|
||||
an Asterinas distribution based on [NixOS](https://nixos.org/).
|
||||
This release marks Asterinas reaching the Minimum Viable Product (MVP) milestone.
|
||||
In 2026, we aim to make Asterinas production-ready on x86-64 virtual machines and attract real users.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Get yourself an x86-64 Linux machine with Docker installed.
|
||||
Follow the three simple steps below to get Asterinas up and running.
|
||||
### For End Users
|
||||
|
||||
1. Download the latest source code.
|
||||
We provide [Asterinas NixOS ISO Installer](https://github.com/asterinas/asterinas/releases)
|
||||
to make the Asterinas kernel more accessible for early adopters and enthusiasts.
|
||||
We encourage you to try out Asterinas NixOS and share feedback.
|
||||
Instructions on how to use the ISO installer can be found [here](https://asterinas.github.io/book/distro/index.html#end-users).
|
||||
|
||||
### For Kernel Developers
|
||||
|
||||
Follow the steps below to get Asterinas up and running.
|
||||
|
||||
1. Download the latest source code on an x86-64 Linux machine:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/asterinas/asterinas
|
||||
```
|
||||
|
||||
2. Run a Docker container as the development environment.
|
||||
2. Run a Docker container as the development environment:
|
||||
|
||||
```bash
|
||||
docker run -it --privileged --network=host -v /dev:/dev -v $(pwd)/asterinas:/root/asterinas asterinas/asterinas:0.16.2-20251211
|
||||
```
|
||||
|
||||
3. Inside the container, go to the project folder to build and run Asterinas.
|
||||
3. Inside the container,
|
||||
go to the project folder (`/root/asterinas`) and run:
|
||||
|
||||
```bash
|
||||
make kernel
|
||||
make run_kernel
|
||||
```
|
||||
|
||||
If everything goes well, Asterinas is now up and running inside a VM.
|
||||
This results in a VM running the Asterinas kernel with a small initramfs.
|
||||
|
||||
4. To install and test real-world applications on Asterinas,
|
||||
build and run Asterinas NixOS in a VM:
|
||||
|
||||
```bash
|
||||
make nixos
|
||||
make run_nixos
|
||||
```
|
||||
|
||||
This boots into an interactive shell in Asterinas NixOS,
|
||||
where you can use Nix to install and try more packages.
|
||||
|
||||
## The Book
|
||||
|
||||
|
|
|
|||
|
|
@ -10,9 +10,17 @@ focused on developing cutting-edge Rust OS kernels.
|
|||
|
||||
## Book Structure
|
||||
|
||||
This book is divided into five distinct parts:
|
||||
This book is divided into six distinct parts:
|
||||
|
||||
#### [Part 1: Asterinas Kernel](kernel/)
|
||||
#### [Part 1: Asterinas NixOS](distro/)
|
||||
|
||||
Asterinas NixOS is the first distribution built on top of the Asterinas kernel.
|
||||
It is based on NixOS,
|
||||
leveraging its powerful configuration model
|
||||
and rich package ecosystem,
|
||||
while swapping out the Linux kernel for Asterinas.
|
||||
|
||||
#### [Part 2: Asterinas Kernel](kernel/)
|
||||
|
||||
Explore the modern OS kernel at the heart of Asterinas.
|
||||
Designed to realize the full potential of Rust,
|
||||
|
|
@ -20,7 +28,7 @@ Asterinas Kernel implements the Linux ABI in a safe and efficient way.
|
|||
This means it can seamlessly replace Linux,
|
||||
offering enhanced safety and security.
|
||||
|
||||
#### [Part 2: Asterinas OSTD](ostd/)
|
||||
#### [Part 3: Asterinas OSTD](ostd/)
|
||||
|
||||
The Asterinas OSTD lays down a minimalistic, powerful, and solid foundation
|
||||
for OS development.
|
||||
|
|
@ -28,7 +36,7 @@ It's akin to Rust's `std` crate
|
|||
but crafted for the demands of _safe_ Rust OS development.
|
||||
The Asterinas Kernel is built on this very OSTD.
|
||||
|
||||
#### [Part 3: Asterinas OSDK](osdk/guide/)
|
||||
#### [Part 4: Asterinas OSDK](osdk/guide/)
|
||||
|
||||
The OSDK is a command-line tool
|
||||
that streamlines the workflow to
|
||||
|
|
@ -38,14 +46,14 @@ Developed specifically for OS developers,
|
|||
it extends Rust's Cargo tool to better suite their specific needs.
|
||||
OSDK is instrumental in the development of Asterinas Kernel.
|
||||
|
||||
#### [Part 4: Contributing to Asterinas](to-contribute/)
|
||||
#### [Part 5: Contributing to Asterinas](to-contribute/)
|
||||
|
||||
Asterinas is in its early stage
|
||||
and welcomes your contributions!
|
||||
This part provides guidance
|
||||
on how you can become an integral part of the Asterinas project.
|
||||
|
||||
#### [Part 5: Requests for Comments (RFCs)](rfcs/)
|
||||
#### [Part 6: Requests for Comments (RFCs)](rfcs/)
|
||||
|
||||
Significant decisions in Asterinas are made through a transparent RFC process.
|
||||
This part describes the RFC process
|
||||
|
|
|
|||
|
|
@ -2,6 +2,10 @@
|
|||
|
||||
[Introduction](README.md)
|
||||
|
||||
# Asterinas NixOS
|
||||
|
||||
* [Getting Started](distro/README.md)
|
||||
|
||||
# Asterinas Kernel
|
||||
|
||||
* [Getting Started](kernel/README.md)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,156 @@
|
|||
# Asterinas NixOS
|
||||
|
||||
Asterinas NixOS is the first distribution for Asterinas.
|
||||
We choose [NixOS](https://nixos.org/) as the base OS
|
||||
for its unparalleled customizability and rich package ecosystem.
|
||||
Asterinas NixOS is intended to look and feel like vanilla NixOS,
|
||||
except that it replaces Linux with Asterinas as its kernel.
|
||||
For more rationale about choosing NixOS,
|
||||
see [the RFC](https://asterinas.github.io/book/rfcs/0002-asterinas-nixos.html).
|
||||
|
||||
Asterinas NixOS is not ready for production use.
|
||||
We provide Asterinas NixOS to make the Asterinas kernel more accessible,
|
||||
allowing early adopters and enthusiasts to try it out and provide feedback.
|
||||
In addition, Asterinas developers use this distro
|
||||
as a key development vehicle
|
||||
to facilitate enabling and testing more real-world applications
|
||||
on the Asterinas kernel.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### End Users
|
||||
|
||||
The following instructions describe how to install Asterinas NixOS in a VM
|
||||
using the Asterinas NixOS installer ISO.
|
||||
|
||||
1. Launch an x86-64 Ubuntu container:
|
||||
|
||||
```bash
|
||||
docker run -it --privileged --network=host ubuntu:latest bash
|
||||
```
|
||||
|
||||
2. Inside the container, install QEMU:
|
||||
|
||||
```bash
|
||||
apt update
|
||||
apt install -y qemu-system-x86 qemu-utils
|
||||
```
|
||||
|
||||
3. Download the latest Asterinas NixOS installer ISO from [GitHub Releases](https://github.com/asterinas/asterinas/releases).
|
||||
|
||||
4. Create a file that will be used as the target disk to install Asterinas NixOS:
|
||||
|
||||
```bash
|
||||
# The capacity of the disk is 10GB; adjust it as you see fit
|
||||
dd if=/dev/zero of=aster_nixos_disk.img bs=1G count=10
|
||||
```
|
||||
|
||||
5. Start an x86-64 VM with two drives:
|
||||
one is the installer CD-ROM and the other is the target disk:
|
||||
|
||||
```bash
|
||||
export INSTALLER_ISO=/path/to/your/downloaded/installer.iso
|
||||
qemu-system-x86_64 \
|
||||
-cpu host -m 8G -enable-kvm \
|
||||
-drive file="$INSTALLER_ISO",media=cdrom -boot d \
|
||||
-drive if=virtio,format=raw,file=aster_nixos_disk.img \
|
||||
-chardev stdio,id=mux,mux=on,logfile=qemu.log \
|
||||
-device virtio-serial-pci -device virtconsole,chardev=mux \
|
||||
-serial chardev:mux -monitor chardev:mux \
|
||||
-nographic
|
||||
```
|
||||
|
||||
After the VM boots, you now have access to the installation environment.
|
||||
|
||||
6. Edit the `configuration.nix` file in the home directory
|
||||
to customize the NixOS system to be installed:
|
||||
|
||||
```bash
|
||||
vim configuration.nix
|
||||
```
|
||||
|
||||
The complete syntax and guidance for the `configuration.nix` file
|
||||
can be found in [the NixOS manual](https://nixos.org/manual/nixos/stable/#ch-configuration).
|
||||
If you are not familiar with NixOS,
|
||||
you can simply skip this step.
|
||||
|
||||
Not all combinations of settings in `configuration.nix` are supported by Asterinas NixOS yet.
|
||||
The ones that have been tested are documented in the subsequent chapters.
|
||||
|
||||
7. Start installation:
|
||||
|
||||
```bash
|
||||
install_aster_nixos.sh --config configuration.nix --disk /dev/vda --force-format-disk
|
||||
```
|
||||
|
||||
The installation process involves downloading packages
|
||||
and may take around 30 minutes to complete,
|
||||
depending on your network speed.
|
||||
|
||||
8. After the installation is complete, you can shut down the VM:
|
||||
|
||||
```bash
|
||||
poweroff
|
||||
```
|
||||
|
||||
Now Asterinas NixOS is installed in `aster_nixos_disk.img`.
|
||||
|
||||
9. Start a VM to boot the newly installed Asterinas NixOS:
|
||||
|
||||
```bash
|
||||
qemu-system-x86_64 \
|
||||
-cpu host -m 8G -enable-kvm \
|
||||
-bios /usr/share/qemu/OVMF.fd \
|
||||
-drive if=none,format=raw,id=x0,file=aster_nixos_disk.img \
|
||||
-device virtio-blk-pci,drive=x0,disable-legacy=on,disable-modern=off \
|
||||
-chardev stdio,id=mux,mux=on,logfile=qemu.log \
|
||||
-device virtio-serial-pci -device virtconsole,chardev=mux \
|
||||
-serial chardev:mux -monitor chardev:mux \
|
||||
-device virtio-net-pci,netdev=net0,disable-legacy=on,disable-modern=off \
|
||||
-netdev user,id=net0 \
|
||||
-device isa-debug-exit,iobase=0xf4,iosize=0x04 \
|
||||
-nographic -display vnc=127.0.0.1:21
|
||||
```
|
||||
|
||||
If a desktop environment is enabled in the `configuration.nix` file,
|
||||
you can view the graphical interface using a VNC client.
|
||||
|
||||
### Kernel Developers
|
||||
|
||||
1. Download the latest source code on an x86-64 Linux machine:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/asterinas/asterinas
|
||||
```
|
||||
|
||||
2. Run a Docker container as the development environment:
|
||||
|
||||
```bash
|
||||
docker run -it --privileged --network=host -v /dev:/dev -v $(pwd)/asterinas:/root/asterinas asterinas/asterinas:0.16.2-20251211
|
||||
```
|
||||
|
||||
3. Inside the Docker container,
|
||||
generate a disk image with Asterinas NixOS installed using this command:
|
||||
|
||||
```bash
|
||||
make nixos
|
||||
```
|
||||
|
||||
or this command:
|
||||
|
||||
```bash
|
||||
make iso && make run_iso
|
||||
```
|
||||
|
||||
The difference between the two methods is that
|
||||
the first installs NixOS to a disk image entirely inside the container,
|
||||
whereas the second emulates the manual ISO installation steps
|
||||
(see the [previous section](#end-users))
|
||||
by running a VM.
|
||||
Using either method results in a disk image with an Asterinas NixOS installation.
|
||||
|
||||
4. Start a VM to run the installed Asterinas NixOS:
|
||||
|
||||
```bash
|
||||
make run_nixos
|
||||
```
|
||||
Loading…
Reference in New Issue