Skip to main content
Otter Shell v0.13.0 uses otr 0.2.0 for native applications and libraries. Each component has its own repository and otr/build.otr runner. Run it from the component’s repository root, not from its otr/ directory.

​
Prerequisites

  • Install otr 0.2.0. The packaging pin is otter-zenith/otr-toolchain.pin.
  • Keep sibling library repositories at the matching v0.13.0 release. Package manifests in otr/otr.toml refer to sibling packages.
  • Install system development headers required by the component. Common dependencies include Wayland, Fontconfig, FreeType, and xkbcommon. otter-zenith/debian/control contains the complete packaging build dependencies.
  • Keep Zig 0.17.0 available for the intentional Zig dependencies below and differential test baselines. Zig is not the primary application build tool.
  • Use an isolated headless compositor for visual E2E tests. Do not capture your running desktop session.
For common development headers on PikaOS:
Additional dependencies vary: PAM headers for authentication, FFmpeg/DRM/EGL/GLES headers for recording, and libapt-pkg headers for the package manager. The browser has a separate engine build.

​
Build a component

For example, from a workspace containing otter-bar and its sibling libraries:
The bar installs to otr-out/bin/otter-bar by default. Its run step builds and starts it:
Step names and output directories vary by package. Read the header of that package’s otr/build.otr before using an optional step. A step marked as having no otr counterpart does not verify that feature.

​
Verification

The bar’s runner exposes these additional steps:
check runs package type checks and formatter checks. test runs the package’s test modules; some runners test both debug and release-fast modes. e2e exercises integration behavior in an isolated environment. bench runs that package’s performance suite. Installation builds use release-fast. Some legacy E2E and benchmark runners still expect the old Zig source tree as a comparison baseline. A clean otr checkout no longer contains those root Zig build files; use the required preserved historical tree or frozen artifacts rather than treating the step as ready to run. Any Zig comparison builds must use -Doptimize=ReleaseFast. The bar’s standalone e2e-lua-quiet test checks Lua widget rendering without a Zig baseline. Passing --release-fast to otr run builds the runner in release mode; the runner determines its child test modes.

​
CPU target and installation prefix

Packaging targets x86_64_v3 through OTR_CPU. For the bar:
To stage a package without writing into the live system:
This puts the bar under stage/usr/bin/. Prefix handling and supported flags belong to the package runner; old Zig -D... options are not interchangeable with otr runner arguments. Otter libraries are statically linked into the released otr applications. You do not install a shared libotter-*-0 runtime library set for them. System libraries and packaged external engines can still be dynamic dependencies.

​
Intentional Zig dependencies

Run the component’s deps step rather than rebuilding those boundaries by hand. Dependency steps also prepare native libraries such as LuaJIT and rendering dependencies. Packaging can supply an offline dependency tree through OTTER_VENDOR.

​
Packaging with otter-zenith

otter-zenith assembles tagged source trees from pins.json, checks the otr toolchain pin, and builds PikaOS packages:
debian/rules runs each selected component’s deps step, then its install step, from that component’s root. It passes DESTDIR, /usr as prefix, and OTR_CPU=x86_64_v3. The browser instead uses zig-maint/otter-browser/scripts/packaging-zenith.sh to build its engine and stage its files. End users install those packages with pikman install otter-shell; they need neither compiler.

​
Repository workflow

The workspace root is a thin Git repository with package submodules. Code changes belong in the affected component’s repository. Root commits record workspace documentation, tools, or submodule pins; they do not replace component commits. Native application sources live in otr/, alongside otr/build.otr and otr/otr.toml. Retained .zig sources are not the primary v0.13.0 build entry point. See Creating an app for the native application workflow.