Commit 54066682 authored by Sam Ravnborg's avatar Sam Ravnborg

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_$@
parent 87b2da2b
...@@ -10,7 +10,7 @@ This document describes the Linux kernel Makefiles. ...@@ -10,7 +10,7 @@ This document describes the Linux kernel Makefiles.
--- 3.1 Goal definitions --- 3.1 Goal definitions
--- 3.2 Built-in object goals - obj-y --- 3.2 Built-in object goals - obj-y
--- 3.3 Loadable module goals - obj-m --- 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.5 Library file goals - L_TARGET
--- 3.6 Descending down in directories --- 3.6 Descending down in directories
--- 3.7 Compilation flags --- 3.7 Compilation flags
...@@ -208,32 +208,11 @@ more details, with real examples. ...@@ -208,32 +208,11 @@ more details, with real examples.
kbuild will build an ext2.o file for you out of the individual 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. 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 No special notation is required in the makefiles for
kernel / other modules is automatically available, only those modules exporting symbols.
explicitly exported are available for your module. See also Documentation/modules.txt.
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.
--- 3.5 Library file goals - L_TARGET --- 3.5 Library file goals - L_TARGET
...@@ -400,7 +379,7 @@ done utilising the variable host-prog. ...@@ -400,7 +379,7 @@ done utilising the variable host-prog.
The second step is to add an explicit dependency to the executable. 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, 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. Both possibilities are described in the following.
--- 4.1 Simple Host Program --- 4.1 Simple Host Program
...@@ -526,15 +505,15 @@ Both possibilities are described in the following. ...@@ -526,15 +505,15 @@ Both possibilities are described in the following.
$(obj)/gen-devlist is updated. Note that references to $(obj)/gen-devlist is updated. Note that references to
the host programs in special rules must be prefixed with $(obj). 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 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. variable shall be used.
Example: Example:
#scripts/lxdialog/Makefile #scripts/lxdialog/Makefile
host-progs := lxdialog host-progs := lxdialog
build-targets := $(host-progs) always := $(host-progs)
This will tell kbuild to build lxdialog even if not referenced in This will tell kbuild to build lxdialog even if not referenced in
any rule. any rule.
...@@ -543,13 +522,13 @@ Both possibilities are described in the following. ...@@ -543,13 +522,13 @@ Both possibilities are described in the following.
"make clean" deletes most generated files in the src tree where the kernel "make clean" deletes most generated files in the src tree where the kernel
is compiled. This includes generated files such as host programs. is compiled. This includes generated files such as host programs.
Kbuild knows targets listed in $(host-progs) and $(EXTRA_TARGETS) and Kbuild knows targets listed in $(host-progs), $(always), $(extra-y) and
they are all deleted during "make clean". $(targets). They are all deleted during "make clean".
Files matching the patterns "*.[oas]", "*.ko", plus some additional files Files matching the patterns "*.[oas]", "*.ko", plus some additional files
generated by kbuild are deleted all over the kernel src tree when generated by kbuild are deleted all over the kernel src tree when
"make clean" is executed. "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: Example:
#drivers/pci/Makefile #drivers/pci/Makefile
...@@ -818,31 +797,23 @@ When kbuild executes the following steps are followed (roughly): ...@@ -818,31 +797,23 @@ When kbuild executes the following steps are followed (roughly):
--- 6.5 Building non-kbuild targets --- 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-*. directory, in addition to any targets specified by obj-*.
Listing all targets in EXTRA_TARGETS is required for three purposes: Listing all targets in extra-y is required for two purposes:
1) Avoid that the target is linked in as part of built-in.o 1) Enable kbuild to check changes in command lines
2) Enable kbuild to check changes in command lines
- When $(call if_changed,xxx) is used - 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: Example:
#arch/i386/kernel/Makefile #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. 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 --- 6.6 Commands useful for building a boot image
...@@ -861,9 +832,10 @@ When kbuild executes the following steps are followed (roughly): ...@@ -861,9 +832,10 @@ When kbuild executes the following steps are followed (roughly):
needs an update, or the commandline has changed since last needs an update, or the commandline has changed since last
invocation. The latter will force a rebuild if any options invocation. The latter will force a rebuild if any options
to the executable have changed. 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 otherwise the command line check will fail, and the target will
always be built. always be built.
Assignments to $(targets) are without $(obj)/ prefix.
if_changed may be used in conjunction with custom commands as if_changed may be used in conjunction with custom commands as
defined in 6.7 "Custom kbuild commands". defined in 6.7 "Custom kbuild commands".
Note: It is a typical mistake to forget the FORCE prerequisite. Note: It is a typical mistake to forget the FORCE prerequisite.
...@@ -874,10 +846,34 @@ When kbuild executes the following steps are followed (roughly): ...@@ -874,10 +846,34 @@ When kbuild executes the following steps are followed (roughly):
objcopy objcopy
Copy binary. Uses OBJCOPYFLAGS usually specified in Copy binary. Uses OBJCOPYFLAGS usually specified in
arch/$(ARCH)/Makefile. arch/$(ARCH)/Makefile.
OBJCOPYFLAGS_$@ may be used to set additional options.
gzip gzip
Compress target. Use maximum compression to compress target. 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 --- 6.7 Custom kbuild commands
...@@ -894,6 +890,7 @@ When kbuild executes the following steps are followed (roughly): ...@@ -894,6 +890,7 @@ When kbuild executes the following steps are followed (roughly):
cmd_image = $(obj)/tools/build $(BUILDFLAGS) \ cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
$(obj)/vmlinux.bin > $@ $(obj)/vmlinux.bin > $@
targets += bzImage
$(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
$(call if_changed,image) $(call if_changed,image)
@echo 'Kernel: $@ is ready' @echo 'Kernel: $@ is ready'
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment