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.

  • Update and Build

    # svnlite update /usr/src  1
    check /usr/src/UPDATING  2
    # cd /usr/src          3
    # make -j4 buildworld  4
    # make -j4 kernel      5
    # shutdown -r now      6
    # cd /usr/src          7
    # make installworld    8
    # mergemaster -Ui      9
    # shutdown -r now      10

    1

    Get the latest version of the source. See Section 23.5.3, “Updating the Source” for more information on obtaining and updating source.

    2

    Check /usr/src/UPDATING for any manual steps required before or after building from source.

    3

    Go to the source directory.

    4

    Compile the world, everything except the kernel.

    5

    Compile and install the kernel. This is equivalent to make buildkernel installkernel.

    6

    Reboot the system to the new kernel.

    7

    Go to the source directory.

    8

    Install the world.

    9

    Update and merge configuration files in /etc/.

    10

    Restart the system to use the newly-built world and kernel.

23.5.2. Preparing for a Source Update

Read /usr/src/UPDATING. Any manual steps that must be performed before or after an update are described in this file.

23.5.3. Updating the Source

FreeBSD source code is located in /usr/src/. The preferred method of updating this source is through the Subversion version control system. Verify that the source code is under version control:

# svnlite info /usr/src
Path: /usr/src
Working Copy Root Path: /usr/src
...

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

# svnlite 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 OutputRepository PathDescription
X.Y-RELEASEbase/releng/X.YThe Release version plus only critical security and bug fix patches. This branch is recommended for most users.
X.Y-STABLEbase/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-CURRENTbase/head/The latest unreleased development version of FreeBSD. The CURRENT branch can have major bugs or incompatibilities and is recommended only for advanced users.

Determine which version of FreeBSD is being used with uname(1):

# uname -r
10.3-RELEASE

Based on Table 23.1, “FreeBSD Versions and Repository Paths”, the source used to update 10.3-RELEASE has a repository path of base/releng/10.3. That path is used when checking out the source:

# mv /usr/src /usr/src.bak  1
# svnlite checkout https://svn.freebsd.org/base/releng/10.3 /usr/src  2

1

Move the old directory out of the way. If there are no local modifications in this directory, it can be deleted.

2

The path from Table 23.1, “FreeBSD Versions and Repository Paths” is added to the repository URL. The third parameter is the destination directory for the source code on the local system.

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:

# cp /usr/src/sys/amd64/conf/GENERIC /root/STORAGESERVER
# cd /usr/src/sys/amd64/conf
# ln -s /root/STORAGESERVER .

/root/STORAGESERVER is then edited, adding or removing devices or options as shown in config(5).

The custom kernel is built by setting KERNCONF to the kernel config file on the command line:

# make buildkernel KERNCONF=STORAGESERVER

23.5.5. Installing the Compiled Code

After the buildworld and buildkernel steps have been completed, the new kernel and world are installed:

# cd /usr/src
# make installkernel
# shutdown -r now
# cd /usr/src
# make installworld
# shutdown -r now

If a custom kernel was built, KERNCONF must also be set to use the new custom kernel:

# cd /usr/src
# make installkernel KERNCONF=STORAGESERVER
# shutdown -r now
# cd /usr/src
# make installworld
# shutdown -r now

23.5.6. Completing the Update

A few final tasks complete the update. Any modified configuration files are merged with the new versions, outdated libraries are located and removed, then the system is restarted.

23.5.6.1. Merging Configuration Files with mergemaster(8)

mergemaster(8) provides an easy way to merge changes that have been made to system configuration files with new versions of those files.

With -Ui, mergemaster(8) automatically updates files that have not been user-modified and installs new files that are not already present:

# mergemaster -Ui

If a file must be manually merged, an interactive display allows the user to choose which portions of the files are kept. See mergemaster(8) for more information.

23.5.6.2. Checking for Outdated Files and Libraries

Some obsolete files or directories can remain after an update. These files can be located:

# make check-old

and deleted:

# make delete-old

Some obsolete libraries can also remain. These can be detected with:

# make check-old-libs

and deleted with

# make delete-old-libs

Programs which were still using those old libraries will stop working when the library has been deleted. These programs must be rebuilt or replaced after deleting the old libraries.

Tip:

When all the old files or directories are known to be safe to delete, pressing y and Enter to delete each file can be avoided by setting BATCH_DELETE_OLD_FILES in the command. For example:

# make BATCH_DELETE_OLD_FILES=yes delete-old-libs

23.5.6.3. Restarting After the Update

The last step after updating is to restart the computer so all the changes take effect:

# shutdown -r now

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.