23.5. Updating FreeBSD from Source

Updating FreeBSD by compiling from source offers several
advantages over binary updates. Code can be built with options
to take advantage of specific hardware. Parts of the base
system can be built with non-default settings, or left out
entirely where they are not needed or desired. The build
process takes longer to update a system than just installing
binary updates, but allows complete customization to produce
a tailored version of FreeBSD.

23.5.1. Quick Start

This is a quick reference for the typical steps used to
update FreeBSD by building from source. Later sections describe
the process in more detail.

This indicates that /usr/src/
is under version control and can be updated with
svn(1):

#svn update /usr/src

The update process can take some time if the directory has
not been updated recently. After it finishes, the source code
is up to date and the build process described in the next
section can begin.

Obtaining the Source:

If the output says
'/usr/src' is not a working copy, the
files there are missing or were installed with a different
method. A new checkout of the source is required.

Table 23.1. FreeBSD Versions and Repository Paths

uname -r Output

Repository Path

Description

X.Y-RELEASE

base/releng/X.Y

The Release version plus only critical security
and bug fix patches. This branch is recommended
for most users.

X.Y-STABLE

base/stable/X

The Release version plus all additional
development on that branch.
STABLE refers to the
Applications Binary Interface
(ABI) not changing, so software
compiled for earlier versions still runs. For
example, software compiled to run on FreeBSD 10.1
will still run on FreeBSD 10-STABLE compiled
later.

STABLE branches occasionally have bugs or
incompatibilities which might affect users,
although these are typically fixed quickly.

X-CURRENT

base/head/

The latest unreleased development version of
FreeBSD. The CURRENT branch can have major bugs or
incompatibilities and is recommended only for
advanced users.

23.5.4. Building from Source

The world, or all
of the operating system except the kernel, is compiled. This
is done first to provide up-to-date tools to build the kernel.
Then the kernel itself is built:

#cd /usr/src#make buildworld#make buildkernel

The compiled code is written to
/usr/obj.

These are the basic steps. Additional options to control
the build are described below.

23.5.4.1. Performing a Clean Build

Some versions of the FreeBSD build system leave
previously-compiled code in the temporary object directory,
/usr/obj. This can speed up later
builds by avoiding recompiling code that has not changed.
To force a clean rebuild of everything, use
cleanworld before starting
a build:

#make cleanworld

23.5.4.2. Setting the Number of Jobs

Increasing the number of build jobs on multi-core
processors can improve build speed. Determine the number of
cores with sysctl hw.ncpu. Processors
vary, as do the build systems used with different versions
of FreeBSD, so testing is the only sure method to tell how a
different number of jobs affects the build speed. For a
starting point, consider values between half and double the
number of cores. The number of jobs is specified with
-j.

Example 23.1. Increasing the Number of Build Jobs

Building the world and kernel with four jobs:

#make -j4 buildworld buildkernel

23.5.4.3. Building Only the Kernel

A buildworld must be
completed if the source code has changed. After that, a
buildkernel to build a kernel can
be run at any time. To build just the kernel:

#cd /usr/src#make buildkernel

23.5.4.4. Building a Custom Kernel

The standard FreeBSD kernel is based on a
kernel config file called
GENERIC. The
GENERIC kernel includes the most
commonly-needed device drivers and options. Sometimes it
is useful or necessary to build a custom kernel, adding or
removing device drivers or options to fit a specific
need.

For example, someone developing a small embedded
computer with severely limited RAM could
remove unneeded device drivers or options to make the kernel
slightly smaller.

Kernel config files are located in
/usr/src/sys/arch/conf/,
where arch is the output from
uname -m. On most computers, that is
amd64, giving a config file directory of
/usr/src/sys/amd64/conf/.

Tip:

/usr/src can be deleted or
recreated, so it is preferable to keep custom kernel
config files in a separate directory, like
/root. Link the kernel config file
into the conf directory. If that
directory is deleted or overwritten, the kernel config
can be re-linked into the new one.

A custom config file can be created by copying the
GENERIC config file. In this example,
the new custom kernel is for a storage server, so is named
STORAGESERVER: