makefiles.txt

Linux Kernel 2.6.9 for OMAP1710

		Example:
		#arch/s390/Makefile
		prepare: include/asm-$(ARCH)/offsets.h

	In this example the file include/asm-$(ARCH)/offsets.h will
	be built before descending down in the subdirectories.
	See also chapter XXX-TODO that describe how kbuild supports
	generating offset header files.


--- 6.3 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) list objects to be linked first in vmlinux.
	$(libs-y) list 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 define 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.4 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/i386/Makefile
		boot := arch/i386/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 of the architecture specific targets,
	but executing "make help" will list all relevant targets.
	To support this $(archhelp) must be defined.

	Example:
		#arch/i386/Makefile
		define archhelp
		  echo  '* bzImage      - Image (arch/$(ARCH)/boot/bzImage)'
		endef

	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/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
	needs an update, or the commandline has changed since 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.

    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 assinged all potential targets, herby 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 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.


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

    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-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
		GCC_VERSION := $(call cc-version)
		cflags-y += $(shell \
		if [ $(GCC_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.
	

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

=== 8 Makefile language

The kernel Makefiles are designed to 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.

=== 9 Credits

Original version made by Michael Elizabeth Chastain, <mailto:[e-mail]>
Updates by Kai Germaschewski <[e-mail]>
Updates by Sam Ravnborg <[e-mail]>

=== 10 TODO

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