Linux Kernel Makefiles
This document describes the Linux kernel Makefiles.
1. Overview
The Makefiles have five parts:
| Makefile | the top Makefile. |
| .config | the kernel configuration file. |
| arch/$(ARCH)/Makefile | the arch Makefile. |
| scripts/Makefile.* | common rules etc. for all kbuild Makefiles. |
| kbuild Makefiles | there are about 500 of these. |
The top Makefile reads the .config file, which comes from the kernel configuration process.
The top Makefile is responsible for building two major products: vmlinux (the resident kernel image) and modules (any module files). It builds these goals by recursively descending into the subdirectories of the kernel source tree. The list of subdirectories which are visited depends upon the kernel configuration. The top Makefile textually includes an arch Makefile with the name arch/$(ARCH)/Makefile. The arch Makefile supplies architecture-specific information to the top Makefile.
Each subdirectory has a kbuild Makefile which carries out the commands passed down from above. The kbuild Makefile uses information from the .config file to construct various file lists used by kbuild to build any built-in or modular targets.
scripts/Makefile.* contains all the definitions/rules etc. that are used to build the kernel based on the kbuild makefiles.
2. Who does what
People have four different relationships with the kernel Makefiles.
- Users
-
are people who build kernels. These people type commands such as "make menuconfig" or "make". They usually do not read or edit any kernel Makefiles (or any other source files).
- Normal developers
-
are people who work on features such as device drivers, file systems, and network protocols. These people need to maintain the kbuild Makefiles for the subsystem they are working on. In order to do this effectively, they need some overall knowledge about the kernel Makefiles, plus detailed knowledge about the public interface for kbuild.
- Arch developers
-
are people who work on an entire architecture, such as sparc or ia64. Arch developers need to know about the arch Makefile as well as kbuild Makefiles.
- Kbuild developers
-
are people who work on the kernel build system itself. These people need to know about all aspects of the kernel Makefiles.
This document is aimed towards normal developers and arch developers.
3. The kbuild files
Most Makefiles within the kernel are kbuild Makefiles that use the kbuild infrastructure. This chapter introduces the syntax used in the kbuild makefiles. The preferred name for the kbuild files are Makefile but Kbuild can be used and if both a Makefile and a Kbuild file exists, then the Kbuild file will be used.
Section 3.1 "Goal definitions" is a quick intro, further chapters provide more details, with real examples.
3.1. Goal definitions
Goal definitions are the main part (heart) of the kbuild Makefile. These lines define the files to be built, any special compilation options, and any subdirectories to be entered recursively.
The most simple kbuild makefile contains one line:
This tells kbuild that there is one object in that directory, named foo.o. foo.o will be built from foo.c or foo.S.
If foo.o shall be built as a module, the variable obj-m is used. Therefore the following pattern is often used:
$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module). If CONFIG_FOO is neither y nor m, then the file will not be compiled nor linked.
3.2. Built-in object goals - obj-y
The kbuild Makefile specifies object files for vmlinux in the obj-y lists. These lists depend on the kernel configuration.
Kbuild compiles all the obj-y files. It then calls $(LD) -r to merge these files into one built-in.o file. built-in.o is later linked into vmlinux by the parent Makefile.
The order of files in obj-y is significant. Duplicates in the lists are allowed: the first instance will be linked into built-in.o and succeeding instances will be ignored.
Link order is significant, because certain functions (module_init() / __initcall) will be called during boot in the order they appear. So keep in mind that changing the link order may e.g. change the order in which your SCSI controllers are detected, and thus your disks are renumbered.
3.3. Loadable module goals - obj-m
obj-m specify object files which are built as loadable kernel modules.
A module may be built from one source file or several source files. In the case of one source file, the kbuild makefile simply adds the file to obj-m.
Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to m
If a kernel module is built from several source files, you specify that you want to build a module in the same way as above.
Kbuild needs to know which the parts that you want to build your module from, so you have to tell it by setting an <module_name>-objs variable.
In this example, the module name will be isdn.o. Kbuild will compile the objects listed in isdn-objs and then run $(LD) -r on the list of these files to generate isdn.o.
Kbuild recognises objects used for composite objects by the suffix -objs, and the suffix -y. This allows the Makefiles to use the value of a CONFIG_ symbol to determine if an object is part of a composite object.
In this example, xattr.o is only part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR) evaluates to y.
Note: Of course, when you are building objects into the kernel, the syntax above will also work. So, if you have CONFIG_EXT2_FS=y, kbuild will build an ext2.o file for you out of the individual parts and then link this into built-in.o, as you would expect.
3.4. Objects which export symbols
No special notation is required in the makefiles for modules exporting symbols.
3.5. Library file goals - lib-y
Objects listed with obj-* are used for modules, or combined in a built-in.o for that specific directory. There is also the possibility to list objects that will be included in a library, lib.a. All objects listed with lib-y are combined in a single library for that directory. Objects that are listed in obj-y and additionally listed in lib-y will not be included in the library, since they will be accessible anyway. For consistency, objects listed in lib-m will be included in lib.a.
Note that the same kbuild makefile may list files to be built-in and to be part of a library. Therefore the same directory may contain both a built-in.o and a lib.a file.
This will create a library lib.a based on checksum.o and delay.o. For kbuild to actually recognize that there is a lib.a being built, the directory shall be listed in libs-y. See also "6.3 List directories to visit when descending".
Use of lib-y is normally restricted to lib/ and arch/*/lib.
3.6. Descending down in directories
3.7. Compilation flags
3.8. Dependency tracking
3.9. Special Rules
3.10. $(CC) support functions
4. Host Program support
Kbuild supports building executables on the host for use during the compilation stage. Two steps are required in order to use a host executable.
The first step is to tell kbuild that a host program exists. This is done utilising the variable hostprogs-y.
The second step is to add an explicit dependency to the executable. This can be done in two ways. Either add the dependency in a rule, or utilise the variable $(always). Both possibilities are described in the following.
4.1. Simple Host Program
4.2. Composite Host Programs
4.3. Defining shared libraries
4.4. Using C++ for host programs
4.5. Controlling compiler options for host programs
4.6. When host programs are actually built
4.7. Using hostprogs-$(CONFIG_FOO)
5. Kbuild clean infrastructure
"make clean" deletes most generated files in the obj tree where the kernel is compiled. This includes generated files such as host programs. Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always), $(extra-y) and $(targets). They are all deleted during "make clean". Files matching the patterns ".[oas]", ".ko", plus some additional files generated by kbuild are deleted all over the kernel src tree when "make clean" is executed.
Additional files can be specified in kbuild makefiles by use of $(clean-files).
When executing "make clean", the two files "devlist.h classlist.h" will be deleted. Kbuild will assume files to be in same relative directory as the Makefile except if an absolute path is specified (path starting with /).
To delete a directory hierarchy use:
This will delete the directory debian, including all subdirectories. Kbuild will assume the directories to be in the same relative path as the Makefile if no absolute path is specified (path does not start with /).
Usually kbuild descends down in subdirectories due to "obj-* := dir/", but in the architecture makefiles where the kbuild infrastructure is not sufficient this sometimes needs to be explicit.
The above assignment instructs kbuild to descend down in the directory compressed/ when "make clean" is executed.
To support the clean infrastructure in the Makefiles that builds the final bootimage there is an optional target named archclean:
When "make clean" is executed, make will descend down in arch/i386/boot, and clean as usual. The Makefile located in arch/i386/boot/ may use the subdir- trick to descend further down.
Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is included in the top level makefile, and the kbuild infrastructure is not operational at that point.
Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will be visited during "make clean".
6. Architecture Makefiles
The top level Makefile sets up the environment and does the preparation, before starting to descend down in the individual directories. The top level makefile contains the generic part, whereas arch/$(ARCH)/Makefile contains what is required to set up kbuild for said architecture. To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines a few targets.
When kbuild executes, the following steps are followed (roughly): 1) Configuration of the kernel => produce .config 2) Store kernel version in include/linux/version.h 3) Symlink include/asm to include/asm-$(ARCH) 4) Updating all other prerequisites to the target prepare: - Additional prerequisites are specified in arch/$(ARCH)/Makefile 5) Recursively descend down in all directories listed in init- core drivers- net- libs-* and build all targets. - The values of the above variables are expanded in arch/$(ARCH)/Makefile. 6) All object files are then linked and the resulting file vmlinux is located at the root of the obj tree. The very first objects linked are listed in head-y, assigned by arch/$(ARCH)/Makefile. 7) Finally, the architecture-specific part does any required post processing and builds the final bootimage. - This includes building boot records - Preparing initrd images and the like
6.1. Set variables to tweak the build to the architecture
6.2. Add prerequisites to archprepare:
6.3. List directories to visit when descending
6.4. Architecture-specific boot images
6.5. Building non-kbuild targets
6.6. Commands useful for building a boot image
6.7. Custom kbuild commands
6.8. Preprocessing linker scripts
7. Kbuild Variables
The top Makefile exports the following variables:
8. Makefile language
The kernel Makefiles are designed to be run with GNU Make. The Makefiles use only the documented features of GNU Make, but they do use many GNU extensions.
GNU Make supports elementary list-processing functions. The kernel Makefiles use a novel style of list building and manipulation with few "if" statements.
GNU Make has two assignment operators, ":=" and "=". ":=" performs immediate evaluation of the right-hand side and stores an actual string into the left-hand side. "=" is like a formula definition; it stores the right-hand side in an unevaluated form and then evaluates this form each time the left-hand side is used.
There are some cases where "=" is appropriate. Usually, though, ":=" is the right choice.
9. Credits
Original version made by Michael Elizabeth Chastain, <mailto:[email protected]> Updates by Kai Germaschewski <[email protected]> Updates by Sam Ravnborg <[email protected]> Language QA by Jan Engelhardt <[email protected]>
10. TODO
-
Describe how kbuild supports shipped files with _shipped.
-
Generating offset header files.
-
Add more variables to section 7?