DEVELOPMENT(7) Miscellaneous Information Manual DEVELOPMENT(7)

development — navigate and change the MOUSE source tree

MOUSE keeps its owned code, policy, external source identities, build logic, and manuals in one source tree. The installed copy is /usr/src. It is owned by and is group-writable so an administrative user can build and edit it without running development tools as root. The source tree, rather than generated build output or a running image, is the source of truth.

The top-level Makefile is the bmake dependency graph. Scoped POSIX scripts below scripts carry the stage implementations and are directly runnable for focused work. The public build interface is documented by build(7).

Decide which boundary owns a change before editing the build.

World
Software and policy required for boot, recovery, administration, development, self-maintenance, or the standard desktop belong in World. The inclusion rule and installed boundary are documented by world(7) and hier(7).
Ports
User-selected software belongs in pkgsrc and installs below /usr/local. Do not add it to World merely to make it convenient on one machine. See ports(7).
MOUSE implementation
Code implementing a MOUSE interface or policy belongs below the narrowest owning directory under base.
Upstream integration
An unmodified upstream release is identified below release. A MOUSE-required portability or integration change is carried as a reviewed patch beside the component that needs it.

Makefile
The bmake graph, public targets, stage dependencies, and build variables.
scripts
Scoped POSIX implementations for source preparation, component builds, World assembly, image operations, manual rendering, and virtual machines.
release
SHA-256, URL, and filename records for every external source archive or pinned Git object used by the build.
base/world
System accounts, default policy, selected NetBSD commands, service definitions, fixed runlevels, network configuration, and system overview manuals.
base/cheesed
PID 1, platform bootstrap code, service-policy parsing, and the cheesed(8) and rc.conf(5) manuals.
base/netbsd
Kernel configuration, the selected early userland, the PID 1 rescue build, and the ZFS image bootstrap and check environment.
base/openrc
MOUSE changes required by the pinned OpenRC source.
base/merde
MERDE source, session wrappers, default configuration and assets, manuals, and patches carried for its upstream compositor and terminal dependencies.
base/lidm
LiDM configuration, session description, authentication backend, and patches.
base/desktop
Desktop portability patches and MOUSE-supplied manuals for desktop components that do not provide their own.
base/pkgsrc/mk.conf
The template used by the optional pkgsrc bootstrap in ports(7). It is not installed as active World configuration.
web
The hand-written website entry page and stylesheet. web/man is generated from the manuals in an assembled World.

Every external source used to construct World must have exactly one lock entry containing a lowercase SHA-256 digest, an HTTPS URL, and a filename. Use a release archive when upstream publishes one. Git-only sources are named with their full commit identifier and are converted to deterministic archives by the source fetcher.

Keep a portability or integration patch next to the MOUSE component that owns the reason for carrying it. When updating an external source, reapply and review each patch rather than silently accepting rejects or preserving obsolete compatibility code.

pkgsrc is deliberately outside the World release inputs. An administrator fetches and updates it after installation as described by ports(7); that mutable checkout does not change the World release identity.

Selected NetBSD commands
base/world/list defines programs built into and installed from the native multicall executable.
System policy
Accounts, privilege rules, network defaults, and system configuration belong below base/world. Persistent service enablement belongs only in base/world/rc.conf; the installed interface is documented by rc.conf(5).
Services
Put MOUSE service definitions below base/world/init.d; the World recipe installs them below /usr/lib/mouse/init.d. An administrator may override a definition explicitly in /etc/init.d; the MOUSE OpenRC integration searches that path before the World defaults. Use the fixed manifests below base/world/runlevels only for services that users cannot disable. Other services are enabled or disabled through rc.conf. OpenRC framework settings live separately in /etc/openrc/rc.conf. MOUSE patches OpenRC to read that path and deliberately omits rc-update because persistent runlevel membership belongs to rc.conf(5).
Desktop
MERDE-owned behavior belongs below base/merde. Login behavior belongs below base/lidm. Shared desktop dependency fixes belong below base/desktop. Do not move MERDE into Ports; it is a statically linked World component.
Ports boundary
World may provide compilers, headers, libraries, and NetBSD package tools, but an administrator bootstraps pkgsrc when optional packages are wanted. Those packages install below /usr/local. The filesystem and package boundaries are documented by hier(7) and ports(7).

World has no generic component registration file. Adding a program or library requires each of the following steps that applies:

  1. Put MOUSE-owned source, defaults, patches, and manuals below the component that owns them. If a new top-level component directory is introduced, add it to the owning stage's input list in the Makefile or scoped script so the build cache observes changes.
  2. Build with the target compiler and sysroot exposed by the owning stage script, then install into that script's staged root. Do not write directly into build/${MOUSE_ARCH}/world; it is extracted from the completed World archive.
  3. Install an appropriate manual page and link it from the nearest overview page.
  4. Rebuild and inspect World before creating an image.

A World service consists of an executable OpenRC definition below base/world/init.d and, when needed, defaults below base/world/conf.d. Install both from the World recipe.

Put the service in a fixed manifest below base/world/runlevels only when MOUSE cannot operate correctly with it disabled. Otherwise add an explicit service_enable=NO default to base/world/rc.conf and let the user opt in through rc.conf(5). Declare ordering and provided virtual services in the OpenRC definition rather than relying on the textual order of either file.

Document the executable or daemon interface in section 8. Document a MOUSE-owned configuration format in section 5. Use the upstream OpenRC pages for ordinary service-script mechanics instead of duplicating them. Those pages describe the MOUSE OpenRC configuration path after the integration patch is applied.

base/world/list selects commands built into the native multicall executable. Each PROG entry names the installed command and may name aliases after it. Use SPECIAL when the source directory does not follow the ordinary NetBSD layout.

Adding a command may also require a library in the LIBS entry, an explicit manual source, an installed-path requirement, or a World installation rule.

Changes to the kernel or early image environment belong below base/netbsd. Kernel configuration, the PID 1 rescue environment, and the ZFS bootstrap are separate consumers and must not be assumed to contain the same commands as the finished World.

MERDE session behavior is divided by interface rather than placed in one executable.

Session and window management
base/merde/src/session.c owns compositor session state and control commands; base/merde/src/workspace.c owns workspace and window placement behavior. Keep the state file and control protocol documented by merde(1) and merdectl(1) consistent with both producers and consumers.
Configuration
base/merde/src/config.c parses and validates the schema represented by base/merde/src/config.h. A schema change also requires a default in base/merde/share/merde.default.lua and corresponding documentation in merde-config(5). Unknown keys remain errors; do not add undocumented compatibility aliases.
Companions
The bar, notifier, and wallpaper are long-lived programs started and stopped by the session. The launcher is a session popup and the screenshot tool runs on demand. A new companion requires source, an installed command, default configuration, its runtime contract, and a section 1 manual. Put shared supervision behavior in base/merde/src/companion.c rather than duplicating it in each program.
Login integration
Session startup and environment setup belong in base/merde/scripts/merde-session and base/lidm. Keep authentication changes separate from graphical session changes.
Upstream desktop code
Patches for Havoc and MERDE's upstream compositor dependencies live beside the MOUSE component carrying them. Update the corresponding lock and recheck every carried patch when changing an upstream revision.

The MOUSE_ARCH selection at the top of the Makefile maps a public architecture name to the NetBSD machine, machine architecture, kernel configuration, cross-tool prefix, and EFI loader name. Adding that mapping is necessary but not sufficient for a bootable image.

An image architecture also needs a kernel configuration below base/netbsd/conf, working early-userland and ZFS bootstrap code, architecture-correct EFI and GPT media generation, QEMU image and runner definitions, firmware discovery, and a successful implementation of the existing image check and interactive run. Keep architecture-dependent output below build/${MOUSE_ARCH}. Do not describe an architecture as image-supported until bmake image, bmake check, and bmake run all use it without special manual assembly. RISC-V 64 is experimental until those gates pass on a fresh build.

Do not edit files below build. They are source caches, intermediate objects, staged roots, archives, and images produced by the bmake graph and its scoped scripts. Do not edit web/man; regenerate it with bmake web after assembling World once. That target refreshes the MOUSE-owned manuals in build/${MOUSE_ARCH}/world from their source directories before rendering, while retaining the upstream manuals installed by the component builds.

The source archive used for /usr/src contains tracked paths with current working-tree modifications and deletions. The build stops when nonignored untracked paths exist; use git add to make a new file part of the source set before building a release.

Shipping the exact source tree at /usr/src, with its build tools and manuals allows the installed system to be inspected, changed, and rebuilt without finding a matching repository elsewhere.

MOUSE manuals have their own installation stage because documentation should be previewable without recompiling the operating system; release assembly and the website share that installation recipe.

Render and lint a changed manual with mandoc(1) before rebuilding. For a complete system change, run the public targets explicitly:

bmake build
bmake world
bmake image
bmake check
bmake web

The image check installs a disposable system, upgrades it in place, and verifies the rebooted result. Use a narrower component check first when one exists.

havoc(1), mandoc(1), merde(1), rc.conf(5), build(7), hier(7), mouse(7), ports(7), world(7), cheesed(8)

MOUSE September 1, 2026 DEVELOPMENT(7)