Recompiling world


Jump to: navigation, search



World is just a shorter way of referring to both the kernel and the userland. Recompiling world is the same thing as recompiling the entire base operating system. The approved FreeBSD way of doing this is described in the FreeBSD handbook. Here I will present a slightly modified method - painstakingly put together from years of recompiling world. This guide contains a few steps that are unnecessary if this is a brand new FreeBSD installation but it's written in a way so you can use it to recompile FreeBSD at any time.


Removing temporary files from previous compilation

While the operating system is being compiled, the new binaries are temporarily stored in /usr/obj and they aren't physically moved to the live filesystem until you say so. Before you start your world compilation you have to remove any files left there. If this is your first time, the folder is probably empty and the commands will generate some warnings, but that's fine.

# cd /usr/obj
# chflags -R noschg *
# rm -rf *

Check /usr/src/UPDATING

Before doing any compilation you should look at /usr/src/UPDATING to see if any important information has been added since last time you recompiled world. There may be extra steps to be carried out that is not covered in the generic compilation guide.

# less /usr/src/UPDATING

Compiling userland

Start this marathon procedure by compiling the userland first. Although the make option to do this is called buildworld it's only the userland being compiled. This may take a long time depending on the speed of your computer. One reference would be the 1,6GHz Core2 Duo I'm using which completes this task in 64 minutes.

In case something goes wrong during compilation it might be a good idea to capture all output. The script command takes care of that and stores the output in the file you specify.

# cd /usr/src
# make clean
# script /var/tmp/mw.out
# make buildworld
Note: If you have multiple CPUs in your computer, you can spawn several parallel compiler threads by modifying the last command. A good value for the -j option is the number of CPUs in your system +1.
# make -j3 buildworld

When the compilation has finished you exit script.

# exit

Compiling the kernel

Next you'll compile the kernel. The example assumes you have a custom kernel configuration file named MYKERNEL created earlier. This procedure also takes a while but the Core2 Duo finishes it in 11 minutes. Don't forget to capture the output here too.

# script /var/tmp/mk.out
# make buildkernel KERNCONF=MYKERNEL

When the compilation ends, exit script.

# exit
Note: You can of course use multiple CPUs during compilation here too.

Installing the kernel

The kernel is a critical component of the operating system. If you accidentally removed something from the configuration that is needed during boot you won't be able to start your computer normally. If you're not used to recover from such an event you should probably test the new kernel first before installing it permanently. The following commands will install the new kernel in a temporary directory, tell the computer to only use it during the next boot and then revert automatically to the previous kernel. If everything goes well you can replace the old kernel with the new one permanently.

# make installkernel KERNCONF=MYKERNEL KODIR=/boot/testing
# nextboot -k testing
# shutdown -r now

Check the console for any obvious error messages during boot. If everything looks good, logon and check with ifconfig that all your network adapters are recognized. If you feel satisfied the new kernel is working correctly, you can now install it permanently after backing up the old kernel.

# cd /boot
# rm -rf kernel.old
# mv kernel kernel.old
# mv testing kernel
# shutdown -r now

Stopping unnecessary services

You are now ready to install the userland system binaries. This guide will now differ slightly from the official FreeBSD guide in the way that you will not enter single user mode. FreeBSD is a multi user environment and it can be pretty dangerous replacing system binaries when users are working online and with several services running. Single user mode prevents all those problems but is a bit awkward to work in since you're limited to the console. Since this is a home router, you probably don't have that many users working on it so you can safely do this step in multi user mode if you just stop all unnecessary services first. Below are some examples of services that can be stopped and the commands to do it. If this is a new installation you don't have much else running than the services below.

# /etc/rc.d/sendmail stop
# /etc/rc.d/cron stop
# /etc/rc.d/syslogd stop

But if you're using this guide on a fully installed system you probably have a few more services running. Note that the folder for the start/stop scripts differs depending on whether it's services built into FreeBSD or if it's services you installed from ports.

# /usr/local/etc/rc.d/apache22 stop
# /usr/local/etc/rc.d/mysql-server stop

Don't stop sshd or dhclient since you need them running to be able to logon over the network.

Installing userland

When you install the rest of the system binaries, there's one folder that won't be overwritten automatically and that's /etc where most of the config files and startup scripts live. The content of the files in this folder must be compared carefully with the newly compiled versions and any differences must be merged manually so modifications you've done won't be overwritten accidentally. There is a utility to assist you with this and it's called mergemaster but it's not exceptionally user friendly. It's difficult to write a guide for this utility since the output from it will differ depending on how many configuration modifications you've done to your system and what version you're upgrading to. The basic idea though is that if mergemaster encounters a file that can't be replaced, because the original has been modified, you will be given a choice to keep the old version, install the new version or merge the two versions. The merging is done line by line with both versions showing on the screen side by side and you can select the left or right version line by line and then install the merged copy when finished. This example will only guide you through the use of mergemaster on a fresh FreeBSD installation and you won't encounter that merging scenario here but you should read section in the official FreeBSD guide to learn more.

Mergemaster is first run once before you install all the binaries to make sure important system groups and accounts needed are in place. This is usually only necessary when upgrading between major versions of FreeBSD.

# cd /usr/src
# mergemaster -p

Mergemaster won't find anything that needs to be updated in this run so it's perfectly fine to delete the temporary files created.

*** Beginning comparison

 *** Temp ./etc/master.passwd and installed have the same CVS Id, deleting
 *** Temp ./etc/group and installed have the same CVS Id, deleting

*** Comparison complete

Do you wish to delete what is left of /var/tmp/temproot? [no] yes

Now you'll install the actual system binaries.

# make installworld

After that you must run mergemaster again to compare the configuration files in /etc.

# mergemaster -iFU

This second run of mergemaster will find one conflicting file and it's the motd (Message of the Day), which is displayed every time you logon through ssh, so it's not a critical file in any way but a good example for this guide. Let's break the output down piece by piece.

  *** Displaying differences between ./etc/motd and installed version:

--- /etc/motd   2008-09-05 13:54:00.000000000 +0200
+++ ./etc/motd  2008-09-05 14:03:36.000000000 +0200

First, the output shows what files are being compared. The original file and its path is listed with the "---" in front of it. Below it, the new, temporary version of that file is listed with "+++" in front of it. Note that the temporary version has a dot first in its path. Then comes the actual differences between the two versions.

@@ -1,4 +1,4 @@
-FreeBSD 7.0-RELEASE-p3 (MYKERNEL) #0: Fri Jul 25 20:31:01 CEST 2008
+FreeBSD ?.?.?  (UNKNOWN)
 Welcome to FreeBSD!

The differences are displayed as a standard Unix unified diff listing. The first row tells you what ranges in the two versions are being compared. The "-" refers to the original file and the "+" refers to the new, temporary file. In this case the ranges compared are from row 1 and 4 rows in total in both versions. Rows beginning with a "-" have disappeared in the new version and rows beginning with a "+" have been added. In this particular case you can see something very strange. The motd displays some system information here, like the FreeBSD version and when it was compiled. But the new version of motd doesn't seem to contain this information. Well, that's correct but motd is one of those unfortunate special circumstances. It gets updated with the correct system information at every boot so you should select to install the new version of it even though it's counter intuitive. You're choices are listed next.

  Use 'd' to delete the temporary ./etc/motd
  Use 'i' to install the temporary ./etc/motd
  Use 'm' to merge the temporary and installed versions
  Use 'v' to view the diff results again

  Default is to leave the temporary file to deal with by hand

How should I deal with this? [Leave it for later] i

Here you choose to install the new version, which is the normal case, but this is the place you may have to choose other options during future upgrades. No more conflicting files should be found and once again you can remove any remaining temporary files.

*** Comparison complete
*** Saving mtree database for future upgrades

Do you wish to delete what is left of /var/tmp/temproot? [no] yes

The final steps would be to delete any obsolete files but this only makes sense if you upgrade between major version numbers. Still it doesn't hurt and for the completeness of this guide, I list the commands here.

# make delete-old
# make delete-old-libs

A reboot is now in place.

# shutdown -r now


  • /usr/src/UPDATING contains last minute updates that might affect the way you should recompile the operating system.
  • script is a utility that captures all output to a file. You terminate it by typing exit.


Next guide: Additional network configuration
Personal tools