FAQ - Building the System from Source
There are three flavors of OpenBSD:
Graphically, the development of these flavors looks something like this:
- -release: The version of OpenBSD shipped every six months.
- -stable: The -stable branch is -release plus patches
found on the errata page.
When very important fixes are made to -current, they are backported
to the supported -stable branches.
- -current: The -current branch is where active development
work is done.
Every six months, -current is tagged and becomes the next
In the above illustration, the vertical dotted lines denote bug fixes being
incorporated into the -stable branches.
,------o-----------o----X 5.7 Stable
| . .
| . ,------o---------o----X 5.8 Stable
| . | . .
| . | . ,----o----------o--> 5.9 Stable
| . | . | . .
| . | . | . ,-----o--> 6.0 Stable
| . | . | . | .
| . | . | . | .
The name -stable refers to API-stability: the way programs talk to the
OS is not changed in this branch.
In contrast, in -current, the APIs are changing and evolving.
New users should be running either -stable or -release.
That being said, many people do run -current on production systems to
help catch bugs and test new features.
Between formal releases of OpenBSD, snapshots are made available through
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, make sure it is reported.
A recent snapshot is usually all you need to run -current.
If you wish to build it from source, starting from the latest snapshot is
Check following -current and using snapshots
for any configuration changes or extra steps necessary to build -current
Building OpenBSD from source
Building OpenBSD from source involves a number of steps:
This FAQ section is intended to help you with the necessary preparation.
The main reference is
- Upgrading to the closest available binaries
- Fetching the source code
- Building a new kernel and userland, as explained in steps 2 and 3 of
- Optionally, making a release and
Upgrading to the closest available binaries
Do not attempt to go from one release to another by compiling from source.
Make sure you have the closest available binaries installed.
This is either OpenBSD x.y-release if you want to build
OpenBSD x.y-stable, or the latest snapshot if you wish to build
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.
You can also maintain a local CVS repository using the
CVSync or rsync programs, available as
An introduction to cvs(1)
and detailed instructions for fetching the source trees are on the
anonymous CVS page.
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.
Avoiding root privileges
Avoid running cvs(1) as root.
The /usr/src directory (where your source will typically go) is
writable by the wsrc group by default, so add users that need
to use cvs(1) to that group.
This change takes effect with exampleuser's next login.
# user mod -G wsrc exampleuser
If you want to fetch xenocara or ports as this user, you must create the
directories and set their permissions manually.
# cd /usr
# mkdir -p xenocara ports
# chgrp wsrc xenocara ports
# chmod 775 xenocara ports
Example: Fetching the -stable trees
To fetch the -stable src tree, specify the branch you want with
the -r flag
Once you have the tree checked out, you can update it at a later time with:
$ cd /usr
$ cvs -qd email@example.com:/cvs checkout -rOPENBSD_6_0 -P src
Replace src with xenocara or ports as appropriate.
As all parts of OpenBSD must be kept in sync, all the trees you use should be
checked out and updated at the same time.
$ cd /usr/src
$ cvs -q up -Pd
Example: Fetching the -current trees
To fetch a -current src tree, you can use the following:
Update the tree with:
$ cd /usr
$ cvs -qd firstname.lastname@example.org:/cvs checkout -P src
Replace src with the module you want, such as xenocara or
$ cd /usr/src
$ cvs -q up -Pd
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 steps 2 and 3 of
Making a release
A release is the complete set of files that can be used to install or upgrade
OpenBSD on another system.
An example use would be to build -stable on a fast machine, then make a
release to be installed on all your other machines.
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.
The instructions on making a release are in
The release process uses the binaries created in the /usr/obj
directory in the building process above.
Note: if you wish to distribute the resulting 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.
If you'd like to cryptographically sign the sets you created, the
signify(1) man page has details
on how to do so.
# ls -nT > index.txt
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
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
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
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...
...than to remove the contents of the directory with rm.
# umount /usr/obj
# newfs YourObjPartition
# mount /usr/obj
How do I skip building parts of the tree?
Use the SKIPDIR option of
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.
There are three ways to customize a kernel:
It is recommended that you read
- boot-time configuration using
- permanent modification of a compiled kernel using
- compilation of a custom kernel
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
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
To boot into the User Kernel Config, or UKC, use the -c option at
Doing this will bring up a UKC prompt.
Type help for a list of available commands.
boot> boot hd0a:/bsd -c
Using config(8) to change your kernel
The -e and -u options of
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
Kernel modification examples are given in the
config(8) man page.
Building a custom kernel
Only the GENERIC and GENERIC.MP kernels are supported by the
The GENERIC kernel configuration is the combination of the options in
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) man pages 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