diff mbox series

[6/7] kbuild: doc: clarify the difference between extra-y and always-y

Message ID 20201123045403.63402-6-masahiroy@kernel.org (mailing list archive)
State New
Headers show
Series [1/7] kbuild: doc: update the description about kbuild Makefiles | expand

Commit Message

Masahiro Yamada Nov. 23, 2020, 4:54 a.m. UTC
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'             o          o
  'make vmlinux'     o          o
  'make modules'     x          o

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: Masahiro Yamada <masahiroy@kernel.org>
---

 Documentation/kbuild/makefiles.rst | 110 +++++++++++++++++++----------
 1 file changed, 71 insertions(+), 39 deletions(-)

Comments

Randy Dunlap Nov. 23, 2020, 6 p.m. UTC | #1
On 11/22/20 8:54 PM, Masahiro Yamada wrote:
> 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'             o          o
>   'make vmlinux'     o          o
>   'make modules'     x          o

FWIW, I would find y/n easier to comprehend that x/o here.

> 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: Masahiro Yamada <masahiroy@kernel.org>
> ---
> 
>  Documentation/kbuild/makefiles.rst | 110 +++++++++++++++++++----------
>  1 file changed, 71 insertions(+), 39 deletions(-)
> 
> diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
> index 49afcb1d3695..159e470f2616 100644
> --- a/Documentation/kbuild/makefiles.rst
> +++ b/Documentation/kbuild/makefiles.rst
> @@ -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-

	Should that be 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 our 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 visited the Makefile.

	       visits

> +
> +	Example::
> +	  # ./Kbuild
> +	  offsets-file := include/generated/asm-offsets.h
> +	  always-y += $(offsets-file)
> +
> +3.9 Compilation flags
>  ---------------------
>  
>      ccflags-y, asflags-y and ldflags-y

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>


thanks.
diff mbox series

Patch

diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 49afcb1d3695..159e470f2616 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -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-
+	   --- 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 our 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 visited 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
 ---------------------------------------------