kbuild: Updated Documentation/kbuild/makefiles.txt

1) export-objs no longer needed
2) build-targets replaced by always
3) EXTRA_TARGETS is replaced by extra-y, for the part used to list .o files
4) introduced targets := to list additional targets for kbuild
5) documented OBJCOPYFLAGS_$@

Documentation/kbuild/makefiles.txt

@@ -10,7 +10,7 @@ This document describes the Linux kernel Makefiles.
 	   --- 3.1 Goal definitions
 	   --- 3.2 Built-in object goals - obj-y
 	   --- 3.3 Loadable module goals - obj-m
-	   --- 3.4 Objects which export symbols - export-objs
+	   --- 3.4 Objects which export symbols
 	   --- 3.5 Library file goals - L_TARGET
 	   --- 3.6 Descending down in directories
 	   --- 3.7 Compilation flags
@@ -208,32 +208,11 @@ more details, with real examples.
 	kbuild will build an ext2.o file for you out of the individual
 	parts and then link this into built-in.o, as you would expect.
 
---- 3.4 Objects which export symbols - export-objs
+--- 3.4 Objects which export symbols
 
-	When using loadable modules, not every global symbol in the
-	kernel / other modules is automatically available, only those
-	explicitly exported are available for your module.
-
-	To make a symbol available for use in modules, to "export" it,
-	use the EXPORT_SYMBOL(<symbol>) directive in your source. In
-	addition, you need to list all object files which export symbols
-	(i.e. their source contains an EXPORT_SYMBOL() directive) in the
-	Makefile variable $(export-objs).
-
-	Example:
-		#drivers/isdn/i4l/Makefile
-		# Objects that export symbols.
-		export-objs     := isdn_common.o
-
-	since isdn_common.c contains
-
-	    EXPORT_SYMBOL(register_isdn);
-
-	which makes the function register_isdn available to
-	low-level ISDN drivers.
-	There exist a EXPORT_SYMBOL_GPL() variant with similar functionality,
-	but more restrictive with what may use that symbol. The requirement
-	to list the .o file in export-objs is the same.
+	No special notation is required in the makefiles for
+	modules exporting symbols.
+	See also Documentation/modules.txt.
 
 --- 3.5 Library file goals - L_TARGET
 
@@ -400,7 +379,7 @@ done utilising the variable host-prog.
 
 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 build-targets.
+or utilise the variable $(always).
 Both possibilities are described in the following.
 
 --- 4.1 Simple Host Program
@@ -526,15 +505,15 @@ Both possibilities are described in the following.
 	$(obj)/gen-devlist is updated. Note that references to
 	the host programs in special rules must be prefixed with $(obj).
 
-	(2) Use $(build-targets)
+	(2) Use $(always)
 	When there is no suitable special rule, and the host program
-	shall be built when a makefile is entered, the $(build-targets)
+	shall be built when a makefile is entered, the $(always)
 	variable shall be used.
 
 	Example:
 		#scripts/lxdialog/Makefile
 		host-progs    := lxdialog
-		build-targets := $(host-progs)
+		always        := $(host-progs)
 
 	This will tell kbuild to build lxdialog even if not referenced in
 	any rule.
@@ -543,13 +522,13 @@ Both possibilities are described in the following.
 
 "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) and $(EXTRA_TARGETS) and
-they are all deleted during "make clean".
+Kbuild knows targets listed in $(host-progs), $(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 by means of $(clean-files).
+Additional files can be specified in kbuild makefiles by use of $(clean-files).
 
 	Example:
 		#drivers/pci/Makefile
@@ -818,31 +797,23 @@ When kbuild executes the following steps are followed (roughly):
 
 --- 6.5 Building non-kbuild targets
 
-    EXTRA_TARGETS
+    extra-y
 
-	EXTRA_TARGETS specify additional targets created in current
+	extra-y specify additional targets created in current
 	directory, in addition to any targets specified by obj-*.
 
-	Listing all targets in EXTRA_TARGETS is required for three purposes:
-	1) Avoid that the target is linked in as part of built-in.o
-	2) Enable kbuild to check changes in command lines
+	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
-	3) kbuild knows what file to delete during "make clean"
+	2) kbuild knows what files to delete during "make clean"
 
 	Example:
 		#arch/i386/kernel/Makefile
-		EXTRA_TARGETS := head.o init_task.o
+		extra-y := head.o init_task.o
 
-	In this example EXTRA_TARGETS is used to list object files that
+	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.
 
-	Example:
-		#arch/i386/boot/Makefile
-		EXTRA_TARGETS := vmlinux.bin bootsect bootsect.o
-
-	In this example EXTRA_TARGETS is used to list all intermediate
-	targets, and all final targets.
-	The targets are added to EXTRA_TARGETS to enable 2) and 3) above.
 	
 --- 6.6 Commands useful for building a boot image
 
@@ -861,9 +832,10 @@ When kbuild executes the following steps are followed (roughly):
 	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 EXTRA_TARGETS,
+	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.
@@ -874,10 +846,34 @@ When kbuild executes the following steps are followed (roughly):
     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 is 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
 
@@ -894,6 +890,7 @@ When kbuild executes the following steps are followed (roughly):
 		      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'