BUILD(7) Miscellaneous Information Manual BUILD(7)

build — construct, install, and upgrade MOUSE

The complete MOUSE source tree is installed at /usr/src. Its top-level Makefile is a bmake graph that constructs World and the boot environment, packages World, creates live installation media, installs a blank system, upgrades a running system, and renders the manual website. Scoped POSIX scripts below scripts carry the stage implementations. Build products are isolated below build/aarch64, build/riscv64, and build/x86_64.

The source tree is and group-writable. Build as a member of ; do not run bmake build through doas(1). The bootstrap and install targets modify their target disks or the running system. run does not modify the host itself, but a guest can write an image attached with MOUSE_RUN_DISK or MOUSE_RUN_ATTACH.

BSD make is required as bmake for the MOUSE graph. GNU make remains required by upstream projects that use it and is selected explicitly by the build scripts. A build host also needs a C and C++ compiler, Python 3, Git, curl, tar, gzip, xz, zstd, patch, CMake, pkgconf, a SHA-256 implementation, and ordinary POSIX command-line tools.

The check and run targets require QEMU and UEFI firmware for the target architecture. The check target additionally requires qemu-img. The web target requires mandoc(1). QEMU is not part of World.

The image target invokes build first, and check invokes image first. Other public targets do not build prerequisites implicitly; invoke build before world, run, or install when their required artifacts are absent.

Fetch and verify source inputs, construct the selected NetBSD substrate and World, prepare the normal and live kernels, and create mouse-world.tar and mouse-${MOUSE_ARCH}-rootfs.tar.zst.
Extract mouse-world.tar as build/${MOUSE_ARCH}/world for inspection and consumers such as web.
Create the UEFI-bootable live image build/${MOUSE_ARCH}/mouse-${MOUSE_ARCH}.iso. The ISO contains the assembled World tree as an uncompressed read-only live root, the compressed rootfs archive, and its UEFI boot image. At boot it mounts World from the ISO and places mutable live state on memory filesystems; it does not expand World into memory. It then starts the normal MOUSE init and service policy. The default build reaches LiDM and MERDE; a build without MERDE reaches its console login. The live account is with password . It exists only in the live system and is not installed. It does not run QEMU or create an installed disk.
Install the live ISO's rootfs archive onto blank partitions. This target is available only from the live system and requires root. ROOT must name a GPT wedge labelled MOUSE_ROOT; EFI must name a different GPT wedge labelled MOUSE_EFI. For in-place upgrade recovery, the EFI system partition needs room for the active and retained previous payloads plus two staged payloads; allocate at least 512 MiB. The target creates the standard zroot datasets, extracts World, creates device nodes, and formats and writes the EFI system partition last. It does not build anything.

See installation(7) for the live-media partitioning and bootstrap procedure.

After bootstrap, it returns to the live system. Enter the installed root manually:

doas chroot /altroot /usr/bin/login -f root

This login supplies the identity required by passwd(1). For example:

passwd toor
useradd -mG wheel alice
passwd alice
man 7 wifi
exit
doas reboot
Upgrade a running MOUSE system from build/${MOUSE_ARCH}/mouse-${MOUSE_ARCH}-rootfs.tar.zst. Set MOUSE_INSTALL_ROOTFS to use another rootfs archive. The archive must already exist. Installation requires root and the standard ZFS layout. It stages and validates World, retains one previous root snapshot, updates the kernel, EFI loader, and boot configuration as one payload, and preserves /etc, /media, /home, /var, /usr/local, /tmp, and device nodes. It never reboots automatically.
Construct a disposable check ISO from the built World payload, then use a disposable QEMU disk to install it, boot the installed system, upgrade World in place, and verify the reboot.
Boot an existing image interactively on the graphical display. With MOUSE_RUN_DISK set, attach the named raw QEMU disk image as a writable guest disk and boot from it; the ISO remains attached as a recovery fallback. With MOUSE_RUN_ATTACH set, attach the named raw QEMU disk image while booting the ISO instead. When both MOUSE_RUN_DISK and MOUSE_RUN_ATTACH are unset, run attaches no disk and boots the ISO only. The run target does not partition or format the disk; use a disposable image for installation experiments and perform those operations from the live system.
Refresh the MOUSE-owned manuals in the assembled World and render the installed manual set below web/man.
Remove build products and working state while retaining verified downloads in build/sources.
Remove build in its entirety, including downloaded sources.

Build release artifacts and the live ISO:

cd /usr/src
bmake build
bmake image
bmake check

For a new installation, boot the ISO and follow installation(7).

To boot an installed test disk with its ISO as a recovery fallback:

bmake MOUSE_RUN_DISK=./testdisk run

To boot the ISO with the test disk attached:

bmake MOUSE_RUN_ATTACH=./testdisk run

Upgrade a source checkout in place:

cd /usr/src
git pull
bmake build
doas bmake install
reboot

To install an archive built elsewhere:

doas bmake MOUSE_ARCH=aarch64 MOUSE_INSTALL_ROOTFS=/path/mouse-aarch64-rootfs.tar.zst install

MOUSE_ARCH
Target architecture: aarch64, riscv64, or x86_64. When unset, arm64, aarch64, and NetBSD evbarm select AArch64; amd64 and x86_64 select x86_64. NetBSD riscv and riscv64 select RISC-V 64, which remains experimental until its image, check, and interactive runner paths pass fresh acceptance.
MOUSE_BUILD_JOBS
Shared build job budget, including NetBSD builds. The default is the processor count reported by getconf, or 2 when unavailable.
MOUSE_GNU_MAKE
GNU make executable used by upstream build projects. The default is gmake. It does not select the MOUSE graph driver.
INCLUDE_MERDE
Include the MERDE desktop stack when set to 1, the default. Set it to 0 to omit MERDE, Havoc, LiDM, their manuals and service policy. The resulting system starts a console login.
MOUSE_RUN_DISK
Existing writable regular raw disk image for run to attach as a virtio disk and boot. A relative path is resolved from the invoking directory. The image is never created or truncated. It must not name the ISO or be empty.
MOUSE_RUN_ATTACH
Existing writable regular raw disk image to attach while booting the ISO. A relative path is resolved from the invoking directory. The image is never created or truncated. It must not name the ISO or be empty. The variables are mutually exclusive; set at most one.
MOUSE_RUN_SIZE
QEMU guest size. minimal uses 512 MiB and two processors, and is the default for run. full uses 8192 MiB and eight processors for larger graphical sessions.
MOUSE_INSTALL_ROOTFS
Rootfs archive consumed by install. An empty value is invalid.
ROOT
Blank MOUSE_ROOT wedge consumed by bootstrap.
EFI
Blank MOUSE_EFI wedge consumed by bootstrap.

Optional packages are not a build option. An administrator bootstraps pkgsrc into /usr/local after installation as described by ports(7).

The target architecture, version, tracked-source fingerprint, selected GNU make command, host C and C++ compiler commands, and INCLUDE_MERDE form the release identity carried by the rootfs archive and live ISO. Run and installation variables affect operations but not that identity. A fresh bootstrap therefore installs exactly that World. An in-place install removes omitted World files, but preserves machine-owned /etc and /usr/local; it does not remove an existing pkgsrc checkout or local desktop policy.

An upgrade retains zroot/ROOT/mouse@mouse-previous and the matching kernel, EFI loader, and boot configuration payload. An interrupted install leaves zroot/ROOT/mouse@mouse-install and, if EFI activation began, a pending EFI payload. On the next normal boot, MOUSE rolls the installation back automatically, including any pending EFI payload, exports zroot, and stops in the bootstrap emergency shell; reboot from that shell to use the restored payload. To deliberately restore the retained previous system, select “Previous MOUSE recovery” from the boot menu, then run:

mousectl rollback
reboot

The mouse-previous rollback is explicit and available only from recovery. It restores the World root and complete boot payload but does not change the machine-owned datasets mounted at /etc, /home, /var, and /usr/local.

Locked source identities are declared below release. Verified downloads are retained below build/sources. clean preserves them; distclean removes them. Each stage fingerprints its inputs below build/${MOUSE_ARCH}/work/state; an unchanged stage reuses its outputs. Fix the first failed stage and repeat the public target instead of deleting the whole build tree.

The source archive installed at /usr/src contains tracked paths with current working-tree modifications and deletions. The build stops when nonignored untracked paths exist; add every release input to Git before building it. Internal targets beginning with an underscore are implementation details.

/usr/src/Makefile
bmake graph and public targets.
/usr/src/scripts
Scoped POSIX stage implementations.
/usr/src/release
Locked source identities.
/usr/src/build/${MOUSE_ARCH}/mouse-world.tar
Uncompressed World archive.
/usr/src/build/${MOUSE_ARCH}/mouse-${MOUSE_ARCH}-rootfs.tar.zst
Compressed World archive currently carried by the live ISO and used by bootstrap, and install.
/usr/src/build/${MOUSE_ARCH}/mouse-${MOUSE_ARCH}.iso
Live installation image.
/usr/src/build/${MOUSE_ARCH}/world
Assembled World tree.
/usr/lib/mouse
Release metadata, World manifest, kernel, EFI loader, and normal boot configuration.

Detailed build failures are preserved below build/${MOUSE_ARCH}/work. An “is up to date” message covers only that stage; it does not mean image or check ran.

The top-level bmake graph exposes the system path while scoped POSIX scripts keep stage implementations directly runnable and reviewable. The live ISO mounts its assembled World tree read-only and uses bounded memory filesystems for mutable state. The compressed World archive is carried on the ISO for bootstrap and installation compatibility; live boot uses the assembled World tree.

make(1), development(7), hier(7), mouse(7), ports(7), world(7)

MOUSE September 1, 2026 BUILD(7)