What does a kernel source tree contain? Is this related to Linux kernel headers?

Question

In books, I typically read references to the Linux Source Tree at /usr/src/linux with the usual set of subdirectories (arch, block, crypto, ...).

I was expecting this tree to contain the binary files making up the kernel. In my system (Ubuntu 10.04)...

1. for the different kernels I have (using automated software downloads, not manually installed), I find in this location instead two sub-directories for each kernel as follows:

   /usr/src/linux-headers-2.6.32-22
   /usr/src/linux-headers-2.6.32-22-generic
   

2. In the sub directories I expected binary files, among others. However, I checked a fair amount of the tree, and the last sub-directory from here seems to always have a Makefile (when reading it, it sounds typically more like a configuration file then an install file), plus occasionally a few isolated other files (mostly Kconfig).

My question may be naive, but I'm a bit confused. Is (2) what I should expect to see in the Kernel Source Tree; and why do I have the explicit reference to 'headers'? I needed to install linux-generic-headers a while back for some other software and am unsure if this might be related. I realize there is good reason for the makefiles (eg, to install modules in the /driver sub-directory), but (pretty much) only makefiles?

Solution

Distribution kernel-header packages contain, as their name implies, only kernel header files (plus the necessary plumbing) that are required to build software like kernel modules.

You shouldn't expect to find binary files at all in a kernel source directory, except for build output. (If you configure and build a kernel yourself, the kernel source directory will also contain the compiled objects, modules, the built kernel itself and a few other binary bits and pieces that make it work.)
KConfig files are a description of the kernel configuration options (and their dependencies) that are available for a given directory/module.
Apart from that, it's all (mostly) C source code, header files and Makefiles. There are a few helper scripts here and there, and assembly source too.

Header packages (what you installed) only contain the header part of the above (and not all of that - only the "exported" headers), and some of the build infrastructure. So what you are seeing is expected. Header packages do not contain C source code (except for some stubs and build infrastructure code). The whole point of having this type of package is to save space (and bandwidth) - the whole Linux kernel source tree is rather large, and completely unnecessary if you don't intend to compile the kernel yourself. The header packages are built and shipped by distributions to provide just the right things necessary to build modules, but no more. (They certainly do not contain the compiled kernel.)

Addressing your comment: header packages don't relocate anywhere. They are built for specific versions of the kernel, packaged in a specific directory, and that's that. It's just a set of files. (Note that the header packages don't necessarily have the same version as the current stable kernel binary packages - the header packages are generic, and can lag behind the actual kernel you're running. They should not, however, be from a kernel version that is more recent than the current installed (or target) kernel.)

Installed kernel binaries are usually installed in the /boot directory, along with bootloader binaries and configuration files. (This is sometimes an independent filesystem, not mounted by default.) The exact name of the files depends on the kernel and distribution. (So does the bootloader.)

Installed kernel modules reside in sub-directories of:

/lib/modules/`uname -r`/

So for instance on my system, they are currently in

/lib/modules/3.1.4-gentoo/

Full kernel source code: On Ubuntu, if you want the full kernel sources to build a kernel yourself, you should install following the instructions here.

You could also download a source tarball from kernel.org and unpack it somewhere (do not overwrite Ubuntu-installed files if you use this tarball, keep your personal stuff and the stuff managed by RPM separate).

/usr/src/linux is a traditional place to put kernel sources, but nothing prevents you from putting kernel sources elsewhere. This path is also often just a symbolic link to a directory. e.g. I have this on my machine:

 $ ls -l /usr/src/linux
lrwxrwxrwx 1 root root 18 Dec  7 17:03 /usr/src/linux -> linux-3.1.4-gentoo

The symlink is there to simplify building applications that depend on the kernel source. You link that path to your running (or target) kernel so that you don't have to specify exact version or path information when you build a module out-of-tree. Helps a bunch for source-based distributions at least.

Comments

[gnometorule]

Thank you very much for this detailed and rather complete answer. This had been bugging me for a while. If I'm not overextending my welcome, and if you find the time, could I kindly add, following up: (a) I read the above that in my case (not self-installed kernel), some (one) of the sub directories should(might) contain the kernel C and Assembler source code. Where would that be - not a complete list, only as in my browsing of maybe 20 - 30 of the sub-directories, I never came across one? I have downloaded kernel source files from kernel.org; I just mean to understand my system better. (b)...

[gnometorule]

(if you answer, use 'answer'not comment so I can at least upvote you again for your help)

[enzotib]

Also, linux-source would only install a tarball, up to the user to extract somewhere.

[gnometorule]

Well, after adding so much more that really helped finally getting this straight, it's simply not fair I can upvote only once. Many thanks.

[Lekensteyn]

linux-source contains the upstream source, apt-get source linux-image-$(uname -r) gets the source for the kernel with Ubuntu' patches.

[enzotib]

@Lekensteyn: the Description of linux-source reports "Linux kernel source with Ubuntu patches".