makefiles.txt

	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.


--- 6.4 List directories to visit when descending

	An arch Makefile cooperates with the top Makefile to define variables
	which specify how to build the vmlinux file.  Note that there is no
	corresponding arch-specific section for modules; the module-building
	machinery 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.o object file can be
	located.

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

	Example:
		#arch/sparc64/Makefile
		core-y += arch/sparc64/kernel/
		libs-y += arch/sparc64/prom/ arch/sparc64/lib/
		drivers-$(CONFIG_OPROFILE)  += arch/sparc64/oprofile/


--- 6.5 Architecture-specific boot images

	An arch Makefile specifies goals that take the vmlinux file, compress
	it, wrap it in bootstrapping code, and copy the resulting files
	somewhere. 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 a
	target specified in boot/. Therefore arch/$(ARCH)/Makefile shall
	call make manually to build a target in boot/.

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

	Example:
		#arch/x86/Makefile
		boot := arch/x86/boot
		bzImage: vmlinux
			$(Q)$(MAKE) $(build)=$(boot) $(boot)/$@

	"$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
	make 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/Makefile
		define archhelp
		  echo  '* bzImage      - Image (arch/$(ARCH)/boot/bzImage)'
		endif

	When make is executed without arguments, the first goal encountered
	will be built. In the top level Makefile the first goal present
	is 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 different
	from vmlinux.

	Example:
		#arch/x86/Makefile
		all: bzImage

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

--- 6.6 Building non-kbuild targets

    extra-y

	extra-y specify additional targets created in the current
	directory, in addition to any targets specified by obj-*.

	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/Makefile
		extra-y := head.o init_task.o

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


--- 6.7 Commands useful for building a boot image

	Kbuild provides a few macros that are useful when building a
	boot 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 files
	need an update, or the command line has changed since the last
	invocation. The latter will force a rebuild if any options
	to 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 will
	always be built.
	Assignments to $(targets) are without $(obj)/ prefix.
	if_changed may be used in conjunction with custom commands as
	defined in 6.8 "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.

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

    gzip
	Compress target. Use maximum compression to compress target.

	Example:
		#arch/x86/boot/Makefile
		LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
		LDFLAGS_setup    := -Ttext 0x0 -s --oformat binary -e begtext

		targets += 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 different
	options to the linker. The linker options are specified using the
	LDFLAGS_$@ syntax - one for each potential target.
	$(targets) are assigned all potential targets, by which kbuild knows
	the targets and will:
		1) check for commandline changes
		2) delete target during make clean

	The ": %: %.o" part of the prerequisite is a shorthand that
	free us from listing the setup.o and bootsect.o files.
	Note: It is a common mistake to forget the "target :=" assignment,
	      resulting in the target file being recompiled for no
	      obvious reason.

    dtc
	Create flattend device tree blob object suitable for linking
	into vmlinux. Device tree blobs linked into vmlinux are placed
	in an init section in the image. Platform code *must* copy the
	blob to non-init memory prior to calling unflatten_device_tree().

	To use this command, simply add *.dtb into obj-y or targets, or make
	some 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)
		clean-files += *.dtb
		DTC_FLAGS ?= -p 1024

    dtc_cpp
	This is just like dtc as describe above, except that the C pre-
	processor is invoked upon the .dtsp file before compiling the result
	with dtc.

	In order for build dependencies to work, all files compiled using
	dtc_cpp must use the C pre-processor's #include functionality and not
	dtc's /include/ functionality.

	Using the C pre-processor allows use of #define to create named
	constants. In turn, the #defines will typically appear in a header
	file, which may be shared with regular C code. Since the dtc language
	represents a data structure rather than code in C syntax, similar
	restrictions are placed on a header file included by a device tree
	file as for a header file included by an assembly language file.
	In particular, the C pre-processor is passed -x assembler-with-cpp,
	which sets macro __ASSEMBLY__. __DTS__ is also set. These allow header
	files to restrict their content to that compatible with device tree
	source.

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

--- 6.8 Custom kbuild commands

	When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
	of a command is normally displayed.
	To enable this behaviour for custom commands kbuild requires
	two 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".


--- 6.9 Preprocessing linker scripts

	When the vmlinux image is built, 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 files and includes a rule *lds.S -> *lds.

	Example:
		#arch/x86/kernel/Makefile
		always := vmlinux.lds

		#Makefile
		export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)

	The assignment to $(always) is used to tell kbuild to build the
	target vmlinux.lds.
	The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
	specified options when building the target vmlinux.lds.

	When building the *.lds target, kbuild uses the variables:
	KBUILD_CPPFLAGS	: Set in top-level Makefile
	cppflags-y	: 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.

--- 6.10 Generic header files

	The directory include/asm-generic contains the header files
	that may be shared between individual architectures.
	The recommended approach how to use a generic header file is
	to list the file in the Kbuild file.
	See "7.4 generic-y" for further info on syntax etc.

=== 7 Kbuild syntax for exported headers

The kernel include a set of headers that is exported to userspace.
Many headers can be exported as-is but other headers require a
minimal 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 by ifdef __KERNEL__)

Each relevant directory contains a file name "Kbuild" which specifies the
headers to be exported.
See subsequent chapter for the syntax of the Kbuild file.

	--- 7.1 header-y

	header-y specify header files to be exported.

		Example:
			#include/linux/Kbuild
			header-y += usb/
			header-y += aio_abi.h

	The convention is to list one file per line and
	preferably in alphabetic order.

	header-y also specify which subdirectories to visit.
	A subdirectory is identified by a trailing '/' which
	can be seen in the example above for the usb subdirectory.

	Subdirectories are visited before their parent directories.

	--- 7.2 genhdr-y

	genhdr-y specifies generated files to be exported.
	Generated files are special as they need to be looked
	up in another directory when doing 'make O=...' builds.

		Example:
			#include/linux/Kbuild
			genhdr-y += version.h

	--- 7.3 destination-y

	When an architecture have a set of exported headers that needs to be
	exported to a different directory destination-y is used.
	destination-y specify the destination directory for all exported
	headers in the file where it is present.

		Example:
			#arch/xtensa/platforms/s6105/include/platform/Kbuild
			destination-y := include/linux

	In the example above all exported headers in the Kbuild file
	will be located in the directory "include/linux" when exported.

	--- 7.4 generic-y

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

		Example:
			#arch/x86/include/asm/Kbuild
			generic-y += termios.h
			generic-y += rtc.h

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

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

	When a header is exported where the architecture uses
	the generic header a similar wrapper is generated as part
	of 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 Kbuild Variables

The top Makefile exports the following variables:

    VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION

	These variables define the current kernel version.  A few arch
	Makefiles actually use these values directly; they should use
	$(KERNELRELEASE) instead.

	$(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
	three-part version number, such as "2", "4", and "0".  These three
	values are always numeric.

	$(EXTRAVERSION) defines an even tinier sublevel for pre-patches
	or additional patches.	It is usually some non-numeric string
	such as "-pre4", and is often blank.

    KERNELRELEASE

	$(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
	for constructing installation directory names or showing in
	version strings.  Some arch Makefiles use it for this purpose.

    ARCH

	This variable defines the target architecture, such as "i386",
	"arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
	determine which files to compile.

	By default, the top Makefile sets $(ARCH) to be the same as the
	host system architecture.  For a cross build, a user may
	override the value of $(ARCH) on the command line:

	    make ARCH=m68k ...


    INSTALL_PATH

	This variable defines a place for the arch Makefiles to install
	the resident kernel image and System.map file.
	Use this for architecture-specific install targets.

    INSTALL_MOD_PATH, MODLIB

	$(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
	installation.  This variable is not defined in the Makefile but
	may be passed in by the user if desired.

	$(MODLIB) specifies the directory for module installation.
	The top Makefile defines $(MODLIB) to
	$(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE).  The user may
	override this value on the command line if desired.

    INSTALL_MOD_STRIP

	If this variable is specified, will cause modules to be stripped
	after they are installed.  If INSTALL_MOD_STRIP is '1', then the
	default option --strip-debug will be used.  Otherwise,
	INSTALL_MOD_STRIP value will be used as the option(s) to the strip
	command.


=== 9 Makefile language

The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
use only the documented features of GNU Make, but they do use many
GNU extensions.

GNU Make supports elementary list-processing functions.  The kernel
Makefiles use a novel style of list building and manipulation with few
"if" statements.

GNU Make has two assignment operators, ":=" and "=".  ":=" performs
immediate evaluation of the right-hand side and stores an actual string
into the left-hand side.  "=" is like a formula definition; it stores the
right-hand side in an unevaluated form and then evaluates this form each
time the left-hand side is used.

There are some cases where "=" is appropriate.  Usually, though, ":="
is the right choice.

=== 10 Credits

Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
Updates by Sam Ravnborg <sam@ravnborg.org>
Language QA by Jan Engelhardt <jengelh@gmx.de>

=== 11 TODO

- Describe how kbuild supports shipped files with _shipped.
- Generating offset header files.
- Add more variables to section 7?