> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Otter Shell from source

> Compile Otter Shell components locally with Zig 0.16.0 and run tests.

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

## Prerequisites

Install Zig 0.16.0 and system dependencies:

```bash theme={null}
# 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

```bash theme={null}
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:

```bash theme={null}
zig build -Doptimize=ReleaseFast -Dcpu=x86_64_v3
```

## Packaging (otter-zenith)

PikaOS packages come from [otter-zenith](https://git.pika-os.com/otter-shell/otter-zenith):

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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`.