First, let us take a quick tour of the kernel build directory. All directories
mentioned will be relative to the main /usr/src/sys directory,
which is also accessible through the path name /sys. There are
a number of subdirectories here representing different parts of the kernel, but the most
important for our purposes are arch/conf, where you will edit your custom kernel
configuration, and compile, which is the staging area where
your kernel will be built. arch represents one of i386, alpha, amd64, ia64, powerpc, sparc64, or pc98 (an alternative development branch of PC hardware, popular in
Japan). Everything inside a particular architecture's directory deals with that
architecture only; the rest of the code is machine independent code common to all
platforms to which FreeBSD could potentially be ported. Notice the logical organization
of the directory structure, with each supported device, file system, and option in its
own subdirectory.
This chapter assumes that you are using the i386 architecture in the examples. If this
is not the case for your situation, make appropriate adjustments to the path names for
your system's architecture.
Note: If there is not a
/usr/src/sys directory on your system, then the kernel source
has not been installed. The easiest way to do this is by running sysinstall as root, choosing , then , then , then
and . If you
have an aversion to sysinstall and you have access to an
“official” FreeBSD CDROM, then you can also install the source from the
command line:
# mount /cdrom
# mkdir -p /usr/src/sys
# ln -s /usr/src/sys /sys
# cat /cdrom/src/ssys.[a-d]* | tar -xzvf -
# cat /cdrom/src/sbase.[a-d]* | tar -xzvf -
Next, move to the arch/conf directory and copy the GENERIC configuration file to the name you want to give your
kernel. For example:
# cd /usr/src/sys/i386/conf
# cp GENERIC MYKERNEL
Traditionally, this name is in all capital letters and, if you are maintaining
multiple FreeBSD machines with different hardware, it is a good idea to name it after
your machine's hostname. We will call it MYKERNEL for the purpose of this example.
Tip: Storing your kernel configuration file directly under /usr/src can be a bad idea. If you are experiencing problems it can
be tempting to just delete /usr/src and start again. After
doing this, it usually only takes a few seconds for you to realize that you have deleted
your custom kernel configuration file. Also, do not edit GENERIC directly, as it may get overwritten the next time you update your source tree, and your kernel modifications will
be lost.
You might want to keep your kernel configuration file elsewhere, and then create a
symbolic link to the file in the i386 directory.
For example:
# cd /usr/src/sys/i386/conf
# mkdir /root/kernels
# cp GENERIC /root/kernels/MYKERNEL
# ln -s /root/kernels/MYKERNEL
Now, edit MYKERNEL with
your favorite text editor. If you are just starting out, the only editor available will
probably be vi, which is too complex to explain here, but is
covered well in many books in the bibliography. However,
FreeBSD does offer an easier editor called ee which, if you
are a beginner, should be your editor of choice. Feel free to change the comment lines at
the top to reflect your configuration or the changes you have made to differentiate it
from GENERIC.
If you have built a kernel under SunOS™ or some
other BSD operating system, much of this file will be very familiar to you. If you are
coming from some other operating system such as DOS, on the other hand, the GENERIC configuration file might seem overwhelming to you, so
follow the descriptions in the Configuration File
section slowly and carefully.
Note: If you sync your source tree with the
latest sources of the FreeBSD project, be sure to always check the file /usr/src/UPDATING before you perform any update steps. This file
describes any important issues or areas requiring special attention within the updated
source code. /usr/src/UPDATING always matches your version of
the FreeBSD source, and is therefore more up to date with new information than this
handbook.
You must now compile the source code for the kernel.
Building a Kernel
-
Change to the /usr/src directory:
# cd /usr/src
-
Compile the kernel:
# make buildkernel KERNCONF=MYKERNEL
-
Install the new kernel:
# make installkernel KERNCONF=MYKERNEL
Note: It is required to have full FreeBSD source tree to build the kernel.
Tip: By default, when you build a custom kernel, all kernel modules will be rebuilt as well. If you want to
update a kernel faster or to build only custom modules, you should edit /etc/make.conf before starting to build the kernel:
MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs
This variable sets up a list of modules to build instead of all of them.
WITHOUT_MODULES = linux acpi sound/sound sound/driver/ds1 ntfs
This variable sets up a list of modules to exclude from the build process. For other
variables which you may find useful in the process of building kernel, refer to make.conf(5) manual
page.
The new kernel will be copied to the /boot/kernel directory
as /boot/kernel/kernel and the old kernel will be moved to /boot/kernel.old/kernel. Now, shutdown the system and reboot to use
your new kernel. If something goes wrong, there are some troubleshooting instructions at the end of this
chapter that you may find useful. Be sure to read the section which explains how to
recover in case your new kernel does not boot.
Note: Other files relating to the boot process, such as the boot loader(8) and
configuration are stored in /boot. Third party or custom
modules can be placed in /boot/kernel, although users should be
aware that keeping modules in sync with the compiled kernel is very important. Modules
not intended to run with the compiled kernel may result in instability or
incorrectness.
