Loading...
1======================
2Linux Kernel Makefiles
3======================
4
5This document describes the Linux kernel Makefiles.
6
7Overview
8========
9
10The Makefiles have five parts::
11
12 Makefile the top Makefile.
13 .config the kernel configuration file.
14 arch/$(SRCARCH)/Makefile the arch Makefile.
15 scripts/Makefile.* common rules etc. for all kbuild Makefiles.
16 kbuild Makefiles exist in every subdirectory
17
18The top Makefile reads the .config file, which comes from the kernel
19configuration process.
20
21The top Makefile is responsible for building two major products: vmlinux
22(the resident kernel image) and modules (any module files).
23It builds these goals by recursively descending into the subdirectories of
24the kernel source tree.
25
26The list of subdirectories which are visited depends upon the kernel
27configuration. The top Makefile textually includes an arch Makefile
28with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies
29architecture-specific information to the top Makefile.
30
31Each subdirectory has a kbuild Makefile which carries out the commands
32passed down from above. The kbuild Makefile uses information from the
33.config file to construct various file lists used by kbuild to build
34any built-in or modular targets.
35
36scripts/Makefile.* contains all the definitions/rules etc. that
37are used to build the kernel based on the kbuild makefiles.
38
39Who does what
40=============
41
42People have four different relationships with the kernel Makefiles.
43
44*Users* are people who build kernels. These people type commands such as
45``make menuconfig`` or ``make``. They usually do not read or edit
46any kernel Makefiles (or any other source files).
47
48*Normal developers* are people who work on features such as device
49drivers, file systems, and network protocols. These people need to
50maintain the kbuild Makefiles for the subsystem they are
51working on. In order to do this effectively, they need some overall
52knowledge about the kernel Makefiles, plus detailed knowledge about the
53public interface for kbuild.
54
55*Arch developers* are people who work on an entire architecture, such
56as sparc or x86. Arch developers need to know about the arch Makefile
57as well as kbuild Makefiles.
58
59*Kbuild developers* are people who work on the kernel build system itself.
60These people need to know about all aspects of the kernel Makefiles.
61
62This document is aimed towards normal developers and arch developers.
63
64
65The kbuild files
66================
67
68Most Makefiles within the kernel are kbuild Makefiles that use the
69kbuild infrastructure. This chapter introduces the syntax used in the
70kbuild makefiles.
71
72The preferred name for the kbuild files are ``Makefile`` but ``Kbuild`` can
73be used and if both a ``Makefile`` and a ``Kbuild`` file exists, then the ``Kbuild``
74file will be used.
75
76Section `Goal definitions`_ is a quick intro; further chapters provide
77more details, with real examples.
78
79Goal definitions
80----------------
81
82Goal definitions are the main part (heart) of the kbuild Makefile.
83These lines define the files to be built, any special compilation
84options, and any subdirectories to be entered recursively.
85
86The most simple kbuild makefile contains one line:
87
88Example::
89
90 obj-y += foo.o
91
92This tells kbuild that there is one object in that directory, named
93foo.o. foo.o will be built from foo.c or foo.S.
94
95If foo.o shall be built as a module, the variable obj-m is used.
96Therefore the following pattern is often used:
97
98Example::
99
100 obj-$(CONFIG_FOO) += foo.o
101
102$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
103If CONFIG_FOO is neither y nor m, then the file will not be compiled
104nor linked.
105
106Built-in object goals - obj-y
107-----------------------------
108
109The kbuild Makefile specifies object files for vmlinux
110in the $(obj-y) lists. These lists depend on the kernel
111configuration.
112
113Kbuild compiles all the $(obj-y) files. It then calls
114``$(AR) rcSTP`` to merge these files into one built-in.a file.
115This is a thin archive without a symbol table. It will be later
116linked into vmlinux by scripts/link-vmlinux.sh
117
118The order of files in $(obj-y) is significant. Duplicates in
119the lists are allowed: the first instance will be linked into
120built-in.a and succeeding instances will be ignored.
121
122Link order is significant, because certain functions
123(module_init() / __initcall) will be called during boot in the
124order they appear. So keep in mind that changing the link
125order may e.g. change the order in which your SCSI
126controllers are detected, and thus your disks are renumbered.
127
128Example::
129
130 #drivers/isdn/i4l/Makefile
131 # Makefile for the kernel ISDN subsystem and device drivers.
132 # Each configuration option enables a list of files.
133 obj-$(CONFIG_ISDN_I4L) += isdn.o
134 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
135
136Loadable module goals - obj-m
137-----------------------------
138
139$(obj-m) specifies object files which are built as loadable
140kernel modules.
141
142A module may be built from one source file or several source
143files. In the case of one source file, the kbuild makefile
144simply adds the file to $(obj-m).
145
146Example::
147
148 #drivers/isdn/i4l/Makefile
149 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
150
151Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to "m"
152
153If a kernel module is built from several source files, you specify
154that you want to build a module in the same way as above; however,
155kbuild needs to know which object files you want to build your
156module from, so you have to tell it by setting a $(<module_name>-y)
157variable.
158
159Example::
160
161 #drivers/isdn/i4l/Makefile
162 obj-$(CONFIG_ISDN_I4L) += isdn.o
163 isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
164
165In this example, the module name will be isdn.o. Kbuild will
166compile the objects listed in $(isdn-y) and then run
167``$(LD) -r`` on the list of these files to generate isdn.o.
168
169Due to kbuild recognizing $(<module_name>-y) for composite objects,
170you can use the value of a ``CONFIG_`` symbol to optionally include an
171object file as part of a composite object.
172
173Example::
174
175 #fs/ext2/Makefile
176 obj-$(CONFIG_EXT2_FS) += ext2.o
177 ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
178 namei.o super.o symlink.o
179 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
180 xattr_trusted.o
181
182In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
183part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
184evaluates to "y".
185
186Note: Of course, when you are building objects into the kernel,
187the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
188kbuild will build an ext2.o file for you out of the individual
189parts and then link this into built-in.a, as you would expect.
190
191Library file goals - lib-y
192--------------------------
193
194Objects listed with obj-* are used for modules, or
195combined in a built-in.a for that specific directory.
196There is also the possibility to list objects that will
197be included in a library, lib.a.
198All objects listed with lib-y are combined in a single
199library for that directory.
200Objects that are listed in obj-y and additionally listed in
201lib-y will not be included in the library, since they will
202be accessible anyway.
203For consistency, objects listed in lib-m will be included in lib.a.
204
205Note that the same kbuild makefile may list files to be built-in
206and to be part of a library. Therefore the same directory
207may contain both a built-in.a and a lib.a file.
208
209Example::
210
211 #arch/x86/lib/Makefile
212 lib-y := delay.o
213
214This will create a library lib.a based on delay.o. For kbuild to
215actually recognize that there is a lib.a being built, the directory
216shall be listed in libs-y.
217
218See also `List directories to visit when descending`_.
219
220Use of lib-y is normally restricted to ``lib/`` and ``arch/*/lib``.
221
222Descending down in directories
223------------------------------
224
225A Makefile is only responsible for building objects in its own
226directory. Files in subdirectories should be taken care of by
227Makefiles in these subdirs. The build system will automatically
228invoke make recursively in subdirectories, provided you let it know of
229them.
230
231To do so, obj-y and obj-m are used.
232ext2 lives in a separate directory, and the Makefile present in fs/
233tells kbuild to descend down using the following assignment.
234
235Example::
236
237 #fs/Makefile
238 obj-$(CONFIG_EXT2_FS) += ext2/
239
240If CONFIG_EXT2_FS is set to either "y" (built-in) or "m" (modular)
241the corresponding obj- variable will be set, and kbuild will descend
242down in the ext2 directory.
243
244Kbuild uses this information not only to decide that it needs to visit
245the directory, but also to decide whether or not to link objects from
246the directory into vmlinux.
247
248When Kbuild descends into the directory with "y", all built-in objects
249from that directory are combined into the built-in.a, which will be
250eventually linked into vmlinux.
251
252When Kbuild descends into the directory with "m", in contrast, nothing
253from that directory will be linked into vmlinux. If the Makefile in
254that directory specifies obj-y, those objects will be left orphan.
255It is very likely a bug of the Makefile or of dependencies in Kconfig.
256
257Kbuild also supports dedicated syntax, subdir-y and subdir-m, for
258descending into subdirectories. It is a good fit when you know they
259do not contain kernel-space objects at all. A typical usage is to let
260Kbuild descend into subdirectories to build tools.
261
262Examples::
263
264 # scripts/Makefile
265 subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins
266 subdir-$(CONFIG_MODVERSIONS) += genksyms
267 subdir-$(CONFIG_SECURITY_SELINUX) += selinux
268
269Unlike obj-y/m, subdir-y/m does not need the trailing slash since this
270syntax is always used for directories.
271
272It is good practice to use a ``CONFIG_`` variable when assigning directory
273names. This allows kbuild to totally skip the directory if the
274corresponding ``CONFIG_`` option is neither "y" nor "m".
275
276Non-builtin vmlinux targets - extra-y
277-------------------------------------
278
279extra-y specifies targets which are needed for building vmlinux,
280but not combined into built-in.a.
281
282Examples are:
283
2841) vmlinux linker script
285
286 The linker script for vmlinux is located at
287 arch/$(SRCARCH)/kernel/vmlinux.lds
288
289Example::
290
291 # arch/x86/kernel/Makefile
292 extra-y += vmlinux.lds
293
294$(extra-y) should only contain targets needed for vmlinux.
295
296Kbuild skips extra-y when vmlinux is apparently not a final goal.
297(e.g. ``make modules``, or building external modules)
298
299If you intend to build targets unconditionally, always-y (explained
300in the next section) is the correct syntax to use.
301
302Always built goals - always-y
303-----------------------------
304
305always-y specifies targets which are literally always built when
306Kbuild visits the Makefile.
307
308Example::
309
310 # ./Kbuild
311 offsets-file := include/generated/asm-offsets.h
312 always-y += $(offsets-file)
313
314Compilation flags
315-----------------
316
317ccflags-y, asflags-y and ldflags-y
318 These three flags apply only to the kbuild makefile in which they
319 are assigned. They are used for all the normal cc, as and ld
320 invocations happening during a recursive build.
321 Note: Flags with the same behaviour were previously named:
322 EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
323 They are still supported but their usage is deprecated.
324
325 ccflags-y specifies options for compiling with $(CC).
326
327 Example::
328
329 # drivers/acpi/acpica/Makefile
330 ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA
331 ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
332
333 This variable is necessary because the top Makefile owns the
334 variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
335 entire tree.
336
337 asflags-y specifies assembler options.
338
339 Example::
340
341 #arch/sparc/kernel/Makefile
342 asflags-y := -ansi
343
344 ldflags-y specifies options for linking with $(LD).
345
346 Example::
347
348 #arch/cris/boot/compressed/Makefile
349 ldflags-y += -T $(src)/decompress_$(arch-y).lds
350
351subdir-ccflags-y, subdir-asflags-y
352 The two flags listed above are similar to ccflags-y and asflags-y.
353 The difference is that the subdir- variants have effect for the kbuild
354 file where they are present and all subdirectories.
355 Options specified using subdir-* are added to the commandline before
356 the options specified using the non-subdir variants.
357
358 Example::
359
360 subdir-ccflags-y := -Werror
361
362ccflags-remove-y, asflags-remove-y
363 These flags are used to remove particular flags for the compiler,
364 assembler invocations.
365
366 Example::
367
368 ccflags-remove-$(CONFIG_MCOUNT) += -pg
369
370CFLAGS_$@, AFLAGS_$@
371 CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
372 kbuild makefile.
373
374 $(CFLAGS_$@) specifies per-file options for $(CC). The $@
375 part has a literal value which specifies the file that it is for.
376
377 CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@
378 can re-add compiler flags that were removed by ccflags-remove-y.
379
380 Example::
381
382 # drivers/scsi/Makefile
383 CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
384
385 This line specify compilation flags for aha152x.o.
386
387 $(AFLAGS_$@) is a similar feature for source files in assembly
388 languages.
389
390 AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@
391 can re-add assembler flags that were removed by asflags-remove-y.
392
393 Example::
394
395 # arch/arm/kernel/Makefile
396 AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET)
397 AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
398 AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
399
400Dependency tracking
401-------------------
402
403Kbuild tracks dependencies on the following:
404
4051) All prerequisite files (both ``*.c`` and ``*.h``)
4062) ``CONFIG_`` options used in all prerequisite files
4073) Command-line used to compile target
408
409Thus, if you change an option to $(CC) all affected files will
410be re-compiled.
411
412Custom Rules
413------------
414
415Custom rules are used when the kbuild infrastructure does
416not provide the required support. A typical example is
417header files generated during the build process.
418Another example are the architecture-specific Makefiles which
419need custom rules to prepare boot images etc.
420
421Custom rules are written as normal Make rules.
422Kbuild is not executing in the directory where the Makefile is
423located, so all custom rules shall use a relative
424path to prerequisite files and target files.
425
426Two variables are used when defining custom rules:
427
428$(src)
429 $(src) is the directory where the Makefile is located. Always use $(src) when
430 referring to files located in the src tree.
431
432$(obj)
433 $(obj) is the directory where the target is saved. Always use $(obj) when
434 referring to generated files. Use $(obj) for pattern rules that need to work
435 for both generated files and real sources (VPATH will help to find the
436 prerequisites not only in the object tree but also in the source tree).
437
438 Example::
439
440 #drivers/scsi/Makefile
441 $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
442 $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
443
444 This is a custom rule, following the normal syntax
445 required by make.
446
447 The target file depends on two prerequisite files. References
448 to the target file are prefixed with $(obj), references
449 to prerequisites are referenced with $(src) (because they are not
450 generated files).
451
452$(srcroot)
453 $(srcroot) refers to the root of the source you are building, which can be
454 either the kernel source or the external modules source, depending on whether
455 KBUILD_EXTMOD is set. This can be either a relative or an absolute path, but
456 if KBUILD_ABS_SRCTREE=1 is set, it is always an absolute path.
457
458$(srctree)
459 $(srctree) refers to the root of the kernel source tree. When building the
460 kernel, this is the same as $(srcroot).
461
462$(objtree)
463 $(objtree) refers to the root of the kernel object tree. It is ``.`` when
464 building the kernel, but it is different when building external modules.
465
466$(kecho)
467 echoing information to user in a rule is often a good practice
468 but when execution ``make -s`` one does not expect to see any output
469 except for warnings/errors.
470 To support this kbuild defines $(kecho) which will echo out the
471 text following $(kecho) to stdout except if ``make -s`` is used.
472
473 Example::
474
475 # arch/arm/Makefile
476 $(BOOT_TARGETS): vmlinux
477 $(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@
478 @$(kecho) ' Kernel: $(boot)/$@ is ready'
479
480 When kbuild is executing with KBUILD_VERBOSE unset, then only a shorthand
481 of a command is normally displayed.
482 To enable this behaviour for custom commands kbuild requires
483 two variables to be set::
484
485 quiet_cmd_<command> - what shall be echoed
486 cmd_<command> - the command to execute
487
488 Example::
489
490 # lib/Makefile
491 quiet_cmd_crc32 = GEN $@
492 cmd_crc32 = $< > $@
493
494 $(obj)/crc32table.h: $(obj)/gen_crc32table
495 $(call cmd,crc32)
496
497 When updating the $(obj)/crc32table.h target, the line::
498
499 GEN lib/crc32table.h
500
501 will be displayed with ``make KBUILD_VERBOSE=``.
502
503Command change detection
504------------------------
505
506When the rule is evaluated, timestamps are compared between the target
507and its prerequisite files. GNU Make updates the target when any of the
508prerequisites is newer than that.
509
510The target should be rebuilt also when the command line has changed
511since the last invocation. This is not supported by Make itself, so
512Kbuild achieves this by a kind of meta-programming.
513
514if_changed is the macro used for this purpose, in the following form::
515
516 quiet_cmd_<command> = ...
517 cmd_<command> = ...
518
519 <target>: <source(s)> FORCE
520 $(call if_changed,<command>)
521
522Any target that utilizes if_changed must be listed in $(targets),
523otherwise the command line check will fail, and the target will
524always be built.
525
526If the target is already listed in the recognized syntax such as
527obj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuild
528automatically adds it to $(targets). Otherwise, the target must be
529explicitly added to $(targets).
530
531Assignments to $(targets) are without $(obj)/ prefix. if_changed may be
532used in conjunction with custom rules as defined in `Custom Rules`_.
533
534Note: It is a typical mistake to forget the FORCE prerequisite.
535Another common pitfall is that whitespace is sometimes significant; for
536instance, the below will fail (note the extra space after the comma)::
537
538 target: source(s) FORCE
539
540**WRONG!** $(call if_changed, objcopy)
541
542Note:
543 if_changed should not be used more than once per target.
544 It stores the executed command in a corresponding .cmd
545 file and multiple calls would result in overwrites and
546 unwanted results when the target is up to date and only the
547 tests on changed commands trigger execution of commands.
548
549$(CC) support functions
550-----------------------
551
552The kernel may be built with several different versions of
553$(CC), each supporting a unique set of features and options.
554kbuild provides basic support to check for valid options for $(CC).
555$(CC) is usually the gcc compiler, but other alternatives are
556available.
557
558as-option
559 as-option is used to check if $(CC) -- when used to compile
560 assembler (``*.S``) files -- supports the given option. An optional
561 second option may be specified if the first option is not supported.
562
563 Example::
564
565 #arch/sh/Makefile
566 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
567
568 In the above example, cflags-y will be assigned the option
569 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
570 The second argument is optional, and if supplied will be used
571 if first argument is not supported.
572
573as-instr
574 as-instr checks if the assembler reports a specific instruction
575 and then outputs either option1 or option2
576 C escapes are supported in the test instruction
577 Note: as-instr-option uses KBUILD_AFLAGS for assembler options
578
579cc-option
580 cc-option is used to check if $(CC) supports a given option, and if
581 not supported to use an optional second option.
582
583 Example::
584
585 #arch/x86/Makefile
586 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
587
588 In the above example, cflags-y will be assigned the option
589 -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
590 The second argument to cc-option is optional, and if omitted,
591 cflags-y will be assigned no value if first option is not supported.
592 Note: cc-option uses KBUILD_CFLAGS for $(CC) options
593
594cc-option-yn
595 cc-option-yn is used to check if $(CC) supports a given option
596 and return "y" if supported, otherwise "n".
597
598 Example::
599
600 #arch/ppc/Makefile
601 biarch := $(call cc-option-yn, -m32)
602 aflags-$(biarch) += -a32
603 cflags-$(biarch) += -m32
604
605 In the above example, $(biarch) is set to y if $(CC) supports the -m32
606 option. When $(biarch) equals "y", the expanded variables $(aflags-y)
607 and $(cflags-y) will be assigned the values -a32 and -m32,
608 respectively.
609
610 Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
611
612cc-disable-warning
613 cc-disable-warning checks if $(CC) supports a given warning and returns
614 the commandline switch to disable it. This special function is needed,
615 because gcc 4.4 and later accept any unknown -Wno-* option and only
616 warn about it if there is another warning in the source file.
617
618 Example::
619
620 KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
621
622 In the above example, -Wno-unused-but-set-variable will be added to
623 KBUILD_CFLAGS only if $(CC) really accepts it.
624
625gcc-min-version
626 gcc-min-version tests if the value of $(CONFIG_GCC_VERSION) is greater than
627 or equal to the provided value and evaluates to y if so.
628
629 Example::
630
631 cflags-$(call gcc-min-version, 70100) := -foo
632
633 In this example, cflags-y will be assigned the value -foo if $(CC) is gcc and
634 $(CONFIG_GCC_VERSION) is >= 7.1.
635
636clang-min-version
637 clang-min-version tests if the value of $(CONFIG_CLANG_VERSION) is greater
638 than or equal to the provided value and evaluates to y if so.
639
640 Example::
641
642 cflags-$(call clang-min-version, 110000) := -foo
643
644 In this example, cflags-y will be assigned the value -foo if $(CC) is clang
645 and $(CONFIG_CLANG_VERSION) is >= 11.0.0.
646
647cc-cross-prefix
648 cc-cross-prefix is used to check if there exists a $(CC) in path with
649 one of the listed prefixes. The first prefix where there exist a
650 prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
651 then nothing is returned.
652
653 Additional prefixes are separated by a single space in the
654 call of cc-cross-prefix.
655
656 This functionality is useful for architecture Makefiles that try
657 to set CROSS_COMPILE to well-known values but may have several
658 values to select between.
659
660 It is recommended only to try to set CROSS_COMPILE if it is a cross
661 build (host arch is different from target arch). And if CROSS_COMPILE
662 is already set then leave it with the old value.
663
664 Example::
665
666 #arch/m68k/Makefile
667 ifneq ($(SUBARCH),$(ARCH))
668 ifeq ($(CROSS_COMPILE),)
669 CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
670 endif
671 endif
672
673$(LD) support functions
674-----------------------
675
676ld-option
677 ld-option is used to check if $(LD) supports the supplied option.
678 ld-option takes two options as arguments.
679
680 The second argument is an optional option that can be used if the
681 first option is not supported by $(LD).
682
683 Example::
684
685 #Makefile
686 LDFLAGS_vmlinux += $(call ld-option, -X)
687
688Script invocation
689-----------------
690
691Make rules may invoke scripts to build the kernel. The rules shall
692always provide the appropriate interpreter to execute the script. They
693shall not rely on the execute bits being set, and shall not invoke the
694script directly. For the convenience of manual script invocation, such
695as invoking ./scripts/checkpatch.pl, it is recommended to set execute
696bits on the scripts nonetheless.
697
698Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL),
699and $(PYTHON3) to refer to interpreters for the respective
700scripts.
701
702Example::
703
704 #Makefile
705 cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \
706 $(KERNELRELEASE)
707
708Host Program support
709====================
710
711Kbuild supports building executables on the host for use during the
712compilation stage.
713
714Two steps are required in order to use a host executable.
715
716The first step is to tell kbuild that a host program exists. This is
717done utilising the variable ``hostprogs``.
718
719The second step is to add an explicit dependency to the executable.
720This can be done in two ways. Either add the dependency in a rule,
721or utilise the variable ``always-y``.
722Both possibilities are described in the following.
723
724Simple Host Program
725-------------------
726
727In some cases there is a need to compile and run a program on the
728computer where the build is running.
729
730The following line tells kbuild that the program bin2hex shall be
731built on the build host.
732
733Example::
734
735 hostprogs := bin2hex
736
737Kbuild assumes in the above example that bin2hex is made from a single
738c-source file named bin2hex.c located in the same directory as
739the Makefile.
740
741Composite Host Programs
742-----------------------
743
744Host programs can be made up based on composite objects.
745The syntax used to define composite objects for host programs is
746similar to the syntax used for kernel objects.
747$(<executable>-objs) lists all objects used to link the final
748executable.
749
750Example::
751
752 #scripts/lxdialog/Makefile
753 hostprogs := lxdialog
754 lxdialog-objs := checklist.o lxdialog.o
755
756Objects with extension .o are compiled from the corresponding .c
757files. In the above example, checklist.c is compiled to checklist.o
758and lxdialog.c is compiled to lxdialog.o.
759
760Finally, the two .o files are linked to the executable, lxdialog.
761Note: The syntax <executable>-y is not permitted for host-programs.
762
763Using C++ for host programs
764---------------------------
765
766kbuild offers support for host programs written in C++. This was
767introduced solely to support kconfig, and is not recommended
768for general use.
769
770Example::
771
772 #scripts/kconfig/Makefile
773 hostprogs := qconf
774 qconf-cxxobjs := qconf.o
775
776In the example above the executable is composed of the C++ file
777qconf.cc - identified by $(qconf-cxxobjs).
778
779If qconf is composed of a mixture of .c and .cc files, then an
780additional line can be used to identify this.
781
782Example::
783
784 #scripts/kconfig/Makefile
785 hostprogs := qconf
786 qconf-cxxobjs := qconf.o
787 qconf-objs := check.o
788
789Using Rust for host programs
790----------------------------
791
792Kbuild offers support for host programs written in Rust. However,
793since a Rust toolchain is not mandatory for kernel compilation,
794it may only be used in scenarios where Rust is required to be
795available (e.g. when ``CONFIG_RUST`` is enabled).
796
797Example::
798
799 hostprogs := target
800 target-rust := y
801
802Kbuild will compile ``target`` using ``target.rs`` as the crate root,
803located in the same directory as the ``Makefile``. The crate may
804consist of several source files (see ``samples/rust/hostprogs``).
805
806Controlling compiler options for host programs
807----------------------------------------------
808
809When compiling host programs, it is possible to set specific flags.
810The programs will always be compiled utilising $(HOSTCC) passed
811the options specified in $(KBUILD_HOSTCFLAGS).
812
813To set flags that will take effect for all host programs created
814in that Makefile, use the variable HOST_EXTRACFLAGS.
815
816Example::
817
818 #scripts/lxdialog/Makefile
819 HOST_EXTRACFLAGS += -I/usr/include/ncurses
820
821To set specific flags for a single file the following construction
822is used:
823
824Example::
825
826 #arch/ppc64/boot/Makefile
827 HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
828
829It is also possible to specify additional options to the linker.
830
831Example::
832
833 #scripts/kconfig/Makefile
834 HOSTLDLIBS_qconf := -L$(QTDIR)/lib
835
836When linking qconf, it will be passed the extra option
837``-L$(QTDIR)/lib``.
838
839When host programs are actually built
840-------------------------------------
841
842Kbuild will only build host-programs when they are referenced
843as a prerequisite.
844
845This is possible in two ways:
846
847(1) List the prerequisite explicitly in a custom rule.
848
849 Example::
850
851 #drivers/pci/Makefile
852 hostprogs := gen-devlist
853 $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
854 ( cd $(obj); ./gen-devlist ) < $<
855
856 The target $(obj)/devlist.h will not be built before
857 $(obj)/gen-devlist is updated. Note that references to
858 the host programs in custom rules must be prefixed with $(obj).
859
860(2) Use always-y
861
862 When there is no suitable custom rule, and the host program
863 shall be built when a makefile is entered, the always-y
864 variable shall be used.
865
866 Example::
867
868 #scripts/lxdialog/Makefile
869 hostprogs := lxdialog
870 always-y := $(hostprogs)
871
872 Kbuild provides the following shorthand for this::
873
874 hostprogs-always-y := lxdialog
875
876 This will tell kbuild to build lxdialog even if not referenced in
877 any rule.
878
879Userspace Program support
880=========================
881
882Just like host programs, Kbuild also supports building userspace executables
883for the target architecture (i.e. the same architecture as you are building
884the kernel for).
885
886The syntax is quite similar. The difference is to use ``userprogs`` instead of
887``hostprogs``.
888
889Simple Userspace Program
890------------------------
891
892The following line tells kbuild that the program bpf-direct shall be
893built for the target architecture.
894
895Example::
896
897 userprogs := bpf-direct
898
899Kbuild assumes in the above example that bpf-direct is made from a
900single C source file named bpf-direct.c located in the same directory
901as the Makefile.
902
903Composite Userspace Programs
904----------------------------
905
906Userspace programs can be made up based on composite objects.
907The syntax used to define composite objects for userspace programs is
908similar to the syntax used for kernel objects.
909$(<executable>-objs) lists all objects used to link the final
910executable.
911
912Example::
913
914 #samples/seccomp/Makefile
915 userprogs := bpf-fancy
916 bpf-fancy-objs := bpf-fancy.o bpf-helper.o
917
918Objects with extension .o are compiled from the corresponding .c
919files. In the above example, bpf-fancy.c is compiled to bpf-fancy.o
920and bpf-helper.c is compiled to bpf-helper.o.
921
922Finally, the two .o files are linked to the executable, bpf-fancy.
923Note: The syntax <executable>-y is not permitted for userspace programs.
924
925Controlling compiler options for userspace programs
926---------------------------------------------------
927
928When compiling userspace programs, it is possible to set specific flags.
929The programs will always be compiled utilising $(CC) passed
930the options specified in $(KBUILD_USERCFLAGS).
931
932To set flags that will take effect for all userspace programs created
933in that Makefile, use the variable userccflags.
934
935Example::
936
937 # samples/seccomp/Makefile
938 userccflags += -I usr/include
939
940To set specific flags for a single file the following construction
941is used:
942
943Example::
944
945 bpf-helper-userccflags += -I user/include
946
947It is also possible to specify additional options to the linker.
948
949Example::
950
951 # net/bpfilter/Makefile
952 bpfilter_umh-userldflags += -static
953
954To specify libraries linked to a userspace program, you can use
955``<executable>-userldlibs``. The ``userldlibs`` syntax specifies libraries
956linked to all userspace programs created in the current Makefile.
957
958When linking bpfilter_umh, it will be passed the extra option -static.
959
960From command line, :ref:`USERCFLAGS and USERLDFLAGS <userkbuildflags>` will also be used.
961
962When userspace programs are actually built
963------------------------------------------
964
965Kbuild builds userspace programs only when told to do so.
966There are two ways to do this.
967
968(1) Add it as the prerequisite of another file
969
970 Example::
971
972 #net/bpfilter/Makefile
973 userprogs := bpfilter_umh
974 $(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh
975
976 $(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o
977
978(2) Use always-y
979
980 Example::
981
982 userprogs := binderfs_example
983 always-y := $(userprogs)
984
985 Kbuild provides the following shorthand for this::
986
987 userprogs-always-y := binderfs_example
988
989 This will tell Kbuild to build binderfs_example when it visits this
990 Makefile.
991
992Kbuild clean infrastructure
993===========================
994
995``make clean`` deletes most generated files in the obj tree where the kernel
996is compiled. This includes generated files such as host programs.
997Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m),
998$(always-), $(extra-y), $(extra-) and $(targets). They are all deleted
999during ``make clean``. Files matching the patterns ``*.[oas]``, ``*.ko``, plus
1000some additional files generated by kbuild are deleted all over the kernel
1001source tree when ``make clean`` is executed.
1002
1003Additional files or directories can be specified in kbuild makefiles by use of
1004$(clean-files).
1005
1006Example::
1007
1008 #lib/Makefile
1009 clean-files := crc32table.h
1010
1011When executing ``make clean``, the file ``crc32table.h`` will be deleted.
1012Kbuild will assume files to be in the same relative directory as the
1013Makefile.
1014
1015To exclude certain files or directories from make clean, use the
1016$(no-clean-files) variable.
1017
1018Usually kbuild descends down in subdirectories due to ``obj-* := dir/``,
1019but in the architecture makefiles where the kbuild infrastructure
1020is not sufficient this sometimes needs to be explicit.
1021
1022Example::
1023
1024 #arch/x86/boot/Makefile
1025 subdir- := compressed
1026
1027The above assignment instructs kbuild to descend down in the
1028directory compressed/ when ``make clean`` is executed.
1029
1030Note 1: arch/$(SRCARCH)/Makefile cannot use ``subdir-``, because that file is
1031included in the top level makefile. Instead, arch/$(SRCARCH)/Kbuild can use
1032``subdir-``.
1033
1034Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
1035be visited during ``make clean``.
1036
1037Architecture Makefiles
1038======================
1039
1040The top level Makefile sets up the environment and does the preparation,
1041before starting to descend down in the individual directories.
1042
1043The top level makefile contains the generic part, whereas
1044arch/$(SRCARCH)/Makefile contains what is required to set up kbuild
1045for said architecture.
1046
1047To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines
1048a few targets.
1049
1050When kbuild executes, the following steps are followed (roughly):
1051
10521) Configuration of the kernel => produce .config
1053
10542) Store kernel version in include/linux/version.h
1055
10563) Updating all other prerequisites to the target prepare:
1057
1058 - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile
1059
10604) Recursively descend down in all directories listed in
1061 init-* core* drivers-* net-* libs-* and build all targets.
1062
1063 - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile.
1064
10655) All object files are then linked and the resulting file vmlinux is
1066 located at the root of the obj tree.
1067 The very first objects linked are listed in scripts/head-object-list.txt.
1068
10696) Finally, the architecture-specific part does any required post processing
1070 and builds the final bootimage.
1071
1072 - This includes building boot records
1073 - Preparing initrd images and the like
1074
1075Set variables to tweak the build to the architecture
1076----------------------------------------------------
1077
1078KBUILD_LDFLAGS
1079 Generic $(LD) options
1080
1081 Flags used for all invocations of the linker.
1082 Often specifying the emulation is sufficient.
1083
1084 Example::
1085
1086 #arch/s390/Makefile
1087 KBUILD_LDFLAGS := -m elf_s390
1088
1089 Note: ldflags-y can be used to further customise
1090 the flags used. See `Non-builtin vmlinux targets - extra-y`_.
1091
1092LDFLAGS_vmlinux
1093 Options for $(LD) when linking vmlinux
1094
1095 LDFLAGS_vmlinux is used to specify additional flags to pass to
1096 the linker when linking the final vmlinux image.
1097
1098 LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
1099
1100 Example::
1101
1102 #arch/x86/Makefile
1103 LDFLAGS_vmlinux := -e stext
1104
1105OBJCOPYFLAGS
1106 objcopy flags
1107
1108 When $(call if_changed,objcopy) is used to translate a .o file,
1109 the flags specified in OBJCOPYFLAGS will be used.
1110
1111 $(call if_changed,objcopy) is often used to generate raw binaries on
1112 vmlinux.
1113
1114 Example::
1115
1116 #arch/s390/Makefile
1117 OBJCOPYFLAGS := -O binary
1118
1119 #arch/s390/boot/Makefile
1120 $(obj)/image: vmlinux FORCE
1121 $(call if_changed,objcopy)
1122
1123 In this example, the binary $(obj)/image is a binary version of
1124 vmlinux. The usage of $(call if_changed,xxx) will be described later.
1125
1126KBUILD_AFLAGS
1127 Assembler flags
1128
1129 Default value - see top level Makefile.
1130
1131 Append or modify as required per architecture.
1132
1133 Example::
1134
1135 #arch/sparc64/Makefile
1136 KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
1137
1138KBUILD_CFLAGS
1139 $(CC) compiler flags
1140
1141 Default value - see top level Makefile.
1142
1143 Append or modify as required per architecture.
1144
1145 Often, the KBUILD_CFLAGS variable depends on the configuration.
1146
1147 Example::
1148
1149 #arch/x86/boot/compressed/Makefile
1150 cflags-$(CONFIG_X86_32) := -march=i386
1151 cflags-$(CONFIG_X86_64) := -mcmodel=small
1152 KBUILD_CFLAGS += $(cflags-y)
1153
1154 Many arch Makefiles dynamically run the target C compiler to
1155 probe supported options::
1156
1157 #arch/x86/Makefile
1158
1159 ...
1160 cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\
1161 -march=pentium2,-march=i686)
1162 ...
1163 # Disable unit-at-a-time mode ...
1164 KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
1165 ...
1166
1167
1168 The first example utilises the trick that a config option expands
1169 to "y" when selected.
1170
1171KBUILD_RUSTFLAGS
1172 $(RUSTC) compiler flags
1173
1174 Default value - see top level Makefile.
1175
1176 Append or modify as required per architecture.
1177
1178 Often, the KBUILD_RUSTFLAGS variable depends on the configuration.
1179
1180 Note that target specification file generation (for ``--target``)
1181 is handled in ``scripts/generate_rust_target.rs``.
1182
1183KBUILD_AFLAGS_KERNEL
1184 Assembler options specific for built-in
1185
1186 $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
1187 resident kernel code.
1188
1189KBUILD_AFLAGS_MODULE
1190 Assembler options specific for modules
1191
1192 $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
1193 are used for assembler.
1194
1195 From commandline AFLAGS_MODULE shall be used (see kbuild.rst).
1196
1197KBUILD_CFLAGS_KERNEL
1198 $(CC) options specific for built-in
1199
1200 $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
1201 resident kernel code.
1202
1203KBUILD_CFLAGS_MODULE
1204 Options for $(CC) when building modules
1205
1206 $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
1207 are used for $(CC).
1208
1209 From commandline CFLAGS_MODULE shall be used (see kbuild.rst).
1210
1211KBUILD_RUSTFLAGS_KERNEL
1212 $(RUSTC) options specific for built-in
1213
1214 $(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to
1215 compile resident kernel code.
1216
1217KBUILD_RUSTFLAGS_MODULE
1218 Options for $(RUSTC) when building modules
1219
1220 $(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that
1221 are used for $(RUSTC).
1222
1223 From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst).
1224
1225KBUILD_LDFLAGS_MODULE
1226 Options for $(LD) when linking modules
1227
1228 $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
1229 used when linking modules. This is often a linker script.
1230
1231 From commandline LDFLAGS_MODULE shall be used (see kbuild.rst).
1232
1233KBUILD_LDS
1234 The linker script with full path. Assigned by the top-level Makefile.
1235
1236KBUILD_VMLINUX_OBJS
1237 All object files for vmlinux. They are linked to vmlinux in the same
1238 order as listed in KBUILD_VMLINUX_OBJS.
1239
1240 The objects listed in scripts/head-object-list.txt are exceptions;
1241 they are placed before the other objects.
1242
1243KBUILD_VMLINUX_LIBS
1244 All .a ``lib`` files for vmlinux. KBUILD_VMLINUX_OBJS and
1245 KBUILD_VMLINUX_LIBS together specify all the object files used to
1246 link vmlinux.
1247
1248Add prerequisites to archheaders
1249--------------------------------
1250
1251The archheaders: rule is used to generate header files that
1252may be installed into user space by ``make header_install``.
1253
1254It is run before ``make archprepare`` when run on the
1255architecture itself.
1256
1257Add prerequisites to archprepare
1258--------------------------------
1259
1260The archprepare: rule is used to list prerequisites that need to be
1261built before starting to descend down in the subdirectories.
1262
1263This is usually used for header files containing assembler constants.
1264
1265Example::
1266
1267 #arch/arm/Makefile
1268 archprepare: maketools
1269
1270In this example, the file target maketools will be processed
1271before descending down in the subdirectories.
1272
1273See also chapter XXX-TODO that describes how kbuild supports
1274generating offset header files.
1275
1276List directories to visit when descending
1277-----------------------------------------
1278
1279An arch Makefile cooperates with the top Makefile to define variables
1280which specify how to build the vmlinux file. Note that there is no
1281corresponding arch-specific section for modules; the module-building
1282machinery is all architecture-independent.
1283
1284core-y, libs-y, drivers-y
1285 $(libs-y) lists directories where a lib.a archive can be located.
1286
1287 The rest list directories where a built-in.a object file can be
1288 located.
1289
1290 Then the rest follows in this order:
1291
1292 $(core-y), $(libs-y), $(drivers-y)
1293
1294 The top level Makefile defines values for all generic directories,
1295 and arch/$(SRCARCH)/Makefile only adds architecture-specific
1296 directories.
1297
1298 Example::
1299
1300 # arch/sparc/Makefile
1301 core-y += arch/sparc/
1302
1303 libs-y += arch/sparc/prom/
1304 libs-y += arch/sparc/lib/
1305
1306 drivers-$(CONFIG_PM) += arch/sparc/power/
1307
1308Architecture-specific boot images
1309---------------------------------
1310
1311An arch Makefile specifies goals that take the vmlinux file, compress
1312it, wrap it in bootstrapping code, and copy the resulting files
1313somewhere. This includes various kinds of installation commands.
1314The actual goals are not standardized across architectures.
1315
1316It is common to locate any additional processing in a boot/
1317directory below arch/$(SRCARCH)/.
1318
1319Kbuild does not provide any smart way to support building a
1320target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall
1321call make manually to build a target in boot/.
1322
1323The recommended approach is to include shortcuts in
1324arch/$(SRCARCH)/Makefile, and use the full path when calling down
1325into the arch/$(SRCARCH)/boot/Makefile.
1326
1327Example::
1328
1329 #arch/x86/Makefile
1330 boot := arch/x86/boot
1331 bzImage: vmlinux
1332 $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
1333
1334``$(Q)$(MAKE) $(build)=<dir>`` is the recommended way to invoke
1335make in a subdirectory.
1336
1337There are no rules for naming architecture-specific targets,
1338but executing ``make help`` will list all relevant targets.
1339To support this, $(archhelp) must be defined.
1340
1341Example::
1342
1343 #arch/x86/Makefile
1344 define archhelp
1345 echo '* bzImage - Compressed kernel image (arch/x86/boot/bzImage)'
1346 endif
1347
1348When make is executed without arguments, the first goal encountered
1349will be built. In the top level Makefile the first goal present
1350is all:.
1351
1352An architecture shall always, per default, build a bootable image.
1353In ``make help``, the default goal is highlighted with a ``*``.
1354
1355Add a new prerequisite to all: to select a default goal different
1356from vmlinux.
1357
1358Example::
1359
1360 #arch/x86/Makefile
1361 all: bzImage
1362
1363When ``make`` is executed without arguments, bzImage will be built.
1364
1365Commands useful for building a boot image
1366-----------------------------------------
1367
1368Kbuild provides a few macros that are useful when building a
1369boot image.
1370
1371ld
1372 Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1373
1374 Example::
1375
1376 #arch/x86/boot/Makefile
1377 LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
1378 LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext
1379
1380 targets += setup setup.o bootsect bootsect.o
1381 $(obj)/setup $(obj)/bootsect: %: %.o FORCE
1382 $(call if_changed,ld)
1383
1384 In this example, there are two possible targets, requiring different
1385 options to the linker. The linker options are specified using the
1386 LDFLAGS_$@ syntax - one for each potential target.
1387
1388 $(targets) are assigned all potential targets, by which kbuild knows
1389 the targets and will:
1390
1391 1) check for commandline changes
1392 2) delete target during make clean
1393
1394 The ``: %: %.o`` part of the prerequisite is a shorthand that
1395 frees us from listing the setup.o and bootsect.o files.
1396
1397 Note:
1398 It is a common mistake to forget the ``targets :=`` assignment,
1399 resulting in the target file being recompiled for no
1400 obvious reason.
1401
1402objcopy
1403 Copy binary. Uses OBJCOPYFLAGS usually specified in
1404 arch/$(SRCARCH)/Makefile.
1405
1406 OBJCOPYFLAGS_$@ may be used to set additional options.
1407
1408gzip
1409 Compress target. Use maximum compression to compress target.
1410
1411 Example::
1412
1413 #arch/x86/boot/compressed/Makefile
1414 $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE
1415 $(call if_changed,gzip)
1416
1417dtc
1418 Create flattened device tree blob object suitable for linking
1419 into vmlinux. Device tree blobs linked into vmlinux are placed
1420 in an init section in the image. Platform code *must* copy the
1421 blob to non-init memory prior to calling unflatten_device_tree().
1422
1423 To use this command, simply add ``*.dtb`` into obj-y or targets, or make
1424 some other target depend on ``%.dtb``
1425
1426 A central rule exists to create ``$(obj)/%.dtb`` from ``$(src)/%.dts``;
1427 architecture Makefiles do no need to explicitly write out that rule.
1428
1429 Example::
1430
1431 targets += $(dtb-y)
1432 DTC_FLAGS ?= -p 1024
1433
1434Preprocessing linker scripts
1435----------------------------
1436
1437When the vmlinux image is built, the linker script
1438arch/$(SRCARCH)/kernel/vmlinux.lds is used.
1439
1440The script is a preprocessed variant of the file vmlinux.lds.S
1441located in the same directory.
1442
1443kbuild knows .lds files and includes a rule ``*lds.S`` -> ``*lds``.
1444
1445Example::
1446
1447 #arch/x86/kernel/Makefile
1448 extra-y := vmlinux.lds
1449
1450The assignment to extra-y is used to tell kbuild to build the
1451target vmlinux.lds.
1452
1453The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1454specified options when building the target vmlinux.lds.
1455
1456When building the ``*.lds`` target, kbuild uses the variables::
1457
1458 KBUILD_CPPFLAGS : Set in top-level Makefile
1459 cppflags-y : May be set in the kbuild makefile
1460 CPPFLAGS_$(@F) : Target-specific flags.
1461 Note that the full filename is used in this
1462 assignment.
1463
1464The kbuild infrastructure for ``*lds`` files is used in several
1465architecture-specific files.
1466
1467Generic header files
1468--------------------
1469
1470The directory include/asm-generic contains the header files
1471that may be shared between individual architectures.
1472
1473The recommended approach how to use a generic header file is
1474to list the file in the Kbuild file.
1475
1476See `generic-y`_ for further info on syntax etc.
1477
1478Post-link pass
1479--------------
1480
1481If the file arch/xxx/Makefile.postlink exists, this makefile
1482will be invoked for post-link objects (vmlinux and modules.ko)
1483for architectures to run post-link passes on. Must also handle
1484the clean target.
1485
1486This pass runs after kallsyms generation. If the architecture
1487needs to modify symbol locations, rather than manipulate the
1488kallsyms, it may be easier to add another postlink target for
1489.tmp_vmlinux? targets to be called from link-vmlinux.sh.
1490
1491For example, powerpc uses this to check relocation sanity of
1492the linked vmlinux file.
1493
1494Kbuild syntax for exported headers
1495==================================
1496
1497The kernel includes a set of headers that is exported to userspace.
1498Many headers can be exported as-is but other headers require a
1499minimal pre-processing before they are ready for user-space.
1500
1501The pre-processing does:
1502
1503- drop kernel-specific annotations
1504- drop include of compiler.h
1505- drop all sections that are kernel internal (guarded by ``ifdef __KERNEL__``)
1506
1507All headers under include/uapi/, include/generated/uapi/,
1508arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/
1509are exported.
1510
1511A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and
1512arch/<arch>/include/asm/ to list asm files coming from asm-generic.
1513
1514See subsequent chapter for the syntax of the Kbuild file.
1515
1516no-export-headers
1517-----------------
1518
1519no-export-headers is essentially used by include/uapi/linux/Kbuild to
1520avoid exporting specific headers (e.g. kvm.h) on architectures that do
1521not support it. It should be avoided as much as possible.
1522
1523generic-y
1524---------
1525
1526If an architecture uses a verbatim copy of a header from
1527include/asm-generic then this is listed in the file
1528arch/$(SRCARCH)/include/asm/Kbuild like this:
1529
1530Example::
1531
1532 #arch/x86/include/asm/Kbuild
1533 generic-y += termios.h
1534 generic-y += rtc.h
1535
1536During the prepare phase of the build a wrapper include
1537file is generated in the directory::
1538
1539 arch/$(SRCARCH)/include/generated/asm
1540
1541When a header is exported where the architecture uses
1542the generic header a similar wrapper is generated as part
1543of the set of exported headers in the directory::
1544
1545 usr/include/asm
1546
1547The generated wrapper will in both cases look like the following:
1548
1549Example: termios.h::
1550
1551 #include <asm-generic/termios.h>
1552
1553generated-y
1554-----------
1555
1556If an architecture generates other header files alongside generic-y
1557wrappers, generated-y specifies them.
1558
1559This prevents them being treated as stale asm-generic wrappers and
1560removed.
1561
1562Example::
1563
1564 #arch/x86/include/asm/Kbuild
1565 generated-y += syscalls_32.h
1566
1567mandatory-y
1568-----------
1569
1570mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild
1571to define the minimum set of ASM headers that all architectures must have.
1572
1573This works like optional generic-y. If a mandatory header is missing
1574in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically
1575generate a wrapper of the asm-generic one.
1576
1577Kbuild Variables
1578================
1579
1580The top Makefile exports the following variables:
1581
1582VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
1583 These variables define the current kernel version. A few arch
1584 Makefiles actually use these values directly; they should use
1585 $(KERNELRELEASE) instead.
1586
1587 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
1588 three-part version number, such as "2", "4", and "0". These three
1589 values are always numeric.
1590
1591 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches
1592 or additional patches. It is usually some non-numeric string
1593 such as "-pre4", and is often blank.
1594
1595KERNELRELEASE
1596 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
1597 for constructing installation directory names or showing in
1598 version strings. Some arch Makefiles use it for this purpose.
1599
1600ARCH
1601 This variable defines the target architecture, such as "i386",
1602 "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
1603 determine which files to compile.
1604
1605 By default, the top Makefile sets $(ARCH) to be the same as the
1606 host system architecture. For a cross build, a user may
1607 override the value of $(ARCH) on the command line::
1608
1609 make ARCH=m68k ...
1610
1611SRCARCH
1612 This variable specifies the directory in arch/ to build.
1613
1614 ARCH and SRCARCH may not necessarily match. A couple of arch
1615 directories are biarch, that is, a single ``arch/*/`` directory supports
1616 both 32-bit and 64-bit.
1617
1618 For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86.
1619 For all of them, SRCARCH=x86 because arch/x86/ supports both i386 and
1620 x86_64.
1621
1622INSTALL_PATH
1623 This variable defines a place for the arch Makefiles to install
1624 the resident kernel image and System.map file.
1625 Use this for architecture-specific install targets.
1626
1627INSTALL_MOD_PATH, MODLIB
1628 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
1629 installation. This variable is not defined in the Makefile but
1630 may be passed in by the user if desired.
1631
1632 $(MODLIB) specifies the directory for module installation.
1633 The top Makefile defines $(MODLIB) to
1634 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may
1635 override this value on the command line if desired.
1636
1637INSTALL_MOD_STRIP
1638 If this variable is specified, it will cause modules to be stripped
1639 after they are installed. If INSTALL_MOD_STRIP is "1", then the
1640 default option --strip-debug will be used. Otherwise, the
1641 INSTALL_MOD_STRIP value will be used as the option(s) to the strip
1642 command.
1643
1644INSTALL_DTBS_PATH
1645 This variable specifies a prefix for relocations required by build
1646 roots. It defines a place for installing the device tree blobs. Like
1647 INSTALL_MOD_PATH, it isn't defined in the Makefile, but can be passed
1648 by the user if desired. Otherwise it defaults to the kernel install
1649 path.
1650
1651Makefile language
1652=================
1653
1654The kernel Makefiles are designed to be run with GNU Make. The Makefiles
1655use only the documented features of GNU Make, but they do use many
1656GNU extensions.
1657
1658GNU Make supports elementary list-processing functions. The kernel
1659Makefiles use a novel style of list building and manipulation with few
1660``if`` statements.
1661
1662GNU Make has two assignment operators, ``:=`` and ``=``. ``:=`` performs
1663immediate evaluation of the right-hand side and stores an actual string
1664into the left-hand side. ``=`` is like a formula definition; it stores the
1665right-hand side in an unevaluated form and then evaluates this form each
1666time the left-hand side is used.
1667
1668There are some cases where ``=`` is appropriate. Usually, though, ``:=``
1669is the right choice.
1670
1671Credits
1672=======
1673
1674- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1675- Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1676- Updates by Sam Ravnborg <sam@ravnborg.org>
1677- Language QA by Jan Engelhardt <jengelh@gmx.de>
1678
1679TODO
1680====
1681
1682- Generating offset header files.
1683- Add more variables to chapters 7 or 9?
1======================
2Linux Kernel Makefiles
3======================
4
5This document describes the Linux kernel Makefiles.
6
7.. Table of Contents
8
9 === 1 Overview
10 === 2 Who does what
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 <deleted>
20 --- 3.9 Dependency tracking
21 --- 3.10 Special Rules
22 --- 3.11 $(CC) support functions
23 --- 3.12 $(LD) support functions
24
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
32 === 5 Userspace Program support
33 --- 5.1 Simple Userspace Program
34 --- 5.2 Composite Userspace Programs
35 --- 5.3 Controlling compiler options for userspace programs
36 --- 5.4 When userspace programs are actually built
37
38 === 6 Kbuild clean infrastructure
39
40 === 7 Architecture Makefiles
41 --- 7.1 Set variables to tweak the build to the architecture
42 --- 7.2 Add prerequisites to archheaders
43 --- 7.3 Add prerequisites to archprepare
44 --- 7.4 List directories to visit when descending
45 --- 7.5 Architecture-specific boot images
46 --- 7.6 Building non-kbuild targets
47 --- 7.7 Commands useful for building a boot image
48 --- 7.8 Custom kbuild commands
49 --- 7.9 Preprocessing linker scripts
50 --- 7.10 Generic header files
51 --- 7.11 Post-link pass
52
53 === 8 Kbuild syntax for exported headers
54 --- 8.1 no-export-headers
55 --- 8.2 generic-y
56 --- 8.3 generated-y
57 --- 8.4 mandatory-y
58
59 === 9 Kbuild Variables
60 === 10 Makefile language
61 === 11 Credits
62 === 12 TODO
63
641 Overview
65==========
66
67The Makefiles have five parts::
68
69 Makefile the top Makefile.
70 .config the kernel configuration file.
71 arch/$(ARCH)/Makefile the arch Makefile.
72 scripts/Makefile.* common rules etc. for all kbuild Makefiles.
73 kbuild Makefiles there are about 500 of these.
74
75The top Makefile reads the .config file, which comes from the kernel
76configuration process.
77
78The top Makefile is responsible for building two major products: vmlinux
79(the resident kernel image) and modules (any module files).
80It builds these goals by recursively descending into the subdirectories of
81the kernel source tree.
82The list of subdirectories which are visited depends upon the kernel
83configuration. The top Makefile textually includes an arch Makefile
84with the name arch/$(ARCH)/Makefile. The arch Makefile supplies
85architecture-specific information to the top Makefile.
86
87Each subdirectory has a kbuild Makefile which carries out the commands
88passed down from above. The kbuild Makefile uses information from the
89.config file to construct various file lists used by kbuild to build
90any built-in or modular targets.
91
92scripts/Makefile.* contains all the definitions/rules etc. that
93are used to build the kernel based on the kbuild makefiles.
94
95
962 Who does what
97===============
98
99People have four different relationships with the kernel Makefiles.
100
101*Users* are people who build kernels. These people type commands such as
102"make menuconfig" or "make". They usually do not read or edit
103any kernel Makefiles (or any other source files).
104
105*Normal developers* are people who work on features such as device
106drivers, file systems, and network protocols. These people need to
107maintain the kbuild Makefiles for the subsystem they are
108working on. In order to do this effectively, they need some overall
109knowledge about the kernel Makefiles, plus detailed knowledge about the
110public interface for kbuild.
111
112*Arch developers* are people who work on an entire architecture, such
113as sparc or ia64. Arch developers need to know about the arch Makefile
114as well as kbuild Makefiles.
115
116*Kbuild developers* are people who work on the kernel build system itself.
117These people need to know about all aspects of the kernel Makefiles.
118
119This document is aimed towards normal developers and arch developers.
120
121
1223 The kbuild files
123==================
124
125Most Makefiles within the kernel are kbuild Makefiles that use the
126kbuild infrastructure. This chapter introduces the syntax used in the
127kbuild makefiles.
128The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
129be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
130file will be used.
131
132Section 3.1 "Goal definitions" is a quick intro; further chapters provide
133more details, with real examples.
134
1353.1 Goal definitions
136--------------------
137
138 Goal definitions are the main part (heart) of the kbuild Makefile.
139 These lines define the files to be built, any special compilation
140 options, and any subdirectories to be entered recursively.
141
142 The most simple kbuild makefile contains one line:
143
144 Example::
145
146 obj-y += foo.o
147
148 This tells kbuild that there is one object in that directory, named
149 foo.o. foo.o will be built from foo.c or foo.S.
150
151 If foo.o shall be built as a module, the variable obj-m is used.
152 Therefore the following pattern is often used:
153
154 Example::
155
156 obj-$(CONFIG_FOO) += foo.o
157
158 $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
159 If CONFIG_FOO is neither y nor m, then the file will not be compiled
160 nor linked.
161
1623.2 Built-in object goals - obj-y
163---------------------------------
164
165 The kbuild Makefile specifies object files for vmlinux
166 in the $(obj-y) lists. These lists depend on the kernel
167 configuration.
168
169 Kbuild compiles all the $(obj-y) files. It then calls
170 "$(AR) rcSTP" to merge these files into one built-in.a file.
171 This is a thin archive without a symbol table. It will be later
172 linked into vmlinux by scripts/link-vmlinux.sh
173
174 The order of files in $(obj-y) is significant. Duplicates in
175 the lists are allowed: the first instance will be linked into
176 built-in.a and succeeding instances will be ignored.
177
178 Link order is significant, because certain functions
179 (module_init() / __initcall) will be called during boot in the
180 order they appear. So keep in mind that changing the link
181 order may e.g. change the order in which your SCSI
182 controllers are detected, and thus your disks are renumbered.
183
184 Example::
185
186 #drivers/isdn/i4l/Makefile
187 # Makefile for the kernel ISDN subsystem and device drivers.
188 # Each configuration option enables a list of files.
189 obj-$(CONFIG_ISDN_I4L) += isdn.o
190 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
191
1923.3 Loadable module goals - obj-m
193---------------------------------
194
195 $(obj-m) specifies object files which are built as loadable
196 kernel modules.
197
198 A module may be built from one source file or several source
199 files. In the case of one source file, the kbuild makefile
200 simply adds the file to $(obj-m).
201
202 Example::
203
204 #drivers/isdn/i4l/Makefile
205 obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
206
207 Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
208
209 If a kernel module is built from several source files, you specify
210 that you want to build a module in the same way as above; however,
211 kbuild needs to know which object files you want to build your
212 module from, so you have to tell it by setting a $(<module_name>-y)
213 variable.
214
215 Example::
216
217 #drivers/isdn/i4l/Makefile
218 obj-$(CONFIG_ISDN_I4L) += isdn.o
219 isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
220
221 In this example, the module name will be isdn.o. Kbuild will
222 compile the objects listed in $(isdn-y) and then run
223 "$(LD) -r" on the list of these files to generate isdn.o.
224
225 Due to kbuild recognizing $(<module_name>-y) for composite objects,
226 you can use the value of a `CONFIG_` symbol to optionally include an
227 object file as part of a composite object.
228
229 Example::
230
231 #fs/ext2/Makefile
232 obj-$(CONFIG_EXT2_FS) += ext2.o
233 ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
234 namei.o super.o symlink.o
235 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
236 xattr_trusted.o
237
238 In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
239 part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
240 evaluates to 'y'.
241
242 Note: Of course, when you are building objects into the kernel,
243 the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
244 kbuild will build an ext2.o file for you out of the individual
245 parts and then link this into built-in.a, as you would expect.
246
2473.4 Objects which export symbols
248--------------------------------
249
250 No special notation is required in the makefiles for
251 modules exporting symbols.
252
2533.5 Library file goals - lib-y
254------------------------------
255
256 Objects listed with obj-* are used for modules, or
257 combined in a built-in.a for that specific directory.
258 There is also the possibility to list objects that will
259 be included in a library, lib.a.
260 All objects listed with lib-y are combined in a single
261 library for that directory.
262 Objects that are listed in obj-y and additionally listed in
263 lib-y will not be included in the library, since they will
264 be accessible anyway.
265 For consistency, objects listed in lib-m will be included in lib.a.
266
267 Note that the same kbuild makefile may list files to be built-in
268 and to be part of a library. Therefore the same directory
269 may contain both a built-in.a and a lib.a file.
270
271 Example::
272
273 #arch/x86/lib/Makefile
274 lib-y := delay.o
275
276 This will create a library lib.a based on delay.o. For kbuild to
277 actually recognize that there is a lib.a being built, the directory
278 shall be listed in libs-y.
279
280 See also "6.4 List directories to visit when descending".
281
282 Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.
283
2843.6 Descending down in directories
285----------------------------------
286
287 A Makefile is only responsible for building objects in its own
288 directory. Files in subdirectories should be taken care of by
289 Makefiles in these subdirs. The build system will automatically
290 invoke make recursively in subdirectories, provided you let it know of
291 them.
292
293 To do so, obj-y and obj-m are used.
294 ext2 lives in a separate directory, and the Makefile present in fs/
295 tells kbuild to descend down using the following assignment.
296
297 Example::
298
299 #fs/Makefile
300 obj-$(CONFIG_EXT2_FS) += ext2/
301
302 If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
303 the corresponding obj- variable will be set, and kbuild will descend
304 down in the ext2 directory.
305
306 Kbuild uses this information not only to decide that it needs to visit
307 the directory, but also to decide whether or not to link objects from
308 the directory into vmlinux.
309
310 When Kbuild descends into the directory with 'y', all built-in objects
311 from that directory are combined into the built-in.a, which will be
312 eventually linked into vmlinux.
313
314 When Kbuild descends into the directory with 'm', in contrast, nothing
315 from that directory will be linked into vmlinux. If the Makefile in
316 that directory specifies obj-y, those objects will be left orphan.
317 It is very likely a bug of the Makefile or of dependencies in Kconfig.
318
319 It is good practice to use a `CONFIG_` variable when assigning directory
320 names. This allows kbuild to totally skip the directory if the
321 corresponding `CONFIG_` option is neither 'y' nor 'm'.
322
3233.7 Compilation flags
324---------------------
325
326 ccflags-y, asflags-y and ldflags-y
327 These three flags apply only to the kbuild makefile in which they
328 are assigned. They are used for all the normal cc, as and ld
329 invocations happening during a recursive build.
330 Note: Flags with the same behaviour were previously named:
331 EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
332 They are still supported but their usage is deprecated.
333
334 ccflags-y specifies options for compiling with $(CC).
335
336 Example::
337
338 # drivers/acpi/acpica/Makefile
339 ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA
340 ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
341
342 This variable is necessary because the top Makefile owns the
343 variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
344 entire tree.
345
346 asflags-y specifies assembler options.
347
348 Example::
349
350 #arch/sparc/kernel/Makefile
351 asflags-y := -ansi
352
353 ldflags-y specifies options for linking with $(LD).
354
355 Example::
356
357 #arch/cris/boot/compressed/Makefile
358 ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
359
360 subdir-ccflags-y, subdir-asflags-y
361 The two flags listed above are similar to ccflags-y and asflags-y.
362 The difference is that the subdir- variants have effect for the kbuild
363 file where they are present and all subdirectories.
364 Options specified using subdir-* are added to the commandline before
365 the options specified using the non-subdir variants.
366
367 Example::
368
369 subdir-ccflags-y := -Werror
370
371 ccflags-remove-y, asflags-remove-y
372 These flags are used to remove particular flags for the compiler,
373 assembler invocations.
374
375 Example::
376
377 ccflags-remove-$(CONFIG_MCOUNT) += -pg
378
379 CFLAGS_$@, AFLAGS_$@
380 CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
381 kbuild makefile.
382
383 $(CFLAGS_$@) specifies per-file options for $(CC). The $@
384 part has a literal value which specifies the file that it is for.
385
386 CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@
387 can re-add compiler flags that were removed by ccflags-remove-y.
388
389 Example::
390
391 # drivers/scsi/Makefile
392 CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
393 CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
394 -DGDTH_STATISTICS
395
396 These two lines specify compilation flags for aha152x.o and gdth.o.
397
398 $(AFLAGS_$@) is a similar feature for source files in assembly
399 languages.
400
401 AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@
402 can re-add assembler flags that were removed by asflags-remove-y.
403
404 Example::
405
406 # arch/arm/kernel/Makefile
407 AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET)
408 AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
409 AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
410
411
4123.9 Dependency tracking
413-----------------------
414
415 Kbuild tracks dependencies on the following:
416
417 1) All prerequisite files (both `*.c` and `*.h`)
418 2) `CONFIG_` options used in all prerequisite files
419 3) Command-line used to compile target
420
421 Thus, if you change an option to $(CC) all affected files will
422 be re-compiled.
423
4243.10 Special Rules
425------------------
426
427 Special rules are used when the kbuild infrastructure does
428 not provide the required support. A typical example is
429 header files generated during the build process.
430 Another example are the architecture-specific Makefiles which
431 need special rules to prepare boot images etc.
432
433 Special rules are written as normal Make rules.
434 Kbuild is not executing in the directory where the Makefile is
435 located, so all special rules shall provide a relative
436 path to prerequisite files and target files.
437
438 Two variables are used when defining special rules:
439
440 $(src)
441 $(src) is a relative path which points to the directory
442 where the Makefile is located. Always use $(src) when
443 referring to files located in the src tree.
444
445 $(obj)
446 $(obj) is a relative path which points to the directory
447 where the target is saved. Always use $(obj) when
448 referring to generated files.
449
450 Example::
451
452 #drivers/scsi/Makefile
453 $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
454 $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
455
456 This is a special rule, following the normal syntax
457 required by make.
458
459 The target file depends on two prerequisite files. References
460 to the target file are prefixed with $(obj), references
461 to prerequisites are referenced with $(src) (because they are not
462 generated files).
463
464 $(kecho)
465 echoing information to user in a rule is often a good practice
466 but when execution "make -s" one does not expect to see any output
467 except for warnings/errors.
468 To support this kbuild defines $(kecho) which will echo out the
469 text following $(kecho) to stdout except if "make -s" is used.
470
471 Example::
472
473 #arch/blackfin/boot/Makefile
474 $(obj)/vmImage: $(obj)/vmlinux.gz
475 $(call if_changed,uimage)
476 @$(kecho) 'Kernel: $@ is ready'
477
478
4793.11 $(CC) support functions
480----------------------------
481
482 The kernel may be built with several different versions of
483 $(CC), each supporting a unique set of features and options.
484 kbuild provides basic support to check for valid options for $(CC).
485 $(CC) is usually the gcc compiler, but other alternatives are
486 available.
487
488 as-option
489 as-option is used to check if $(CC) -- when used to compile
490 assembler (`*.S`) files -- supports the given option. An optional
491 second option may be specified if the first option is not supported.
492
493 Example::
494
495 #arch/sh/Makefile
496 cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
497
498 In the above example, cflags-y will be assigned the option
499 -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
500 The second argument is optional, and if supplied will be used
501 if first argument is not supported.
502
503 as-instr
504 as-instr checks if the assembler reports a specific instruction
505 and then outputs either option1 or option2
506 C escapes are supported in the test instruction
507 Note: as-instr-option uses KBUILD_AFLAGS for assembler options
508
509 cc-option
510 cc-option is used to check if $(CC) supports a given option, and if
511 not supported to use an optional second option.
512
513 Example::
514
515 #arch/x86/Makefile
516 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
517
518 In the above example, cflags-y will be assigned the option
519 -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
520 The second argument to cc-option is optional, and if omitted,
521 cflags-y will be assigned no value if first option is not supported.
522 Note: cc-option uses KBUILD_CFLAGS for $(CC) options
523
524 cc-option-yn
525 cc-option-yn is used to check if gcc supports a given option
526 and return 'y' if supported, otherwise 'n'.
527
528 Example::
529
530 #arch/ppc/Makefile
531 biarch := $(call cc-option-yn, -m32)
532 aflags-$(biarch) += -a32
533 cflags-$(biarch) += -m32
534
535 In the above example, $(biarch) is set to y if $(CC) supports the -m32
536 option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
537 and $(cflags-y) will be assigned the values -a32 and -m32,
538 respectively.
539 Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options
540
541 cc-disable-warning
542 cc-disable-warning checks if gcc supports a given warning and returns
543 the commandline switch to disable it. This special function is needed,
544 because gcc 4.4 and later accept any unknown -Wno-* option and only
545 warn about it if there is another warning in the source file.
546
547 Example::
548
549 KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
550
551 In the above example, -Wno-unused-but-set-variable will be added to
552 KBUILD_CFLAGS only if gcc really accepts it.
553
554 cc-ifversion
555 cc-ifversion tests the version of $(CC) and equals the fourth parameter
556 if version expression is true, or the fifth (if given) if the version
557 expression is false.
558
559 Example::
560
561 #fs/reiserfs/Makefile
562 ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
563
564 In this example, ccflags-y will be assigned the value -O1 if the
565 $(CC) version is less than 4.2.
566 cc-ifversion takes all the shell operators:
567 -eq, -ne, -lt, -le, -gt, and -ge
568 The third parameter may be a text as in this example, but it may also
569 be an expanded variable or a macro.
570
571 cc-cross-prefix
572 cc-cross-prefix is used to check if there exists a $(CC) in path with
573 one of the listed prefixes. The first prefix where there exist a
574 prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
575 then nothing is returned.
576 Additional prefixes are separated by a single space in the
577 call of cc-cross-prefix.
578 This functionality is useful for architecture Makefiles that try
579 to set CROSS_COMPILE to well-known values but may have several
580 values to select between.
581 It is recommended only to try to set CROSS_COMPILE if it is a cross
582 build (host arch is different from target arch). And if CROSS_COMPILE
583 is already set then leave it with the old value.
584
585 Example::
586
587 #arch/m68k/Makefile
588 ifneq ($(SUBARCH),$(ARCH))
589 ifeq ($(CROSS_COMPILE),)
590 CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
591 endif
592 endif
593
5943.12 $(LD) support functions
595----------------------------
596
597 ld-option
598 ld-option is used to check if $(LD) supports the supplied option.
599 ld-option takes two options as arguments.
600 The second argument is an optional option that can be used if the
601 first option is not supported by $(LD).
602
603 Example::
604
605 #Makefile
606 LDFLAGS_vmlinux += $(call ld-option, -X)
607
608
6094 Host Program support
610======================
611
612Kbuild supports building executables on the host for use during the
613compilation stage.
614Two steps are required in order to use a host executable.
615
616The first step is to tell kbuild that a host program exists. This is
617done utilising the variable "hostprogs".
618
619The second step is to add an explicit dependency to the executable.
620This can be done in two ways. Either add the dependency in a rule,
621or utilise the variable "always-y".
622Both possibilities are described in the following.
623
6244.1 Simple Host Program
625-----------------------
626
627 In some cases there is a need to compile and run a program on the
628 computer where the build is running.
629 The following line tells kbuild that the program bin2hex shall be
630 built on the build host.
631
632 Example::
633
634 hostprogs := bin2hex
635
636 Kbuild assumes in the above example that bin2hex is made from a single
637 c-source file named bin2hex.c located in the same directory as
638 the Makefile.
639
6404.2 Composite Host Programs
641---------------------------
642
643 Host programs can be made up based on composite objects.
644 The syntax used to define composite objects for host programs is
645 similar to the syntax used for kernel objects.
646 $(<executable>-objs) lists all objects used to link the final
647 executable.
648
649 Example::
650
651 #scripts/lxdialog/Makefile
652 hostprogs := lxdialog
653 lxdialog-objs := checklist.o lxdialog.o
654
655 Objects with extension .o are compiled from the corresponding .c
656 files. In the above example, checklist.c is compiled to checklist.o
657 and lxdialog.c is compiled to lxdialog.o.
658
659 Finally, the two .o files are linked to the executable, lxdialog.
660 Note: The syntax <executable>-y is not permitted for host-programs.
661
6624.3 Using C++ for host programs
663-------------------------------
664
665 kbuild offers support for host programs written in C++. This was
666 introduced solely to support kconfig, and is not recommended
667 for general use.
668
669 Example::
670
671 #scripts/kconfig/Makefile
672 hostprogs := qconf
673 qconf-cxxobjs := qconf.o
674
675 In the example above the executable is composed of the C++ file
676 qconf.cc - identified by $(qconf-cxxobjs).
677
678 If qconf is composed of a mixture of .c and .cc files, then an
679 additional line can be used to identify this.
680
681 Example::
682
683 #scripts/kconfig/Makefile
684 hostprogs := qconf
685 qconf-cxxobjs := qconf.o
686 qconf-objs := check.o
687
6884.4 Controlling compiler options for host programs
689--------------------------------------------------
690
691 When compiling host programs, it is possible to set specific flags.
692 The programs will always be compiled utilising $(HOSTCC) passed
693 the options specified in $(KBUILD_HOSTCFLAGS).
694 To set flags that will take effect for all host programs created
695 in that Makefile, use the variable HOST_EXTRACFLAGS.
696
697 Example::
698
699 #scripts/lxdialog/Makefile
700 HOST_EXTRACFLAGS += -I/usr/include/ncurses
701
702 To set specific flags for a single file the following construction
703 is used:
704
705 Example::
706
707 #arch/ppc64/boot/Makefile
708 HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
709
710 It is also possible to specify additional options to the linker.
711
712 Example::
713
714 #scripts/kconfig/Makefile
715 HOSTLDLIBS_qconf := -L$(QTDIR)/lib
716
717 When linking qconf, it will be passed the extra option
718 "-L$(QTDIR)/lib".
719
7204.5 When host programs are actually built
721-----------------------------------------
722
723 Kbuild will only build host-programs when they are referenced
724 as a prerequisite.
725 This is possible in two ways:
726
727 (1) List the prerequisite explicitly in a special rule.
728
729 Example::
730
731 #drivers/pci/Makefile
732 hostprogs := gen-devlist
733 $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
734 ( cd $(obj); ./gen-devlist ) < $<
735
736 The target $(obj)/devlist.h will not be built before
737 $(obj)/gen-devlist is updated. Note that references to
738 the host programs in special rules must be prefixed with $(obj).
739
740 (2) Use always-y
741
742 When there is no suitable special rule, and the host program
743 shall be built when a makefile is entered, the always-y
744 variable shall be used.
745
746 Example::
747
748 #scripts/lxdialog/Makefile
749 hostprogs := lxdialog
750 always-y := $(hostprogs)
751
752 Kbuild provides the following shorthand for this:
753
754 hostprogs-always-y := lxdialog
755
756 This will tell kbuild to build lxdialog even if not referenced in
757 any rule.
758
7595 Userspace Program support
760===========================
761
762Just like host programs, Kbuild also supports building userspace executables
763for the target architecture (i.e. the same architecture as you are building
764the kernel for).
765
766The syntax is quite similar. The difference is to use "userprogs" instead of
767"hostprogs".
768
7695.1 Simple Userspace Program
770----------------------------
771
772 The following line tells kbuild that the program bpf-direct shall be
773 built for the target architecture.
774
775 Example::
776
777 userprogs := bpf-direct
778
779 Kbuild assumes in the above example that bpf-direct is made from a
780 single C source file named bpf-direct.c located in the same directory
781 as the Makefile.
782
7835.2 Composite Userspace Programs
784--------------------------------
785
786 Userspace programs can be made up based on composite objects.
787 The syntax used to define composite objects for userspace programs is
788 similar to the syntax used for kernel objects.
789 $(<executable>-objs) lists all objects used to link the final
790 executable.
791
792 Example::
793
794 #samples/seccomp/Makefile
795 userprogs := bpf-fancy
796 bpf-fancy-objs := bpf-fancy.o bpf-helper.o
797
798 Objects with extension .o are compiled from the corresponding .c
799 files. In the above example, bpf-fancy.c is compiled to bpf-fancy.o
800 and bpf-helper.c is compiled to bpf-helper.o.
801
802 Finally, the two .o files are linked to the executable, bpf-fancy.
803 Note: The syntax <executable>-y is not permitted for userspace programs.
804
8055.3 Controlling compiler options for userspace programs
806-------------------------------------------------------
807
808 When compiling userspace programs, it is possible to set specific flags.
809 The programs will always be compiled utilising $(CC) passed
810 the options specified in $(KBUILD_USERCFLAGS).
811 To set flags that will take effect for all userspace programs created
812 in that Makefile, use the variable userccflags.
813
814 Example::
815
816 # samples/seccomp/Makefile
817 userccflags += -I usr/include
818
819 To set specific flags for a single file the following construction
820 is used:
821
822 Example::
823
824 bpf-helper-userccflags += -I user/include
825
826 It is also possible to specify additional options to the linker.
827
828 Example::
829
830 # net/bpfilter/Makefile
831 bpfilter_umh-userldflags += -static
832
833 When linking bpfilter_umh, it will be passed the extra option -static.
834
8355.4 When userspace programs are actually built
836----------------------------------------------
837
838 Kbuild builds userspace programs only when told to do so.
839 There are two ways to do this.
840
841 (1) Add it as the prerequisite of another file
842
843 Example::
844
845 #net/bpfilter/Makefile
846 userprogs := bpfilter_umh
847 $(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh
848
849 $(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o
850
851 (2) Use always-y
852
853 Example::
854
855 userprogs := binderfs_example
856 always-y := $(userprogs)
857
858 Kbuild provides the following shorthand for this:
859
860 userprogs-always-y := binderfs_example
861
862 This will tell Kbuild to build binderfs_example when it visits this
863 Makefile.
864
8656 Kbuild clean infrastructure
866=============================
867
868"make clean" deletes most generated files in the obj tree where the kernel
869is compiled. This includes generated files such as host programs.
870Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m),
871$(always-), $(extra-y), $(extra-) and $(targets). They are all deleted
872during "make clean". Files matching the patterns "*.[oas]", "*.ko", plus
873some additional files generated by kbuild are deleted all over the kernel
874source tree when "make clean" is executed.
875
876Additional files or directories can be specified in kbuild makefiles by use of
877$(clean-files).
878
879 Example::
880
881 #lib/Makefile
882 clean-files := crc32table.h
883
884When executing "make clean", the file "crc32table.h" will be deleted.
885Kbuild will assume files to be in the same relative directory as the
886Makefile, except if prefixed with $(objtree).
887
888To exclude certain files or directories from make clean, use the
889$(no-clean-files) variable.
890
891Usually kbuild descends down in subdirectories due to "obj-* := dir/",
892but in the architecture makefiles where the kbuild infrastructure
893is not sufficient this sometimes needs to be explicit.
894
895 Example::
896
897 #arch/x86/boot/Makefile
898 subdir- := compressed
899
900The above assignment instructs kbuild to descend down in the
901directory compressed/ when "make clean" is executed.
902
903To support the clean infrastructure in the Makefiles that build the
904final bootimage there is an optional target named archclean:
905
906 Example::
907
908 #arch/x86/Makefile
909 archclean:
910 $(Q)$(MAKE) $(clean)=arch/x86/boot
911
912When "make clean" is executed, make will descend down in arch/x86/boot,
913and clean as usual. The Makefile located in arch/x86/boot/ may use
914the subdir- trick to descend further down.
915
916Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
917included in the top level makefile, and the kbuild infrastructure
918is not operational at that point.
919
920Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
921be visited during "make clean".
922
9237 Architecture Makefiles
924========================
925
926The top level Makefile sets up the environment and does the preparation,
927before starting to descend down in the individual directories.
928The top level makefile contains the generic part, whereas
929arch/$(ARCH)/Makefile contains what is required to set up kbuild
930for said architecture.
931To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
932a few targets.
933
934When kbuild executes, the following steps are followed (roughly):
935
9361) Configuration of the kernel => produce .config
9372) Store kernel version in include/linux/version.h
9383) Updating all other prerequisites to the target prepare:
939 - Additional prerequisites are specified in arch/$(ARCH)/Makefile
9404) Recursively descend down in all directories listed in
941 init-* core* drivers-* net-* libs-* and build all targets.
942 - The values of the above variables are expanded in arch/$(ARCH)/Makefile.
9435) All object files are then linked and the resulting file vmlinux is
944 located at the root of the obj tree.
945 The very first objects linked are listed in head-y, assigned by
946 arch/$(ARCH)/Makefile.
9476) Finally, the architecture-specific part does any required post processing
948 and builds the final bootimage.
949 - This includes building boot records
950 - Preparing initrd images and the like
951
952
9537.1 Set variables to tweak the build to the architecture
954--------------------------------------------------------
955
956 KBUILD_LDFLAGS
957 Generic $(LD) options
958
959 Flags used for all invocations of the linker.
960 Often specifying the emulation is sufficient.
961
962 Example::
963
964 #arch/s390/Makefile
965 KBUILD_LDFLAGS := -m elf_s390
966
967 Note: ldflags-y can be used to further customise
968 the flags used. See section 3.7.
969
970 LDFLAGS_vmlinux
971 Options for $(LD) when linking vmlinux
972
973 LDFLAGS_vmlinux is used to specify additional flags to pass to
974 the linker when linking the final vmlinux image.
975 LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
976
977 Example::
978
979 #arch/x86/Makefile
980 LDFLAGS_vmlinux := -e stext
981
982 OBJCOPYFLAGS
983 objcopy flags
984
985 When $(call if_changed,objcopy) is used to translate a .o file,
986 the flags specified in OBJCOPYFLAGS will be used.
987 $(call if_changed,objcopy) is often used to generate raw binaries on
988 vmlinux.
989
990 Example::
991
992 #arch/s390/Makefile
993 OBJCOPYFLAGS := -O binary
994
995 #arch/s390/boot/Makefile
996 $(obj)/image: vmlinux FORCE
997 $(call if_changed,objcopy)
998
999 In this example, the binary $(obj)/image is a binary version of
1000 vmlinux. The usage of $(call if_changed,xxx) will be described later.
1001
1002 KBUILD_AFLAGS
1003 Assembler flags
1004
1005 Default value - see top level Makefile
1006 Append or modify as required per architecture.
1007
1008 Example::
1009
1010 #arch/sparc64/Makefile
1011 KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
1012
1013 KBUILD_CFLAGS
1014 $(CC) compiler flags
1015
1016 Default value - see top level Makefile
1017 Append or modify as required per architecture.
1018
1019 Often, the KBUILD_CFLAGS variable depends on the configuration.
1020
1021 Example::
1022
1023 #arch/x86/boot/compressed/Makefile
1024 cflags-$(CONFIG_X86_32) := -march=i386
1025 cflags-$(CONFIG_X86_64) := -mcmodel=small
1026 KBUILD_CFLAGS += $(cflags-y)
1027
1028 Many arch Makefiles dynamically run the target C compiler to
1029 probe supported options::
1030
1031 #arch/x86/Makefile
1032
1033 ...
1034 cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\
1035 -march=pentium2,-march=i686)
1036 ...
1037 # Disable unit-at-a-time mode ...
1038 KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
1039 ...
1040
1041
1042 The first example utilises the trick that a config option expands
1043 to 'y' when selected.
1044
1045 KBUILD_AFLAGS_KERNEL
1046 Assembler options specific for built-in
1047
1048 $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
1049 resident kernel code.
1050
1051 KBUILD_AFLAGS_MODULE
1052 Assembler options specific for modules
1053
1054 $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
1055 are used for assembler.
1056
1057 From commandline AFLAGS_MODULE shall be used (see kbuild.rst).
1058
1059 KBUILD_CFLAGS_KERNEL
1060 $(CC) options specific for built-in
1061
1062 $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
1063 resident kernel code.
1064
1065 KBUILD_CFLAGS_MODULE
1066 Options for $(CC) when building modules
1067
1068 $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
1069 are used for $(CC).
1070 From commandline CFLAGS_MODULE shall be used (see kbuild.rst).
1071
1072 KBUILD_LDFLAGS_MODULE
1073 Options for $(LD) when linking modules
1074
1075 $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
1076 used when linking modules. This is often a linker script.
1077
1078 From commandline LDFLAGS_MODULE shall be used (see kbuild.rst).
1079
1080 KBUILD_LDS
1081
1082 The linker script with full path. Assigned by the top-level Makefile.
1083
1084 KBUILD_LDS_MODULE
1085
1086 The module linker script with full path. Assigned by the top-level
1087 Makefile and additionally by the arch Makefile.
1088
1089 KBUILD_VMLINUX_OBJS
1090
1091 All object files for vmlinux. They are linked to vmlinux in the same
1092 order as listed in KBUILD_VMLINUX_OBJS.
1093
1094 KBUILD_VMLINUX_LIBS
1095
1096 All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and
1097 KBUILD_VMLINUX_LIBS together specify all the object files used to
1098 link vmlinux.
1099
11007.2 Add prerequisites to archheaders
1101------------------------------------
1102
1103 The archheaders: rule is used to generate header files that
1104 may be installed into user space by "make header_install".
1105
1106 It is run before "make archprepare" when run on the
1107 architecture itself.
1108
1109
11107.3 Add prerequisites to archprepare
1111------------------------------------
1112
1113 The archprepare: rule is used to list prerequisites that need to be
1114 built before starting to descend down in the subdirectories.
1115 This is usually used for header files containing assembler constants.
1116
1117 Example::
1118
1119 #arch/arm/Makefile
1120 archprepare: maketools
1121
1122 In this example, the file target maketools will be processed
1123 before descending down in the subdirectories.
1124 See also chapter XXX-TODO that describes how kbuild supports
1125 generating offset header files.
1126
1127
11287.4 List directories to visit when descending
1129---------------------------------------------
1130
1131 An arch Makefile cooperates with the top Makefile to define variables
1132 which specify how to build the vmlinux file. Note that there is no
1133 corresponding arch-specific section for modules; the module-building
1134 machinery is all architecture-independent.
1135
1136
1137 head-y, init-y, core-y, libs-y, drivers-y, net-y
1138 $(head-y) lists objects to be linked first in vmlinux.
1139
1140 $(libs-y) lists directories where a lib.a archive can be located.
1141
1142 The rest list directories where a built-in.a object file can be
1143 located.
1144
1145 $(init-y) objects will be located after $(head-y).
1146
1147 Then the rest follows in this order:
1148
1149 $(core-y), $(libs-y), $(drivers-y) and $(net-y).
1150
1151 The top level Makefile defines values for all generic directories,
1152 and arch/$(ARCH)/Makefile only adds architecture-specific
1153 directories.
1154
1155 Example::
1156
1157 #arch/sparc64/Makefile
1158 core-y += arch/sparc64/kernel/
1159 libs-y += arch/sparc64/prom/ arch/sparc64/lib/
1160 drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
1161
1162
11637.5 Architecture-specific boot images
1164-------------------------------------
1165
1166 An arch Makefile specifies goals that take the vmlinux file, compress
1167 it, wrap it in bootstrapping code, and copy the resulting files
1168 somewhere. This includes various kinds of installation commands.
1169 The actual goals are not standardized across architectures.
1170
1171 It is common to locate any additional processing in a boot/
1172 directory below arch/$(ARCH)/.
1173
1174 Kbuild does not provide any smart way to support building a
1175 target specified in boot/. Therefore arch/$(ARCH)/Makefile shall
1176 call make manually to build a target in boot/.
1177
1178 The recommended approach is to include shortcuts in
1179 arch/$(ARCH)/Makefile, and use the full path when calling down
1180 into the arch/$(ARCH)/boot/Makefile.
1181
1182 Example::
1183
1184 #arch/x86/Makefile
1185 boot := arch/x86/boot
1186 bzImage: vmlinux
1187 $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@
1188
1189 "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
1190 make in a subdirectory.
1191
1192 There are no rules for naming architecture-specific targets,
1193 but executing "make help" will list all relevant targets.
1194 To support this, $(archhelp) must be defined.
1195
1196 Example::
1197
1198 #arch/x86/Makefile
1199 define archhelp
1200 echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)'
1201 endif
1202
1203 When make is executed without arguments, the first goal encountered
1204 will be built. In the top level Makefile the first goal present
1205 is all:.
1206 An architecture shall always, per default, build a bootable image.
1207 In "make help", the default goal is highlighted with a '*'.
1208 Add a new prerequisite to all: to select a default goal different
1209 from vmlinux.
1210
1211 Example::
1212
1213 #arch/x86/Makefile
1214 all: bzImage
1215
1216 When "make" is executed without arguments, bzImage will be built.
1217
12187.6 Building non-kbuild targets
1219-------------------------------
1220
1221 extra-y
1222 extra-y specifies additional targets created in the current
1223 directory, in addition to any targets specified by `obj-*`.
1224
1225 Listing all targets in extra-y is required for two purposes:
1226
1227 1) Enable kbuild to check changes in command lines
1228
1229 - When $(call if_changed,xxx) is used
1230
1231 2) kbuild knows what files to delete during "make clean"
1232
1233 Example::
1234
1235 #arch/x86/kernel/Makefile
1236 extra-y := head.o init_task.o
1237
1238 In this example, extra-y is used to list object files that
1239 shall be built, but shall not be linked as part of built-in.a.
1240
12417.7 Commands useful for building a boot image
1242---------------------------------------------
1243
1244 Kbuild provides a few macros that are useful when building a
1245 boot image.
1246
1247 if_changed
1248 if_changed is the infrastructure used for the following commands.
1249
1250 Usage::
1251
1252 target: source(s) FORCE
1253 $(call if_changed,ld/objcopy/gzip/...)
1254
1255 When the rule is evaluated, it is checked to see if any files
1256 need an update, or the command line has changed since the last
1257 invocation. The latter will force a rebuild if any options
1258 to the executable have changed.
1259 Any target that utilises if_changed must be listed in $(targets),
1260 otherwise the command line check will fail, and the target will
1261 always be built.
1262 Assignments to $(targets) are without $(obj)/ prefix.
1263 if_changed may be used in conjunction with custom commands as
1264 defined in 7.8 "Custom kbuild commands".
1265
1266 Note: It is a typical mistake to forget the FORCE prerequisite.
1267 Another common pitfall is that whitespace is sometimes
1268 significant; for instance, the below will fail (note the extra space
1269 after the comma)::
1270
1271 target: source(s) FORCE
1272
1273 **WRONG!** $(call if_changed, ld/objcopy/gzip/...)
1274
1275 Note:
1276 if_changed should not be used more than once per target.
1277 It stores the executed command in a corresponding .cmd
1278
1279 file and multiple calls would result in overwrites and
1280 unwanted results when the target is up to date and only the
1281 tests on changed commands trigger execution of commands.
1282
1283 ld
1284 Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1285
1286 Example::
1287
1288 #arch/x86/boot/Makefile
1289 LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
1290 LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext
1291
1292 targets += setup setup.o bootsect bootsect.o
1293 $(obj)/setup $(obj)/bootsect: %: %.o FORCE
1294 $(call if_changed,ld)
1295
1296 In this example, there are two possible targets, requiring different
1297 options to the linker. The linker options are specified using the
1298 LDFLAGS_$@ syntax - one for each potential target.
1299 $(targets) are assigned all potential targets, by which kbuild knows
1300 the targets and will:
1301
1302 1) check for commandline changes
1303 2) delete target during make clean
1304
1305 The ": %: %.o" part of the prerequisite is a shorthand that
1306 frees us from listing the setup.o and bootsect.o files.
1307
1308 Note:
1309 It is a common mistake to forget the "targets :=" assignment,
1310 resulting in the target file being recompiled for no
1311 obvious reason.
1312
1313 objcopy
1314 Copy binary. Uses OBJCOPYFLAGS usually specified in
1315 arch/$(ARCH)/Makefile.
1316 OBJCOPYFLAGS_$@ may be used to set additional options.
1317
1318 gzip
1319 Compress target. Use maximum compression to compress target.
1320
1321 Example::
1322
1323 #arch/x86/boot/compressed/Makefile
1324 $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE
1325 $(call if_changed,gzip)
1326
1327 dtc
1328 Create flattened device tree blob object suitable for linking
1329 into vmlinux. Device tree blobs linked into vmlinux are placed
1330 in an init section in the image. Platform code *must* copy the
1331 blob to non-init memory prior to calling unflatten_device_tree().
1332
1333 To use this command, simply add `*.dtb` into obj-y or targets, or make
1334 some other target depend on `%.dtb`
1335
1336 A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`;
1337 architecture Makefiles do no need to explicitly write out that rule.
1338
1339 Example::
1340
1341 targets += $(dtb-y)
1342 DTC_FLAGS ?= -p 1024
1343
13447.8 Custom kbuild commands
1345--------------------------
1346
1347 When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
1348 of a command is normally displayed.
1349 To enable this behaviour for custom commands kbuild requires
1350 two variables to be set::
1351
1352 quiet_cmd_<command> - what shall be echoed
1353 cmd_<command> - the command to execute
1354
1355 Example::
1356
1357 #
1358 quiet_cmd_image = BUILD $@
1359 cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
1360 $(obj)/vmlinux.bin > $@
1361
1362 targets += bzImage
1363 $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
1364 $(call if_changed,image)
1365 @echo 'Kernel: $@ is ready'
1366
1367 When updating the $(obj)/bzImage target, the line:
1368
1369 BUILD arch/x86/boot/bzImage
1370
1371 will be displayed with "make KBUILD_VERBOSE=0".
1372
1373
13747.9 Preprocessing linker scripts
1375--------------------------------
1376
1377 When the vmlinux image is built, the linker script
1378 arch/$(ARCH)/kernel/vmlinux.lds is used.
1379 The script is a preprocessed variant of the file vmlinux.lds.S
1380 located in the same directory.
1381 kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`.
1382
1383 Example::
1384
1385 #arch/x86/kernel/Makefile
1386 extra-y := vmlinux.lds
1387
1388 #Makefile
1389 export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
1390
1391 The assignment to extra-y is used to tell kbuild to build the
1392 target vmlinux.lds.
1393 The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1394 specified options when building the target vmlinux.lds.
1395
1396 When building the `*.lds` target, kbuild uses the variables::
1397
1398 KBUILD_CPPFLAGS : Set in top-level Makefile
1399 cppflags-y : May be set in the kbuild makefile
1400 CPPFLAGS_$(@F) : Target-specific flags.
1401 Note that the full filename is used in this
1402 assignment.
1403
1404 The kbuild infrastructure for `*lds` files is used in several
1405 architecture-specific files.
1406
14077.10 Generic header files
1408-------------------------
1409
1410 The directory include/asm-generic contains the header files
1411 that may be shared between individual architectures.
1412 The recommended approach how to use a generic header file is
1413 to list the file in the Kbuild file.
1414 See "8.2 generic-y" for further info on syntax etc.
1415
14167.11 Post-link pass
1417-------------------
1418
1419 If the file arch/xxx/Makefile.postlink exists, this makefile
1420 will be invoked for post-link objects (vmlinux and modules.ko)
1421 for architectures to run post-link passes on. Must also handle
1422 the clean target.
1423
1424 This pass runs after kallsyms generation. If the architecture
1425 needs to modify symbol locations, rather than manipulate the
1426 kallsyms, it may be easier to add another postlink target for
1427 .tmp_vmlinux? targets to be called from link-vmlinux.sh.
1428
1429 For example, powerpc uses this to check relocation sanity of
1430 the linked vmlinux file.
1431
14328 Kbuild syntax for exported headers
1433------------------------------------
1434
1435The kernel includes a set of headers that is exported to userspace.
1436Many headers can be exported as-is but other headers require a
1437minimal pre-processing before they are ready for user-space.
1438The pre-processing does:
1439
1440- drop kernel-specific annotations
1441- drop include of compiler.h
1442- drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`)
1443
1444All headers under include/uapi/, include/generated/uapi/,
1445arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/
1446are exported.
1447
1448A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and
1449arch/<arch>/include/asm/ to list asm files coming from asm-generic.
1450See subsequent chapter for the syntax of the Kbuild file.
1451
14528.1 no-export-headers
1453---------------------
1454
1455 no-export-headers is essentially used by include/uapi/linux/Kbuild to
1456 avoid exporting specific headers (e.g. kvm.h) on architectures that do
1457 not support it. It should be avoided as much as possible.
1458
14598.2 generic-y
1460-------------
1461
1462 If an architecture uses a verbatim copy of a header from
1463 include/asm-generic then this is listed in the file
1464 arch/$(ARCH)/include/asm/Kbuild like this:
1465
1466 Example::
1467
1468 #arch/x86/include/asm/Kbuild
1469 generic-y += termios.h
1470 generic-y += rtc.h
1471
1472 During the prepare phase of the build a wrapper include
1473 file is generated in the directory::
1474
1475 arch/$(ARCH)/include/generated/asm
1476
1477 When a header is exported where the architecture uses
1478 the generic header a similar wrapper is generated as part
1479 of the set of exported headers in the directory::
1480
1481 usr/include/asm
1482
1483 The generated wrapper will in both cases look like the following:
1484
1485 Example: termios.h::
1486
1487 #include <asm-generic/termios.h>
1488
14898.3 generated-y
1490---------------
1491
1492 If an architecture generates other header files alongside generic-y
1493 wrappers, generated-y specifies them.
1494
1495 This prevents them being treated as stale asm-generic wrappers and
1496 removed.
1497
1498 Example::
1499
1500 #arch/x86/include/asm/Kbuild
1501 generated-y += syscalls_32.h
1502
15038.4 mandatory-y
1504---------------
1505
1506 mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild
1507 to define the minimum set of ASM headers that all architectures must have.
1508
1509 This works like optional generic-y. If a mandatory header is missing
1510 in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate
1511 a wrapper of the asm-generic one.
1512
15139 Kbuild Variables
1514==================
1515
1516The top Makefile exports the following variables:
1517
1518 VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
1519 These variables define the current kernel version. A few arch
1520 Makefiles actually use these values directly; they should use
1521 $(KERNELRELEASE) instead.
1522
1523 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
1524 three-part version number, such as "2", "4", and "0". These three
1525 values are always numeric.
1526
1527 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches
1528 or additional patches. It is usually some non-numeric string
1529 such as "-pre4", and is often blank.
1530
1531 KERNELRELEASE
1532 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
1533 for constructing installation directory names or showing in
1534 version strings. Some arch Makefiles use it for this purpose.
1535
1536 ARCH
1537 This variable defines the target architecture, such as "i386",
1538 "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
1539 determine which files to compile.
1540
1541 By default, the top Makefile sets $(ARCH) to be the same as the
1542 host system architecture. For a cross build, a user may
1543 override the value of $(ARCH) on the command line::
1544
1545 make ARCH=m68k ...
1546
1547
1548 INSTALL_PATH
1549 This variable defines a place for the arch Makefiles to install
1550 the resident kernel image and System.map file.
1551 Use this for architecture-specific install targets.
1552
1553 INSTALL_MOD_PATH, MODLIB
1554 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
1555 installation. This variable is not defined in the Makefile but
1556 may be passed in by the user if desired.
1557
1558 $(MODLIB) specifies the directory for module installation.
1559 The top Makefile defines $(MODLIB) to
1560 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may
1561 override this value on the command line if desired.
1562
1563 INSTALL_MOD_STRIP
1564 If this variable is specified, it will cause modules to be stripped
1565 after they are installed. If INSTALL_MOD_STRIP is '1', then the
1566 default option --strip-debug will be used. Otherwise, the
1567 INSTALL_MOD_STRIP value will be used as the option(s) to the strip
1568 command.
1569
1570
157110 Makefile language
1572====================
1573
1574The kernel Makefiles are designed to be run with GNU Make. The Makefiles
1575use only the documented features of GNU Make, but they do use many
1576GNU extensions.
1577
1578GNU Make supports elementary list-processing functions. The kernel
1579Makefiles use a novel style of list building and manipulation with few
1580"if" statements.
1581
1582GNU Make has two assignment operators, ":=" and "=". ":=" performs
1583immediate evaluation of the right-hand side and stores an actual string
1584into the left-hand side. "=" is like a formula definition; it stores the
1585right-hand side in an unevaluated form and then evaluates this form each
1586time the left-hand side is used.
1587
1588There are some cases where "=" is appropriate. Usually, though, ":="
1589is the right choice.
1590
159111 Credits
1592==========
1593
1594- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1595- Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1596- Updates by Sam Ravnborg <sam@ravnborg.org>
1597- Language QA by Jan Engelhardt <jengelh@gmx.de>
1598
159912 TODO
1600=======
1601
1602- Describe how kbuild supports shipped files with _shipped.
1603- Generating offset header files.
1604- Add more variables to chapters 7 or 9?