jwgoerz@users.sourceforge.net
Revision History | ||
---|---|---|
Revision v0.4 | 21 March 2002 | Revised by: jwg |
Rewrite. Added use of fakeroot, compiling modules by themselves. General corrections, license change from GNU FDL to GNU GPL. | ||
Revision v0.3 | 23 May 2001 | Revised by: jwg |
Updated section on symlinks, program version checks, how to compile as a regular user rather than root, filled in the checklist, added troubleshooting section(needs work). | ||
Revision v0.2 | 22 April 2001 | Revised by: jwg |
Quick fix on grammatical and spelling errors. |
This document is intended to help Debian newbies use the kernel-packaging system to create custom kernels. Copyright © 2001-2002 Jesse Goerz, NewbieDoc project. This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.
This manual is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.
A copy of the GNU General Public License is available as /usr/doc/copyright/GPL in the Debian GNU/Linux distribution or on the World Wide Web at the GNU website. You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Thank you Erdmut Pfeifer and Oliver Elphick for your prompt responses to my questions about make xconfig on debian-user! I couldn't have completed this document without your help.
Thanks to Sebastiaan for pointing out that almost everything could be done as a regular user when you're a member of the src group. Thanks to Robert Voigt for actually following the instructions to the letter and relaying his test results by identifying specific weaknesses in this document.
![]() | Compiling a kernel is not an insignificant thing. What you are about to attempt is usually only accomplished by experienced Debian users and administrators. |
![]() | You can make your system unbootable if you're not careful. I highly recommend you read the entire document, start to finish, at least once, and then build the kernel. (And even then, you may want to get more information.) |
Please remember that, inevitably, someone will use this document and screw up their system. Don't let that be you. If you don't understand something, get more information before proceeding. If you happen to be reading this and you see something you know is a mistake, please let me know at <newbiedoc-discuss@lists.sourceforge.net>.
First you need to install the following packages in order to follow along with this document.
You can install these by simply doing this (as the root user):
bash# apt-get install kernel-package dpkg-dev debianutils binutils libc6-dev gcc make kernel-source-2.2.19 task-tcltk-dev bin86 |
![]() | Note that bin86 is only required for PC's (not Macs or Alphas). Also, you can download any version of the kernel sources you wish but I chose 2.2.19 because it's the most current in Potato at the time of writing. I also recommend you choose a kernel version which is not the same as your current version. I will cover what to do if you must use the same version in later sections. |
![]() | A note about kernel source packages. The Debian maintainers have done an excellent job in packaging the kernel source into .deb files. I recommend you use those rather than source packages from other resources. The primary reason is the maintainers' packages unzip into a directory named kernel-source-Version. For some reason, the "official" kernel sources unzip into a directory called linux. This can cause problems if you're not careful when you do your unzipping. The only reason I can see not to use the Debian kernel source packages is if they don't have the version you need for some hardware requirement. If that's the case, the next section will cover how to avoid messing up your kernel sources. |
To find out the current version of your kernel do this:
bash$ uname -r |
bash# addgroup your_username src Adding user your_username to group src... Done. |
bash$ groups your_username src |
You should see the src group as shown in the above example. Next, we need to set up the source tree.
bash$ cd /usr/src |
bash:/usr/src$ ls kernel-source-2.2.19.tar.bz2 |
![]() | If you downloaded kernel sources from anywhere other than the Debian site you need to make sure you do not have a symlink called linux in your /usr/src directory. If you do you should remove that symlink before unzipping any sources. If you do not remove it before unzipping there is a good chance you will overwrite old source files and you will probably get a mess which may or may not compile correctly. Jump ahead to the section called Setting up the symlink. If you downloaded the sources using the apt-get command from the "What to install" section, you can ignore this warning. |
To unzip the tar file using bzip do (this should be done as a regular user!):
bash:/usr/src$ tar -xIf kernel-source-2.2.19.tar.bz2 |
![]() | The version of tar in stable (aka Potato) uses the -I option for bzip2 compression. If you're using a newer version of tar there's a chance it uses the -j option for bzip2 compression. |
To unzip the tar file using gzip do (this should be done as a regular user!):
bash:/usr/src$ tar -xzf kernel-source-2.2.19.tar.gz |
Example 1. Partial contents of /usr/src/kernel-source-2.2.19/Documentation/Changes
Current Minimal Requirements **************************** Upgrade to at *least* these software revisions before thinking you've encountered a bug! If you're unsure what version you're currently running, the suggested command should tell you. - Kernel modutils 2.1.121 ; insmod -V - Gnu C 2.7.2.3 ; gcc --version - Binutils 2.8.1.0.23 ; ld -v - Linux libc5 C Library 5.4.46 ; ls -l /lib/libc* - Linux libc6 C Library 2.0.7pre6 ; ls -l /lib/libc* - Dynamic Linker (ld.so) 1.9.9 ; ldd --version or ldd -v - Linux C++ Library 2.7.2.8 ; ls -l /usr/lib/libg++.so.* - Procps 2.0.3 ; ps --version - Procinfo 16 ; procinfo -v - Psmisc 17 ; pstree -V - Net-tools 1.52 ; hostname -V - Loadlin 1.6a - Sh-utils 1.16 ; basename --v - Autofs 3.1.3 ; automount --version - NFS 2.2beta40 ; showmount --version - Bash 1.14.7 ; bash -version - Ncpfs 2.2.0 ; ncpmount -v - Pcmcia-cs 3.0.14 ; cardmgr -V - PPP 2.3.10 ; pppd --version - Util-linux 2.9z ; chsh -v - isdn4k-utils v3.1beta7 ; isdnctrl 2>&1|grep version |
![]() | This documentation was written by a kernel developer based on the distribution of Linux he/she was working on. What that means is some of these commands may not work for determining versions installed on your Debian system. If that's the case, try finding the version command to use by following the example below. |
bash:/usr/src$ man program_name |
Substituting program_name for the program you're wondering about.
bash:/usr/src$ cd /usr/src |
Before you make a symlink called linux check to make sure you don't already have one in that directory by following Example 2. If you already have one there, it's probably because you have installed or compiled kernel source before. Make sure you remove the old link and make a new one which points to the source tree you wish to compile.
In that same directory (/usr/srcyou need to create a "soft link" or symlink to the source tree. You do that like this:
bash:/usr/src$ ln -s kernel-source-2.2.19 linux |
The format for this is ln -s name_of_kernel_source_tree linux.
The directory that was created when you unzipped your kernel source is what is substituted for name_of_kernel_source_tree.
To make sure you did it correctly it's a good idea to do an ls -l. It should look like the example below.
Example 2. Symlink
Now that you have the symlink set up we can move on to configuring the kernel.
bash:/usr/src$ cd linux And then do: bash:/usr/src/linux$ make xconfig |
If you get an error check out the "Troubleshooting" section. If everything goes well you'll get a window that looks like this:
Covering how to configure all the options available for the kernel is way beyond the scope of this document. To find out more about the options you can configure, please reference The Linux Documentation Project's kernel-howto, the documentation in /usr/src/linux/Documentation, and your hardware documentation. I hope to add a section here in the future listing the most common "constant" options.
Once you are done configuring the kernel to your wishes and have pressed the "Save and Exit" button, you can move on to the next section, "Building the kernel image."
![]() | make-kpkg is part of the "kernel-package" package. The relevant documents should be located in /usr/share/doc/kernel-package/. It's not a bad idea to also consult man make-kpkg. |
![]() | If you decide to use the form --revision=1:custom.1.0 kernel_image Please read /usr/share/doc/kernel-package/README. This creates an epoch. The discussion of that is beyond the scope of this document (for now). |
![]() | Please read /usr/share/doc/kernel-package/README if any of the preceding paragraph was unclear or if you plan on using options that are different then the ones I suggest. |
![]() | You will need to do make-kpkg clean FIRST if you wish to recompile the kernel-image using a flavour. There are also module conflict issues you need to worry about. |
If you followed my advice and got a kernel version different than the one you are currently running, you won't have to worry about the flavours option. If you don't have a choice then please consult the flavours documentation. In future versions I hope to cover this in more detail. If you are knowledgable about this and would like to coauthor please contact me at <newbiedoc-discuss@lists.sourceforge.net>.
![]() | Please read /usr/share/doc/kernel-package/Flavours if you are compiling a custom kernel with the same version number as the one you are currently running. You can find out which version you are running on the bottom of this page. |
![]() | You can get by without using the flavours options if you're willing to get rid of your old modules and overwrite your current kernel. I don't recommend this because if you make a mistake, your only recourse is a boot floppy (if you made one!) and some repairs with utilities you probably aren't that familiar with. I try to avoid stuff like that as much as possible. If you're adventurous and want to give it a try, go for it. Just make sure your important data is backed up and you have a current boot floppy. |
bash# mkboot path_to_kernel |
bash$ cd /usr/src/linux And then do: bash:/usr/src/linux$ make-kpkg --revision=custom.1.0 kernel_image |
![]() | If you've already used this document to install a kernel as a Debian package you'll need to make sure you increment your revision number by some amount. For example you would change the above revision number to 1.1 or maybe 2.0. You'll need to do this because dpkg will not upgrade your previous kernel because it sees the same revision number and thinks it's already current. You will also need to move you're old modules "out of the way" by renaming their folder to something like 2.2.19-old. The modules are located in /lib/modules/. |
bash:/usr/src/linux# cd .. bash:/usr/src# ls custom-kernel.config kernel-source-2.2.19 kernel-source-2.2.19.tar.bz2 |
Now to install the kernel and all its modules simply do this:
bash:/usr/src# dpkg -i kernel-image-2.2.19_custom.1.0_i386.deb |
As part of the post-installation process it will ask you if you want to install the modules. You definitely want to say yes.
![]() | If you are using the flavour option or are installing a kernel version which is the same as the one you are currently running you should immediately jump to another terminal and move your current modules "out of the way." If you don't there is a very good possibility you will end up with module conflicts and a broken or wacky-acting system. Please reference the Flavour documentation in /usr/share/doc/kernel-package/Flavour. |
![]() | The command to move your modules "out of the way" is (as root user):
|
The post-installation should then ask you if you want to make a boot disk. If you made one earlier then you can say no here. Otherwise, grab a floppy you don't mind erasing, and say yes.
Next the post-installation should ask you if you want to run lilo. The documentation says it is a bit buggy but I didn't notice any problems. Say yes.
![]() | If you haven't made a boot disk yet then you need to do so. If for whatever reason the post-install wacks lilo you will not be able to reboot without it. Also, if you are using loadlin or some other bootloader you will probably want to reference the documentation in /usr/share/doc/kernel-package before answering this question. Your answer should most likely be no. |
If everything went well then all you need to do is reboot and see if it works. If the reboot fails, insert your boot floppy and reboot. In future versions I hope to cover more troubleshooting issues, but for now, seek out help wherever you can find it;-)
bash# echo "kernel-image-2.2.19 hold" | dpkg --set-selections |
bash# dpkg --get-selections | grep kernel-image |
If you put it on hold successfully it should look like this:
bash# dpkg --get-selections | grep kernel-image kernel-image-2.2.19 hold |
bash# cd /usr/src bash:/usr/src# rm linux |
Finally, it's not required, but a good idea is to backup the custom debianized kernel you created onto whatever medium you choose. As a minimum, create another boot disk, this time using the new kernel you just created. Grab another floppy you don't mind being erased. It's not a good idea to overwrite the original boot disk you created. You haven't been using your new kernel long enough to determine if it's going to work the way you want it to. If you installed kernel-2.2.19 like I did just do (otherwise substitute your information) (as root user):
bash# mkboot /boot/vmlinuz-2.2.19 |
One final note. If you happen to need to rebuild your kernel, because you just bought a new sound card or you want to enable a new feature which you just realized you forgot to put in the first time, all you have to do is make-kpkg clean and increment your kernel image one revision. Your new command should look something like this:
bash$ cd /usr/src/linux And then do: bash:/usr/src/linux$ make-kpkg clean And reconfigure your kernel: bash:/usr/src/linux$ make xconfig And then do: bash:/usr/src/linux$ make-kpkg --revision=custom.2.0 kernel_image |
Fixing make xconfig error. NEED to get this updated
bash:/usr/src/linux# make xconfig rm -f include/asm ( cd include ; ln -sf asm-i386 asm) make -C scripts kconfig.tk make[1]: Entering directory `/usr/src/kernel-source-2.2.19/scripts' cat header.tk >> ./kconfig.tk ./tkparse < ../arch/i386/config.in >> kconfig.tk echo "set defaults \"arch/i386/defconfig\"" >> kconfig.tk echo "set ARCH \"i386\"" >> kconfig.tk cat tail.tk >> kconfig.tk chmod 755 kconfig.tk make[1]: Leaving directory `/usr/src/kernel-source-2.2.19/scripts' wish -f scripts/kconfig.tk Xlib: connection to ":0.0" refused by server Xlib: Client is not authorized to connect to Server Application initialization failed: couldn't connect to display ":0" Error in startup script: invalid command name "button" while executing "button .ref" (file "scripts/kconfig.tk" line 51) make: *** [xconfig] Error 1 |
bash:/usr/src/linux# xauth merge ~user/.Xauthority And then try it again: bash:/usr/src/linux# make xconfig |
![]() | There are some security issues to doing this. I don't know what they are, but I do know that there was a huge discussion about it on the debian-user mailing list. If you're worried about it check the archives. |