dfly handbook suggestion...

John Leimon jleimon at sbcglobal.net
Fri Oct 14 16:57:09 PDT 2005

I have modified the Building and Installing a Custom
Kernel page in the dfly to better suit new users.

In specific I added segment within 'Building a Kernel'
that states that buildworld needs to be run after
using cvsup. This is not mentioned explicitly in the
original page and should ease confusion esp. in new
users trying to build a custom kernel after cvsup'ing
in a source tree.

Modified version attached.

 - JohnTitle: Building and Installing a Custom Kernel

DragonFly Handbook

Chapter 9 Configuring the DragonFly

9.3 Building
and Installing a Custom Kernel

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 /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 either i386 or
amd64, at this point in development. Everything inside a
particular architecture's directory deals with that architecture only; the rest of the
code is common to all platforms to which DragonFly could potentially be ported. Notice
the logical organization of the directory structure, with each supported device, file
system, and option in its own subdirectory.

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 via cvsup.

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

Traditionally, this name is in all capital letters and, if you are maintaining
multiple DragonFly 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 config 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. Five
seconds after you do that you realize that you have deleted your custom kernel config
file. 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 config 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

Note: You must execute these and all of the following commands under the root account or you will get permission
denied errors.

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, DragonFly 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: Be sure to always check the file /usr/src/UPDATING, before you perform any update steps, in the case
you sync your source tree with the latest
sources of the DragonFly project. In this file all important issues with updating
DragonFly are typed out. /usr/src/UPDATING always fits your
version of the DragonFly source, and is therefore more accurate for new information than
the handbook.

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

If you have modified your source tree using CVSup then you will have to
 use the buildworld, buildkernel sequence as follows:

Change to the /usr/src directory.

# cd /usr/src

Build userland programs.

# make buildworld

Compile the kernel.

# make buildkernel KERNCONF=MYKERNEL

Install the new kernel.

# make installkernel KERNCONF=MYKERNEL

Install userland files.

# make installworld

installworld cycle (you
have not run CVSup), then it is safe to use the quickworld and quickkernel, buildworld, buildkernel sequence.

The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and reboot to use your new
kernel. In case something goes wrong, there are some troubleshooting instructions at the end of this
chapter. Be sure to read the section which explains how to recover in case your new
kernel does not boot.

Note: If you have added any new devices (such as sound cards), you may have to
add some device nodes to your /dev directory before you can use
them. For more information, take a look at Making
Device Nodes section later on in this chapter.


Why Build a Custom Kernel?
The Configuration File

Contact the Documentation
mailing list for comments, suggestions and questions about this document.

More information about the Docs mailing list