VitruvianOS Wiki

Building

Mon, 01 Jan 0001 00:00:00 +0000

Building#

How to compile Vitruvian from source on a Debian-based system.

Prerequisites#

Required software:

cmake ≥ 3.25
gcc ≥ 8
libinput ≥ 1.16.4-3
ninja

Install all build dependencies:

sudo apt install -y \
 autoconf \
 automake \
 bison \
 build-essential \
 cmake \
 debhelper \
 debootstrap \
 dh-dkms \
 dkms \
 elfutils \
 flex \
 generate-ninja \
 git \
 grub-common \
 grub-efi-amd64-bin \
 grub-pc-bin \
 libbfd-dev \
 libdrm-dev \
 libdw-dev \
 libdwarf-dev \
 libelf-dev \
 libfl-dev \
 libfreetype6-dev \
 libgif-dev \
 libicns-dev \
 libicu-dev \
 libinput-dev \
 libjpeg-dev \
 libncurses-dev \
 libopenexr-dev \
 libpng-dev \
 libtiff-dev \
 libudev-dev \
 libwebp-dev \
 linux-headers-$(uname -r) \
 mtools \
 ninja-build \
 xorriso \
 zlib1g-dev \
 squashfs-tools \
 --fix-missing

Getting the Source#

git clone https://github.com/VitruvianOS/Vitruvian.git

Building VitruvianOS#

git submodule update --init --recursive
mkdir buildtools/ && mkdir generated.x86/
cd buildtools/
cmake -DBUILDTOOLS_MODE=1 .. -GNinja
ninja
cd ../generated.x86 && ../build/scripts/setupenv.sh
../configure --chroot-build
ninja

setupenv.sh uses debootstrap to bootstrap a minimal Debian Trixie (amd64) environment under generated.x86/image_tree/chroot, installs all required -dev packages inside it, and writes imagekernelversion.conf with the chroot kernel version. The compiler and build tools are always taken from the host.

Coding Guidelines

Mon, 01 Jan 0001 00:00:00 +0000

Coding Guidelines#

These are the conventions used across the Vitruvian codebase. Consistency matters more than personal preference — when touching existing code, match the surrounding style.

Indentation#

Use tabs, not spaces. A tab represents 4 characters of visual width.

Braces#

Opening braces go on their own line for functions and class definitions. Short control flow bodies may keep the brace on the same line.

void
NodeMonitor::HandleEvent(uint32 opcode)
{
 if (opcode == B_ENTRY_CREATED) {
 NotifyListeners();
 }
}

Function return types go on the line above the function name:

Legacy Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Legacy Documentation#

Reference materials from BeOS and Haiku relevant to VitruvianOS development.

The BeBook#

The original BeOS API reference, maintained by the Haiku project. The primary reference for the API that VitruvianOS targets.

haiku-os.org/legacy-docs/bebook

Practical File System Design#

By Dominic Giampaolo — the book behind the Be File System (BFS). Essential reading for understanding attribute-based filesystems and the foundation for live queries.

archive.org/details/fsdesign

The BeOS Bible#

By Scot Hacker — a comprehensive guide to BeOS for users and developers. Covers the desktop environment, applications, and the BeOS philosophy. Useful background for understanding the UX and design goals that Vitruvian aims to carry forward.

Linux

Mon, 01 Jan 0001 00:00:00 +0000

Virtualization on Linux#

QEMU with KVM (recommended)#

QEMU with KVM gives near-native performance on Linux hosts and is the primary tested environment.

Install#

sudo apt install qemu-system-x86 qemu-kvm virt-manager

Check that KVM is available:

kvm-ok

If KVM is not available, QEMU will still work but will run slower without hardware acceleration.

Boot a raw image#

qemu-system-x86_64 \
 -cdrom vitruvian.img -boot menu=on \
 -m 8G -cpu host -smp sockets=1,cores=2,threads=2 --enable-kvm \
 -netdev user,id=mynet,hostfwd=tcp::2222-:22 \
 -device virtio-net-pci,netdev=mynet

Adjust -m (RAM in MB) and -smp (CPU cores) to your host. Remove -enable-kvm if KVM is unavailable.

API Changes

Mon, 01 Jan 0001 00:00:00 +0000

API Changes#

Differences between the Vitruvian native APIs and BeOS/Haiku.

Images#

image_id values are local to the application.

Processes#

start_watching_system must be called with superuser privileges.

Threads#

Thread suspension is forbidden. Any application calling suspend_thread will be killed.

Filesystem#

See Filesystem Layout for directory structure changes.

libbe Annotations#

This section tracks generic differences in the C++ API provided by libbe. It will be expanded as the compatibility layer matures.

How To Install

Mon, 01 Jan 0001 00:00:00 +0000

How To Install#

From a Nightly Image#

Nightly builds are available via GitHub Actions. Download the latest successful build artifact.

Write to a USB drive#

Replace /dev/sdX with your actual device (check with lsblk):

sudo dd if=vitruvian.img of=/dev/sdX bs=4M status=progress oflag=sync

**Double-check the target device.** `dd` will overwrite it completely.

Boot from the USB drive. Most systems require selecting the boot device from the firmware menu (usually F12, F11, or Escape at startup).

Nexus

Mon, 01 Jan 0001 00:00:00 +0000

Nexus#

Nexus is the Vitruvian kernel subsystem that bridges the Linux kernel with the BeOS/Haiku runtime. It is implemented as a set of custom Linux kernel modules loaded at boot.

Purpose#

BeOS and Haiku expose a set of kernel APIs that have no direct equivalent in Linux. Nexus implements these APIs as thin kernel modules, allowing the Vitruvian userspace — including the BeOS/Haiku API compatibility layer — to run on an otherwise standard Linux kernel.

Windows

Mon, 01 Jan 0001 00:00:00 +0000

Virtualization on Windows#

VirtualBox (recommended for most users)#

VirtualBox is the easiest option on Windows and works on all hardware.

Download and install from virtualbox.org
Create a new VM:
- Type: Linux, version Linux 2.6 / 3.x / 4.x (64-bit)
- RAM: 4 GB or more
- Disk: skip (attach the image manually)
In VM settings → Storage, attach the Vitruvian raw image or ISO as a storage device
In VM settings → Display, set adapter to VMSVGA, disable 3D acceleration
Boot the VM

QEMU on Windows#

QEMU runs on Windows and provides better performance than VirtualBox when used with WHPX (Windows Hypervisor Platform) or HAXM acceleration.

Donate

Mon, 01 Jan 0001 00:00:00 +0000

Donate#

Vitruvian is developed entirely by volunteers in their spare time. If you find the project useful and want to support its development, donations are welcome.

You can support VitruvianO development through GitHub Sponsors. You can also contribute by:

Testing — Run nightly builds and report issues
Contributing code — See the coding guidelines and open a pull request
Spreading the word — Tell others about the project

Filesystem Layout

Mon, 01 Jan 0001 00:00:00 +0000

Filesystem Layout#

Vitruvian runs on a standard Linux filesystem hierarchy, but maps BeOS/Haiku path conventions onto it so that application source code written for BeOS or Haiku compiles and runs without path changes.

Boot Filesystem#

The reference boot filesystems are XFS (standard desktop installs) and SquashFS (live images and embedded targets). Both support Linux extended attributes, which are required for the BeOS attribute store. Most other Linux-supported filesystems with extended attribute support also work; see the FAQ for details.

macOS

Mon, 01 Jan 0001 00:00:00 +0000

Virtualization on macOS#

UTM (recommended)#

UTM is a native macOS virtualization frontend built on QEMU. It works on both Intel and Apple Silicon Macs and is the easiest way to run Vitruvian on macOS.

Download UTM from mac.getutm.app or the Mac App Store
Click + to create a new VM
Select Emulate → Linux
Follow the setup wizard — assign at least 4 GB RAM and 2+ CPU cores
In the drive settings, attach the Vitruvian ISO or raw image
Set the display to VirtIO GPU
Start the VM

Apple Silicon note#

On Apple Silicon (M1, M2, M3…), Vitruvian runs under x86-64 emulation since there is no KVM-equivalent hardware acceleration for foreign architectures. Expect reduced performance compared to a native x86-64 host. ARM support in Vitruvian will change this in the future.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

FAQ#

What is Vitruvian?#

VitruvianOS (V\OS) is an operating system based on Linux, inspired by BeOS. It runs the BeOS/Haiku desktop and API on top of a real-time patched Linux kernel, with custom kernel modules — collectively called Nexus — providing the missing BeOS-style system services.

See the Nexus reference page for details on the kernel bridge.

Is it ready to use?#

The project is in active development and experimental. Core components (Deskbar, Tracker, app_server, registrar) run, and BeOS/Haiku application source code compiles and runs with minimal changes. Expect rough edges.