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

Randy Dunlap
2020-11-23T18:01:18Z

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.
--
~Randy