makefiles.txt

Linux Kernel 2.6.9 for OMAP1710

	$(obj) is a relative path which points to the directory
	where the target is saved. Always use $(obj) when
	referring to generated files.

	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 special rule, following the normal syntax
	required by make.
	The target file depends on two prerequisite files. References
	to the target file are prefixed with $(obj), references
	to prerequisites are referenced with $(src) (because they are not
	generated files).


=== 4 Host Program support

Kbuild supports building executables on the host for use during the
compilation stage.
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 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, 
or utilise the variable $(always).
Both possibilities are described in the following.

--- 4.1 Simple Host Program

	In some cases there is a need to compile and run a program on the
	computer where the build is running.
	The following line tells kbuild that the program bin2hex shall be
	built on the build host.

	Example:
		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
	the Makefile.
  
--- 4.2 Composite Host Programs

	Host programs can be made up based on composite objects.
	The syntax used to define composite objects for host programs is
	similar to the syntax used for kernel objects.
	$(<executeable>-objs) list all objects used to link the final
	executable.

	Example:
		#scripts/lxdialog/Makefile
		hostprogs-y   := lxdialog  
		lxdialog-objs := checklist.o lxdialog.o

	Objects with extension .o are compiled from the corresponding .c
	files. In the above example checklist.c is compiled to checklist.o
	and 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.

--- 4.3 Defining shared libraries  
  
	Objects with extension .so are considered shared libraries, and
	will be compiled as position independent objects.
	Kbuild provides support for shared libraries, but the usage
	shall be restricted.
	In the following example the libkconfig.so shared library is used
	to link the executable conf.

	Example:
		#scripts/kconfig/Makefile
		hostprogs-y     := conf
		conf-objs       := conf.o libkconfig.so
		libkconfig-objs := expr.o type.o
  
	Shared libraries always require a corresponding -objs line, and
	in the example above the shared library libkconfig is composed by
	the two objects expr.o and type.o.
	expr.o and type.o will be built as position independent code and
	linked as a shared library libkconfig.so. C++ is not supported for
	shared libraries.

--- 4.4 Using C++ for host programs

	kbuild offers support for host programs written in C++. This was
	introduced solely to support kconfig, and is not recommended
	for general use.

	Example:
		#scripts/kconfig/Makefile
		hostprogs-y   := qconf
		qconf-cxxobjs := qconf.o

	In the example above the executable is composed of the C++ file
	qconf.cc - identified by $(qconf-cxxobjs).
	
	If qconf is composed by a mixture of .c and .cc files, then an
	additional line can be used to identify this.

	Example:
		#scripts/kconfig/Makefile
		hostprogs-y   := qconf
		qconf-cxxobjs := qconf.o
		qconf-objs    := check.o
	
--- 4.5 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) passed
	the options specified in $(HOSTCFLAGS).
	To set flags that will take effect for all host programs created
	in that Makefile use the variable HOST_EXTRACFLAGS.

	Example:
		#scripts/lxdialog/Makefile
		HOST_EXTRACFLAGS += -I/usr/include/ncurses
  
	To set specific flags for a single file the following construction
	is used:

	Example:
		#arch/ppc64/boot/Makefile
		HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
  
	It is also possible to specify additional options to the linker.
  
	Example:
		#scripts/kconfig/Makefile
		HOSTLOADLIBES_qconf := -L$(QTDIR)/lib

	When linking qconf it will be passed the extra option "-L$(QTDIR)/lib".
 
--- 4.6 When host programs are actually built

	Kbuild will only build host-programs when they are referenced
	as a prerequisite.
	This is possible in two ways:

	(1) List the prerequisite explicitly in a special rule.

	Example:
		#drivers/pci/Makefile
		hostprogs-y := 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 to
	the host programs in special rules must be prefixed with $(obj).

	(2) Use $(always)
	When there is no suitable special rule, and the host program
	shall be built when a makefile is entered, the $(always)
	variable shall be used.

	Example:
		#scripts/lxdialog/Makefile
		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 $(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.

Additional files can be specified in kbuild makefiles by use of $(clean-files).

	Example:
		#drivers/pci/Makefile
		clean-files := devlist.h classlist.h

When executing "make clean", the two files "devlist.h classlist.h" will
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
is not sufficient this sometimes needs to be explicit.

	Example:
		#arch/i386/boot/Makefile
		subdir- := compressed/

The above assignment instructs kbuild to descend down in the
directory compressed/ when "make clean" is executed.

To support the clean infrastructure in the Makefiles that builds the
final bootimage there is an optional target named archclean:

	Example:
		#arch/i386/Makefile
		archclean:
			$(Q)$(MAKE) $(clean)=arch/i386/boot

When "make clean" is executed, make will descend down in arch/i386/boot,
and clean as usual. The Makefile located in arch/i386/boot/ may use
the subdir- trick to descend further down.

Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is
included in the top level makefile, and the kbuild infrastructure
is not operational at that point.

Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
be visited during "make clean".

=== 6 Architecture Makefiles

The top level Makefile sets up the environment and does the preparation,
before starting to descend down in the individual directories.
The top level makefile contains the generic part, whereas the
arch/$(ARCH)/Makefile contains what is required to set-up kbuild
to the said architecture.
To do so arch/$(ARCH)/Makefile sets a number of variables, and defines
a few targets.

When kbuild executes the following steps are followed (roughly):
1) Configuration of the kernel => produced .config
2) Store kernel version in include/linux/version.h
3) Symlink include/asm to include/asm-$(ARCH)
4) Updating all other prerequisites to the target prepare:
   - Additional prerequisites are specified in arch/$(ARCH)/Makefile
5) Recursively descend down in all directories listed in
   init-* core* drivers-* net-* libs-* and build all targets.
   - The value of the above variables are extended in arch/$(ARCH)/Makefile.
6) All object files are then linked and the resulting file vmlinux is 
   located at the root of the src tree.
   The very first objects linked are listed in head-y, assigned by
   arch/$(ARCH)/Makefile.
7) Finally the architecture specific part does any required post processing
   and builds the final bootimage.
   - This includes building boot records
   - Preparing initrd images and the like


--- 6.1 Set variables to tweak the build to the architecture

    LDFLAGS		Generic $(LD) options

	Flags used for all invocations of the linker.
	Often specifying the emulation is sufficient.

	Example:
		#arch/s390/Makefile
		LDFLAGS         := -m elf_s390
	Note: EXTRA_LDFLAGS and LDFLAGS_$@ can be used to further customise
	the flags used. See chapter 7.
	
    LDFLAGS_MODULE	Options for $(LD) when linking modules

	LDFLAGS_MODULE is used to set specific flags for $(LD) when
	linking the .ko files used for modules.
	Default is "-r", for relocatable output.

    LDFLAGS_vmlinux	Options for $(LD) when linking vmlinux

	LDFLAGS_vmlinux is used to specify additional flags to pass to
	the linker when linking the final vmlinux.
	LDFLAGS_vmlinux uses the LDFLAGS_$@ support.

	Example:
		#arch/i386/Makefile
		LDFLAGS_vmlinux := -e stext

    OBJCOPYFLAGS	objcopy flags

	When $(call if_changed,objcopy) is used to translate a .o file,
	then the flags specified in OBJCOPYFLAGS will be used.
	$(call if_changed,objcopy) is often used to generate raw binaries on
	vmlinux.

	Example:
		#arch/s390/Makefile
		OBJCOPYFLAGS := -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 of
	vmlinux. The usage of $(call if_changed,xxx) will be described later.

    AFLAGS		$(AS) assembler flags

	Default value - see top level Makefile
	Append or modify as required per architecture.

	Example:
		#arch/sparc64/Makefile
		AFLAGS += -m64 -mcpu=ultrasparc

    CFLAGS		$(CC) compiler flags

	Default value - see top level Makefile
	Append or modify as required per architecture.

	Often the CFLAGS variable depends on the configuration.

	Example:
		#arch/i386/Makefile
		cflags-$(CONFIG_M386) += -march=i386
		CFLAGS += $(cflags-y)

	Many arch Makefiles dynamically run the target C compiler to
	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)

	The above examples both utilise the trick that a config option expands
	to 'y' when selected.

    CFLAGS_KERNEL	$(CC) options specific for built-in

	$(CFLAGS_KERNEL) contains extra C compiler flags used to compile
	resident kernel code.

    CFLAGS_MODULE	$(CC) options specific for modules

	$(CFLAGS_MODULE) contains extra C compiler flags used to compile code
	for loadable kernel modules.

 
--- 6.2 Add prerequisites to prepare:

	The prepare: 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.