Running in QEMU

Run SerenityOS in QEMU virtual machine

QEMU is the default and recommended way to run SerenityOS. The build system includes automated QEMU support for easy testing and development.

Prerequisites

QEMU 6.2 or later

Version 6.2 of QEMU is available in Ubuntu 22.04. On earlier versions of Ubuntu, you can build the recommended version of QEMU as provided by the toolchain.

1. Install QEMU dependencies

   Install the required development packages:

   sudo apt install libgtk-3-dev libpixman-1-dev libsdl2-dev libslirp-dev libspice-server-dev
   
2. Build QEMU from toolchain

   If your distribution’s QEMU version is older than 6.2:

   Toolchain/BuildQemu.sh
   

Running SerenityOS

The simplest way to build and run SerenityOS in QEMU:

Meta/serenity.sh run

This command will:

• Compile all of SerenityOS
• Install built files into Build/<architecture>/Root
• Build a disk image
• Start SerenityOS using QEMU

The chosen architecture defaults to your host architecture. Supported architectures are x86_64, aarch64, and riscv64.

First Build

The first time you run the build command, it will:

• Download required database files from the internet
• Build the SerenityOS cross-compiler toolchain

Subsequent builds will be much faster as these steps only need to be done once.

Default Credentials

By default, the anon user account’s password is: foo

The anon user can become root without a password by default as a development convenience. To prevent this, remove anon from the wheel group.

Build Options

Selecting an Architecture

Force a build for a specific architecture:

SERENITY_ARCH=aarch64 Meta/serenity.sh run

Supported values: x86_64, aarch64, riscv64

Build Only (No VM)

To test compilation without running the VM:

Meta/serenity.sh build

Kernel Command Line Parameters

Pass additional kernel parameters:

Meta/serenity.sh run x86_64 smp=on

QEMU Integration Features

SPICE Integration

SPICE provides enhanced clipboard and display integration.

1. Build QEMU via toolchain

   Toolchain/BuildQemu.sh
   
2. Install virt-viewer

   On Ubuntu 23.04+:

   sudo apt-get install virt-viewer
   

   For earlier versions, you may need to build virt-viewer 8.0 from source.

3. Enable SPICE and run

   export SERENITY_SPICE=1
   Meta/serenity.sh run
   

File Transfer from QEMU

Method 1: WebServer

Serenity has a built-in web server accessible from your host:

1. Start WebServer in SerenityOS

   In the SerenityOS terminal:

   ws .
   
2. Access from host browser

   Open localhost:8000 in your host machine’s browser.

Some browsers download unrecognized files as plain text. Use wget to download files as-is instead.

Method 2: Mount the Disk Image

On *nix systems or inside WSL:

cd "Build/${SERENITY_ARCH}"
mkdir mnt
sudo mount -t ext2 _disk_image mnt

Method 3: Archiving Tool

Some archiving tools like 7-Zip can directly open ext2 images like Serenity’s _disk_image.

For WSL users: Access the WSL drive in Windows Explorer via \\wsl$\<distro name>\<path to serenity directory>.

Method 4: OpenSSH and SFTP

1. Setup OpenSSH server on host

   Configure OpenSSH server on your host system (Windows or Linux).

2. Build OpenSSH port in SerenityOS

   cd Ports/openssh
   ./package.sh
   cd ../..
   Meta/serenity.sh run
   
3. Connect via SFTP

   From within SerenityOS:

   sftp user@192.168.0.11
   

   Use commands like ls, cd, put [filename], get [filename], and quit.

Debugging

GDB Remote Session

Start SerenityOS with GDB attached:

Meta/serenity.sh gdb x86_64 smp=on -ex 'hb *init'

This runs the image in QEMU and attaches a GDB session, setting a breakpoint at the init() function in the Kernel.

Self-Test Mode

Run the built image in self-test mode:

Meta/serenity.sh test

This passes system_mode=self-test to the Kernel.

Advanced Configuration

Custom QEMU Arguments

Set additional QEMU arguments:

export SERENITY_EXTRA_QEMU_ARGS="-device virtio-serial"
Meta/serenity.sh run

Disk Image Types

Build different disk image formats:

cd Build/x86_64
ninja limine-image      # Builds limine_disk_image with Limine
ninja grub-image        # Builds grub_disk_image with GRUB (BIOS)
ninja grub-uefi-image   # Builds grub_uefi_disk_image with GRUB (UEFI)
ninja extlinux-image    # Builds extlinux_disk_image with extlinux

Troubleshooting

Toolchain Outdated

If prompted to rebuild the toolchain after updates:

rm Build/*/CMakeCache.txt

Filesystem Errors

If you see fusermount: failed to open /etc/mtab:

ln -sv /proc/self/mounts /etc/mtab

Performance on Windows

If using native Windows QEMU with WSL2, QEMU accesses the ext4 partition via 9P network share, which may be slower. Your WSL2 distro is accessible at \\wsl$\{distro-name}.

Consider copying Build/_disk_image and Build/Kernel/Kernel to a native Windows partition before running.