Building the KUSP Kernel¶
This is a brief guide on how to checkout and build the most current, stable version of a kernel from the (svn) repository.
Checking out the Kernel¶
Check out a kernel. Be careful about ensuring the correctness of the SVN URL for the kernel you wish to check out:
bash$ svn co <url-for-desired-kernel>
An example URL is:
https://subversion.ittc.ku.edu/svn/libertos/kernel/kurt/2.6.29/2.6.29.2-rt11-kusp
The SVN URL for the most recent KUSP kernel can be found here: Subversion Advice
Add a Build Directory¶
Now create a build directory for your kernel in the root of the kernel directory you just checked out and define a shell variable holding the root directory of the kernel, which is used many subsequent example commands:
bash$ cd <kernel-directory>; mkdir build
bash$ cd <kernel-directory>; export KERNELROOT='pwd'
- Note that KERNELROOT now contains the full path name of your kernel root directory.
Choosing a Configuration¶
Building a kernel requires the creation of a kernel configuration file, ‘.config’, in the /build file you just created. There are several methods of generating this file.
Using the Default Configuration¶
The simplest method is to use the default option which uses the predefined defaults for all kernel configuration options and tends to work with the vast majority of machines. If this is the first time you are building a kernel for a given target machine, it is prudent to build the kernel using this default configuration and see if it runs on the machine:
bash$ cd $KERNELROOT; make O=build defconfig
The O option allows you to target your build directory, using the .config file located within and placing all compiled object files there. After this step, it is no longer necessary to use the O option as long as you only attempt to configure, make, or install your kernel from the build directory.
Checking out a Configuration¶
Another method is to check out a set of existing example configurations, which can generally be found in the kernel SVN repositories, using a SVN URL containing a component specifying the kernel version which must match the version of kernel you have checked out. Be sure to check out the configuration file directory in some sibling location, and not directly within the root of your kernel tree. For example the command to check out the example configurations for the 2.6.29 KUSP kernels would be:
bash$ svn co https://subversion.ittc.ku.edu/svn/libertos/kernel/kurt/2.6.29/configs
Once this is done, simply select the <type>.config that will best suit your needs and move it to your kernel. An example might be:
bash$ cp config/default.config $KERNELROOT/build/.config
When using an example configuration file, you will need to use the oldconfig makefile option executed in the root of your kernel tree to target your existing .config file:
bash$ cd $KERNELROOT; make O=build oldconfig
Notes:
In processing the example configuration file, the oldconfig make target will, in essence, ask and answer for itself a large number kernel configuration questions, and in doing so, echo them to the screen. You do not need to be concerned with the details of what this means.
This merely establishes the environment in which the example configuration is used to build the kernel in this directory tree. As you wish to change the configuration as part of working with this kernel tree, you will use one of the standard interfaces for editing this configuration file:
bash$ cd $KERNELROOT/build; make menuconfig
or:
bash$ cd $KERNELROOT/build; make xconfig
If the .config file you selected is out of date with respect to the kernel you are building the first build step may ask questions about kernel configuration options that have been added since the .config file was made. As before, if you are unsure of the added options, it is usually safest to simply use the default for the given option, which will be the capitalized response option. You can also simply hit enter without typing in an option, and the default value will be automatically added to your configuration file.
This tutorial is not claiming to tell to how to configure your kernel as such. There are a wide range of tutorials on the WWW which you may wish to consult.
Using an Existing Configuration¶
The third method is to copy a .config file from an existing test kernel into the build directory that you just created:
bash$ cp $CONFIG_FILE_SOURCE/<your-selected-config> build/.config
- Note: The $CONFIG_FILE_SOURCE corresponds to the specific path to the .config file you wish to copy’‘
When using an existing configuration file, you will need to use the oldconfig makefile option executed in the root of your kernel tree to target your existing .config file:
bash$ cd $KERNELROOT; make O=build oldconfig
Notes:
In processing the example configuration file, the oldconfig make target will, in essence, ask and answer for itself a large number kernel configuration questions, and in doing so, echo them to the screen. You do not need to be concerned with the details of what this means.
This merely establishes the environment in which the example configuration is used to build the kernel in this directory tree. As you wish to change the configuration as part of working with this kernel tree, you will use one of the standard interfaces for editing this configuration file:
bash$ cd $KERNELROOT/build; make menuconfig or:: bash$ cd $KERNELROOT/build; make xconfig
If the .config file you selected is out of date with respect to the kernel you are building the first build step may ask questions about kernel configuration options that have been added since the .config file was made. As before, if you are unsure of the added options, it is usually safest to simply use the default for the given option, which will be the capitalized response option. You can also simply hit enter without typing in an option, and the default value will be automatically added to your configuration file.
This tutorial is not claiming to tell to how to configure your kernel as such. There are a wide range of tutorials on the WWW which you may wish to consult.
Make the Kernel¶
Simply change to your build directory, and type make. Here, we are additionally redirecting the makefile output to a separate file. We recommend this step as a method of collecting possible failure and warning statements for later review. Note that on slower machines, this can be a lengthy process. Consider making some tea or eating a sandwich:
bash$ cd $KERNELROOT/build; make >& make.out &
bash$ tail -f make.out
- Note that the first line starts making the kernel and echos output into “make.out” but there is nothing to watch on the screen. So, we let it run in the background and watch the output as it is put into the file with the tail command. One slight danger of this approach is that one has to pay attention to what is on the screen to know when the build has finished, because tail does not terminate automatically. Instead, you should type Ctl-c to exit tail.
- Note that this builds the kernel, all modules that are configured and maybe needed for installation on your target machine, and other administrative files that are handled as part of installing a kernel on a target machine.
Install the Kernel¶
For this step, you must be logged into the testbed machine on which you wish to install the kernel and in the build directory of the kernel you wish to install. These instructions assume that you are building the kernel on Yggdrasil in your work directory, and an important implication of that is that the /yggnfs is partition is available across NSF to the testbed machines on which we generally test kernels. Therefor, it is relatively easy to change into the directory of a kernel you wish to install on the testbed you wish to use. When first using a given testbed after it has been freshly kickstarted, you will have to set up the NFS mounting of the yggdrasil:/yggnfs partition and a couple of other things, as described in Testbed Setup.
Note that when you log into another machine, $KERNELROOT will no longer be defined on that machine, and you will have to define it again. You will need to install any modules your kernel has configured, and then install the kernel image itself. To do this, type:
bash$ cd $KERNELROOT/build; sudo make modules_install; sudo make install
Be careful not to miss the underline between “modules” and “install” on the first command.
Before you can use your kernel, you need to ensure your computer knows which kernel to boot up. To do this, you should edit your system’s grub configuration file to see how kernel installation may have changed it and to edit as required to make it say what you wish. The grub configuration file tells the computer which Linux kernel images are available when booting up, and which to use by default if the user does not make an explicit choice at boot time. On Fedora Core systems the grub configuration file is in ‘’/boot/grub/grub.conf’’ and the installation step in the kernel build process automatically creates a new entry for your newly built KUSP kernel.
Ubuntu Procedural Differences¶
On Ubuntu, and presumably other Debian based systems, the older file name /boot/grub/menu.lst is used, and the kernel install step does not automatically insert an entry in menu.lst for the new kernel, as happens automatically under Fedora Core. Under Ubuntu you will also have to create the initial RAM Disk image by hand, using the update-initramfs command:
bash$ cd /boot; sudo update-initramfs -k 2.6.29.2-rt11-kusp -c
You should execute this command before editing the grub configuration file int he next step, because one of the grub kernel configuration parameters is the name of the file this step creates.
Editing the Grub Configuration File¶
So you should open either /boot/grub/grub.conf or /boot/grub/menu.lst as present on your target machine. Recall that because you are using the sudo command you will be required to enter your password:
bash$ sudo <text-editor of your choice> /boot/grub/<your-system-grub-config-file>
- Note that if the editor of your choice does not happen to be installed, it is useful to be able to use the vi editor because it is virtually always installed with Linux.
Your grub configuration file should look something like this. You will have to make a new entry for your new kernel. In this case, the first entry is the one made for the kernel just built, “2.6.29.2-rt11-kusp”. Do not panic if they are not identical:
#boot=/dev/sda
default=1
timeout=5
splashimage=(hd0,0)/grub/splash.xpm.gz
hiddenmenu
title Fedora (2.6.29.2-rt11-kusp)
root (hd0,0)
kernel /vmlinuz-2.6.29.2-rt11-kusp ro root=LABEL=/ rhgb quiet n
initrd /initrd-2.6.29.2-rt11-kusp.img
title Fedora (2.6.24.4-rt4)
root (hd0,0)
kernel /vmlinuz-2.6.24.4-rt4 ro root=LABEL=/ rhgb quiet
initrd /initrd-2.6.24.4-rt4.img
title Fedora (2.6.21-1.3194.fc7)
root (hd0,0)
kernel /vmlinuz-2.6.21-1.3194.fc7 ro root=LABEL=/ rhgb quiet
initrd /initrd-2.6.21-1.3194.fc7.img
There are several things that are worth observing about the grub configuration file and it is important to remember that different Linux distributions at different times have followed different conventions so that your specific experience may well involve some variations.
- The grub configuration file contains references to all the kernel images your system may boot.
- The order in which the images are listed is important, and are numbered from the top starting at 0.
- The “default” variable specifies the number of the image booted if the user does not make an explicit choice from the grub.conf menu displayed during boot.
- At different times and with different distributions, the act of installing a new kernel image has inserted the new kernel’s information at the top of the list (position 0) or elsewhere, and updated the default variable to use the previous default or the new kernel. Therefore, you must be careful in examining the contents of the file to make sure it is saying what you want it to say.
- The “timeout” variable specifies the number of seconds the grub.conf menu will be displayed during boot, before the default kernel is used.
- In this particular grub configuration file, we have 3 kernel images available. The first, 2.6.29.2-rt11-kusp-icc, is number 0, with those following numbered 1 and 2. Locate the kernel image whose name matches the kernel you have just built and installed, and then set the default to match its number, then save your changes.
- If you are uncomfortable having your new kernel be the default, you will have to make sure you can see the console output during boot. The obvious way to do this is to have a keyboard and screen attached to the testing machine, or to a KVM switch attached to the testing machine. At ITTC we use both of these methods for different test targets. However, for the test bed machines we most often simply make the new kernel the default because problems during boot are relatively rare. If the machine fails to boot, seeing the console output is mandatory to choose a working kernel from the menu since the default does not boot successfully. Further, the netconsole approach is a powerful option, but it requires addition grub.conf line specification, inclusion of the netconsole option in the target kernel configuration, and running specific software on the development machine with which the target kernel is told to communicate.
- If you can see the console during boot, then it is often convenient to increase the value of the “timeout” option, which indicates the number of seconds your system will wait for you to select which kernel it should boot from the displayed menu.
The last step is to reboot your machine:
bash$ sudo reboot
During reboot, the system will send out a broadcast message indicating the machine is being brought down, and shortly thereafter, your ssh session connection will be terminated. Wait a “reasonable period” of time and then ssh into the machine again. If the machine has failed to reboot, or you are too eager, the ssh attempt will fail. Booting time varies with the target hardware, the kernel options, and possibly with phases of the moon, but 3 minutes is a reasonably conservative value to begin with. As you gain experience with a specific kernel you will have a fairly accurate feel for how long it will take.
Next Step: Now that you have built and installing the kernel, you must now build and install the KUSP user-level software tree.
