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.

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

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.

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 alsoList directories to visit when descending.

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

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.

Kbuild also supports dedicated syntax, subdir-y and subdir-m, fordescending into subdirectories. It is a good fit when you know theydo not contain kernel-space objects at all. A typical usage is to letKbuild descend into subdirectories to build tools.

Examples:

# scripts/Makefilesubdir-$(CONFIG_GCC_PLUGINS) += gcc-pluginssubdir-$(CONFIG_MODVERSIONS) += genksymssubdir-$(CONFIG_SECURITY_SELINUX) += selinux

Unlike obj-y/m, subdir-y/m does not need the trailing slash since thissyntax is always used for directories.

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”.

Non-builtin vmlinux targets - extra-y¶

extra-y specifies targets which are needed for building vmlinux,but not combined into built-in.a.

Examples are:

1. vmlinux linker script

   The linker script for vmlinux is located atarch/$(SRCARCH)/kernel/vmlinux.lds

Example:

# arch/x86/kernel/Makefileextra-y       += vmlinux.lds

extra-y is now deprecated because this is equivalent to:

always-$(KBUILD_BUILTIN) += vmlinux.lds

$(extra-y) should only contain targets needed for vmlinux.

Kbuild skips extra-y when vmlinux is apparently not a final goal.(e.g.makemodules, or building external modules)

If you intend to build targets unconditionally, always-y (explainedin the next section) is the correct syntax to use.

Always built goals - always-y¶

always-y specifies targets which are literally always built whenKbuild visits the Makefile.

Example:

# ./Kbuildoffsets-file := include/generated/asm-offsets.halways-y += $(offsets-file)

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.

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 $(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 -DAUTOCONF

This line specify compilation flags for aha152x.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

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.

Custom Rules¶

Custom 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 custom rules to prepare boot images etc.

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

Two variables are used when defining custom rules:

$(src)

$(src) is the directory where the Makefile is located. Always use $(src) whenreferring to files located in the src tree.

$(obj)

$(obj) is the directory where the target is saved. Always use $(obj) whenreferring to generated files. Use $(obj) for pattern rules that need to workfor both generated files and real sources (VPATH will help to find theprerequisites not only in the object tree but also in the source tree).

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 custom 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).

$(srcroot)

$(srcroot) refers to the root of the source you are building, which can beeither the kernel source or the external modules source, depending on whetherKBUILD_EXTMOD is set. This can be either a relative or an absolute path, butif KBUILD_ABS_SRCTREE=1 is set, it is always an absolute path.

$(srctree)

$(srctree) refers to the root of the kernel source tree. When building thekernel, this is the same as $(srcroot).

$(objtree)

$(objtree) refers to the root of the kernel object tree. It is. whenbuilding the kernel, but it is different when building external modules.

$(kecho)

echoing information to user in a rule is often a good practicebut when executionmake-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 ifmake-s is used.

Example:

# arch/arm/Makefile$(BOOT_TARGETS): vmlinux        $(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@        @$(kecho) '  Kernel: $(boot)/$@ is ready'

When kbuild is executing with KBUILD_VERBOSE unset, 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:

# lib/Makefilequiet_cmd_crc32 = GEN     $@      cmd_crc32 = $< > $@$(obj)/crc32table.h: $(obj)/gen_crc32table        $(call cmd,crc32)

When updating the $(obj)/crc32table.h target, the line:

GEN     lib/crc32table.h

will be displayed withmakeKBUILD_VERBOSE=.

Command change detection¶

When the rule is evaluated, timestamps are compared between the targetand its prerequisite files. GNU Make updates the target when any of theprerequisites is newer than that.

The target should be rebuilt also when the command line has changedsince the last invocation. This is not supported by Make itself, soKbuild achieves this by a kind of meta-programming.

if_changed is the macro used for this purpose, in the following form:

quiet_cmd_<command> = ...      cmd_<command> = ...<target>: <source(s)> FORCE        $(call if_changed,<command>)

Any target that utilizes if_changed must be listed in $(targets),otherwise the command line check will fail, and the target willalways be built.

If the target is already listed in the recognized syntax such asobj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuildautomatically adds it to $(targets). Otherwise, the target must beexplicitly added to $(targets).

Assignments to $(targets) are without $(obj)/ prefix. if_changed may beused in conjunction with custom rules as defined inCustom Rules.

Note: It is a typical mistake to forget the FORCE prerequisite.Another common pitfall is that whitespace is sometimes significant; forinstance, the below will fail (note the extra space after the comma):

target: source(s) FORCE

WRONG! $(call if_changed, objcopy)

Note:

if_changed should not be used more than once per target.It stores the executed command in a corresponding .cmdfile 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.

$(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 $(CC) 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 $(CC) 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 $(CC) really accepts it.

gcc-min-version

gcc-min-version tests if the value of $(CONFIG_GCC_VERSION) is greater thanor equal to the provided value and evaluates to y if so.

Example:

cflags-$(call gcc-min-version, 110100) := -foo

In this example, cflags-y will be assigned the value -foo if $(CC) is gcc and$(CONFIG_GCC_VERSION) is >= 11.1.

clang-min-version

clang-min-version tests if the value of $(CONFIG_CLANG_VERSION) is greaterthan or equal to the provided value and evaluates to y if so.

Example:

cflags-$(call clang-min-version, 110000) := -foo

In this example, cflags-y will be assigned the value -foo if $(CC) is clangand $(CONFIG_CLANG_VERSION) is >= 11.0.0.

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

$(RUSTC) support functions¶

rustc-min-version

rustc-min-version tests if the value of $(CONFIG_RUSTC_VERSION) is greaterthan or equal to the provided value and evaluates to y if so.

Example:

rustflags-$(call rustc-min-version, 108500) := -Cfoo

In this example, rustflags-y will be assigned the value -Cfoo if$(CONFIG_RUSTC_VERSION) is >= 1.85.0.

$(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)

Script invocation¶

Make rules may invoke scripts to build the kernel. The rules shallalways provide the appropriate interpreter to execute the script. Theyshall not rely on the execute bits being set, and shall not invoke thescript directly. For the convenience of manual script invocation, suchas invoking ./scripts/checkpatch.pl, it is recommended to set executebits on the scripts nonetheless.

Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL),and $(PYTHON3) to refer to interpreters for the respectivescripts.

Example:

#Makefilecmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \        $(KERNELRELEASE)

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.

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.

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

Using Rust for host programs¶

Kbuild offers support for host programs written in Rust. However,since a Rust toolchain is not mandatory for kernel compilation,it may only be used in scenarios where Rust is required to beavailable (e.g. whenCONFIG_RUST is enabled).

Example:

hostprogs     := targettarget-rust   := y

Kbuild will compiletarget usingtarget.rs as the crate root,located in the same directory as theMakefile. The crate mayconsist of several source files (seesamples/rust/hostprogs).

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.

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 custom 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 custom rules must be prefixed with $(obj).

2. Use always-y

   When there is no suitable custom 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.

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.

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.

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

To specify libraries linked to a userspace program, you can use<executable>-userldlibs. Theuserldlibs syntax specifies librarieslinked to all userspace programs created in the current Makefile.

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

From command line,USERCFLAGS and USERLDFLAGS will also be used.

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.

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. SeeNon-builtin vmlinux targets - extra-y.

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 Makefile.

Append or modify as required per architecture.

Example:

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

KBUILD_CFLAGS

$(CC) compiler flags

Default value - see top level Makefile.

Append 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_RUSTFLAGS

$(RUSTC) compiler flags

Default value - see top level Makefile.

Append or modify as required per architecture.

Often, the KBUILD_RUSTFLAGS variable depends on the configuration.

Note that target specification file generation (for--target)is handled inscripts/generate_rust_target.rs.

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 (seeKbuild).

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 (seeKbuild).

KBUILD_RUSTFLAGS_KERNEL

$(RUSTC) options specific for built-in

$(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used tocompile resident kernel code.

KBUILD_RUSTFLAGS_MODULE

Options for $(RUSTC) when building modules

$(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options thatare used for $(RUSTC).

From commandline RUSTFLAGS_MODULE shall be used (seeKbuild).

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 (seeKbuild).

KBUILD_LDS

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

KBUILD_VMLINUX_OBJS

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

The objects listed in scripts/head-object-list.txt are exceptions;they are placed before the other objects.

KBUILD_VMLINUX_LIBS

All .alib files for vmlinux. KBUILD_VMLINUX_OBJS andKBUILD_VMLINUX_LIBS together specify all the object files used tolink vmlinux.

Add prerequisites to archheaders¶

The archheaders: rule is used to generate header files thatmay be installed into user space bymakeheader_install.

It is run beforemakearchprepare when run on thearchitecture itself.

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.

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.

core-y, libs-y, drivers-y

$(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.

Then the rest follows in this order:

$(core-y), $(libs-y), $(drivers-y)

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

Example:

# arch/sparc/Makefilecore-y                 += arch/sparc/libs-y                 += arch/sparc/prom/libs-y                 += arch/sparc/lib/drivers-$(CONFIG_PM) += arch/sparc/power/

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/$(SRCARCH)/.

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

The recommended approach is to include shortcuts inarch/$(SRCARCH)/Makefile, and use the full path when calling downinto the arch/$(SRCARCH)/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 executingmakehelp will list all relevant targets.To support this, $(archhelp) must be defined.

Example:

#arch/x86/Makefiledefine archhelp  echo  '* bzImage      - Compressed kernel image (arch/x86/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.Inmakehelp, 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

Whenmake is executed without arguments, bzImage will be built.

Commands useful for building a boot image¶

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

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 thetargets:= assignment,resulting in the target file being recompiled for noobvious reason.

objcopy

Copy binary. Uses OBJCOPYFLAGS usually specified inarch/$(SRCARCH)/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 callingunflatten_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

Preprocessing linker scripts¶

When the vmlinux image is built, the linker scriptarch/$(SRCARCH)/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

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.

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.

Seegeneric-y for further info on syntax etc.

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.

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.

generic-y¶

If an architecture uses a verbatim copy of a header frominclude/asm-generic then this is listed in the filearch/$(SRCARCH)/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/$(SRCARCH)/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>

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

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/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automaticallygenerate a wrapper of the asm-generic one.