Commit d0e628cd authored by Masahiro Yamada's avatar Masahiro Yamada
Browse files

kbuild: doc: clarify the difference between extra-y and always-y 

The difference between extra-y and always-y is obscure.

Basically, Kbuild builds targets listed in extra-y and always-y in
visited Makefiles without relying on any dependency.

The difference is that extra-y is used to list the targets needed for
vmlinux whereas always-y is used to list the targets that must be always
built irrespective of final targets.

Kbuild skips extra-y when it is building only modules (i.e.
'make modules'). This is the long-standing behavior since extra-y was
introduced in 2003, and it is explained in that commit log [1].

For clarification, this is the extra-y vs always-y table:

                  extra-y    always-y
  'make'             y          y
  'make vmlinux'     y          y
  'make modules'     n          y

Kbuild skips extra-y also when building external modules since obviously
it never builds vmlinux.

Unfortunately, extra-y is wrongly used in many places of upstream code,
and even in external modules.

Using extra-y in external module Makefiles is wrong. What you should
use is probably always-y or 'targets'.

The current documentation for extra-y is misleading. I rewrote it, and
moved it to the section 3.7.

always-y is not documented anywhere. I added.

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/commit/?id=f94e5fd7e5d09a56a60670a9bb211a791654bba8



Signed-off-by: default avatarMasahiro Yamada <masahiroy@kernel.org>
Reviewed-by: default avatarRandy Dunlap <rdunlap@infradead.org>
parent 39bb232a

Documentation/kbuild/makefiles.rst

+71 −39
Original line number Diff line number Diff line
@@ -15,13 +15,15 @@ This document describes the Linux kernel Makefiles. 
	   --- 3.4 Objects which export symbols

	   --- 3.5 Library file goals - lib-y

	   --- 3.6 Descending down in directories

	   --- 3.7 Compilation flags

	   --- 3.8 Dependency tracking

	   --- 3.9 Custom Rules

	   --- 3.10 Command change detection

	   --- 3.11 $(CC) support functions

	   --- 3.12 $(LD) support functions

	   --- 3.13 Script Invocation

	   --- 3.7 Non-builtin vmlinux targets - extra-y

	   --- 3.8 Always built goals - always-y

	   --- 3.9 Compilation flags

	   --- 3.10 Dependency tracking

	   --- 3.11 Custom Rules

	   --- 3.12 Command change detection

	   --- 3.13 $(CC) support functions

	   --- 3.14 $(LD) support functions

	   --- 3.15 Script Invocation



	=== 4 Host Program support

	   --- 4.1 Simple Host Program
@@ -321,7 +323,60 @@ more details, with real examples. 
	names. This allows kbuild to totally skip the directory if the

	corresponding `CONFIG_` option is neither 'y' nor 'm'.



3.7 Compilation flags

3.7 Non-builtin vmlinux targets - extra-y

-----------------------------------------



	extra-y specifies targets which are needed for building vmlinux,

	but not combined into built-in.a.



	Examples are:



	1) head objects



	    Some objects must be placed at the head of vmlinux. They are

	    directly linked to vmlinux without going through built-in.a

	    A typical use-case is an object that contains the entry point.



	    arch/$(SRCARCH)/Makefile should specify such objects as head-y.



	    Discussion:

	      Given that we can control the section order in the linker script,

	      why do we need head-y?



	2) vmlinux linker script



	    The linker script for vmlinux is located at

	    arch/$(SRCARCH)/kernel/vmlinux.lds



	Example::



		# arch/x86/kernel/Makefile

		extra-y	:= head_$(BITS).o

		extra-y	+= head$(BITS).o

		extra-y	+= ebda.o

		extra-y	+= platform-quirks.o

		extra-y	+= vmlinux.lds



	$(extra-y) should only contain targets needed for vmlinux.



	Kbuild skips extra-y when vmlinux is apparently not a final goal.

	(e.g. 'make modules', or building external modules)



	If you intend to build targets unconditionally, always-y (explained

	in the next section) is the correct syntax to use.



3.8 Always built goals - always-y

---------------------------------



	always-y specifies targets which are literally always built when

	Kbuild visits the Makefile.



	Example::

	  # ./Kbuild

	  offsets-file := include/generated/asm-offsets.h

	  always-y += $(offsets-file)



3.9 Compilation flags

---------------------



    ccflags-y, asflags-y and ldflags-y
@@ -410,8 +465,8 @@ more details, with real examples. 
		AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt





3.8 Dependency tracking

-----------------------

3.10 Dependency tracking

------------------------



	Kbuild tracks dependencies on the following:
@@ -422,8 +477,8 @@ more details, with real examples. 
	Thus, if you change an option to $(CC) all affected files will

	be re-compiled.



3.9 Custom Rules

----------------

3.11 Custom Rules

-----------------



	Custom rules are used when the kbuild infrastructure does

	not provide the required support. A typical example is
@@ -499,7 +554,7 @@ more details, with real examples. 


	will be displayed with "make KBUILD_VERBOSE=0".



3.10 Command change detection

3.12 Command change detection

-----------------------------



	When the rule is evaluated, timestamps are compared between the target
@@ -545,7 +600,7 @@ more details, with real examples. 
		unwanted results when the target is up to date and only the

		tests on changed commands trigger execution of commands.



3.11 $(CC) support functions

3.13 $(CC) support functions

----------------------------



	The kernel may be built with several different versions of
@@ -660,7 +715,7 @@ more details, with real examples. 
			endif

		endif



3.12 $(LD) support functions

3.14 $(LD) support functions

----------------------------



    ld-option
@@ -674,7 +729,7 @@ more details, with real examples. 
		#Makefile

		LDFLAGS_vmlinux += $(call ld-option, -X)



3.13 Script invocation

3.15 Script invocation

----------------------



	Make rules may invoke scripts to build the kernel. The rules shall
@@ -1304,29 +1359,6 @@ When kbuild executes, the following steps are followed (roughly): 


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



7.6 Building non-kbuild targets

-------------------------------



    extra-y

	extra-y specifies 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/x86/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.a.



7.7 Commands useful for building a boot image

---------------------------------------------

CRA Git | Maintained and supported by SUSTech CRA and CCSE