5 This document describes the Linux kernel Makefiles.
11 === 3 The kbuild files
12 --- 3.1 Goal definitions
13 --- 3.2 Built-in object goals - obj-y
14 --- 3.3 Loadable module goals - obj-m
15 --- 3.4 Objects which export symbols
16 --- 3.5 Library file goals - lib-y
17 --- 3.6 Descending down in directories
18 --- 3.7 Compilation flags
19 --- 3.8 Command line dependency
20 --- 3.9 Dependency tracking
21 --- 3.10 Special Rules
22 --- 3.11 $(CC) support functions
23 --- 3.12 $(LD) support functions
25 === 4 Host Program support
26 --- 4.1 Simple Host Program
27 --- 4.2 Composite Host Programs
28 --- 4.3 Using C++ for host programs
29 --- 4.4 Controlling compiler options for host programs
30 --- 4.5 When host programs are actually built
31 --- 4.6 Using hostprogs-$(CONFIG_FOO)
33 === 5 Kbuild clean infrastructure
35 === 6 Architecture Makefiles
36 --- 6.1 Set variables to tweak the build to the architecture
37 --- 6.2 Add prerequisites to archheaders:
38 --- 6.3 Add prerequisites to archprepare:
39 --- 6.4 List directories to visit when descending
40 --- 6.5 Architecture-specific boot images
41 --- 6.6 Building non-kbuild targets
42 --- 6.7 Commands useful for building a boot image
43 --- 6.8 Custom kbuild commands
44 --- 6.9 Preprocessing linker scripts
45 --- 6.10 Generic header files
46 --- 6.11 Post-link pass
48 === 7 Kbuild syntax for exported headers
49 --- 7.1 no-export-headers
54 === 8 Kbuild Variables
55 === 9 Makefile language
62 The Makefiles have five parts::
64 Makefile the top Makefile.
65 .config the kernel configuration file.
66 arch/$(ARCH)/Makefile the arch Makefile.
67 scripts/Makefile.* common rules etc. for all kbuild Makefiles.
68 kbuild Makefiles there are about 500 of these.
70 The top Makefile reads the .config file, which comes from the kernel
71 configuration process.
73 The top Makefile is responsible for building two major products: vmlinux
74 (the resident kernel image) and modules (any module files).
75 It builds these goals by recursively descending into the subdirectories of
76 the kernel source tree.
77 The list of subdirectories which are visited depends upon the kernel
78 configuration. The top Makefile textually includes an arch Makefile
79 with the name arch/$(ARCH)/Makefile. The arch Makefile supplies
80 architecture-specific information to the top Makefile.
82 Each subdirectory has a kbuild Makefile which carries out the commands
83 passed down from above. The kbuild Makefile uses information from the
84 .config file to construct various file lists used by kbuild to build
85 any built-in or modular targets.
87 scripts/Makefile.* contains all the definitions/rules etc. that
88 are used to build the kernel based on the kbuild makefiles.
94 People have four different relationships with the kernel Makefiles.
96 *Users* are people who build kernels. These people type commands such as
97 "make menuconfig" or "make". They usually do not read or edit
98 any kernel Makefiles (or any other source files).
100 *Normal developers* are people who work on features such as device
101 drivers, file systems, and network protocols. These people need to
102 maintain the kbuild Makefiles for the subsystem they are
103 working on. In order to do this effectively, they need some overall
104 knowledge about the kernel Makefiles, plus detailed knowledge about the
105 public interface for kbuild.
107 *Arch developers* are people who work on an entire architecture, such
108 as sparc or ia64. Arch developers need to know about the arch Makefile
109 as well as kbuild Makefiles.
111 *Kbuild developers* are people who work on the kernel build system itself.
112 These people need to know about all aspects of the kernel Makefiles.
114 This document is aimed towards normal developers and arch developers.
120 Most Makefiles within the kernel are kbuild Makefiles that use the
121 kbuild infrastructure. This chapter introduces the syntax used in the
123 The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
124 be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
127 Section 3.1 "Goal definitions" is a quick intro, further chapters provide
128 more details, with real examples.
133 Goal definitions are the main part (heart) of the kbuild Makefile.
134 These lines define the files to be built, any special compilation
135 options, and any subdirectories to be entered recursively.
137 The most simple kbuild makefile contains one line:
143 This tells kbuild that there is one object in that directory, named
144 foo.o. foo.o will be built from foo.c or foo.S.
146 If foo.o shall be built as a module, the variable obj-m is used.
147 Therefore the following pattern is often used:
151 obj-$(CONFIG_FOO) += foo.o
153 $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
154 If CONFIG_FOO is neither y nor m, then the file will not be compiled
157 3.2 Built-in object goals - obj-y
158 ---------------------------------
160 The kbuild Makefile specifies object files for vmlinux
161 in the $(obj-y) lists. These lists depend on the kernel
164 Kbuild compiles all the $(obj-y) files. It then calls
165 "$(AR) rcSTP" to merge these files into one built-in.a file.
166 This is a thin archive without a symbol table. It will be later
167 linked into vmlinux by scripts/link-vmlinux.sh
169 The order of files in $(obj-y) is significant. Duplicates in
170 the lists are allowed: the first instance will be linked into
171 built-in.a and succeeding instances will be ignored.
173 Link order is significant, because certain functions
174 (module_init() / __initcall) will be called during boot in the
175 order they appear. So keep in mind that changing the link
176 order may e.g. change the order in which your SCSI
177 controllers are detected, and thus your disks are renumbered.
181 #drivers/isdn/i4l/Makefile
182 # Makefile for the kernel ISDN subsystem and device drivers.
183 # Each configuration option enables a list of files.
184 obj-$(CONFIG_ISDN_I4L) += isdn.o
185 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
187 3.3 Loadable module goals - obj-m
188 ---------------------------------
190 $(obj-m) specifies object files which are built as loadable
193 A module may be built from one source file or several source
194 files. In the case of one source file, the kbuild makefile
195 simply adds the file to $(obj-m).
199 #drivers/isdn/i4l/Makefile
200 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
202 Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
204 If a kernel module is built from several source files, you specify
205 that you want to build a module in the same way as above; however,
206 kbuild needs to know which object files you want to build your
207 module from, so you have to tell it by setting a $(<module_name>-y)
212 #drivers/isdn/i4l/Makefile
213 obj-$(CONFIG_ISDN_I4L) += isdn.o
214 isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
216 In this example, the module name will be isdn.o. Kbuild will
217 compile the objects listed in $(isdn-y) and then run
218 "$(LD) -r" on the list of these files to generate isdn.o.
220 Due to kbuild recognizing $(<module_name>-y) for composite objects,
221 you can use the value of a `CONFIG_` symbol to optionally include an
222 object file as part of a composite object.
227 obj-$(CONFIG_EXT2_FS) += ext2.o
228 ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
229 namei.o super.o symlink.o
230 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
233 In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
234 part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
237 Note: Of course, when you are building objects into the kernel,
238 the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
239 kbuild will build an ext2.o file for you out of the individual
240 parts and then link this into built-in.a, as you would expect.
242 3.4 Objects which export symbols
243 --------------------------------
245 No special notation is required in the makefiles for
246 modules exporting symbols.
248 3.5 Library file goals - lib-y
249 ------------------------------
251 Objects listed with obj-* are used for modules, or
252 combined in a built-in.a for that specific directory.
253 There is also the possibility to list objects that will
254 be included in a library, lib.a.
255 All objects listed with lib-y are combined in a single
256 library for that directory.
257 Objects that are listed in obj-y and additionally listed in
258 lib-y will not be included in the library, since they will
259 be accessible anyway.
260 For consistency, objects listed in lib-m will be included in lib.a.
262 Note that the same kbuild makefile may list files to be built-in
263 and to be part of a library. Therefore the same directory
264 may contain both a built-in.a and a lib.a file.
268 #arch/x86/lib/Makefile
271 This will create a library lib.a based on delay.o. For kbuild to
272 actually recognize that there is a lib.a being built, the directory
273 shall be listed in libs-y.
275 See also "6.4 List directories to visit when descending".
277 Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.
279 3.6 Descending down in directories
280 ----------------------------------
282 A Makefile is only responsible for building objects in its own
283 directory. Files in subdirectories should be taken care of by
284 Makefiles in these subdirs. The build system will automatically
285 invoke make recursively in subdirectories, provided you let it know of
288 To do so, obj-y and obj-m are used.
289 ext2 lives in a separate directory, and the Makefile present in fs/
290 tells kbuild to descend down using the following assignment.
295 obj-$(CONFIG_EXT2_FS) += ext2/
297 If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
298 the corresponding obj- variable will be set, and kbuild will descend
299 down in the ext2 directory.
300 Kbuild only uses this information to decide that it needs to visit
301 the directory, it is the Makefile in the subdirectory that
302 specifies what is modular and what is built-in.
304 It is good practice to use a `CONFIG_` variable when assigning directory
305 names. This allows kbuild to totally skip the directory if the
306 corresponding `CONFIG_` option is neither 'y' nor 'm'.
308 3.7 Compilation flags
309 ---------------------
311 ccflags-y, asflags-y and ldflags-y
312 These three flags apply only to the kbuild makefile in which they
313 are assigned. They are used for all the normal cc, as and ld
314 invocations happening during a recursive build.
315 Note: Flags with the same behaviour were previously named:
316 EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
317 They are still supported but their usage is deprecated.
319 ccflags-y specifies options for compiling with $(CC).
323 # drivers/acpi/acpica/Makefile
324 ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA
325 ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
327 This variable is necessary because the top Makefile owns the
328 variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
331 asflags-y specifies assembler options.
335 #arch/sparc/kernel/Makefile
338 ldflags-y specifies options for linking with $(LD).
342 #arch/cris/boot/compressed/Makefile
343 ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
345 subdir-ccflags-y, subdir-asflags-y
346 The two flags listed above are similar to ccflags-y and asflags-y.
347 The difference is that the subdir- variants have effect for the kbuild
348 file where they are present and all subdirectories.
349 Options specified using subdir-* are added to the commandline before
350 the options specified using the non-subdir variants.
354 subdir-ccflags-y := -Werror
357 CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
360 $(CFLAGS_$@) specifies per-file options for $(CC). The $@
361 part has a literal value which specifies the file that it is for.
365 # drivers/scsi/Makefile
366 CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
367 CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
370 These two lines specify compilation flags for aha152x.o and gdth.o.
372 $(AFLAGS_$@) is a similar feature for source files in assembly
377 # arch/arm/kernel/Makefile
378 AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET)
379 AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
380 AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
383 3.9 Dependency tracking
384 -----------------------
386 Kbuild tracks dependencies on the following:
388 1) All prerequisite files (both `*.c` and `*.h`)
389 2) `CONFIG_` options used in all prerequisite files
390 3) Command-line used to compile target
392 Thus, if you change an option to $(CC) all affected files will
398 Special rules are used when the kbuild infrastructure does
399 not provide the required support. A typical example is
400 header files generated during the build process.
401 Another example are the architecture-specific Makefiles which
402 need special rules to prepare boot images etc.
404 Special rules are written as normal Make rules.
405 Kbuild is not executing in the directory where the Makefile is
406 located, so all special rules shall provide a relative
407 path to prerequisite files and target files.
409 Two variables are used when defining special rules:
412 $(src) is a relative path which points to the directory
413 where the Makefile is located. Always use $(src) when
414 referring to files located in the src tree.
417 $(obj) is a relative path which points to the directory
418 where the target is saved. Always use $(obj) when
419 referring to generated files.
423 #drivers/scsi/Makefile
424 $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
425 $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
427 This is a special rule, following the normal syntax
430 The target file depends on two prerequisite files. References
431 to the target file are prefixed with $(obj), references
432 to prerequisites are referenced with $(src) (because they are not
436 echoing information to user in a rule is often a good practice
437 but when execution "make -s" one does not expect to see any output
438 except for warnings/errors.
439 To support this kbuild defines $(kecho) which will echo out the
440 text following $(kecho) to stdout except if "make -s" is used.
444 #arch/blackfin/boot/Makefile
445 $(obj)/vmImage: $(obj)/vmlinux.gz
446 $(call if_changed,uimage)
447 @$(kecho) 'Kernel: $@ is ready'
450 3.11 $(CC) support functions
451 ----------------------------
453 The kernel may be built with several different versions of
454 $(CC), each supporting a unique set of features and options.
455 kbuild provides basic support to check for valid options for $(CC).
456 $(CC) is usually the gcc compiler, but other alternatives are
460 as-option is used to check if $(CC) -- when used to compile
461 assembler (`*.S`) files -- supports the given option. An optional
462 second option may be specified if the first option is not supported.
467 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
469 In the above example, cflags-y will be assigned the option
470 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
471 The second argument is optional, and if supplied will be used
472 if first argument is not supported.
475 cc-ldoption is used to check if $(CC) when used to link object files
476 supports the given option. An optional second option may be
477 specified if first option are not supported.
481 #arch/x86/kernel/Makefile
482 vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
484 In the above example, vsyscall-flags will be assigned the option
485 -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
486 The second argument is optional, and if supplied will be used
487 if first argument is not supported.
490 as-instr checks if the assembler reports a specific instruction
491 and then outputs either option1 or option2
492 C escapes are supported in the test instruction
493 Note: as-instr-option uses KBUILD_AFLAGS for assembler options
496 cc-option is used to check if $(CC) supports a given option, and if
497 not supported to use an optional second option.
502 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
504 In the above example, cflags-y will be assigned the option
505 -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
506 The second argument to cc-option is optional, and if omitted,
507 cflags-y will be assigned no value if first option is not supported.
508 Note: cc-option uses KBUILD_CFLAGS for $(CC) options
511 cc-option-yn is used to check if gcc supports a given option
512 and return 'y' if supported, otherwise 'n'.
517 biarch := $(call cc-option-yn, -m32)
518 aflags-$(biarch) += -a32
519 cflags-$(biarch) += -m32
521 In the above example, $(biarch) is set to y if $(CC) supports the -m32
522 option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
523 and $(cflags-y) will be assigned the values -a32 and -m32,
525 Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
528 cc-disable-warning checks if gcc supports a given warning and returns
529 the commandline switch to disable it. This special function is needed,
530 because gcc 4.4 and later accept any unknown -Wno-* option and only
531 warn about it if there is another warning in the source file.
535 KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
537 In the above example, -Wno-unused-but-set-variable will be added to
538 KBUILD_CFLAGS only if gcc really accepts it.
541 cc-ifversion tests the version of $(CC) and equals the fourth parameter
542 if version expression is true, or the fifth (if given) if the version
547 #fs/reiserfs/Makefile
548 ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
550 In this example, ccflags-y will be assigned the value -O1 if the
551 $(CC) version is less than 4.2.
552 cc-ifversion takes all the shell operators:
553 -eq, -ne, -lt, -le, -gt, and -ge
554 The third parameter may be a text as in this example, but it may also
555 be an expanded variable or a macro.
558 cc-cross-prefix is used to check if there exists a $(CC) in path with
559 one of the listed prefixes. The first prefix where there exist a
560 prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
561 then nothing is returned.
562 Additional prefixes are separated by a single space in the
563 call of cc-cross-prefix.
564 This functionality is useful for architecture Makefiles that try
565 to set CROSS_COMPILE to well-known values but may have several
566 values to select between.
567 It is recommended only to try to set CROSS_COMPILE if it is a cross
568 build (host arch is different from target arch). And if CROSS_COMPILE
569 is already set then leave it with the old value.
574 ifneq ($(SUBARCH),$(ARCH))
575 ifeq ($(CROSS_COMPILE),)
576 CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
580 3.12 $(LD) support functions
581 ----------------------------
584 ld-option is used to check if $(LD) supports the supplied option.
585 ld-option takes two options as arguments.
586 The second argument is an optional option that can be used if the
587 first option is not supported by $(LD).
592 LDFLAGS_vmlinux += $(call ld-option, -X)
595 4 Host Program support
596 ======================
598 Kbuild supports building executables on the host for use during the
600 Two steps are required in order to use a host executable.
602 The first step is to tell kbuild that a host program exists. This is
603 done utilising the variable hostprogs-y.
605 The second step is to add an explicit dependency to the executable.
606 This can be done in two ways. Either add the dependency in a rule,
607 or utilise the variable $(always).
608 Both possibilities are described in the following.
610 4.1 Simple Host Program
611 -----------------------
613 In some cases there is a need to compile and run a program on the
614 computer where the build is running.
615 The following line tells kbuild that the program bin2hex shall be
616 built on the build host.
620 hostprogs-y := bin2hex
622 Kbuild assumes in the above example that bin2hex is made from a single
623 c-source file named bin2hex.c located in the same directory as
626 4.2 Composite Host Programs
627 ---------------------------
629 Host programs can be made up based on composite objects.
630 The syntax used to define composite objects for host programs is
631 similar to the syntax used for kernel objects.
632 $(<executable>-objs) lists all objects used to link the final
637 #scripts/lxdialog/Makefile
638 hostprogs-y := lxdialog
639 lxdialog-objs := checklist.o lxdialog.o
641 Objects with extension .o are compiled from the corresponding .c
642 files. In the above example, checklist.c is compiled to checklist.o
643 and lxdialog.c is compiled to lxdialog.o.
645 Finally, the two .o files are linked to the executable, lxdialog.
646 Note: The syntax <executable>-y is not permitted for host-programs.
648 4.3 Using C++ for host programs
649 -------------------------------
651 kbuild offers support for host programs written in C++. This was
652 introduced solely to support kconfig, and is not recommended
657 #scripts/kconfig/Makefile
659 qconf-cxxobjs := qconf.o
661 In the example above the executable is composed of the C++ file
662 qconf.cc - identified by $(qconf-cxxobjs).
664 If qconf is composed of a mixture of .c and .cc files, then an
665 additional line can be used to identify this.
669 #scripts/kconfig/Makefile
671 qconf-cxxobjs := qconf.o
672 qconf-objs := check.o
674 4.4 Controlling compiler options for host programs
675 --------------------------------------------------
677 When compiling host programs, it is possible to set specific flags.
678 The programs will always be compiled utilising $(HOSTCC) passed
679 the options specified in $(KBUILD_HOSTCFLAGS).
680 To set flags that will take effect for all host programs created
681 in that Makefile, use the variable HOST_EXTRACFLAGS.
685 #scripts/lxdialog/Makefile
686 HOST_EXTRACFLAGS += -I/usr/include/ncurses
688 To set specific flags for a single file the following construction
693 #arch/ppc64/boot/Makefile
694 HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
696 It is also possible to specify additional options to the linker.
700 #scripts/kconfig/Makefile
701 HOSTLDLIBS_qconf := -L$(QTDIR)/lib
703 When linking qconf, it will be passed the extra option
706 4.5 When host programs are actually built
707 -----------------------------------------
709 Kbuild will only build host-programs when they are referenced
711 This is possible in two ways:
713 (1) List the prerequisite explicitly in a special rule.
717 #drivers/pci/Makefile
718 hostprogs-y := gen-devlist
719 $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
720 ( cd $(obj); ./gen-devlist ) < $<
722 The target $(obj)/devlist.h will not be built before
723 $(obj)/gen-devlist is updated. Note that references to
724 the host programs in special rules must be prefixed with $(obj).
728 When there is no suitable special rule, and the host program
729 shall be built when a makefile is entered, the $(always)
730 variable shall be used.
734 #scripts/lxdialog/Makefile
735 hostprogs-y := lxdialog
736 always := $(hostprogs-y)
738 This will tell kbuild to build lxdialog even if not referenced in
741 4.6 Using hostprogs-$(CONFIG_FOO)
742 ---------------------------------
744 A typical pattern in a Kbuild file looks like this:
749 hostprogs-$(CONFIG_KALLSYMS) += kallsyms
751 Kbuild knows about both 'y' for built-in and 'm' for module.
752 So if a config symbol evaluates to 'm', kbuild will still build
753 the binary. In other words, Kbuild handles hostprogs-m exactly
754 like hostprogs-y. But only hostprogs-y is recommended to be used
755 when no CONFIG symbols are involved.
757 5 Kbuild clean infrastructure
758 =============================
760 "make clean" deletes most generated files in the obj tree where the kernel
761 is compiled. This includes generated files such as host programs.
762 Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
763 $(extra-y) and $(targets). They are all deleted during "make clean".
764 Files matching the patterns "*.[oas]", "*.ko", plus some additional files
765 generated by kbuild are deleted all over the kernel src tree when
766 "make clean" is executed.
768 Additional files can be specified in kbuild makefiles by use of $(clean-files).
773 clean-files := crc32table.h
775 When executing "make clean", the file "crc32table.h" will be deleted.
776 Kbuild will assume files to be in the same relative directory as the
777 Makefile, except if prefixed with $(objtree).
779 To delete a directory hierarchy use:
783 #scripts/package/Makefile
784 clean-dirs := $(objtree)/debian/
786 This will delete the directory debian in the toplevel directory, including all
789 To exclude certain files from make clean, use the $(no-clean-files) variable.
790 This is only a special case used in the top level Kbuild file:
795 no-clean-files := $(bounds-file) $(offsets-file)
797 Usually kbuild descends down in subdirectories due to "obj-* := dir/",
798 but in the architecture makefiles where the kbuild infrastructure
799 is not sufficient this sometimes needs to be explicit.
803 #arch/x86/boot/Makefile
804 subdir- := compressed/
806 The above assignment instructs kbuild to descend down in the
807 directory compressed/ when "make clean" is executed.
809 To support the clean infrastructure in the Makefiles that build the
810 final bootimage there is an optional target named archclean:
816 $(Q)$(MAKE) $(clean)=arch/x86/boot
818 When "make clean" is executed, make will descend down in arch/x86/boot,
819 and clean as usual. The Makefile located in arch/x86/boot/ may use
820 the subdir- trick to descend further down.
822 Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
823 included in the top level makefile, and the kbuild infrastructure
824 is not operational at that point.
826 Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
827 be visited during "make clean".
829 6 Architecture Makefiles
830 ========================
832 The top level Makefile sets up the environment and does the preparation,
833 before starting to descend down in the individual directories.
834 The top level makefile contains the generic part, whereas
835 arch/$(ARCH)/Makefile contains what is required to set up kbuild
836 for said architecture.
837 To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
840 When kbuild executes, the following steps are followed (roughly):
842 1) Configuration of the kernel => produce .config
843 2) Store kernel version in include/linux/version.h
844 3) Updating all other prerequisites to the target prepare:
845 - Additional prerequisites are specified in arch/$(ARCH)/Makefile
846 4) Recursively descend down in all directories listed in
847 init-* core* drivers-* net-* libs-* and build all targets.
848 - The values of the above variables are expanded in arch/$(ARCH)/Makefile.
849 5) All object files are then linked and the resulting file vmlinux is
850 located at the root of the obj tree.
851 The very first objects linked are listed in head-y, assigned by
852 arch/$(ARCH)/Makefile.
853 6) Finally, the architecture-specific part does any required post processing
854 and builds the final bootimage.
855 - This includes building boot records
856 - Preparing initrd images and the like
859 6.1 Set variables to tweak the build to the architecture
860 --------------------------------------------------------
863 Generic $(LD) options
865 Flags used for all invocations of the linker.
866 Often specifying the emulation is sufficient.
871 LDFLAGS := -m elf_s390
873 Note: ldflags-y can be used to further customise
874 the flags used. See chapter 3.7.
877 Options for $(LD) when linking vmlinux
879 LDFLAGS_vmlinux is used to specify additional flags to pass to
880 the linker when linking the final vmlinux image.
881 LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
886 LDFLAGS_vmlinux := -e stext
891 When $(call if_changed,objcopy) is used to translate a .o file,
892 the flags specified in OBJCOPYFLAGS will be used.
893 $(call if_changed,objcopy) is often used to generate raw binaries on
899 OBJCOPYFLAGS := -O binary
901 #arch/s390/boot/Makefile
902 $(obj)/image: vmlinux FORCE
903 $(call if_changed,objcopy)
905 In this example, the binary $(obj)/image is a binary version of
906 vmlinux. The usage of $(call if_changed,xxx) will be described later.
911 Default value - see top level Makefile
912 Append or modify as required per architecture.
916 #arch/sparc64/Makefile
917 KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
922 Default value - see top level Makefile
923 Append or modify as required per architecture.
925 Often, the KBUILD_CFLAGS variable depends on the configuration.
929 #arch/x86/boot/compressed/Makefile
930 cflags-$(CONFIG_X86_32) := -march=i386
931 cflags-$(CONFIG_X86_64) := -mcmodel=small
932 KBUILD_CFLAGS += $(cflags-y)
934 Many arch Makefiles dynamically run the target C compiler to
935 probe supported options::
940 cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\
941 -march=pentium2,-march=i686)
943 # Disable unit-at-a-time mode ...
944 KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
948 The first example utilises the trick that a config option expands
949 to 'y' when selected.
952 Assembler options specific for built-in
954 $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
955 resident kernel code.
958 Assembler options specific for modules
960 $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
961 are used for assembler.
963 From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
966 $(CC) options specific for built-in
968 $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
969 resident kernel code.
972 Options for $(CC) when building modules
974 $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
976 From commandline CFLAGS_MODULE shall be used (see kbuild.txt).
978 KBUILD_LDFLAGS_MODULE
979 Options for $(LD) when linking modules
981 $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
982 used when linking modules. This is often a linker script.
984 From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).
986 KBUILD_ARFLAGS Options for $(AR) when creating archives
988 $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic
989 mode) if this option is supported by $(AR).
991 ARCH_CPPFLAGS, ARCH_AFLAGS, ARCH_CFLAGS Overrides the kbuild defaults
993 These variables are appended to the KBUILD_CPPFLAGS,
994 KBUILD_AFLAGS, and KBUILD_CFLAGS, respectively, after the
995 top-level Makefile has set any other flags. This provides a
996 means for an architecture to override the defaults.
999 6.2 Add prerequisites to archheaders
1000 ------------------------------------
1002 The archheaders: rule is used to generate header files that
1003 may be installed into user space by "make header_install".
1005 It is run before "make archprepare" when run on the
1006 architecture itself.
1009 6.3 Add prerequisites to archprepare
1010 ------------------------------------
1012 The archprepare: rule is used to list prerequisites that need to be
1013 built before starting to descend down in the subdirectories.
1014 This is usually used for header files containing assembler constants.
1019 archprepare: maketools
1021 In this example, the file target maketools will be processed
1022 before descending down in the subdirectories.
1023 See also chapter XXX-TODO that describe how kbuild supports
1024 generating offset header files.
1027 6.4 List directories to visit when descending
1028 ---------------------------------------------
1030 An arch Makefile cooperates with the top Makefile to define variables
1031 which specify how to build the vmlinux file. Note that there is no
1032 corresponding arch-specific section for modules; the module-building
1033 machinery is all architecture-independent.
1036 head-y, init-y, core-y, libs-y, drivers-y, net-y
1037 $(head-y) lists objects to be linked first in vmlinux.
1039 $(libs-y) lists directories where a lib.a archive can be located.
1041 The rest list directories where a built-in.a object file can be
1044 $(init-y) objects will be located after $(head-y).
1046 Then the rest follows in this order:
1048 $(core-y), $(libs-y), $(drivers-y) and $(net-y).
1050 The top level Makefile defines values for all generic directories,
1051 and arch/$(ARCH)/Makefile only adds architecture-specific
1056 #arch/sparc64/Makefile
1057 core-y += arch/sparc64/kernel/
1058 libs-y += arch/sparc64/prom/ arch/sparc64/lib/
1059 drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
1062 6.5 Architecture-specific boot images
1063 -------------------------------------
1065 An arch Makefile specifies goals that take the vmlinux file, compress
1066 it, wrap it in bootstrapping code, and copy the resulting files
1067 somewhere. This includes various kinds of installation commands.
1068 The actual goals are not standardized across architectures.
1070 It is common to locate any additional processing in a boot/
1071 directory below arch/$(ARCH)/.
1073 Kbuild does not provide any smart way to support building a
1074 target specified in boot/. Therefore arch/$(ARCH)/Makefile shall
1075 call make manually to build a target in boot/.
1077 The recommended approach is to include shortcuts in
1078 arch/$(ARCH)/Makefile, and use the full path when calling down
1079 into the arch/$(ARCH)/boot/Makefile.
1084 boot := arch/x86/boot
1086 $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
1088 "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
1089 make in a subdirectory.
1091 There are no rules for naming architecture-specific targets,
1092 but executing "make help" will list all relevant targets.
1093 To support this, $(archhelp) must be defined.
1099 echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)'
1102 When make is executed without arguments, the first goal encountered
1103 will be built. In the top level Makefile the first goal present
1105 An architecture shall always, per default, build a bootable image.
1106 In "make help", the default goal is highlighted with a '*'.
1107 Add a new prerequisite to all: to select a default goal different
1115 When "make" is executed without arguments, bzImage will be built.
1117 6.6 Building non-kbuild targets
1118 -------------------------------
1121 extra-y specifies additional targets created in the current
1122 directory, in addition to any targets specified by `obj-*`.
1124 Listing all targets in extra-y is required for two purposes:
1126 1) Enable kbuild to check changes in command lines
1128 - When $(call if_changed,xxx) is used
1130 2) kbuild knows what files to delete during "make clean"
1134 #arch/x86/kernel/Makefile
1135 extra-y := head.o init_task.o
1137 In this example, extra-y is used to list object files that
1138 shall be built, but shall not be linked as part of built-in.a.
1142 header-test-y specifies headers (*.h) in the current directory that
1143 should be compile tested to ensure they are self-contained,
1144 i.e. compilable as standalone units. If CONFIG_HEADER_TEST is enabled,
1145 this builds them as part of extra-y.
1147 header-test-pattern-y
1149 This works as a weaker version of header-test-y, and accepts wildcard
1150 patterns. The typical usage is:
1152 header-test-pattern-y += *.h
1154 This specifies all the files that matches to '*.h' in the current
1155 directory, but the files in 'header-test-' are excluded.
1157 6.7 Commands useful for building a boot image
1158 ---------------------------------------------
1160 Kbuild provides a few macros that are useful when building a
1164 if_changed is the infrastructure used for the following commands.
1168 target: source(s) FORCE
1169 $(call if_changed,ld/objcopy/gzip/...)
1171 When the rule is evaluated, it is checked to see if any files
1172 need an update, or the command line has changed since the last
1173 invocation. The latter will force a rebuild if any options
1174 to the executable have changed.
1175 Any target that utilises if_changed must be listed in $(targets),
1176 otherwise the command line check will fail, and the target will
1178 Assignments to $(targets) are without $(obj)/ prefix.
1179 if_changed may be used in conjunction with custom commands as
1180 defined in 6.8 "Custom kbuild commands".
1182 Note: It is a typical mistake to forget the FORCE prerequisite.
1183 Another common pitfall is that whitespace is sometimes
1184 significant; for instance, the below will fail (note the extra space
1187 target: source(s) FORCE
1189 **WRONG!** $(call if_changed, ld/objcopy/gzip/...)
1192 if_changed should not be used more than once per target.
1193 It stores the executed command in a corresponding .cmd
1195 file and multiple calls would result in overwrites and
1196 unwanted results when the target is up to date and only the
1197 tests on changed commands trigger execution of commands.
1200 Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1204 #arch/x86/boot/Makefile
1205 LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
1206 LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext
1208 targets += setup setup.o bootsect bootsect.o
1209 $(obj)/setup $(obj)/bootsect: %: %.o FORCE
1210 $(call if_changed,ld)
1212 In this example, there are two possible targets, requiring different
1213 options to the linker. The linker options are specified using the
1214 LDFLAGS_$@ syntax - one for each potential target.
1215 $(targets) are assigned all potential targets, by which kbuild knows
1216 the targets and will:
1218 1) check for commandline changes
1219 2) delete target during make clean
1221 The ": %: %.o" part of the prerequisite is a shorthand that
1222 frees us from listing the setup.o and bootsect.o files.
1225 It is a common mistake to forget the "targets :=" assignment,
1226 resulting in the target file being recompiled for no
1230 Copy binary. Uses OBJCOPYFLAGS usually specified in
1231 arch/$(ARCH)/Makefile.
1232 OBJCOPYFLAGS_$@ may be used to set additional options.
1235 Compress target. Use maximum compression to compress target.
1239 #arch/x86/boot/compressed/Makefile
1240 $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE
1241 $(call if_changed,gzip)
1244 Create flattened device tree blob object suitable for linking
1245 into vmlinux. Device tree blobs linked into vmlinux are placed
1246 in an init section in the image. Platform code *must* copy the
1247 blob to non-init memory prior to calling unflatten_device_tree().
1249 To use this command, simply add `*.dtb` into obj-y or targets, or make
1250 some other target depend on `%.dtb`
1252 A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`;
1253 architecture Makefiles do no need to explicitly write out that rule.
1258 DTC_FLAGS ?= -p 1024
1260 6.8 Custom kbuild commands
1261 --------------------------
1263 When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
1264 of a command is normally displayed.
1265 To enable this behaviour for custom commands kbuild requires
1266 two variables to be set::
1268 quiet_cmd_<command> - what shall be echoed
1269 cmd_<command> - the command to execute
1274 quiet_cmd_image = BUILD $@
1275 cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
1276 $(obj)/vmlinux.bin > $@
1279 $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
1280 $(call if_changed,image)
1281 @echo 'Kernel: $@ is ready'
1283 When updating the $(obj)/bzImage target, the line:
1285 BUILD arch/x86/boot/bzImage
1287 will be displayed with "make KBUILD_VERBOSE=0".
1290 --- 6.9 Preprocessing linker scripts
1292 When the vmlinux image is built, the linker script
1293 arch/$(ARCH)/kernel/vmlinux.lds is used.
1294 The script is a preprocessed variant of the file vmlinux.lds.S
1295 located in the same directory.
1296 kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`.
1300 #arch/x86/kernel/Makefile
1301 always := vmlinux.lds
1304 export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
1306 The assignment to $(always) is used to tell kbuild to build the
1308 The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1309 specified options when building the target vmlinux.lds.
1311 When building the `*.lds` target, kbuild uses the variables::
1313 KBUILD_CPPFLAGS : Set in top-level Makefile
1314 cppflags-y : May be set in the kbuild makefile
1315 CPPFLAGS_$(@F) : Target-specific flags.
1316 Note that the full filename is used in this
1319 The kbuild infrastructure for `*lds` files is used in several
1320 architecture-specific files.
1322 6.10 Generic header files
1323 -------------------------
1325 The directory include/asm-generic contains the header files
1326 that may be shared between individual architectures.
1327 The recommended approach how to use a generic header file is
1328 to list the file in the Kbuild file.
1329 See "7.2 generic-y" for further info on syntax etc.
1334 If the file arch/xxx/Makefile.postlink exists, this makefile
1335 will be invoked for post-link objects (vmlinux and modules.ko)
1336 for architectures to run post-link passes on. Must also handle
1339 This pass runs after kallsyms generation. If the architecture
1340 needs to modify symbol locations, rather than manipulate the
1341 kallsyms, it may be easier to add another postlink target for
1342 .tmp_vmlinux? targets to be called from link-vmlinux.sh.
1344 For example, powerpc uses this to check relocation sanity of
1345 the linked vmlinux file.
1347 7 Kbuild syntax for exported headers
1348 ------------------------------------
1350 The kernel includes a set of headers that is exported to userspace.
1351 Many headers can be exported as-is but other headers require a
1352 minimal pre-processing before they are ready for user-space.
1353 The pre-processing does:
1355 - drop kernel-specific annotations
1356 - drop include of compiler.h
1357 - drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`)
1359 All headers under include/uapi/, include/generated/uapi/,
1360 arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/
1363 A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and
1364 arch/<arch>/include/asm/ to list asm files coming from asm-generic.
1365 See subsequent chapter for the syntax of the Kbuild file.
1367 7.1 no-export-headers
1368 ---------------------
1370 no-export-headers is essentially used by include/uapi/linux/Kbuild to
1371 avoid exporting specific headers (e.g. kvm.h) on architectures that do
1372 not support it. It should be avoided as much as possible.
1377 If an architecture uses a verbatim copy of a header from
1378 include/asm-generic then this is listed in the file
1379 arch/$(ARCH)/include/asm/Kbuild like this:
1383 #arch/x86/include/asm/Kbuild
1384 generic-y += termios.h
1387 During the prepare phase of the build a wrapper include
1388 file is generated in the directory::
1390 arch/$(ARCH)/include/generated/asm
1392 When a header is exported where the architecture uses
1393 the generic header a similar wrapper is generated as part
1394 of the set of exported headers in the directory::
1398 The generated wrapper will in both cases look like the following:
1400 Example: termios.h::
1402 #include <asm-generic/termios.h>
1407 If an architecture generates other header files alongside generic-y
1408 wrappers, generated-y specifies them.
1410 This prevents them being treated as stale asm-generic wrappers and
1415 #arch/x86/include/asm/Kbuild
1416 generated-y += syscalls_32.h
1421 mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild
1422 to define the minimum set of ASM headers that all architectures must have.
1424 This works like optional generic-y. If a mandatory header is missing
1425 in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate
1426 a wrapper of the asm-generic one.
1428 The convention is to list one subdir per line and
1429 preferably in alphabetic order.
1434 The top Makefile exports the following variables:
1436 VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
1437 These variables define the current kernel version. A few arch
1438 Makefiles actually use these values directly; they should use
1439 $(KERNELRELEASE) instead.
1441 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
1442 three-part version number, such as "2", "4", and "0". These three
1443 values are always numeric.
1445 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches
1446 or additional patches. It is usually some non-numeric string
1447 such as "-pre4", and is often blank.
1450 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
1451 for constructing installation directory names or showing in
1452 version strings. Some arch Makefiles use it for this purpose.
1455 This variable defines the target architecture, such as "i386",
1456 "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
1457 determine which files to compile.
1459 By default, the top Makefile sets $(ARCH) to be the same as the
1460 host system architecture. For a cross build, a user may
1461 override the value of $(ARCH) on the command line::
1467 This variable defines a place for the arch Makefiles to install
1468 the resident kernel image and System.map file.
1469 Use this for architecture-specific install targets.
1471 INSTALL_MOD_PATH, MODLIB
1472 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
1473 installation. This variable is not defined in the Makefile but
1474 may be passed in by the user if desired.
1476 $(MODLIB) specifies the directory for module installation.
1477 The top Makefile defines $(MODLIB) to
1478 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may
1479 override this value on the command line if desired.
1482 If this variable is specified, it will cause modules to be stripped
1483 after they are installed. If INSTALL_MOD_STRIP is '1', then the
1484 default option --strip-debug will be used. Otherwise, the
1485 INSTALL_MOD_STRIP value will be used as the option(s) to the strip
1492 The kernel Makefiles are designed to be run with GNU Make. The Makefiles
1493 use only the documented features of GNU Make, but they do use many
1496 GNU Make supports elementary list-processing functions. The kernel
1497 Makefiles use a novel style of list building and manipulation with few
1500 GNU Make has two assignment operators, ":=" and "=". ":=" performs
1501 immediate evaluation of the right-hand side and stores an actual string
1502 into the left-hand side. "=" is like a formula definition; it stores the
1503 right-hand side in an unevaluated form and then evaluates this form each
1504 time the left-hand side is used.
1506 There are some cases where "=" is appropriate. Usually, though, ":="
1507 is the right choice.
1512 - Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1513 - Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1514 - Updates by Sam Ravnborg <sam@ravnborg.org>
1515 - Language QA by Jan Engelhardt <jengelh@gmx.de>
1520 - Describe how kbuild supports shipped files with _shipped.
1521 - Generating offset header files.
1522 - Add more variables to section 7?