OpenBSD FAQ - Building the System from Source [FAQ Index]



OpenBSD's flavors

There are three flavors of OpenBSD: Graphically, the development of these flavors looks something like this:
       ,------o-----------o----X                    5.6 Stable
       |      .           .
       |      .    ,------o---------o----X          5.7 Stable
       |      .    |      .         .
       |      .    |      .    ,----o----------o--> 5.8 Stable
       |      .    |      .    |    .          .
       |      .    |      .    |    .    ,-----o--> 5.9 Stable
       |      .    |      .    |    .    |     .
       |      .    |      .    |    .    |     .
 -->5.6Rel----->5.7Rel----->5.8Rel----->5.9Rel----> Current

          Time --->
In the above illustration, the vertical dotted lines denote bug fixes being incorporated into the -stable branches.

Further thoughts on the three flavors are here.

What are snapshots?

Between formal releases of OpenBSD, snapshots are made available through the mirrors. These are builds of whatever code is in the tree at the instant the builder grabbed a copy of the code for that particular platform.

It is possible that you may uncover bugs in snapshots. This is one of the reasons why they are built and distributed. If you find a bug in a snapshot, make sure it is reported.

If you desire to run -current, a recent snapshot is usually all you need. Upgrading to a snapshot is the starting point before building -current from source.

Details can be found on the following -current page.

What code was used to build a snapshot?

It is sometimes asked if there is any way to get a copy of exactly the code used to build a snapshot. The answer is no.
  1. There is no significant benefit to this.

  2. Snapshots are built as desired, as time permits and as resources become available.

    On fast platforms, several snapshots may be released in one day. On slower platforms, it may take a week or more to build a snapshot. Providing tags or markers in the source tree for each snapshot would be quite impractical.

  3. Snapshots often contain experimental code that isn't yet committed to the CVS tree.

Building OpenBSD from source

The main reference is release(8). This FAQ section is intended to help you with the necessary preparation. Read that manpage before you proceed.

Overview

Building OpenBSD from source involves a number of steps:

Preparation:

The actual process of building the base system is explained in steps 2 and 3 of release(8): The next two steps are optional:

Upgrading to the closest available binaries

Make sure you have the closest available binaries installed. Use this table to look at where you are, where you wish to go, and what binary you should start with:

You are at Goal Binary upgrade to then ...
Old -release New release Newest release Done!
-release -stable Newest release Fetch & build -stable
Old -stable -stable Newest release Fetch & build -stable
-release -current Latest snapshot (optional) Fetch & build -current
Old -current -current Latest snapshot (optional) Fetch & build -current

It is recommended that you install the binary sets by using the (U)pgrade option of the install media. If that is not possible, you can also unpack the binary sets as described in the upgrade instructions of the release.

Fetching the source code

OpenBSD uses the CVS version control system to manage its source. The cvs(1) program is used to pull a copy of the desired source to your local machine for compilation. This can be done by using an Anonymous CVS server. You can also maintain a local CVS repository using the CVSync or rsync programs, available as packages.

First, you must cvs checkout the source tree. After that, you maintain the tree by running cvs update to pull updated files to your local tree.

An introduction to cvs(1) and detailed instructions for fetching the source trees are on the Anonymous CVS page. If you are new to using cvs(1), you may also want to read the CVS tips below.

Avoiding root privileges

Avoid running cvs(1) as root. The /usr/src directory is writable for wsrc by default. So, add users that need to use cvs(1) to the wsrc group:
# user mod -G wsrc exampleuser
Since they're not part of the base install, you must create the directories and set their permissions manually to make use of the wsrc group:
# cd /usr
# mkdir -p   xenocara ports
# chgrp wsrc xenocara ports
# chmod 775  xenocara ports

Example: Fetching the -current trees

We'll assume you are using a public Anonymous CVS server, anoncvs@anoncvs.example.org:/cvs. We also assume that sh(1) is the shell.

To checkout a -current src tree, you can use the following:

$ cd /usr
$ cvs -qd anoncvs@anoncvs.example.org:/cvs checkout -P src
Replace src with the module you want, such as xenocara or ports.
$ cd /usr/src
$ cvs -qd anoncvs@anoncvs.example.org:/cvs up -Pd
As all parts of OpenBSD must be kept in sync, all trees you use should be checked out and updated at the same time.

Example: Fetching the -stable trees

To fetch the -stable src tree, specify the branch you want with the -r flag
$ cd /usr
$ cvs -qd anoncvs@anoncvs.example.org:/cvs checkout -rOPENBSD_5_9 -P src
Once you have the tree checked out, you can update it at a later time with
$ cd /usr/src
$ cvs -q up -rOPENBSD_5_9 -Pd
Replace src with xenocara or ports as appropriate.

Build OpenBSD

At this point you are ready to build OpenBSD from source.

If you are building -current, review changes and special build instructions listed on current.html.

Follow the detailed instructions in release(8).

Making a release

A release is the complete set of files that can be used to install or upgrade OpenBSD on another computer. If you have only one computer running OpenBSD, you really don't have any reason to make a release, as the above build process will do everything you need. An example use would be to build -stable on a fast machine, then make a release to be installed on all your other machines.

The instructions on making a release are in release(8). The release process uses the binaries created in the /usr/obj directory in the building process above.

Note: if you wish to distribute the resultant file sets by HTTP for use by the upgrade or install scripts, you will need to add an index.txt file that contains the list of all the files in your newly created release.

# ls -nT > index.txt

Building X

Starting with X.Org v7, X switched to a modular build system, splitting the X.Org source tree into more than three hundred more-or-less independent packages.

To simplify life for OpenBSD users, a meta-build called Xenocara was developed. This system converts X back into one big tree to be built in one process. As an added bonus, this build process is much more similar to the build process used by the rest of OpenBSD than the previous versions were.

The official instructions for building X exist in the xenocara/README file and in step 5 of release(8).

Further reading on the build process

Common problems when compiling

Most of the time, problems in the build process are caused by not following the directions carefully. There are occasional real problems with building -current from the most recent snapshot, but failures when building -release or -stable are almost always user error.

Most problems are usually one of the following:

I forgot to make obj before make build

By doing a make build before doing a make obj, you will end up with the object files scattered in your /usr/src directory. This is a bad thing. If you wish to try to avoid re-fetching your entire src tree again, you can try the following to clean out obj files:
$ cd /usr/src
$ find . -type l -name obj | xargs rm
$ make cleandir
$ rm -rf /usr/obj/*
$ make obj

The build stopped with a "Signal 11" error

Building OpenBSD and other programs from source is a task which pushes hardware harder than most others, making intensive use of CPU, disk and memory. Signal 11 failures are typically caused by hardware problems.

You will probably find it best to repair or replace the components that are causing trouble, as problems may show themselves in other ways in the future.

For much more information, see the Sig11 FAQ.

Miscellaneous questions and tips

Why is /usr/obj on its own partition?

If you build often, one benefit is simple: it is typically much faster to...
# umount /usr/obj
# newfs YourObjPartition
# mount /usr/obj
...than to remove the contents of the directory with rm.

How do I not build parts of the tree?

Use the SKIPDIR option of mk.conf(5).

Can I cross-compile?

Cross-compiling tools are in the system, for use by developers bringing up a new platform. However, they are not maintained for general use.

When the developers bring up support for a new platform, one of the first big tests is a native-build. Building the system from source puts considerable load on the OS and machine, and does a very good job of testing how well the system really works. For this reason, OpenBSD does all the build process on the platform the build is being used for.

Custom kernels

There are three ways to customize a kernel: It is recommended that you read config(8) first.

Boot-time configuration

Sometimes when booting your system you might notice that the kernel finds your device but maybe at the wrong IRQ. Without rebuilding the kernel, you can use OpenBSD's boot time kernel configuration, boot_config(8).

However, this will only correct your problem for one time. If you reboot, you will have to repeat this procedure. So, this is only a temporary fix, and you should correct the problem using config(8).

To boot into the User Kernel Config, or UKC, use the -c option at boot-time.

boot> boot hd0a:/bsd -c
Doing this will bring up a UKC prompt. Type help for a list of available commands.

Using config(8) to change your kernel

The -e and -u options of config(8) can be extremely helpful and save wasted time compiling your kernel. The -e flag allows you to enter the UKC or User Kernel Config on a running system. These changes will then take place on your next reboot. The -u flag tests to see if any changes were made to the running kernel during boot, meaning you used boot -c to enter the UKC while booting your system.

For safety's sake, use the -o option which writes the changes out to the file specified. For example: config -e -o bsd.new /bsd will write the changes to bsd.new. Kernel modification examples are given in the config(8) manpage.

Building a custom kernel

Only the GENERIC and GENERIC.MP kernels are supported by the OpenBSD team. The GENERIC kernel configuration is the combination of the options in /usr/src/sys/arch/$(machine)/conf/GENERIC and /usr/src/sys/conf/GENERIC. Reporting a problem on a customized kernel will almost always result in you being told to try to reproduce the problem with a GENERIC kernel.

Read the config(8) and the options(4) manpages first. The following steps are part of compiling a custom kernel:

$ cd /usr/src/sys/arch/$(machine)/conf
$ cp GENERIC CUSTOM
$ vi CUSTOM    # make your changes
$ config CUSTOM
$ cd ../compile/CUSTOM
$ make

More on OpenBSD's flavors

It is worth pointing out that the name -stable is not intended to imply that -current is unreliable or less robust in production. Rather, the APIs (how the programs talk to the OS) and features of -current are changing and evolving, whereas the operation and APIs of -stable are the same as the release it is based on. This means you shouldn't have to relearn features of your system, change any configuration files, or have any problem adding additional applications to your system.

In fact, as our hope is to continually improve OpenBSD, the goal is that -current should be more reliable, more secure and, of course, have greater features than -stable. Put bluntly, the "best" version of OpenBSD is -current.

Most users should be running either -stable or -release. That being said, many people do run -current on production systems, and it is important that people do so to identify bugs and test new features. However, if you don't know how to properly describe, diagnose and deal with a problem, don't tell yourself (or anyone else) that you're "helping the project" by running -current. "It didn't work!" is not a useful bug report. "The recent changes to the pciide driver broke compatibility with my Slugchip-based IDE interface, dmesg of working and broken systems follow..." might be a useful report.

There are times when "normal" users may wish to live on the cutting edge and run -current. The most common reason is that the user has a device which is not supported by -release (and thus, not -stable), or wishes to use a new feature of -current. In this case, the choice may be either -current or not using the device, and -current may be the better option. However, one should not expect hand-holding from the developers.

CVS tips