3.1 Goal definitions¶

Goal definitions are the main part (heart) of the kbuild Makefile.These lines define the files to be built, any special compilationoptions, and any subdirectories to be entered recursively.

The most simple kbuild makefile contains one line:

Example:

obj-y += foo.o

This tells kbuild that there is one object in that directory, namedfoo.o. foo.o will be built from foo.c or foo.S.

If foo.o shall be built as a module, the variable obj-m is used.Therefore the following pattern is often used:

Example:

obj-$(CONFIG_FOO) += foo.o

$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).If CONFIG_FOO is neither y nor m, then the file will not be compilednor linked.

3.2 Built-in object goals - obj-y¶

The kbuild Makefile specifies object files for vmlinuxin the $(obj-y) lists. These lists depend on the kernelconfiguration.

Kbuild compiles all the $(obj-y) files. It then calls“$(AR) rcSTP” to merge these files into one built-in.a file.This is a thin archive without a symbol table. It will be laterlinked into vmlinux by scripts/link-vmlinux.sh

The order of files in $(obj-y) is significant. Duplicates inthe lists are allowed: the first instance will be linked intobuilt-in.a and succeeding instances will be ignored.

Link order is significant, because certain functions(module_init() / __initcall) will be called during boot in theorder they appear. So keep in mind that changing the linkorder may e.g. change the order in which your SCSIcontrollers are detected, and thus your disks are renumbered.

Example:

#drivers/isdn/i4l/Makefile# Makefile for the kernel ISDN subsystem and device drivers.# Each configuration option enables a list of files.obj-$(CONFIG_ISDN_I4L)         += isdn.oobj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

3.3 Loadable module goals - obj-m¶

$(obj-m) specifies object files which are built as loadablekernel modules.

A module may be built from one source file or several sourcefiles. In the case of one source file, the kbuild makefilesimply adds the file to $(obj-m).

Example:

#drivers/isdn/i4l/Makefileobj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to ‘m’

If a kernel module is built from several source files, you specifythat you want to build a module in the same way as above; however,kbuild needs to know which object files you want to build yourmodule from, so you have to tell it by setting a $(<module_name>-y)variable.

Example:

#drivers/isdn/i4l/Makefileobj-$(CONFIG_ISDN_I4L) += isdn.oisdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o

In this example, the module name will be isdn.o. Kbuild willcompile the objects listed in $(isdn-y) and then run“$(LD) -r” on the list of these files to generate isdn.o.

Due to kbuild recognizing $(<module_name>-y) for composite objects,you can use the value of aCONFIG_ symbol to optionally include anobject file as part of a composite object.

Example:

#fs/ext2/Makefileobj-$(CONFIG_EXT2_FS) += ext2.oext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \          namei.o super.o symlink.oext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \                                xattr_trusted.o

In this example, xattr.o, xattr_user.o and xattr_trusted.o are onlypart of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)evaluates to ‘y’.

Note: Of course, when you are building objects into the kernel,the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,kbuild will build an ext2.o file for you out of the individualparts and then link this into built-in.a, as you would expect.

3.4 Objects which export symbols¶

No special notation is required in the makefiles formodules exporting symbols.

3.5 Library file goals - lib-y¶

Objects listed with obj-* are used for modules, orcombined in a built-in.a for that specific directory.There is also the possibility to list objects that willbe included in a library, lib.a.All objects listed with lib-y are combined in a singlelibrary for that directory.Objects that are listed in obj-y and additionally listed inlib-y will not be included in the library, since they willbe accessible anyway.For consistency, objects listed in lib-m will be included in lib.a.

Note that the same kbuild makefile may list files to be built-inand to be part of a library. Therefore the same directorymay contain both a built-in.a and a lib.a file.

Example:

#arch/x86/lib/Makefilelib-y    := delay.o

This will create a library lib.a based on delay.o. For kbuild toactually recognize that there is a lib.a being built, the directoryshall be listed in libs-y.

See also “6.4 List directories to visit when descending”.

Use of lib-y is normally restricted tolib/ andarch/*/lib.

3.6 Descending down in directories¶

A Makefile is only responsible for building objects in its owndirectory. Files in subdirectories should be taken care of byMakefiles in these subdirs. The build system will automaticallyinvoke make recursively in subdirectories, provided you let it know ofthem.

To do so, obj-y and obj-m are used.ext2 lives in a separate directory, and the Makefile present in fs/tells kbuild to descend down using the following assignment.

Example:

#fs/Makefileobj-$(CONFIG_EXT2_FS) += ext2/

If CONFIG_EXT2_FS is set to either ‘y’ (built-in) or ‘m’ (modular)the corresponding obj- variable will be set, and kbuild will descenddown in the ext2 directory.

Kbuild uses this information not only to decide that it needs to visitthe directory, but also to decide whether or not to link objects fromthe directory into vmlinux.

When Kbuild descends into the directory with ‘y’, all built-in objectsfrom that directory are combined into the built-in.a, which will beeventually linked into vmlinux.

When Kbuild descends into the directory with ‘m’, in contrast, nothingfrom that directory will be linked into vmlinux. If the Makefile inthat directory specifies obj-y, those objects will be left orphan.It is very likely a bug of the Makefile or of dependencies in Kconfig.

It is good practice to use aCONFIG_ variable when assigning directorynames. This allows kbuild to totally skip the directory if thecorrespondingCONFIG_ option is neither ‘y’ nor ‘m’.

3.7 Compilation flags¶

ccflags-y, asflags-y and ldflags-y

These three flags apply only to the kbuild makefile in which theyare assigned. They are used for all the normal cc, as and ldinvocations happening during a recursive build.Note: Flags with the same behaviour were previously named:EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.They are still supported but their usage is deprecated.

ccflags-y specifies options for compiling with $(CC).

Example:

# drivers/acpi/acpica/Makefileccflags-y                       := -Os -D_LINUX -DBUILDING_ACPICAccflags-$(CONFIG_ACPI_DEBUG)    += -DACPI_DEBUG_OUTPUT

This variable is necessary because the top Makefile owns thevariable $(KBUILD_CFLAGS) and uses it for compilation flags for theentire tree.

asflags-y specifies assembler options.

Example:

#arch/sparc/kernel/Makefileasflags-y := -ansi

ldflags-y specifies options for linking with $(LD).

Example:

#arch/cris/boot/compressed/Makefileldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds

subdir-ccflags-y, subdir-asflags-y

The two flags listed above are similar to ccflags-y and asflags-y.The difference is that the subdir- variants have effect for the kbuildfile where they are present and all subdirectories.Options specified using subdir-* are added to the commandline beforethe options specified using the non-subdir variants.

Example:

subdir-ccflags-y := -Werror

ccflags-remove-y, asflags-remove-y

These flags are used to remove particular flags for the compiler,assembler invocations.

Example:

ccflags-remove-$(CONFIG_MCOUNT) += -pg

CFLAGS_$@, AFLAGS_$@

CFLAGS_$@ and AFLAGS_$@ only apply to commands in currentkbuild makefile.

$(CFLAGS_$@) specifies per-file options for $(CC). The $@part has a literal value which specifies the file that it is for.

CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@can re-add compiler flags that were removed by ccflags-remove-y.

Example:

# drivers/scsi/MakefileCFLAGS_aha152x.o =   -DAHA152X_STAT -DAUTOCONFCFLAGS_gdth.o    = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \                     -DGDTH_STATISTICS

These two lines specify compilation flags for aha152x.o and gdth.o.

$(AFLAGS_$@) is a similar feature for source files in assemblylanguages.

AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@can re-add assembler flags that were removed by asflags-remove-y.

Example:

# arch/arm/kernel/MakefileAFLAGS_head.o        := -DTEXT_OFFSET=$(TEXT_OFFSET)AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt

3.9 Dependency tracking¶

Kbuild tracks dependencies on the following:

1. All prerequisite files (both*.c and*.h)
2. CONFIG_ options used in all prerequisite files
3. Command-line used to compile target

Thus, if you change an option to $(CC) all affected files willbe re-compiled.

3.10 Special Rules¶

Special rules are used when the kbuild infrastructure doesnot provide the required support. A typical example isheader files generated during the build process.Another example are the architecture-specific Makefiles whichneed special rules to prepare boot images etc.

Special rules are written as normal Make rules.Kbuild is not executing in the directory where the Makefile islocated, so all special rules shall provide a relativepath to prerequisite files and target files.

Two variables are used when defining special rules:

$(src)

$(src) is a relative path which points to the directorywhere the Makefile is located. Always use $(src) whenreferring to files located in the src tree.

$(obj)

$(obj) is a relative path which points to the directorywhere the target is saved. Always use $(obj) whenreferring to generated files.

Example:

#drivers/scsi/Makefile$(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl        $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl

This is a special rule, following the normal syntaxrequired by make.

The target file depends on two prerequisite files. Referencesto the target file are prefixed with $(obj), referencesto prerequisites are referenced with $(src) (because they are notgenerated files).

$(kecho)

echoing information to user in a rule is often a good practicebut when execution “make -s” one does not expect to see any outputexcept for warnings/errors.To support this kbuild defines $(kecho) which will echo out thetext following $(kecho) to stdout except if “make -s” is used.

Example:

#arch/blackfin/boot/Makefile$(obj)/vmImage: $(obj)/vmlinux.gz        $(call if_changed,uimage)        @$(kecho) 'Kernel: $@ is ready'

3.11 $(CC) support functions¶

The kernel may be built with several different versions of$(CC), each supporting a unique set of features and options.kbuild provides basic support to check for valid options for $(CC).$(CC) is usually the gcc compiler, but other alternatives areavailable.

as-option

as-option is used to check if $(CC) – when used to compileassembler (*.S) files – supports the given option. An optionalsecond option may be specified if the first option is not supported.

Example:

#arch/sh/Makefilecflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)

In the above example, cflags-y will be assigned the option-Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).The second argument is optional, and if supplied will be usedif first argument is not supported.

as-instr

as-instr checks if the assembler reports a specific instructionand then outputs either option1 or option2C escapes are supported in the test instructionNote: as-instr-option uses KBUILD_AFLAGS for assembler options

cc-option

cc-option is used to check if $(CC) supports a given option, and ifnot supported to use an optional second option.

Example:

#arch/x86/Makefilecflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)

In the above example, cflags-y will be assigned the option-march=pentium-mmx if supported by $(CC), otherwise -march=i586.The second argument to cc-option is optional, and if omitted,cflags-y will be assigned no value if first option is not supported.Note: cc-option uses KBUILD_CFLAGS for $(CC) options

cc-option-yn

cc-option-yn is used to check if gcc supports a given optionand return ‘y’ if supported, otherwise ‘n’.

Example:

#arch/ppc/Makefilebiarch := $(call cc-option-yn, -m32)aflags-$(biarch) += -a32cflags-$(biarch) += -m32

In the above example, $(biarch) is set to y if $(CC) supports the -m32option. When $(biarch) equals ‘y’, the expanded variables $(aflags-y)and $(cflags-y) will be assigned the values -a32 and -m32,respectively.Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options

cc-disable-warning

cc-disable-warning checks if gcc supports a given warning and returnsthe commandline switch to disable it. This special function is needed,because gcc 4.4 and later accept any unknown -Wno-* option and onlywarn about it if there is another warning in the source file.

Example:

KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)

In the above example, -Wno-unused-but-set-variable will be added toKBUILD_CFLAGS only if gcc really accepts it.

cc-ifversion

cc-ifversion tests the version of $(CC) and equals the fourth parameterif version expression is true, or the fifth (if given) if the versionexpression is false.

Example:

#fs/reiserfs/Makefileccflags-y := $(call cc-ifversion, -lt, 0402, -O1)

In this example, ccflags-y will be assigned the value -O1 if the$(CC) version is less than 4.2.cc-ifversion takes all the shell operators:-eq, -ne, -lt, -le, -gt, and -geThe third parameter may be a text as in this example, but it may alsobe an expanded variable or a macro.

cc-cross-prefix

cc-cross-prefix is used to check if there exists a $(CC) in path withone of the listed prefixes. The first prefix where there exist aprefix$(CC) in the PATH is returned - and if no prefix$(CC) is foundthen nothing is returned.Additional prefixes are separated by a single space in thecall of cc-cross-prefix.This functionality is useful for architecture Makefiles that tryto set CROSS_COMPILE to well-known values but may have severalvalues to select between.It is recommended only to try to set CROSS_COMPILE if it is a crossbuild (host arch is different from target arch). And if CROSS_COMPILEis already set then leave it with the old value.

Example:

#arch/m68k/Makefileifneq ($(SUBARCH),$(ARCH))        ifeq ($(CROSS_COMPILE),)               CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)        endifendif

3.12 $(LD) support functions¶

ld-option

ld-option is used to check if $(LD) supports the supplied option.ld-option takes two options as arguments.The second argument is an optional option that can be used if thefirst option is not supported by $(LD).

Example:

#MakefileLDFLAGS_vmlinux += $(call ld-option, -X)

4.1 Simple Host Program¶

In some cases there is a need to compile and run a program on thecomputer where the build is running.The following line tells kbuild that the program bin2hex shall bebuilt on the build host.

Example:

hostprogs := bin2hex

Kbuild assumes in the above example that bin2hex is made from a singlec-source file named bin2hex.c located in the same directory asthe Makefile.

4.2 Composite Host Programs¶

Host programs can be made up based on composite objects.The syntax used to define composite objects for host programs issimilar to the syntax used for kernel objects.$(<executable>-objs) lists all objects used to link the finalexecutable.

Example:

#scripts/lxdialog/Makefilehostprogs     := lxdialoglxdialog-objs := checklist.o lxdialog.o

Objects with extension .o are compiled from the corresponding .cfiles. In the above example, checklist.c is compiled to checklist.oand lxdialog.c is compiled to lxdialog.o.

Finally, the two .o files are linked to the executable, lxdialog.Note: The syntax <executable>-y is not permitted for host-programs.

4.3 Using C++ for host programs¶

kbuild offers support for host programs written in C++. This wasintroduced solely to support kconfig, and is not recommendedfor general use.

Example:

#scripts/kconfig/Makefilehostprogs     := qconfqconf-cxxobjs := qconf.o

In the example above the executable is composed of the C++ fileqconf.cc - identified by $(qconf-cxxobjs).

If qconf is composed of a mixture of .c and .cc files, then anadditional line can be used to identify this.

Example:

#scripts/kconfig/Makefilehostprogs     := qconfqconf-cxxobjs := qconf.oqconf-objs    := check.o

4.4 Controlling compiler options for host programs¶

When compiling host programs, it is possible to set specific flags.The programs will always be compiled utilising $(HOSTCC) passedthe options specified in $(KBUILD_HOSTCFLAGS).To set flags that will take effect for all host programs createdin that Makefile, use the variable HOST_EXTRACFLAGS.

Example:

#scripts/lxdialog/MakefileHOST_EXTRACFLAGS += -I/usr/include/ncurses

To set specific flags for a single file the following constructionis used:

Example:

#arch/ppc64/boot/MakefileHOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)

It is also possible to specify additional options to the linker.

Example:

#scripts/kconfig/MakefileHOSTLDLIBS_qconf := -L$(QTDIR)/lib

When linking qconf, it will be passed the extra option“-L$(QTDIR)/lib”.

4.5 When host programs are actually built¶

Kbuild will only build host-programs when they are referencedas a prerequisite.This is possible in two ways:

1. List the prerequisite explicitly in a special rule.

Example:

#drivers/pci/Makefilehostprogs := gen-devlist$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist        ( cd $(obj); ./gen-devlist ) < $<

The target $(obj)/devlist.h will not be built before$(obj)/gen-devlist is updated. Note that references tothe host programs in special rules must be prefixed with $(obj).

2. Use always-y

When there is no suitable special rule, and the host programshall be built when a makefile is entered, the always-yvariable shall be used.

Example:

#scripts/lxdialog/Makefilehostprogs     := lxdialogalways-y      := $(hostprogs)

Kbuild provides the following shorthand for this:

hostprogs-always-y := lxdialog

This will tell kbuild to build lxdialog even if not referenced inany rule.

5.1 Simple Userspace Program¶

The following line tells kbuild that the program bpf-direct shall bebuilt for the target architecture.

Example:

userprogs := bpf-direct

Kbuild assumes in the above example that bpf-direct is made from asingle C source file named bpf-direct.c located in the same directoryas the Makefile.

5.2 Composite Userspace Programs¶

Userspace programs can be made up based on composite objects.The syntax used to define composite objects for userspace programs issimilar to the syntax used for kernel objects.$(<executable>-objs) lists all objects used to link the finalexecutable.

Example:

#samples/seccomp/Makefileuserprogs      := bpf-fancybpf-fancy-objs := bpf-fancy.o bpf-helper.o

Objects with extension .o are compiled from the corresponding .cfiles. In the above example, bpf-fancy.c is compiled to bpf-fancy.oand bpf-helper.c is compiled to bpf-helper.o.

Finally, the two .o files are linked to the executable, bpf-fancy.Note: The syntax <executable>-y is not permitted for userspace programs.

5.3 Controlling compiler options for userspace programs¶

When compiling userspace programs, it is possible to set specific flags.The programs will always be compiled utilising $(CC) passedthe options specified in $(KBUILD_USERCFLAGS).To set flags that will take effect for all userspace programs createdin that Makefile, use the variable userccflags.

Example:

# samples/seccomp/Makefileuserccflags += -I usr/include

To set specific flags for a single file the following constructionis used:

Example:

bpf-helper-userccflags += -I user/include

It is also possible to specify additional options to the linker.

Example:

# net/bpfilter/Makefilebpfilter_umh-userldflags += -static

When linking bpfilter_umh, it will be passed the extra option -static.

5.4 When userspace programs are actually built¶

Kbuild builds userspace programs only when told to do so.There are two ways to do this.

1. Add it as the prerequisite of another file

Example:

#net/bpfilter/Makefileuserprogs := bpfilter_umh$(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh

$(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o

2. Use always-y

Example:

userprogs := binderfs_examplealways-y := $(userprogs)

Kbuild provides the following shorthand for this:

userprogs-always-y := binderfs_example

This will tell Kbuild to build binderfs_example when it visits thisMakefile.

7.1 Set variables to tweak the build to the architecture¶

KBUILD_LDFLAGS

Generic $(LD) options

Flags used for all invocations of the linker.Often specifying the emulation is sufficient.

Example:

#arch/s390/MakefileKBUILD_LDFLAGS         := -m elf_s390

Note: ldflags-y can be used to further customisethe flags used. See section 3.7.

LDFLAGS_vmlinux

Options for $(LD) when linking vmlinux

LDFLAGS_vmlinux is used to specify additional flags to pass tothe linker when linking the final vmlinux image.LDFLAGS_vmlinux uses the LDFLAGS_$@ support.

Example:

#arch/x86/MakefileLDFLAGS_vmlinux := -e stext

OBJCOPYFLAGS

objcopy flags

When $(call if_changed,objcopy) is used to translate a .o file,the flags specified in OBJCOPYFLAGS will be used.$(call if_changed,objcopy) is often used to generate raw binaries onvmlinux.

Example:

#arch/s390/MakefileOBJCOPYFLAGS := -O binary#arch/s390/boot/Makefile$(obj)/image: vmlinux FORCE        $(call if_changed,objcopy)

In this example, the binary $(obj)/image is a binary version ofvmlinux. The usage of $(call if_changed,xxx) will be described later.

KBUILD_AFLAGS

Assembler flags

Default value - see top level MakefileAppend or modify as required per architecture.

Example:

#arch/sparc64/MakefileKBUILD_AFLAGS += -m64 -mcpu=ultrasparc

KBUILD_CFLAGS

$(CC) compiler flags

Default value - see top level MakefileAppend or modify as required per architecture.

Often, the KBUILD_CFLAGS variable depends on the configuration.

Example:

#arch/x86/boot/compressed/Makefilecflags-$(CONFIG_X86_32) := -march=i386cflags-$(CONFIG_X86_64) := -mcmodel=smallKBUILD_CFLAGS += $(cflags-y)

Many arch Makefiles dynamically run the target C compiler toprobe supported options:

#arch/x86/Makefile...cflags-$(CONFIG_MPENTIUMII)     += $(call cc-option,\                                -march=pentium2,-march=i686)...# Disable unit-at-a-time mode ...KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)...

The first example utilises the trick that a config option expandsto ‘y’ when selected.

KBUILD_AFLAGS_KERNEL

Assembler options specific for built-in

$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compileresident kernel code.

KBUILD_AFLAGS_MODULE

Assembler options specific for modules

$(KBUILD_AFLAGS_MODULE) is used to add arch-specific options thatare used for assembler.

From commandline AFLAGS_MODULE shall be used (see kbuild.rst).

KBUILD_CFLAGS_KERNEL

$(CC) options specific for built-in

$(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compileresident kernel code.

KBUILD_CFLAGS_MODULE

Options for $(CC) when building modules

$(KBUILD_CFLAGS_MODULE) is used to add arch-specific options thatare used for $(CC).From commandline CFLAGS_MODULE shall be used (see kbuild.rst).

KBUILD_LDFLAGS_MODULE

Options for $(LD) when linking modules

$(KBUILD_LDFLAGS_MODULE) is used to add arch-specific optionsused when linking modules. This is often a linker script.

From commandline LDFLAGS_MODULE shall be used (see kbuild.rst).

KBUILD_LDS

The linker script with full path. Assigned by the top-level Makefile.

KBUILD_LDS_MODULE

The module linker script with full path. Assigned by the top-levelMakefile and additionally by the arch Makefile.

KBUILD_VMLINUX_OBJS

All object files for vmlinux. They are linked to vmlinux in the sameorder as listed in KBUILD_VMLINUX_OBJS.

KBUILD_VMLINUX_LIBS

All .a “lib” files for vmlinux. KBUILD_VMLINUX_OBJS andKBUILD_VMLINUX_LIBS together specify all the object files used tolink vmlinux.

7.2 Add prerequisites to archheaders¶

The archheaders: rule is used to generate header files thatmay be installed into user space by “make header_install”.

It is run before “make archprepare” when run on thearchitecture itself.

7.3 Add prerequisites to archprepare¶

The archprepare: rule is used to list prerequisites that need to bebuilt before starting to descend down in the subdirectories.This is usually used for header files containing assembler constants.

Example:

#arch/arm/Makefilearchprepare: maketools

In this example, the file target maketools will be processedbefore descending down in the subdirectories.See also chapter XXX-TODO that describes how kbuild supportsgenerating offset header files.

7.4 List directories to visit when descending¶

An arch Makefile cooperates with the top Makefile to define variableswhich specify how to build the vmlinux file. Note that there is nocorresponding arch-specific section for modules; the module-buildingmachinery is all architecture-independent.

head-y, init-y, core-y, libs-y, drivers-y, net-y

$(head-y) lists objects to be linked first in vmlinux.

$(libs-y) lists directories where a lib.a archive can be located.

The rest list directories where a built-in.a object file can belocated.

$(init-y) objects will be located after $(head-y).

Then the rest follows in this order:

$(core-y), $(libs-y), $(drivers-y) and $(net-y).

The top level Makefile defines values for all generic directories,and arch/$(ARCH)/Makefile only adds architecture-specificdirectories.

Example:

#arch/sparc64/Makefilecore-y += arch/sparc64/kernel/libs-y += arch/sparc64/prom/ arch/sparc64/lib/drivers-$(CONFIG_OPROFILE)  += arch/sparc64/oprofile/

7.5 Architecture-specific boot images¶

An arch Makefile specifies goals that take the vmlinux file, compressit, wrap it in bootstrapping code, and copy the resulting filessomewhere. This includes various kinds of installation commands.The actual goals are not standardized across architectures.

It is common to locate any additional processing in a boot/directory below arch/$(ARCH)/.

Kbuild does not provide any smart way to support building atarget specified in boot/. Therefore arch/$(ARCH)/Makefile shallcall make manually to build a target in boot/.

The recommended approach is to include shortcuts inarch/$(ARCH)/Makefile, and use the full path when calling downinto the arch/$(ARCH)/boot/Makefile.

Example:

#arch/x86/Makefileboot := arch/x86/bootbzImage: vmlinux        $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@

“$(Q)$(MAKE) $(build)=<dir>” is the recommended way to invokemake in a subdirectory.

There are no rules for naming architecture-specific targets,but executing “make help” will list all relevant targets.To support this, $(archhelp) must be defined.

Example:

#arch/x86/Makefiledefine archhelp  echo  '* bzImage      - Image (arch/$(ARCH)/boot/bzImage)'endif

When make is executed without arguments, the first goal encounteredwill be built. In the top level Makefile the first goal presentis all:.An architecture shall always, per default, build a bootable image.In “make help”, the default goal is highlighted with a ‘*’.Add a new prerequisite to all: to select a default goal differentfrom vmlinux.

Example:

#arch/x86/Makefileall: bzImage

When “make” is executed without arguments, bzImage will be built.

7.6 Building non-kbuild targets¶

extra-y

extra-y specifies additional targets created in the currentdirectory, in addition to any targets specified byobj-*.

Listing all targets in extra-y is required for two purposes:

1. Enable kbuild to check changes in command lines
   • When $(call if_changed,xxx) is used
2. kbuild knows what files to delete during “make clean”

Example:

#arch/x86/kernel/Makefileextra-y := head.o init_task.o

In this example, extra-y is used to list object files thatshall be built, but shall not be linked as part of built-in.a.

7.7 Commands useful for building a boot image¶

Kbuild provides a few macros that are useful when building aboot image.

if_changed

if_changed is the infrastructure used for the following commands.

Usage:

target: source(s) FORCE        $(call if_changed,ld/objcopy/gzip/...)

When the rule is evaluated, it is checked to see if any filesneed an update, or the command line has changed since the lastinvocation. The latter will force a rebuild if any optionsto the executable have changed.Any target that utilises if_changed must be listed in $(targets),otherwise the command line check will fail, and the target willalways be built.Assignments to $(targets) are without $(obj)/ prefix.if_changed may be used in conjunction with custom commands asdefined in 7.8 “Custom kbuild commands”.

Note: It is a typical mistake to forget the FORCE prerequisite.Another common pitfall is that whitespace is sometimessignificant; for instance, the below will fail (note the extra spaceafter the comma):

target: source(s) FORCE

WRONG! $(call if_changed, ld/objcopy/gzip/…)

Note:

if_changed should not be used more than once per target.It stores the executed command in a corresponding .cmd

file and multiple calls would result in overwrites andunwanted results when the target is up to date and only thetests on changed commands trigger execution of commands.

ld

Link target. Often, LDFLAGS_$@ is used to set specific options to ld.

Example:

#arch/x86/boot/MakefileLDFLAGS_bootsect := -Ttext 0x0 -s --oformat binaryLDFLAGS_setup    := -Ttext 0x0 -s --oformat binary -e begtexttargets += setup setup.o bootsect bootsect.o$(obj)/setup $(obj)/bootsect: %: %.o FORCE        $(call if_changed,ld)

In this example, there are two possible targets, requiring differentoptions to the linker. The linker options are specified using theLDFLAGS_$@ syntax - one for each potential target.$(targets) are assigned all potential targets, by which kbuild knowsthe targets and will:

1. check for commandline changes
2. delete target during make clean

The “: %: %.o” part of the prerequisite is a shorthand thatfrees us from listing the setup.o and bootsect.o files.

Note:

It is a common mistake to forget the “targets :=” assignment,resulting in the target file being recompiled for noobvious reason.

objcopy

Copy binary. Uses OBJCOPYFLAGS usually specified inarch/$(ARCH)/Makefile.OBJCOPYFLAGS_$@ may be used to set additional options.

gzip

Compress target. Use maximum compression to compress target.

Example:

#arch/x86/boot/compressed/Makefile$(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE        $(call if_changed,gzip)

dtc

Create flattened device tree blob object suitable for linkinginto vmlinux. Device tree blobs linked into vmlinux are placedin an init section in the image. Platform codemust copy theblob to non-init memory prior to calling unflatten_device_tree().

To use this command, simply add*.dtb into obj-y or targets, or makesome other target depend on%.dtb

A central rule exists to create$(obj)/%.dtb from$(src)/%.dts;architecture Makefiles do no need to explicitly write out that rule.

Example:

targets += $(dtb-y)DTC_FLAGS ?= -p 1024

7.8 Custom kbuild commands¶

When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthandof a command is normally displayed.To enable this behaviour for custom commands kbuild requirestwo variables to be set:

quiet_cmd_<command>     - what shall be echoed      cmd_<command>     - the command to execute

Example:

#quiet_cmd_image = BUILD   $@      cmd_image = $(obj)/tools/build $(BUILDFLAGS) \                                     $(obj)/vmlinux.bin > $@targets += bzImage$(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE        $(call if_changed,image)        @echo 'Kernel: $@ is ready'

When updating the $(obj)/bzImage target, the line:

BUILD arch/x86/boot/bzImage

will be displayed with “make KBUILD_VERBOSE=0”.

7.9 Preprocessing linker scripts¶

When the vmlinux image is built, the linker scriptarch/$(ARCH)/kernel/vmlinux.lds is used.The script is a preprocessed variant of the file vmlinux.lds.Slocated in the same directory.kbuild knows .lds files and includes a rule*lds.S ->*lds.

Example:

#arch/x86/kernel/Makefileextra-y := vmlinux.lds#Makefileexport CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)

The assignment to extra-y is used to tell kbuild to build thetarget vmlinux.lds.The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use thespecified options when building the target vmlinux.lds.

When building the*.lds target, kbuild uses the variables:

KBUILD_CPPFLAGS : Set in top-level Makefilecppflags-y      : May be set in the kbuild makefileCPPFLAGS_$(@F)  : Target-specific flags.                Note that the full filename is used in this                assignment.

The kbuild infrastructure for*lds files is used in severalarchitecture-specific files.

7.10 Generic header files¶

The directory include/asm-generic contains the header filesthat may be shared between individual architectures.The recommended approach how to use a generic header file isto list the file in the Kbuild file.See “8.2 generic-y” for further info on syntax etc.

7.11 Post-link pass¶

If the file arch/xxx/Makefile.postlink exists, this makefilewill be invoked for post-link objects (vmlinux and modules.ko)for architectures to run post-link passes on. Must also handlethe clean target.

This pass runs after kallsyms generation. If the architectureneeds to modify symbol locations, rather than manipulate thekallsyms, it may be easier to add another postlink target for.tmp_vmlinux? targets to be called from link-vmlinux.sh.

For example, powerpc uses this to check relocation sanity ofthe linked vmlinux file.

8 Kbuild syntax for exported headers¶

The kernel includes a set of headers that is exported to userspace.Many headers can be exported as-is but other headers require aminimal pre-processing before they are ready for user-space.The pre-processing does:

• drop kernel-specific annotations
• drop include of compiler.h
• drop all sections that are kernel internal (guarded byifdef __KERNEL__)

All headers under include/uapi/, include/generated/uapi/,arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/are exported.

A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ andarch/<arch>/include/asm/ to list asm files coming from asm-generic.See subsequent chapter for the syntax of the Kbuild file.

8.1 no-export-headers¶

no-export-headers is essentially used by include/uapi/linux/Kbuild toavoid exporting specific headers (e.g. kvm.h) on architectures that donot support it. It should be avoided as much as possible.

8.2 generic-y¶

If an architecture uses a verbatim copy of a header frominclude/asm-generic then this is listed in the filearch/$(ARCH)/include/asm/Kbuild like this:

Example:

#arch/x86/include/asm/Kbuildgeneric-y += termios.hgeneric-y += rtc.h

During the prepare phase of the build a wrapper includefile is generated in the directory:

arch/$(ARCH)/include/generated/asm

When a header is exported where the architecture usesthe generic header a similar wrapper is generated as partof the set of exported headers in the directory:

usr/include/asm

The generated wrapper will in both cases look like the following:

Example: termios.h:

#include <asm-generic/termios.h>

8.3 generated-y¶

If an architecture generates other header files alongside generic-ywrappers, generated-y specifies them.

This prevents them being treated as stale asm-generic wrappers andremoved.

Example:

#arch/x86/include/asm/Kbuildgenerated-y += syscalls_32.h

8.4 mandatory-y¶

mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuildto define the minimum set of ASM headers that all architectures must have.

This works like optional generic-y. If a mandatory header is missingin arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generatea wrapper of the asm-generic one.