=== 1 Overview
=== 2 Who does what
- === 3 The kbuild Makefiles
+ === 3 The kbuild files
--- 3.1 Goal definitions
--- 3.2 Built-in object goals - obj-y
--- 3.3 Loadable module goals - obj-m
--- 3.8 Command line dependency
--- 3.9 Dependency tracking
--- 3.10 Special Rules
+ --- 3.11 $(CC) support functions
=== 4 Host Program support
--- 4.1 Simple Host Program
--- 4.4 Using C++ for host programs
--- 4.5 Controlling compiler options for host programs
--- 4.6 When host programs are actually built
+ --- 4.7 Using hostprogs-$(CONFIG_FOO)
=== 5 Kbuild clean infrastructure
=== 6 Architecture Makefiles
--- 6.1 Set variables to tweak the build to the architecture
- --- 6.2 Add prerequisites to prepare:
+ --- 6.2 Add prerequisites to archprepare:
--- 6.3 List directories to visit when descending
--- 6.4 Architecture specific boot images
--- 6.5 Building non-kbuild targets
--- 6.6 Commands useful for building a boot image
--- 6.7 Custom kbuild commands
+ --- 6.8 Preprocessing linker scripts
=== 7 Kbuild Variables
=== 8 Makefile language
This document is aimed towards normal developers and arch developers.
-=== 3 The kbuild Makefiles
+=== 3 The kbuild files
Most Makefiles within the kernel are kbuild Makefiles that use the
kbuild infrastructure. This chapter introduce the syntax used in the
kbuild makefiles.
+The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
+be used and if both a 'Makefile' and a 'Kbuild' file exists then the 'Kbuild'
+file will be used.
Section 3.1 "Goal definitions" is a quick intro, further chapters provide
more details, with real examples.
to prerequisites are referenced with $(src) (because they are not
generated files).
+--- 3.11 $(CC) support functions
+
+ The kernel may be build with several different versions of
+ $(CC), each supporting a unique set of features and options.
+ kbuild provide basic support to check for valid options for $(CC).
+ $(CC) is useally the gcc compiler, but other alternatives are
+ available.
+
+ as-option
+ as-option is used to check if $(CC) when used to compile
+ assembler (*.S) files supports the given option. An optional
+ second option may be specified if first option are not supported.
+
+ Example:
+ #arch/sh/Makefile
+ cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
+
+ In the above example cflags-y will be assinged the the option
+ -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
+ The second argument is optional, and if supplied will be used
+ if first argument is not supported.
+
+ cc-option
+ cc-option is used to check if $(CC) support a given option, and not
+ supported to use an optional second option.
+
+ Example:
+ #arch/i386/Makefile
+ cflags-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.
+
+ cc-option-yn
+ cc-option-yn is used to check if gcc supports a given option
+ and return 'y' if supported, otherwise 'n'.
+
+ Example:
+ #arch/ppc/Makefile
+ biarch := $(call cc-option-yn, -m32)
+ aflags-$(biarch) += -a32
+ cflags-$(biarch) += -m32
+
+ In the above example $(biarch) is set to y if $(CC) supports the -m32
+ option. When $(biarch) equals to y the expanded variables $(aflags-y)
+ and $(cflags-y) will be assigned the values -a32 and -m32.
+
+ cc-option-align
+ gcc version >= 3.0 shifted type of options used to speify
+ alignment of functions, loops etc. $(cc-option-align) whrn used
+ as prefix to the align options will select the right prefix:
+ gcc < 3.00
+ cc-option-align = -malign
+ gcc >= 3.00
+ cc-option-align = -falign
+
+ Example:
+ CFLAGS += $(cc-option-align)-functions=4
+
+ In the above example the option -falign-functions=4 is used for
+ gcc >= 3.00. For gcc < 3.00 -malign-functions=4 is used.
+
+ cc-version
+ cc-version return a numerical version of the $(CC) compiler version.
+ The format is <major><minor> where both are two digits. So for example
+ gcc 3.41 would return 0341.
+ cc-version is useful when a specific $(CC) version is faulty in one
+ area, for example the -mregparm=3 were broken in some gcc version
+ even though the option was accepted by gcc.
+
+ Example:
+ #arch/i386/Makefile
+ cflags-y += $(shell \
+ if [ $(call cc-version) -ge 0300 ] ; then \
+ echo "-mregparm=3"; fi ;)
+
+ In the above example -mregparm=3 is only used for gcc version greater
+ than or equal to gcc 3.0.
+
+ cc-ifversion
+ cc-ifversion test the version of $(CC) and equals last argument if
+ version expression is true.
+
+ Example:
+ #fs/reiserfs/Makefile
+ EXTRA_CFLAGS := $(call cc-ifversion, -lt, 0402, -O1)
+
+ In this example EXTRA_CFLAGS 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 -ge
+ The third parameter may be a text as in this example, but it may also
+ be an expanded variable or a macro.
+
=== 4 Host Program support
Two steps are required in order to use a host executable.
The first step is to tell kbuild that a host program exists. This is
-done utilising the variable host-prog.
+done utilising the variable hostprogs-y.
The second step is to add an explicit dependency to the executable.
This can be done in two ways. Either add the dependency in a rule,
built on the build host.
Example:
- host-progs := bin2hex
+ hostprogs-y := bin2hex
Kbuild assumes in the above example that bin2hex is made from a single
c-source file named bin2hex.c located in the same directory as
Example:
#scripts/lxdialog/Makefile
- host-progs := lxdialog
+ hostprogs-y := lxdialog
lxdialog-objs := checklist.o lxdialog.o
Objects with extension .o are compiled from the corresponding .c
Example:
#scripts/kconfig/Makefile
- host-progs := conf
+ hostprogs-y := conf
conf-objs := conf.o libkconfig.so
libkconfig-objs := expr.o type.o
Example:
#scripts/kconfig/Makefile
- host-progs := qconf
+ hostprogs-y := qconf
qconf-cxxobjs := qconf.o
In the example above the executable is composed of the C++ file
Example:
#scripts/kconfig/Makefile
- host-progs := qconf
+ hostprogs-y := qconf
qconf-cxxobjs := qconf.o
qconf-objs := check.o
Example:
#drivers/pci/Makefile
- host-progs := gen-devlist
+ hostprogs-y := gen-devlist
$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
( cd $(obj); ./gen-devlist ) < $<
Example:
#scripts/lxdialog/Makefile
- host-progs := lxdialog
- always := $(host-progs)
+ hostprogs-y := lxdialog
+ always := $(hostprogs-y)
This will tell kbuild to build lxdialog even if not referenced in
any rule.
+--- 4.7 Using hostprogs-$(CONFIG_FOO)
+
+ A typcal pattern in a Kbuild file lok like this:
+
+ Example:
+ #scripts/Makefile
+ hostprogs-$(CONFIG_KALLSYMS) += kallsyms
+
+ Kbuild knows about both 'y' for built-in and 'm' for module.
+ So if a config symbol evaluate to 'm', kbuild will still build
+ the binary. In other words Kbuild handle hostprogs-m exactly
+ like hostprogs-y. But only hostprogs-y is recommend used
+ when no CONFIG symbol are involved.
+
=== 5 Kbuild clean infrastructure
"make clean" deletes most generated files in the src tree where the kernel
is compiled. This includes generated files such as host programs.
-Kbuild knows targets listed in $(host-progs), $(always), $(extra-y) and
-$(targets). They are all deleted during "make clean".
+Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
+$(extra-y) and $(targets). They are all deleted during "make clean".
Files matching the patterns "*.[oas]", "*.ko", plus some additional files
generated by kbuild are deleted all over the kernel src tree when
"make clean" is executed.
clean-files := devlist.h classlist.h
When executing "make clean", the two files "devlist.h classlist.h" will
-be deleted. Kbuild knows that files specified by $(clean-files) are
-located in the same directory as the makefile.
+be deleted. Kbuild will assume files to be in same relative directory as the
+Makefile except if an absolute path is specified (path starting with '/').
+
+To delete a directory hirachy use:
+ Example:
+ #scripts/package/Makefile
+ clean-dirs := $(objtree)/debian/
+
+This will delete the directory debian, including all subdirectories.
+Kbuild will assume the directories to be in the same relative path as the
+Makefile if no absolute path is specified (path does not start with '/').
Usually kbuild descends down in subdirectories due to "obj-* := dir/",
but in the architecture makefiles where the kbuild infrastructure
#arch/i386/Makefile
LDFLAGS_vmlinux := -e stext
- LDFLAGS_BLOB Options for $(LD) when linking the initramfs blob
-
- The image used for initramfs is made during the build process.
- LDFLAGS_BLOB is used to specify additional flags to be used when
- creating the initramfs_data.o file.
- Example:
- #arch/i386/Makefile
- LDFLAGS_BLOB := --format binary --oformat elf32-i386
-
OBJCOPYFLAGS objcopy flags
When $(call if_changed,objcopy) is used to translate a .o file,
probe supported options:
#arch/i386/Makefile
- check_gcc = $(shell if $(CC) $(1) -S -o /dev/null -xc \
- /dev/null\ > /dev/null 2>&1; then echo "$(1)"; \
- else echo "$(2)"; fi)
- cflags-$(CONFIG_MCYRIXIII) += $(call check_gcc,\
- -march=c3,-march=i486)
- CFLAGS += $(cflags-y)
+ ...
+ cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\
+ -march=pentium2,-march=i686)
+ ...
+ # Disable unit-at-a-time mode ...
+ CFLAGS += $(call cc-option,-fno-unit-at-a-time)
+ ...
- The above examples both utilise the trick that a config option expands
+
+ The first examples utilises the trick that a config option expands
to 'y' when selected.
CFLAGS_KERNEL $(CC) options specific for built-in
for loadable kernel modules.
---- 6.2 Add prerequisites to prepare:
+--- 6.2 Add prerequisites to archprepare:
- The prepare: rule is used to list prerequisites that needs to be
+ The archprepare: rule is used to list prerequisites that needs to be
built before starting to descend down in the subdirectories.
This is usual header files containing assembler constants.
Example:
- #arch/s390/Makefile
- prepare: include/asm-$(ARCH)/offsets.h
+ #arch/arm/Makefile
+ archprepare: maketools
- In this example the file include/asm-$(ARCH)/offsets.h will
- be built before descending down in the subdirectories.
+ In this example the file target maketools will be processed
+ before descending down in the subdirectories.
See also chapter XXX-TODO that describe how kbuild supports
generating offset header files.
Assignments to $(targets) are without $(obj)/ prefix.
if_changed may be used in conjunction with custom commands as
defined in 6.7 "Custom kbuild commands".
+
Note: It is a typical mistake to forget the FORCE prerequisite.
+ Another common pitfall is that whitespace is sometimes
+ significant; for instance, the below will fail (note the extra space
+ after the comma):
+ target: source(s) FORCE
+ #WRONG!# $(call if_changed, ld/objcopy/gzip)
ld
Link target. Often LDFLAGS_$@ is used to set specific options to ld.
will be displayed with "make KBUILD_VERBOSE=0".
+--- 6.8 Preprocessing linker scripts
+
+ When the vmlinux image is build the linker script:
+ arch/$(ARCH)/kernel/vmlinux.lds is used.
+ The script is a preprocessed variant of the file vmlinux.lds.S
+ located in the same directory.
+ kbuild knows .lds file and includes a rule *lds.S -> *lds.
+
+ Example:
+ #arch/i386/kernel/Makefile
+ always := vmlinux.lds
+
+ #Makefile
+ export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
+
+ The assigment to $(always) is used to tell kbuild to build the
+ target: vmlinux.lds.
+ The assignment to $(CPPFLAGS_vmlinux.lds) tell kbuild to use the
+ specified options when building the target vmlinux.lds.
+
+ When building the *.lds target kbuild used the variakles:
+ CPPFLAGS : Set in top-level Makefile
+ EXTRA_CPPFLAGS : May be set in the kbuild makefile
+ CPPFLAGS_$(@F) : Target specific flags.
+ Note that the full filename is used in this
+ assignment.
+
+ The kbuild infrastructure for *lds file are used in several
+ architecture specific files.
+
+
=== 7 Kbuild Variables
The top Makefile exports the following variables:
git://git.onelab.eu / linux-2.6.git / blobdiff