3 This document describes the Linux kernel Makefiles.
10 --- 3.1 Goal definitions
11 --- 3.2 Built-in object goals - obj-y
12 --- 3.3 Loadable module goals - obj-m
13 --- 3.4 Objects which export symbols
14 --- 3.5 Library file goals - lib-y
15 --- 3.6 Descending down in directories
16 --- 3.7 Compilation flags
17 --- 3.8 Command line dependency
18 --- 3.9 Dependency tracking
19 --- 3.10 Special Rules
20 --- 3.11 $(CC) support functions
22 === 4 Host Program support
23 --- 4.1 Simple Host Program
24 --- 4.2 Composite Host Programs
25 --- 4.3 Defining shared libraries
26 --- 4.4 Using C++ for host programs
27 --- 4.5 Controlling compiler options for host programs
28 --- 4.6 When host programs are actually built
29 --- 4.7 Using hostprogs-$(CONFIG_FOO)
31 === 5 Kbuild clean infrastructure
33 === 6 Architecture Makefiles
34 --- 6.1 Set variables to tweak the build to the architecture
35 --- 6.2 Add prerequisites to archprepare:
36 --- 6.3 List directories to visit when descending
37 --- 6.4 Architecture-specific boot images
38 --- 6.5 Building non-kbuild targets
39 --- 6.6 Commands useful for building a boot image
40 --- 6.7 Custom kbuild commands
41 --- 6.8 Preprocessing linker scripts
43 === 7 Kbuild Variables
44 === 8 Makefile language
50 The Makefiles have five parts:
52 Makefile the top Makefile.
53 .config the kernel configuration file.
54 arch/$(ARCH)/Makefile the arch Makefile.
55 scripts/Makefile.* common rules etc. for all kbuild Makefiles.
56 kbuild Makefiles there are about 500 of these.
58 The top Makefile reads the .config file, which comes from the kernel
59 configuration process.
61 The top Makefile is responsible for building two major products: vmlinux
62 (the resident kernel image) and modules (any module files).
63 It builds these goals by recursively descending into the subdirectories of
64 the kernel source tree.
65 The list of subdirectories which are visited depends upon the kernel
66 configuration. The top Makefile textually includes an arch Makefile
67 with the name arch/$(ARCH)/Makefile. The arch Makefile supplies
68 architecture-specific information to the top Makefile.
70 Each subdirectory has a kbuild Makefile which carries out the commands
71 passed down from above. The kbuild Makefile uses information from the
72 .config file to construct various file lists used by kbuild to build
73 any built-in or modular targets.
75 scripts/Makefile.* contains all the definitions/rules etc. that
76 are used to build the kernel based on the kbuild makefiles.
81 People have four different relationships with the kernel Makefiles.
83 *Users* are people who build kernels. These people type commands such as
84 "make menuconfig" or "make". They usually do not read or edit
85 any kernel Makefiles (or any other source files).
87 *Normal developers* are people who work on features such as device
88 drivers, file systems, and network protocols. These people need to
89 maintain the kbuild Makefiles for the subsystem they are
90 working on. In order to do this effectively, they need some overall
91 knowledge about the kernel Makefiles, plus detailed knowledge about the
92 public interface for kbuild.
94 *Arch developers* are people who work on an entire architecture, such
95 as sparc or ia64. Arch developers need to know about the arch Makefile
96 as well as kbuild Makefiles.
98 *Kbuild developers* are people who work on the kernel build system itself.
99 These people need to know about all aspects of the kernel Makefiles.
101 This document is aimed towards normal developers and arch developers.
104 === 3 The kbuild files
106 Most Makefiles within the kernel are kbuild Makefiles that use the
107 kbuild infrastructure. This chapter introduces the syntax used in the
109 The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
110 be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
113 Section 3.1 "Goal definitions" is a quick intro, further chapters provide
114 more details, with real examples.
116 --- 3.1 Goal definitions
118 Goal definitions are the main part (heart) of the kbuild Makefile.
119 These lines define the files to be built, any special compilation
120 options, and any subdirectories to be entered recursively.
122 The most simple kbuild makefile contains one line:
127 This tells kbuild that there is one object in that directory, named
128 foo.o. foo.o will be built from foo.c or foo.S.
130 If foo.o shall be built as a module, the variable obj-m is used.
131 Therefore the following pattern is often used:
134 obj-$(CONFIG_FOO) += foo.o
136 $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
137 If CONFIG_FOO is neither y nor m, then the file will not be compiled
140 --- 3.2 Built-in object goals - obj-y
142 The kbuild Makefile specifies object files for vmlinux
143 in the $(obj-y) lists. These lists depend on the kernel
146 Kbuild compiles all the $(obj-y) files. It then calls
147 "$(LD) -r" to merge these files into one built-in.o file.
148 built-in.o is later linked into vmlinux by the parent Makefile.
150 The order of files in $(obj-y) is significant. Duplicates in
151 the lists are allowed: the first instance will be linked into
152 built-in.o and succeeding instances will be ignored.
154 Link order is significant, because certain functions
155 (module_init() / __initcall) will be called during boot in the
156 order they appear. So keep in mind that changing the link
157 order may e.g. change the order in which your SCSI
158 controllers are detected, and thus your disks are renumbered.
161 #drivers/isdn/i4l/Makefile
162 # Makefile for the kernel ISDN subsystem and device drivers.
163 # Each configuration option enables a list of files.
164 obj-$(CONFIG_ISDN) += isdn.o
165 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
167 --- 3.3 Loadable module goals - obj-m
169 $(obj-m) specify object files which are built as loadable
172 A module may be built from one source file or several source
173 files. In the case of one source file, the kbuild makefile
174 simply adds the file to $(obj-m).
177 #drivers/isdn/i4l/Makefile
178 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
180 Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
182 If a kernel module is built from several source files, you specify
183 that you want to build a module in the same way as above.
185 Kbuild needs to know which the parts that you want to build your
186 module from, so you have to tell it by setting an
187 $(<module_name>-objs) variable.
190 #drivers/isdn/i4l/Makefile
191 obj-$(CONFIG_ISDN) += isdn.o
192 isdn-objs := isdn_net_lib.o isdn_v110.o isdn_common.o
194 In this example, the module name will be isdn.o. Kbuild will
195 compile the objects listed in $(isdn-objs) and then run
196 "$(LD) -r" on the list of these files to generate isdn.o.
198 Kbuild recognises objects used for composite objects by the suffix
199 -objs, and the suffix -y. This allows the Makefiles to use
200 the value of a CONFIG_ symbol to determine if an object is part
201 of a composite object.
205 obj-$(CONFIG_EXT2_FS) += ext2.o
206 ext2-y := balloc.o bitmap.o
207 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
209 In this example, xattr.o is only part of the composite object
210 ext2.o if $(CONFIG_EXT2_FS_XATTR) evaluates to 'y'.
212 Note: Of course, when you are building objects into the kernel,
213 the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
214 kbuild will build an ext2.o file for you out of the individual
215 parts and then link this into built-in.o, as you would expect.
217 --- 3.4 Objects which export symbols
219 No special notation is required in the makefiles for
220 modules exporting symbols.
222 --- 3.5 Library file goals - lib-y
224 Objects listed with obj-* are used for modules, or
225 combined in a built-in.o for that specific directory.
226 There is also the possibility to list objects that will
227 be included in a library, lib.a.
228 All objects listed with lib-y are combined in a single
229 library for that directory.
230 Objects that are listed in obj-y and additionally listed in
231 lib-y will not be included in the library, since they will
232 be accessible anyway.
233 For consistency, objects listed in lib-m will be included in lib.a.
235 Note that the same kbuild makefile may list files to be built-in
236 and to be part of a library. Therefore the same directory
237 may contain both a built-in.o and a lib.a file.
240 #arch/i386/lib/Makefile
241 lib-y := checksum.o delay.o
243 This will create a library lib.a based on checksum.o and delay.o.
244 For kbuild to actually recognize that there is a lib.a being built,
245 the directory shall be listed in libs-y.
246 See also "6.3 List directories to visit when descending".
248 Use of lib-y is normally restricted to lib/ and arch/*/lib.
250 --- 3.6 Descending down in directories
252 A Makefile is only responsible for building objects in its own
253 directory. Files in subdirectories should be taken care of by
254 Makefiles in these subdirs. The build system will automatically
255 invoke make recursively in subdirectories, provided you let it know of
258 To do so, obj-y and obj-m are used.
259 ext2 lives in a separate directory, and the Makefile present in fs/
260 tells kbuild to descend down using the following assignment.
264 obj-$(CONFIG_EXT2_FS) += ext2/
266 If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
267 the corresponding obj- variable will be set, and kbuild will descend
268 down in the ext2 directory.
269 Kbuild only uses this information to decide that it needs to visit
270 the directory, it is the Makefile in the subdirectory that
271 specifies what is modules and what is built-in.
273 It is good practice to use a CONFIG_ variable when assigning directory
274 names. This allows kbuild to totally skip the directory if the
275 corresponding CONFIG_ option is neither 'y' nor 'm'.
277 --- 3.7 Compilation flags
279 EXTRA_CFLAGS, EXTRA_AFLAGS, EXTRA_LDFLAGS
281 All the EXTRA_ variables apply only to the kbuild makefile
282 where they are assigned. The EXTRA_ variables apply to all
283 commands executed in the kbuild makefile.
285 $(EXTRA_CFLAGS) specifies options for compiling C files with
289 # drivers/sound/emu10k1/Makefile
290 EXTRA_CFLAGS += -I$(obj)
292 EXTRA_CFLAGS += -DEMU10K1_DEBUG
296 This variable is necessary because the top Makefile owns the
297 variable $(CFLAGS) and uses it for compilation flags for the
300 $(EXTRA_AFLAGS) is a similar string for per-directory options
301 when compiling assembly language source.
304 #arch/x86_64/kernel/Makefile
305 EXTRA_AFLAGS := -traditional
308 $(EXTRA_LDFLAGS) is a string for per-directory options to $(LD).
311 #arch/m68k/fpsp040/Makefile
316 CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
319 $(CFLAGS_$@) specifies per-file options for $(CC). The $@
320 part has a literal value which specifies the file that it is for.
323 # drivers/scsi/Makefile
324 CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
325 CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
327 CFLAGS_seagate.o = -DARBITRATE -DPARITY -DSEAGATE_USE_ASM
329 These three lines specify compilation flags for aha152x.o,
330 gdth.o, and seagate.o
332 $(AFLAGS_$@) is a similar feature for source files in assembly
336 # arch/arm/kernel/Makefile
337 AFLAGS_head-armv.o := -DTEXTADDR=$(TEXTADDR) -traditional
338 AFLAGS_head-armo.o := -DTEXTADDR=$(TEXTADDR) -traditional
340 --- 3.9 Dependency tracking
342 Kbuild tracks dependencies on the following:
343 1) All prerequisite files (both *.c and *.h)
344 2) CONFIG_ options used in all prerequisite files
345 3) Command-line used to compile target
347 Thus, if you change an option to $(CC) all affected files will
350 --- 3.10 Special Rules
352 Special rules are used when the kbuild infrastructure does
353 not provide the required support. A typical example is
354 header files generated during the build process.
355 Another example are the architecture-specific Makefiles which
356 need special rules to prepare boot images etc.
358 Special rules are written as normal Make rules.
359 Kbuild is not executing in the directory where the Makefile is
360 located, so all special rules shall provide a relative
361 path to prerequisite files and target files.
363 Two variables are used when defining special rules:
366 $(src) is a relative path which points to the directory
367 where the Makefile is located. Always use $(src) when
368 referring to files located in the src tree.
371 $(obj) is a relative path which points to the directory
372 where the target is saved. Always use $(obj) when
373 referring to generated files.
376 #drivers/scsi/Makefile
377 $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
378 $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
380 This is a special rule, following the normal syntax
382 The target file depends on two prerequisite files. References
383 to the target file are prefixed with $(obj), references
384 to prerequisites are referenced with $(src) (because they are not
387 --- 3.11 $(CC) support functions
389 The kernel may be built with several different versions of
390 $(CC), each supporting a unique set of features and options.
391 kbuild provide basic support to check for valid options for $(CC).
392 $(CC) is usually the gcc compiler, but other alternatives are
396 as-option is used to check if $(CC) -- when used to compile
397 assembler (*.S) files -- supports the given option. An optional
398 second option may be specified if the first option is not supported.
402 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
404 In the above example, cflags-y will be assigned the option
405 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
406 The second argument is optional, and if supplied will be used
407 if first argument is not supported.
410 ld-option is used to check if $(CC) when used to link object files
411 supports the given option. An optional second option may be
412 specified if first option are not supported.
415 #arch/i386/kernel/Makefile
416 vsyscall-flags += $(call ld-option, -Wl$(comma)--hash-style=sysv)
418 In the above example, vsyscall-flags will be assigned the option
419 -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
420 The second argument is optional, and if supplied will be used
421 if first argument is not supported.
424 as-instr checks if the assembler reports a specific instruction
425 and then outputs either option1 or option2
426 C escapes are supported in the test instruction
429 cc-option is used to check if $(CC) supports a given option, and not
430 supported to use an optional second option.
434 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
436 In the above example, cflags-y will be assigned the option
437 -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
438 The second argument to cc-option is optional, and if omitted,
439 cflags-y will be assigned no value if first option is not supported.
442 cc-option-yn is used to check if gcc supports a given option
443 and return 'y' if supported, otherwise 'n'.
447 biarch := $(call cc-option-yn, -m32)
448 aflags-$(biarch) += -a32
449 cflags-$(biarch) += -m32
451 In the above example, $(biarch) is set to y if $(CC) supports the -m32
452 option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
453 and $(cflags-y) will be assigned the values -a32 and -m32,
457 gcc versions >= 3.0 changed the type of options used to specify
458 alignment of functions, loops etc. $(cc-option-align), when used
459 as prefix to the align options, will select the right prefix:
461 cc-option-align = -malign
463 cc-option-align = -falign
466 CFLAGS += $(cc-option-align)-functions=4
468 In the above example, the option -falign-functions=4 is used for
469 gcc >= 3.00. For gcc < 3.00, -malign-functions=4 is used.
472 cc-version returns a numerical version of the $(CC) compiler version.
473 The format is <major><minor> where both are two digits. So for example
474 gcc 3.41 would return 0341.
475 cc-version is useful when a specific $(CC) version is faulty in one
476 area, for example -mregparm=3 was broken in some gcc versions
477 even though the option was accepted by gcc.
481 cflags-y += $(shell \
482 if [ $(call cc-version) -ge 0300 ] ; then \
483 echo "-mregparm=3"; fi ;)
485 In the above example, -mregparm=3 is only used for gcc version greater
486 than or equal to gcc 3.0.
489 cc-ifversion tests the version of $(CC) and equals last argument if
490 version expression is true.
493 #fs/reiserfs/Makefile
494 EXTRA_CFLAGS := $(call cc-ifversion, -lt, 0402, -O1)
496 In this example, EXTRA_CFLAGS will be assigned the value -O1 if the
497 $(CC) version is less than 4.2.
498 cc-ifversion takes all the shell operators:
499 -eq, -ne, -lt, -le, -gt, and -ge
500 The third parameter may be a text as in this example, but it may also
501 be an expanded variable or a macro.
504 cc-fullversion is useful when the exact version of gcc is needed.
505 One typical use-case is when a specific GCC version is broken.
506 cc-fullversion points out a more specific version than cc-version does.
509 #arch/powerpc/Makefile
510 $(Q)if test "$(call cc-fullversion)" = "040200" ; then \
511 echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \
515 In this example for a specific GCC version the build will error out explaining
516 to the user why it stops.
518 === 4 Host Program support
520 Kbuild supports building executables on the host for use during the
522 Two steps are required in order to use a host executable.
524 The first step is to tell kbuild that a host program exists. This is
525 done utilising the variable hostprogs-y.
527 The second step is to add an explicit dependency to the executable.
528 This can be done in two ways. Either add the dependency in a rule,
529 or utilise the variable $(always).
530 Both possibilities are described in the following.
532 --- 4.1 Simple Host Program
534 In some cases there is a need to compile and run a program on the
535 computer where the build is running.
536 The following line tells kbuild that the program bin2hex shall be
537 built on the build host.
540 hostprogs-y := bin2hex
542 Kbuild assumes in the above example that bin2hex is made from a single
543 c-source file named bin2hex.c located in the same directory as
546 --- 4.2 Composite Host Programs
548 Host programs can be made up based on composite objects.
549 The syntax used to define composite objects for host programs is
550 similar to the syntax used for kernel objects.
551 $(<executable>-objs) lists all objects used to link the final
555 #scripts/lxdialog/Makefile
556 hostprogs-y := lxdialog
557 lxdialog-objs := checklist.o lxdialog.o
559 Objects with extension .o are compiled from the corresponding .c
560 files. In the above example, checklist.c is compiled to checklist.o
561 and lxdialog.c is compiled to lxdialog.o.
562 Finally, the two .o files are linked to the executable, lxdialog.
563 Note: The syntax <executable>-y is not permitted for host-programs.
565 --- 4.3 Defining shared libraries
567 Objects with extension .so are considered shared libraries, and
568 will be compiled as position independent objects.
569 Kbuild provides support for shared libraries, but the usage
571 In the following example the libkconfig.so shared library is used
572 to link the executable conf.
575 #scripts/kconfig/Makefile
577 conf-objs := conf.o libkconfig.so
578 libkconfig-objs := expr.o type.o
580 Shared libraries always require a corresponding -objs line, and
581 in the example above the shared library libkconfig is composed by
582 the two objects expr.o and type.o.
583 expr.o and type.o will be built as position independent code and
584 linked as a shared library libkconfig.so. C++ is not supported for
587 --- 4.4 Using C++ for host programs
589 kbuild offers support for host programs written in C++. This was
590 introduced solely to support kconfig, and is not recommended
594 #scripts/kconfig/Makefile
596 qconf-cxxobjs := qconf.o
598 In the example above the executable is composed of the C++ file
599 qconf.cc - identified by $(qconf-cxxobjs).
601 If qconf is composed by a mixture of .c and .cc files, then an
602 additional line can be used to identify this.
605 #scripts/kconfig/Makefile
607 qconf-cxxobjs := qconf.o
608 qconf-objs := check.o
610 --- 4.5 Controlling compiler options for host programs
612 When compiling host programs, it is possible to set specific flags.
613 The programs will always be compiled utilising $(HOSTCC) passed
614 the options specified in $(HOSTCFLAGS).
615 To set flags that will take effect for all host programs created
616 in that Makefile, use the variable HOST_EXTRACFLAGS.
619 #scripts/lxdialog/Makefile
620 HOST_EXTRACFLAGS += -I/usr/include/ncurses
622 To set specific flags for a single file the following construction
626 #arch/ppc64/boot/Makefile
627 HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
629 It is also possible to specify additional options to the linker.
632 #scripts/kconfig/Makefile
633 HOSTLOADLIBES_qconf := -L$(QTDIR)/lib
635 When linking qconf, it will be passed the extra option
638 --- 4.6 When host programs are actually built
640 Kbuild will only build host-programs when they are referenced
642 This is possible in two ways:
644 (1) List the prerequisite explicitly in a special rule.
647 #drivers/pci/Makefile
648 hostprogs-y := gen-devlist
649 $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
650 ( cd $(obj); ./gen-devlist ) < $<
652 The target $(obj)/devlist.h will not be built before
653 $(obj)/gen-devlist is updated. Note that references to
654 the host programs in special rules must be prefixed with $(obj).
657 When there is no suitable special rule, and the host program
658 shall be built when a makefile is entered, the $(always)
659 variable shall be used.
662 #scripts/lxdialog/Makefile
663 hostprogs-y := lxdialog
664 always := $(hostprogs-y)
666 This will tell kbuild to build lxdialog even if not referenced in
669 --- 4.7 Using hostprogs-$(CONFIG_FOO)
671 A typical pattern in a Kbuild file looks like this:
675 hostprogs-$(CONFIG_KALLSYMS) += kallsyms
677 Kbuild knows about both 'y' for built-in and 'm' for module.
678 So if a config symbol evaluate to 'm', kbuild will still build
679 the binary. In other words, Kbuild handles hostprogs-m exactly
680 like hostprogs-y. But only hostprogs-y is recommended to be used
681 when no CONFIG symbols are involved.
683 === 5 Kbuild clean infrastructure
685 "make clean" deletes most generated files in the obj tree where the kernel
686 is compiled. This includes generated files such as host programs.
687 Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
688 $(extra-y) and $(targets). They are all deleted during "make clean".
689 Files matching the patterns "*.[oas]", "*.ko", plus some additional files
690 generated by kbuild are deleted all over the kernel src tree when
691 "make clean" is executed.
693 Additional files can be specified in kbuild makefiles by use of $(clean-files).
696 #drivers/pci/Makefile
697 clean-files := devlist.h classlist.h
699 When executing "make clean", the two files "devlist.h classlist.h" will
700 be deleted. Kbuild will assume files to be in same relative directory as the
701 Makefile except if an absolute path is specified (path starting with '/').
703 To delete a directory hierarchy use:
706 #scripts/package/Makefile
707 clean-dirs := $(objtree)/debian/
709 This will delete the directory debian, including all subdirectories.
710 Kbuild will assume the directories to be in the same relative path as the
711 Makefile if no absolute path is specified (path does not start with '/').
713 Usually kbuild descends down in subdirectories due to "obj-* := dir/",
714 but in the architecture makefiles where the kbuild infrastructure
715 is not sufficient this sometimes needs to be explicit.
718 #arch/i386/boot/Makefile
719 subdir- := compressed/
721 The above assignment instructs kbuild to descend down in the
722 directory compressed/ when "make clean" is executed.
724 To support the clean infrastructure in the Makefiles that builds the
725 final bootimage there is an optional target named archclean:
730 $(Q)$(MAKE) $(clean)=arch/i386/boot
732 When "make clean" is executed, make will descend down in arch/i386/boot,
733 and clean as usual. The Makefile located in arch/i386/boot/ may use
734 the subdir- trick to descend further down.
736 Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
737 included in the top level makefile, and the kbuild infrastructure
738 is not operational at that point.
740 Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
741 be visited during "make clean".
743 === 6 Architecture Makefiles
745 The top level Makefile sets up the environment and does the preparation,
746 before starting to descend down in the individual directories.
747 The top level makefile contains the generic part, whereas
748 arch/$(ARCH)/Makefile contains what is required to set up kbuild
749 for said architecture.
750 To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
753 When kbuild executes, the following steps are followed (roughly):
754 1) Configuration of the kernel => produce .config
755 2) Store kernel version in include/linux/version.h
756 3) Symlink include/asm to include/asm-$(ARCH)
757 4) Updating all other prerequisites to the target prepare:
758 - Additional prerequisites are specified in arch/$(ARCH)/Makefile
759 5) Recursively descend down in all directories listed in
760 init-* core* drivers-* net-* libs-* and build all targets.
761 - The values of the above variables are expanded in arch/$(ARCH)/Makefile.
762 6) All object files are then linked and the resulting file vmlinux is
763 located at the root of the obj tree.
764 The very first objects linked are listed in head-y, assigned by
765 arch/$(ARCH)/Makefile.
766 7) Finally, the architecture-specific part does any required post processing
767 and builds the final bootimage.
768 - This includes building boot records
769 - Preparing initrd images and the like
772 --- 6.1 Set variables to tweak the build to the architecture
774 LDFLAGS Generic $(LD) options
776 Flags used for all invocations of the linker.
777 Often specifying the emulation is sufficient.
781 LDFLAGS := -m elf_s390
782 Note: EXTRA_LDFLAGS can be used to further customise
783 the flags used. See chapter 3.7.
785 LDFLAGS_MODULE Options for $(LD) when linking modules
787 LDFLAGS_MODULE is used to set specific flags for $(LD) when
788 linking the .ko files used for modules.
789 Default is "-r", for relocatable output.
791 LDFLAGS_vmlinux Options for $(LD) when linking vmlinux
793 LDFLAGS_vmlinux is used to specify additional flags to pass to
794 the linker when linking the final vmlinux image.
795 LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
799 LDFLAGS_vmlinux := -e stext
801 OBJCOPYFLAGS objcopy flags
803 When $(call if_changed,objcopy) is used to translate a .o file,
804 the flags specified in OBJCOPYFLAGS will be used.
805 $(call if_changed,objcopy) is often used to generate raw binaries on
810 OBJCOPYFLAGS := -O binary
812 #arch/s390/boot/Makefile
813 $(obj)/image: vmlinux FORCE
814 $(call if_changed,objcopy)
816 In this example, the binary $(obj)/image is a binary version of
817 vmlinux. The usage of $(call if_changed,xxx) will be described later.
819 AFLAGS $(AS) assembler flags
821 Default value - see top level Makefile
822 Append or modify as required per architecture.
825 #arch/sparc64/Makefile
826 AFLAGS += -m64 -mcpu=ultrasparc
828 CFLAGS $(CC) compiler flags
830 Default value - see top level Makefile
831 Append or modify as required per architecture.
833 Often, the CFLAGS variable depends on the configuration.
837 cflags-$(CONFIG_M386) += -march=i386
838 CFLAGS += $(cflags-y)
840 Many arch Makefiles dynamically run the target C compiler to
841 probe supported options:
846 cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\
847 -march=pentium2,-march=i686)
849 # Disable unit-at-a-time mode ...
850 CFLAGS += $(call cc-option,-fno-unit-at-a-time)
854 The first example utilises the trick that a config option expands
855 to 'y' when selected.
857 CFLAGS_KERNEL $(CC) options specific for built-in
859 $(CFLAGS_KERNEL) contains extra C compiler flags used to compile
860 resident kernel code.
862 CFLAGS_MODULE $(CC) options specific for modules
864 $(CFLAGS_MODULE) contains extra C compiler flags used to compile code
865 for loadable kernel modules.
868 --- 6.2 Add prerequisites to archprepare:
870 The archprepare: rule is used to list prerequisites that need to be
871 built before starting to descend down in the subdirectories.
872 This is usually used for header files containing assembler constants.
876 archprepare: maketools
878 In this example, the file target maketools will be processed
879 before descending down in the subdirectories.
880 See also chapter XXX-TODO that describe how kbuild supports
881 generating offset header files.
884 --- 6.3 List directories to visit when descending
886 An arch Makefile cooperates with the top Makefile to define variables
887 which specify how to build the vmlinux file. Note that there is no
888 corresponding arch-specific section for modules; the module-building
889 machinery is all architecture-independent.
892 head-y, init-y, core-y, libs-y, drivers-y, net-y
894 $(head-y) lists objects to be linked first in vmlinux.
895 $(libs-y) lists directories where a lib.a archive can be located.
896 The rest list directories where a built-in.o object file can be
899 $(init-y) objects will be located after $(head-y).
900 Then the rest follows in this order:
901 $(core-y), $(libs-y), $(drivers-y) and $(net-y).
903 The top level Makefile defines values for all generic directories,
904 and arch/$(ARCH)/Makefile only adds architecture-specific directories.
907 #arch/sparc64/Makefile
908 core-y += arch/sparc64/kernel/
909 libs-y += arch/sparc64/prom/ arch/sparc64/lib/
910 drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
913 --- 6.4 Architecture-specific boot images
915 An arch Makefile specifies goals that take the vmlinux file, compress
916 it, wrap it in bootstrapping code, and copy the resulting files
917 somewhere. This includes various kinds of installation commands.
918 The actual goals are not standardized across architectures.
920 It is common to locate any additional processing in a boot/
921 directory below arch/$(ARCH)/.
923 Kbuild does not provide any smart way to support building a
924 target specified in boot/. Therefore arch/$(ARCH)/Makefile shall
925 call make manually to build a target in boot/.
927 The recommended approach is to include shortcuts in
928 arch/$(ARCH)/Makefile, and use the full path when calling down
929 into the arch/$(ARCH)/boot/Makefile.
933 boot := arch/i386/boot
935 $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
937 "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
938 make in a subdirectory.
940 There are no rules for naming architecture-specific targets,
941 but executing "make help" will list all relevant targets.
942 To support this, $(archhelp) must be defined.
947 echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)'
950 When make is executed without arguments, the first goal encountered
951 will be built. In the top level Makefile the first goal present
953 An architecture shall always, per default, build a bootable image.
954 In "make help", the default goal is highlighted with a '*'.
955 Add a new prerequisite to all: to select a default goal different
962 When "make" is executed without arguments, bzImage will be built.
964 --- 6.5 Building non-kbuild targets
968 extra-y specify additional targets created in the current
969 directory, in addition to any targets specified by obj-*.
971 Listing all targets in extra-y is required for two purposes:
972 1) Enable kbuild to check changes in command lines
973 - When $(call if_changed,xxx) is used
974 2) kbuild knows what files to delete during "make clean"
977 #arch/i386/kernel/Makefile
978 extra-y := head.o init_task.o
980 In this example, extra-y is used to list object files that
981 shall be built, but shall not be linked as part of built-in.o.
984 --- 6.6 Commands useful for building a boot image
986 Kbuild provides a few macros that are useful when building a
991 if_changed is the infrastructure used for the following commands.
994 target: source(s) FORCE
995 $(call if_changed,ld/objcopy/gzip)
997 When the rule is evaluated, it is checked to see if any files
998 need an update, or the command line has changed since the last
999 invocation. The latter will force a rebuild if any options
1000 to the executable have changed.
1001 Any target that utilises if_changed must be listed in $(targets),
1002 otherwise the command line check will fail, and the target will
1004 Assignments to $(targets) are without $(obj)/ prefix.
1005 if_changed may be used in conjunction with custom commands as
1006 defined in 6.7 "Custom kbuild commands".
1008 Note: It is a typical mistake to forget the FORCE prerequisite.
1009 Another common pitfall is that whitespace is sometimes
1010 significant; for instance, the below will fail (note the extra space
1012 target: source(s) FORCE
1013 #WRONG!# $(call if_changed, ld/objcopy/gzip)
1016 Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1019 Copy binary. Uses OBJCOPYFLAGS usually specified in
1020 arch/$(ARCH)/Makefile.
1021 OBJCOPYFLAGS_$@ may be used to set additional options.
1024 Compress target. Use maximum compression to compress target.
1027 #arch/i386/boot/Makefile
1028 LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
1029 LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext
1031 targets += setup setup.o bootsect bootsect.o
1032 $(obj)/setup $(obj)/bootsect: %: %.o FORCE
1033 $(call if_changed,ld)
1035 In this example, there are two possible targets, requiring different
1036 options to the linker. The linker options are specified using the
1037 LDFLAGS_$@ syntax - one for each potential target.
1038 $(targets) are assigned all potential targets, by which kbuild knows
1039 the targets and will:
1040 1) check for commandline changes
1041 2) delete target during make clean
1043 The ": %: %.o" part of the prerequisite is a shorthand that
1044 free us from listing the setup.o and bootsect.o files.
1045 Note: It is a common mistake to forget the "target :=" assignment,
1046 resulting in the target file being recompiled for no
1050 --- 6.7 Custom kbuild commands
1052 When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
1053 of a command is normally displayed.
1054 To enable this behaviour for custom commands kbuild requires
1055 two variables to be set:
1056 quiet_cmd_<command> - what shall be echoed
1057 cmd_<command> - the command to execute
1061 quiet_cmd_image = BUILD $@
1062 cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
1063 $(obj)/vmlinux.bin > $@
1066 $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
1067 $(call if_changed,image)
1068 @echo 'Kernel: $@ is ready'
1070 When updating the $(obj)/bzImage target, the line
1072 BUILD arch/i386/boot/bzImage
1074 will be displayed with "make KBUILD_VERBOSE=0".
1077 --- 6.8 Preprocessing linker scripts
1079 When the vmlinux image is built, the linker script
1080 arch/$(ARCH)/kernel/vmlinux.lds is used.
1081 The script is a preprocessed variant of the file vmlinux.lds.S
1082 located in the same directory.
1083 kbuild knows .lds files and includes a rule *lds.S -> *lds.
1086 #arch/i386/kernel/Makefile
1087 always := vmlinux.lds
1090 export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
1092 The assignment to $(always) is used to tell kbuild to build the
1094 The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1095 specified options when building the target vmlinux.lds.
1097 When building the *.lds target, kbuild uses the variables:
1098 CPPFLAGS : Set in top-level Makefile
1099 EXTRA_CPPFLAGS : May be set in the kbuild makefile
1100 CPPFLAGS_$(@F) : Target specific flags.
1101 Note that the full filename is used in this
1104 The kbuild infrastructure for *lds file are used in several
1105 architecture-specific files.
1108 === 7 Kbuild Variables
1110 The top Makefile exports the following variables:
1112 VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
1114 These variables define the current kernel version. A few arch
1115 Makefiles actually use these values directly; they should use
1116 $(KERNELRELEASE) instead.
1118 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
1119 three-part version number, such as "2", "4", and "0". These three
1120 values are always numeric.
1122 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches
1123 or additional patches. It is usually some non-numeric string
1124 such as "-pre4", and is often blank.
1128 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
1129 for constructing installation directory names or showing in
1130 version strings. Some arch Makefiles use it for this purpose.
1134 This variable defines the target architecture, such as "i386",
1135 "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
1136 determine which files to compile.
1138 By default, the top Makefile sets $(ARCH) to be the same as the
1139 host system architecture. For a cross build, a user may
1140 override the value of $(ARCH) on the command line:
1147 This variable defines a place for the arch Makefiles to install
1148 the resident kernel image and System.map file.
1149 Use this for architecture-specific install targets.
1151 INSTALL_MOD_PATH, MODLIB
1153 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
1154 installation. This variable is not defined in the Makefile but
1155 may be passed in by the user if desired.
1157 $(MODLIB) specifies the directory for module installation.
1158 The top Makefile defines $(MODLIB) to
1159 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may
1160 override this value on the command line if desired.
1164 If this variable is specified, will cause modules to be stripped
1165 after they are installed. If INSTALL_MOD_STRIP is '1', then the
1166 default option --strip-debug will be used. Otherwise,
1167 INSTALL_MOD_STRIP will used as the option(s) to the strip command.
1170 === 8 Makefile language
1172 The kernel Makefiles are designed to be run with GNU Make. The Makefiles
1173 use only the documented features of GNU Make, but they do use many
1176 GNU Make supports elementary list-processing functions. The kernel
1177 Makefiles use a novel style of list building and manipulation with few
1180 GNU Make has two assignment operators, ":=" and "=". ":=" performs
1181 immediate evaluation of the right-hand side and stores an actual string
1182 into the left-hand side. "=" is like a formula definition; it stores the
1183 right-hand side in an unevaluated form and then evaluates this form each
1184 time the left-hand side is used.
1186 There are some cases where "=" is appropriate. Usually, though, ":="
1187 is the right choice.
1191 Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1192 Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1193 Updates by Sam Ravnborg <sam@ravnborg.org>
1194 Language QA by Jan Engelhardt <jengelh@gmx.de>
1198 - Describe how kbuild supports shipped files with _shipped.
1199 - Generating offset header files.
1200 - Add more variables to section 7?