From 55c1aa7d40a17afb671b54c1d1a62daee378950e Mon Sep 17 00:00:00 2001 From: "Tate, Hongliang Tian" Date: Sat, 13 Dec 2025 15:49:05 +0800 Subject: [PATCH] Add Asterinas NixOS to README and the Book --- README.md | 40 +++++++--- book/src/README.md | 20 +++-- book/src/SUMMARY.md | 4 + book/src/distro/README.md | 156 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 204 insertions(+), 16 deletions(-) create mode 100644 book/src/distro/README.md diff --git a/README.md b/README.md index f91e2b96e..134b9ce6e 100644 --- a/README.md +++ b/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 diff --git a/book/src/README.md b/book/src/README.md index 86ce7068e..d3c5528b1 100644 --- a/book/src/README.md +++ b/book/src/README.md @@ -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 diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 81c2bb76e..727fe23e2 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,6 +2,10 @@ [Introduction](README.md) +# Asterinas NixOS + +* [Getting Started](distro/README.md) + # Asterinas Kernel * [Getting Started](kernel/README.md) diff --git a/book/src/distro/README.md b/book/src/distro/README.md new file mode 100644 index 000000000..93949850e --- /dev/null +++ b/book/src/distro/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 + ```