RELEASE(8)

💅 RELEASE(8) — building an OpenBSD release ✨

okay so the manual page name is release, it lives in section 8 of the system manager's manual, and bestie… it is literally the whole glow-up ritual for making an OpenBSD release from scratch. buckle up 🎀

---

🌸 NAME 🌸

release — building an OpenBSD release 🫶

---

✨ DESCRIPTION ✨

There are several steps necessary to build a release, and yes you have to do them in order, no skipping ahead like it's a group project:

1. Update sources.
2. Build and install a new kernel.
3. Build a new base system.
4. Make and validate the base system release.
5. Build and install Xenocara.
6. Make and validate the Xenocara release.
7. Create boot and installation disk images.
8. Make the third party packages.

This manual describes the steps for the release and stable branches. To build a current release, additional steps may be required — see https://www.openbsd.org/faq/current.html for any needed workarounds. (iykyk, current is a whole different beast 🙈)

Commands to be run as a user are preceded by a dollar sign $. Commands that must be run as the superuser are preceded by a hash mark #. Privileges will be de-escalated to the user build whenever possible — so yes, root only when it's actually needed, love that for us 👑

Most of the defaults can be overridden by setting the appropriate variables in mk.conf(5). customize your life 💖

---

🌀 1. Update sources

A release should use sources that were checked out using the same cvs(1) tag. There are two families of tags, and they are not interchangeable:

• OPENBSD_x_y_BASE — the sources for the OpenBSD x.y release. 🎀
• OPENBSD_x_y — the sources for the OpenBSD x.y stable branch. It contains the patches described in https://www.openbsd.org/stable.html.

See https://www.openbsd.org/anoncvs.html for instructions on fetching the sources for the first time.

To update existing sources to the versions identified by one of the above tags, use the commands:

$ cd /usr/src && cvs up -r TAG -Pd
$ cd /usr/xenocara && cvs up -r TAG -Pd
$ cd /usr/ports && cvs up -r TAG -Pd

⚠️ Warning: cvs(1) tags are ‘sticky’. See cvs(1) for more information. this is the kind of sticky that does NOT slay, ok? 😭

---

🧚 2. Build and install a new kernel

Always build and install a new kernel and reboot before building the programs that will use the kernel. This ensures that any new system calls, for example, will be present when needed. no cap, do the kernel first 🔥

# cd /sys/arch/$(machine)/compile/GENERIC.MP

Replace GENERIC.MP with a different kernel configuration if necessary.

Create the build directory and configuration file, then compile and install the kernel:

# make obj
# make config
# make && make install

The current kernel is copied to /obsd and the new kernel to /bsd. Reboot. 🦋

---

🌈 3. Build a new base system

The build process will place the object files in a tree under /usr/obj. This directory must be owned by build:wobj with mode 770.

Create the tree of obj directories and begin the build:

# cd /usr/src
# make obj && make build

After the build is completed, update /etc, /var, and /dev, using sysmerge(8) and MAKEDEV(8):

# sysmerge
# cd /dev && ./MAKEDEV all

At this point, the base system is up to date with the code that will be made into a release. main character energy achieved 💅

---

🍓 4. Make and validate the base system release

The base system release consists of at least one generic kernel, some installation media, the release tarballs, installation instructions, and checksum files. the whole care package 🎀

On arm64, armv7 and riscv64 architectures, additional files are required. Install the following packages using pkg_add(1) or from ports(7):

arm64    raspberrypi-firmware u-boot-rpi
armv7    dtb u-boot-arm

and install the following firmwares using fw_update(8):

riscv64  riscv64-spacemit-dtb

Create a RELEASEDIR directory to store the release files. This directory must be writable by build.

To build a release, it is necessary to prepare a filesystem mounted with the noperm mount(8) option. Either standard FFS or mount_mfs(8) may be used. The root of this filesystem must have owner build and mode 700. On this filesystem, create a DESTDIR directory. This will be the root of a complete OpenBSD installation. 🏠

⚠️ Warning: DESTDIR and RELEASEDIR must not refer to any directory with /mnt in its path, as /mnt is used in the release generation process. The vnd(4) device vnd0 is also used and must not be configured. do not touch, do not look at it, do not claim it 💀

Make the release and check the contents of the release tarballs:

# export DESTDIR=your-destdir RELEASEDIR=your-releasedir
# cd /usr/src/etc && make release
# cd /usr/src/distrib/sets && sh checkflist
# unset RELEASEDIR DESTDIR

---

💜 5. Build and install Xenocara

Xenocara is based on the X.Org modular build system. Its sources are supposed to be in /usr/xenocara. The /usr/src tree is also needed while building Xenocara. The object directory /usr/xobj should be empty and owned by build:wobj with mode 770. empty!! not "mostly empty" 🙈

The following steps will build and install Xenocara:

# cd /usr/xenocara
# make bootstrap
# make obj
# make build

---

⭐ 6. Make and validate the Xenocara release

Xenocara uses DESTDIR and RELEASEDIR as described above. Use a different DESTDIR for the Xenocara release than for the base release, as the contents of DESTDIR will be removed. like, obliterated. so use a fresh one 🫶

The steps to build and validate the Xenocara release are:

# export DESTDIR=your-destdir RELEASEDIR=your-releasedir
# make release
# make checkdist
# unset RELEASEDIR DESTDIR

At this point, OpenBSD base system and X Window System tarballs are in RELEASEDIR. iconic ✨

---

🎀 7. Create boot and installation disk images

The disk images install${VERSION}.img and install${VERSION}.iso are suitable for installs without network connectivity. They contain the tarballs built in the previous steps.

# export RELDIR=your-releasedir RELXDIR=your-xenocara-releasedir
# cd /usr/src/distrib/$(machine)/iso && make
# make install

The two installer images are now stored in the local release directory. two icons, one directory 💖

---

🦋 8. Make the third party packages

The ports subsystem of contributed applications is capable of producing packages for installation, either individually or in bulk. This is described in ports(7).

---

👑 SEE ALSO 👑

cvs(1), pkg_add(1), mk.conf(5), ports(7), sysmerge(8)

---

and that's the whole release pipeline, bestie — go forth and build 🧚💫

this page came from the Debian corner of the world, dated April 18, 2026, and it's RELEASE(8) all the way down 🎀