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.
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
#svn update /usr/src
check /usr/src/UPDATING
#cd /usr/src
#make -j4buildworld
#make -j4kernel
#shutdown -r now
#cd /usr/src
#make installworld
#mergemaster -Ui
#shutdown -r now
Get the latest version of the source. See Section 23.5.3, “Updating the Source” for more information on obtaining and updating source.
Check
/usr/src/UPDATINGfor any manual steps required before or after building from source. Go to the source directory.
Compile the world, everything except the kernel.
Compile and install the kernel. This is equivalent to
make buildkernel installkernel. Reboot the system to the new kernel.
Go to the source directory.
Install the world.
Update and merge configuration files in
/etc/. Restart the system to use the newly-built world and kernel.
Read /usr/src/UPDATING. Any manual
steps that must be performed before or after an update are
described in this file.
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:
#svn info /usr/srcPath: /usr/src Working Copy Root Path: /usr/src ...
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.
Determine which version of FreeBSD is being used with uname(1):
#uname -r10.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#svn checkout https://svn.freebsd.org/base/releng/10.3/usr/src
| Move the old directory out of the way. If there are no local modifications in this directory, it can be deleted. |
| 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. |
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.
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
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.
Building the world and kernel with four jobs:
#make -j4 buildworld buildkernel
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
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/,
where arch/conf/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
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
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.
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