File: [local] / www / faq / faq5.html (download) (as text)
Revision 1.338, Wed Apr 3 19:59:04 2024 UTC (8 weeks, 2 days ago) by tj
Branch: MAIN
CVS Tags: HEAD
Changes since 1.337: +2 -2 lines
7.5 updates
|
<!doctype html>
<html lang=en id=faq>
<!-- If you make edits to any FAQ documents, please start each sentence
on a new line, and try to keep the general formatting consistent
with the rest of the pages -->
<title>OpenBSD FAQ: Building the System from Source</title>
<meta charset=utf-8>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="../openbsd.css">
<link rel="canonical" href="https://www.openbsd.org/faq/faq5.html">
<h2 id=OpenBSD>
<a href="../index.html">
<i>Open</i><b>BSD</b></a>
FAQ - Building the System from Source
<small>
<a href="index.html">[FAQ Index]</a>
</small>
</h2>
<hr>
<ul>
<li><a href="#Flavors" >OpenBSD's Flavors</a>
<li><a href="#Snapshots" >Development Snapshots</a>
<li><a href="#Bld" >Building OpenBSD from Source</a>
<li><a href="#Release" >Making a Release</a>
<li><a href="#Xbld" >Building X</a>
<li><a href="#buildprobs" >Common Problems When Compiling</a>
<li><a href="#Miscellanea">Miscellaneous Questions and Tips</a>
<li><a href="#Custom" >Custom Kernels</a>
<li><a href="#Diff" >Preparing a Diff</a>
</ul>
<hr>
<h2 id="Flavors">OpenBSD's Flavors</h2>
There are three flavors of OpenBSD:
<ul>
<li><b>releases:</b> The version of OpenBSD shipped every six months.
<li><b>-current:</b> The development branch.
Every six months, -current is tagged and becomes the next release.
<li><b>-stable:</b> A release plus patches found on the
<a href="../errata.html">errata page</a>.
When very important fixes are made to -current, they are backported
to the supported -stable branches.
</ul>
Only the two most recent OpenBSD releases receive
<a href="faq10.html#Patches">security and reliability fixes</a> for the
base system.
<p>
New users should be running either -stable or a release.
That being said, many people do run -current on production systems to
help catch bugs and test new features.
<h2 id="Snapshots">Development Snapshots</h2>
Snapshots of the -current branch are made available between formal releases
of OpenBSD.
These are builds of whatever code is in the tree at the time.
<p>
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
required.
Check the <a href="current.html">following -current and using snapshots</a>
page for any configuration changes or extra steps needed to build from source.
<p>
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 <a href="../report.html">reported</a>.
<h2 id="Bld">Building OpenBSD from Source</h2>
Building OpenBSD from source involves a number of steps:
<ul>
<li>Upgrading to the closest available binaries
<li>Fetching the source code
<li>Building a new kernel and userland, as explained in steps 2 and 3 of
<a href="https://man.openbsd.org/release">release(8)</a>
<li>Optionally, <a href="#Release">making a release</a> and
<a href="#Xbld">building X</a>
</ul>
This FAQ section is intended to help you with the necessary preparation.
The main reference is <a href="https://man.openbsd.org/release">release(8)</a>.
<h3 id="BldBinary">Upgrading to the Closest Available Binaries</h3>
Do not attempt to go from one release to another by compiling from source.
<p>
Make sure you have the closest available binaries installed.
This is either OpenBSD x.y if you want to build OpenBSD x.y-stable,
or the latest snapshot if you wish to build -current.
<h3 id="BldGetSrc">Fetching the Source Code</h3>
OpenBSD uses the <a href="https://savannah.nongnu.org/projects/cvs">CVS</a>
version control system to manage its source.
The <a href="https://man.openbsd.org/cvs">cvs(1)</a> program is used to pull a
copy of the desired source to your local machine for compilation.
An introduction to <a href="https://man.openbsd.org/cvs">cvs(1)</a>
and detailed instructions for fetching the source trees are on the
<a href="../anoncvs.html">anonymous CVS</a> page.
First, you must <code>cvs checkout</code> the source tree.
After that, you maintain the tree by running <code>cvs update</code> to pull
updated files to your local tree.
You can also maintain a local CVS repository using the <code>reposync</code>
program, available as a <a href="faq15.html">package</a>.
Setting up a mirror of the repository is also explained on the
<a href="../anoncvs.html#rsync">anonymous CVS</a> page.
<h4 id="wsrc">Avoiding Root Privileges</h4>
Avoid running <a href="https://man.openbsd.org/cvs">cvs(1)</a> as root.
The <code>/usr/src</code> directory (where your source will typically go) is
writable by the <code>wsrc</code> group by default, so add users that need
to use <a href="https://man.openbsd.org/cvs">cvs(1)</a> to that group.
<pre class="cmdbox">
# <b>user mod -G wsrc exampleuser</b>
</pre>
This change takes effect with exampleuser's next login.
<p>
If you want to fetch xenocara or ports as this user, you must create the
directories and set their permissions manually.
<pre class="cmdbox">
# <b>cd /usr</b>
# <b>mkdir -p xenocara ports</b>
# <b>chgrp wsrc xenocara ports</b>
# <b>chmod 775 xenocara ports</b>
</pre>
<h4>Fetching -stable</h4>
To fetch the -stable <code>src</code> tree, specify the branch you want with
the <code>-r</code> flag:
<pre class="cmdbox">
$ <b>cd /usr</b>
$ <b>cvs -qd anoncvs@anoncvs.example.org:/cvs checkout -rOPENBSD_7_5 -P src</b>
</pre>
Once you have the tree checked out, you can update it at a later time with:
<pre class="cmdbox">
$ <b>cd /usr/src</b>
$ <b>cvs -q up -Pd -rOPENBSD_7_5</b>
</pre>
Replace <code>src</code> with <code>xenocara</code> or <code>ports</code>
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.
<h4>Fetching -current</h4>
To fetch a -current src tree, you can use the following:
<pre class="cmdbox">
$ <b>cd /usr</b>
$ <b>cvs -qd anoncvs@anoncvs.example.org:/cvs checkout -P src</b>
</pre>
Update the tree with:
<pre class="cmdbox">
$ <b>cd /usr/src</b>
$ <b>cvs -q up -Pd -A</b>
</pre>
Replace <code>src</code> with the module you want, such as <code>xenocara</code>
or <code>ports</code>.
<h3>Building OpenBSD</h3>
At this point you are ready to build OpenBSD from source.
<p>
If you are building -current, review changes and special build
instructions listed on <a href="current.html">this page</a>.
<p>
Follow the detailed instructions in steps 2 and 3 of
<a href="https://man.openbsd.org/release">release(8)</a>.
<h3>Further Reading on the Build Process</h3>
<ul>
<li><a href="https://man.openbsd.org/mk.conf">mk.conf(5)</a>
<li><a href="https://cvsweb.openbsd.org/src/Makefile">
<code>src/Makefile</code></a>
<li><a href="https://cvsweb.openbsd.org/src/share/mk/bsd.README">
<code>/usr/share/mk/bsd.README</code></a>
<li><a href="https://man.openbsd.org/config">config(8)</a>
<li><a href="https://man.openbsd.org/options">options(4)</a>
</ul>
<h2 id="Release">Making a Release</h2>
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.
<p>
The instructions on making a release are in
<a href="https://man.openbsd.org/release">release(8)</a>.
The release process uses the binaries created in the <code>/usr/obj</code>
directory in the building process above.
<p>
Note: if you wish to distribute the resulting file sets by HTTP(s) for use by
the upgrade or install scripts, you will need to add an <code>index.txt</code>
file that contains the list of all the files in your newly created release.
<pre class="cmdbox">
# <b>ls -nT > index.txt</b>
</pre>
If you'd like to cryptographically sign the sets you created, the
<a href="https://man.openbsd.org/signify">signify(1)</a> man page has details
on how to do so.
<h3>Setting Up Your System</h3>
Making a release requires a <code>noperm</code> partition.
This allows the build infrastructure to use the unprivileged <code>build</code>
user for much of the process.
<p>
Create a filesystem on <code>/dest</code> with the <code>noperm</code>
<a href="https://man.openbsd.org/mount">mount(8)</a> option set.
The corresponding <a href="https://man.openbsd.org/fstab">fstab(5)</a>
line might look like this:
<pre class="cmdbox">
c73d2198f83ef845.m /dest ffs rw,nosuid,noperm 1 2
</pre>
The root directory of this filesystem must be owned by <code>build</code> with
permissions <code>700</code>:
<pre class="cmdbox">
# <b>chown build /dest</b>
# <b>chmod 700 /dest</b>
</pre>
Create the <code>DESTDIR</code> directories for base and xenocara:
<pre class="cmdbox">
# <b>mkdir /dest/{,x}base</b>
</pre>
Your <code>RELEASEDIR</code> does not need to be on a <code>noperm</code>
filesystem.
Make sure that it is owned by <code>build</code> and has at least permissions
<code>u=rwx</code>.
<h3>Using an mfs noperm Partition</h3>
You may want to use an <a href="https://man.openbsd.org/mount_mfs">mfs</a>
partition instead of a physical disk.
Add a line similar to this to your <code>/etc/fstab</code>:
<pre class="cmdbox">
swap /dest mfs rw,nosuid,noperm,-P/var/dest,-s1.5G,noauto 0 0
</pre>
Create the prototype <code>DESTDIR</code> directories:
<pre class="cmdbox">
# <b>mkdir -p /var/dest/{,x}base</b>
# <b>chown -R build /var/dest</b>
# <b>chmod -R 700 /var/dest</b>
</pre>
Now you can mount <code>/dest</code> before making a release:
<pre class="cmdbox">
# <b>mount /dest</b>
</pre>
<h2 id="Xbld">Building X</h2>
Starting with <a href="https://www.x.org/wiki/">X.Org</a> v7, X switched to a
modular build system, splitting the X.Org source tree into more than
three hundred more-or-less independent packages.
<p>
To simplify life for OpenBSD users, a meta-build called
<a href="https://xenocara.org">Xenocara</a> 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.
<p>
The official instructions for building X exist in the
<a href="https://cvsweb.openbsd.org/xenocara/README">
<code>xenocara/README</code></a> file and in step 5 of
<a href="https://man.openbsd.org/release">release(8)</a>.
<h2 id="buildprobs">Common Problems When Compiling</h2>
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 a release or -stable
are almost always user error.
<p>
Most problems are usually one of the following:
<ul>
<li>Failing to start from the <a href="#BldBinary">appropriate binaries</a>.
<li><a href="#BldGetSrc">Checking out</a> the wrong branch of the tree.
<li>Forgetting to read <a href="current.html">following -current</a>
before building -current.
<li>Skipping the reboot step after building and installing a new kernel.
</ul>
<h3 id="ProbObj">I forgot to <code>make obj</code> before <code>make build</code></h3>
By doing a <code>make build</code> before doing a <code>make obj</code>,
you will end up with the object files scattered in your <code>/usr/src</code>
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:
<pre class="cmdbox">
$ <b>cd /usr/src</b>
$ <b>find . -type l -name obj -delete</b>
$ <b>make cleandir</b>
$ <b>rm -rf /usr/obj/*</b>
$ <b>make obj</b>
</pre>
<h3 id="sig11">The build stopped with a "Signal 11" error</h3>
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 <i>typically</i> caused by hardware problems.
<p>
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.
<p>
For much more information, see the
<a href="https://www.bitwizard.nl/sig11/">Sig11 FAQ</a>.
<h2 id="Miscellanea">Miscellaneous Questions and Tips</h2>
<h3>Add your user to the <code>wobj</code> group</h3>
If you intend to compile individual programs in the source tree -- for example,
to do development -- you'll want to add your user to the <code>wobj</code>
group.
This will allow you to write to <code>/usr/obj</code>.
<h3>Tag Files</h3>
Being editors for developers, <a href="https://man.openbsd.org/mg">mg(1)</a>
and <a href="https://man.openbsd.org/vi">vi(1)</a> have built-in support for
<a href="https://man.openbsd.org/ctags">ctags(1)</a> files, which allow you
to navigate source trees quickly.
<p>
In most program or library source directories, you can create a
<code>./tags</code>
file by running:
<pre class="cmdbox">
$ <b>make tags</b>
</pre>
When building and installing <code>libc</code>, a
<code>/var/db/libc.tags</code> file is also created.
<p>
By default, kernel tags for each architecture are located in
<code>/sys/arch/$(machine)/</code>.
These files can be created with <code>make tags</code> from
<code>/sys/kern</code>.
You may want to run <code>make links</code> as root to place a symlink to
your architecture's kernel <code>tags</code> file in each directory and in
<code>/var/db/</code>.
<h3>How do I skip building parts of the tree?</h3>
Use the <code>SKIPDIR</code> option of
<a href="https://man.openbsd.org/mk.conf">mk.conf(5)</a>.
<h3>Can I cross-compile?</h3>
Cross-compiling tools are in the system, for use by developers bringing
up a new platform.
However, they are not maintained for general use.
<p>
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.
<h2 id="Custom">Custom Kernels</h2>
There are three ways to customize a kernel:
<ul>
<li>temporary boot-time configuration using
<a href="https://man.openbsd.org/boot_config">boot_config(8)</a>
<li>permanent modification of a compiled kernel using
<a href="https://man.openbsd.org/config">config(8)</a>
<li>compilation of a custom kernel
</ul>
<h3 id="BootConfig">Boot-Time Configuration</h3>
OpenBSD's boot-time kernel configuration,
<a href="https://man.openbsd.org/boot_config">boot_config(8)</a>,
allows an administrator to modify certain kernel settings, such as
enabling or disabling support for various devices, without recompiling
the kernel itself.
<p>
To boot into the User Kernel Config, or UKC, use the <code>-c</code>
option at startup time:
<pre class="cmdbox">
Using drive 0, partition 3.
Loading......
probing: pc0 com0 com1 mem[638K 1918M a20=on]
disk: hd0+ hd1+
>> OpenBSD/amd64 BOOT 3.33
boot> <b>boot hd0a:/bsd -c</b>
</pre>
Doing this will bring up a UKC prompt.
Type <code>help</code> for a list of available commands.
<p>
Using <a href="https://man.openbsd.org/boot_config">boot_config(8)</a>
only provides a temporary change, meaning the procedure would have to be
repeated on every reboot.
The next section explains how to make the changes permanent.
<h3 id="config">Using config(8) to Change Kernel Options</h3>
Invoking <a href="https://man.openbsd.org/config">config(8)</a> with the
<code>-e</code> flag allows you to enter the UKC on a running system.
Any changes made will then take effect on the next reboot.
The <code>-u</code> flag tests to see if any changes were made to the running
kernel during boot, meaning you used <code>boot -c</code> to enter the UKC
while booting the system.
<p>
To avoid the risk of overwriting the working kernel with a broken one,
consider using the <code>-o</code> flag to write the changes out to a
separate kernel file for testing:
<pre class="cmdbox">
# <b>config -e -o /bsd.new /bsd</b>
</pre>
This will write your changes to the <code>/bsd.new</code> file.
Once you have booted from this new kernel and verified everything
works, the desired changes can be made permanent by placing them in
<a href="https://man.openbsd.org/bsd.re-config">bsd.re-config(5)</a>.
Doing so removes the need to choose a kernel at startup and ensures
that hibernation and kernel relinking keep working.
<p>
Kernel modification examples are given in the
<a href="https://man.openbsd.org/config">config(8)</a> man page.
<h3 id="Options">Building a Custom Kernel</h3>
Only the <code>GENERIC</code> and <code>GENERIC.MP</code> kernels are supported
by the OpenBSD team.
The <code>GENERIC</code> kernel configuration is the combination of the options
in <code>/sys/arch/$(machine)/conf/GENERIC</code>
and <code>/sys/conf/GENERIC</code>.
Reporting a problem on a customized kernel will almost always result in
you being told to try to reproduce the problem with a <code>GENERIC</code>
kernel.
<p>
Read the <a href="https://man.openbsd.org/config">config(8)</a> and the
<a href="https://man.openbsd.org/options">options(4)</a> man pages first.
The following steps are part of compiling a custom kernel:
<pre class="cmdbox">
$ <b>cd /sys/arch/$(machine)/conf</b>
$ <b>cp GENERIC CUSTOM</b>
$ <b>vi CUSTOM # make your changes</b>
$ <b>config CUSTOM</b>
$ <b>cd ../compile/CUSTOM</b>
$ <b>make</b>
</pre>
<h2 id="Diff">Preparing a Diff</h2>
If you have made changes to the source code that you want to share
with developers, follow these conventions:
<ul>
<li>Base your diff on a -current checkout.
<li>Use <code>cvs diff -uNp</code> to generate the diff.
<li>Send your diff inline in an email to the <b>tech</b>
<a href="../mail.html">mailing list</a>.
Make sure your email client does not mangle the whitespace.
</ul>
If you are using a <a href="https://github.com/openbsd">git mirror</a>
of the OpenBSD source tree, set
<pre class="cmdbox">
$ <b>git config diff.noprefix true</b>
</pre>
in your repository and generate your diff like this:
<pre class="cmdbox">
$ <b>git diff --relative .</b>
</pre>
![[BACK]](/icons/back.gif){kind=icon}
Return to faq5.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / www / faq