makefiles.txt

	from vmlinux.

	Example:
		#arch/i386/Makefile
		all: bzImage

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

--- 6.5 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/i386/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.6 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.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.

    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/i386/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.


--- 6.7 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/i386/boot/bzImage

	will be displayed with "make KBUILD_VERBOSE=0".


--- 6.8 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/i386/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.

=== 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 requires  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 is kernel internat (guarded by ifdef __KERNEL__)

Each relevant directory contain a file name "Kbuild" which specify 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 objhdr-y

	objhdr-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
			objhdr-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 unifdef-y (deprecated)

	unifdef-y is deprecated. A direct replacement is header-y.


=== 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 will 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?