Build Otter Shell from source

Each component is its own Zig project. Same build commands for apps and libraries.

Prerequisites

Install Zig 0.16.0 and system dependencies:

# PikaOS / Debian
sudo apt install libwayland-dev libfontconfig-dev libfreetype-dev libxkbcommon-dev

Extra packages by component:

Component	Extra packages
otter-term	`libghostty-vt-dev-git`
otter-rec	`libavcodec-dev`, `libavformat-dev`, `libavutil-dev`, `libswscale-dev`, `libdrm-dev`, `libegl-dev`, `libgles-dev`
otter-lock, otter-greeter, otter-polkit	`libpam0g-dev`

Basic build

cd otter-bar    # or any component directory
zig build       # compile
zig build run   # build and run
zig build test  # run unit tests
zig build install  # install to prefix

Libraries link through path dependencies in sibling build.zig.zon files (../otter-render, etc.) when you build from the monorepo checkout.

Build options

Common flags across apps:

Flag	Effect
`-Doptimize=ReleaseFast`	Release build
`-Dcpu=x86_64_v3`	PikaOS packaging default (AVX2)
`-Denable_dbus=false`	Remove D-Bus widgets (battery, MPRIS, tray)
`-Denable_pipewire=false`	Remove PipeWire audio
`-Denable_pam=false`	Remove PAM auth (lock/greeter)
`-Dc_allocator=jemalloc`	Use jemalloc as C allocator
`-Dc_allocator=mimalloc`	Use mimalloc as C allocator

Release build example:

zig build -Doptimize=ReleaseFast -Dcpu=x86_64_v3

Packaging (otter-zenith)

PikaOS packages come from otter-zenith:

cd otter-zenith
./main.sh

This clones tagged releases, assembles a source tree, and runs dpkg-buildpackage. End users install with pikman install otter-shell. They do not need Zig.

Benchmarks

cd otter-conf/benchmarks && zig build bench
cd otter-render/benchmarks && zig build -Doptimize=ReleaseFast -Dcpu=x86_64_v3
cd otter-ui/benchmarks && zig build -Doptimize=ReleaseFast -Dcpu=x86_64_v3 bench
cd otter-desktop/benchmarks && zig build bench

Per-component git workflow

Each component is its own repo. From inside a component directory:

git add .
git commit -m "your message"
git push origin main

Do not commit from the monorepo root. It is not a git repository.

App structure convention

Most apps use this layout:

File	Purpose
`src/main.zig`	Entry point, Wayland event loop
`src/config.zig`	Config schema and parsing
`src/draw.zig`	Surface Description frame and rendering

Long-running daemons use GeneralPurposeAllocator. One-shot overlays (launcher, logout) use ArenaAllocator.

​Prerequisites

​Basic build

​Build options

​Packaging (otter-zenith)

​Benchmarks

​Per-component git workflow

​App structure convention