docs/kbuild/makefiles: clean up indentation and whitespace

(the resident kernel image) and modules (any module files).

It builds these goals by recursively descending into the subdirectories of

the kernel source tree.

The list of subdirectories which are visited depends upon the kernel

configuration. The top Makefile textually includes an arch Makefile

with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies

scripts/Makefile.* contains all the definitions/rules etc. that

are used to build the kernel based on the kbuild makefiles.

Who does what

=============

Most Makefiles within the kernel are kbuild Makefiles that use the

kbuild infrastructure. This chapter introduces the syntax used in the

kbuild makefiles.

The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can

be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'

file will be used.

Kbuild visits the Makefile.

Example::

  # ./Kbuild

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

  always-y += $(offsets-file)

    AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312

    AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt

Dependency tracking

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

    $(obj)/crc32table.h: $(obj)/gen_crc32table

            $(call cmd,crc32)

	When updating the $(obj)/crc32table.h target, the line:

  When updating the $(obj)/crc32table.h target, the line::

    GEN     lib/crc32table.h

  option. When $(biarch) equals 'y', the expanded variables $(aflags-y)

  and $(cflags-y) will be assigned the values -a32 and -m32,

  respectively.

  Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options

cc-disable-warning

  one of the listed prefixes. The first prefix where there exist a

  prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found

  then nothing is returned.

  Additional prefixes are separated by a single space in the

  call of cc-cross-prefix.

  This functionality is useful for architecture Makefiles that try

  to set CROSS_COMPILE to well-known values but may have several

  values to select between.

  It is recommended only to try to set CROSS_COMPILE if it is a cross

  build (host arch is different from target arch). And if CROSS_COMPILE

  is already set then leave it with the old value.

ld-option

  ld-option is used to check if $(LD) supports the supplied option.

  ld-option takes two options as arguments.

  The second argument is an optional option that can be used if the

  first option is not supported by $(LD).

Kbuild supports building executables on the host for use during the

compilation stage.

Two steps are required in order to use a host executable.

The first step is to tell kbuild that a host program exists. This is

In some cases there is a need to compile and run a program on the

computer where the build is running.

The following line tells kbuild that the program bin2hex shall be

built on the build host.

When compiling host programs, it is possible to set specific flags.

The programs will always be compiled utilising $(HOSTCC) passed

the options specified in $(KBUILD_HOSTCFLAGS).

To set flags that will take effect for all host programs created

in that Makefile, use the variable HOST_EXTRACFLAGS.

Kbuild will only build host-programs when they are referenced

as a prerequisite.

This is possible in two ways:

(1) List the prerequisite explicitly in a custom rule.

      hostprogs     := lxdialog

      always-y      := $(hostprogs)

	Kbuild provides the following shorthand for this:

    Kbuild provides the following shorthand for this::

      hostprogs-always-y := lxdialog

When compiling userspace programs, it is possible to set specific flags.

The programs will always be compiled utilising $(CC) passed

the options specified in $(KBUILD_USERCFLAGS).

To set flags that will take effect for all userspace programs created

in that Makefile, use the variable userccflags.

      userprogs := binderfs_example

      always-y := $(userprogs)

	Kbuild provides the following shorthand for this:

    Kbuild provides the following shorthand for this::

      userprogs-always-y := binderfs_example

The top level Makefile sets up the environment and does the preparation,

before starting to descend down in the individual directories.

The top level makefile contains the generic part, whereas

arch/$(SRCARCH)/Makefile contains what is required to set up kbuild

for said architecture.

To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines

a few targets.

When kbuild executes, the following steps are followed (roughly):

1) Configuration of the kernel => produce .config

2) Store kernel version in include/linux/version.h

3) Updating all other prerequisites to the target prepare:

   - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile

4) Recursively descend down in all directories listed in

   init-* core* drivers-* net-* libs-* and build all targets.

   - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile.

5) All object files are then linked and the resulting file vmlinux is

   located at the root of the obj tree.

   The very first objects linked are listed in scripts/head-object-list.txt.

6) Finally, the architecture-specific part does any required post processing

   and builds the final bootimage.

   - This includes building boot records

   - Preparing initrd images and the like

Set variables to tweak the build to the architecture

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

  LDFLAGS_vmlinux is used to specify additional flags to pass to

  the linker when linking the final vmlinux image.

  LDFLAGS_vmlinux uses the LDFLAGS_$@ support.

  Example::

  When $(call if_changed,objcopy) is used to translate a .o file,

  the flags specified in OBJCOPYFLAGS will be used.

  $(call if_changed,objcopy) is often used to generate raw binaries on

  vmlinux.

KBUILD_AFLAGS

  Assembler flags

	Default value - see top level Makefile

  Default value - see top level Makefile.

  Append or modify as required per architecture.

  Example::

KBUILD_CFLAGS

  $(CC) compiler flags

	Default value - see top level Makefile

  Default value - see top level Makefile.

  Append or modify as required per architecture.

  Often, the KBUILD_CFLAGS variable depends on the configuration.

KBUILD_RUSTFLAGS

  $(RUSTC) compiler flags

	Default value - see top level Makefile

  Default value - see top level Makefile.

  Append or modify as required per architecture.

  Often, the KBUILD_RUSTFLAGS variable depends on the configuration.

  $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that

  are used for $(CC).

  From commandline CFLAGS_MODULE shall be used (see kbuild.rst).

KBUILD_RUSTFLAGS_KERNEL

  $(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that

  are used for $(RUSTC).

  From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst).

KBUILD_LDFLAGS_MODULE

  From commandline LDFLAGS_MODULE shall be used (see kbuild.rst).

KBUILD_LDS

  The linker script with full path. Assigned by the top-level Makefile.

KBUILD_LDS_MODULE

  The module linker script with full path. Assigned by the top-level

  Makefile and additionally by the arch Makefile.

KBUILD_VMLINUX_OBJS

  All object files for vmlinux. They are linked to vmlinux in the same

  order as listed in KBUILD_VMLINUX_OBJS.

  they are placed before the other objects.

KBUILD_VMLINUX_LIBS

  All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and

  KBUILD_VMLINUX_LIBS together specify all the object files used to

  link vmlinux.

It is run before "make archprepare" when run on the

architecture itself.

Add prerequisites to archprepare

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

The archprepare: rule is used to list prerequisites that need to be

built before starting to descend down in the subdirectories.

This is usually used for header files containing assembler constants.

Example::

In this example, the file target maketools will be processed

before descending down in the subdirectories.

See also chapter XXX-TODO that describes how kbuild supports

generating offset header files.

List directories to visit when descending

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

corresponding arch-specific section for modules; the module-building

machinery is all architecture-independent.

core-y, libs-y, drivers-y

  $(libs-y) lists directories where a lib.a archive can be located.

  The rest list directories where a built-in.a object file can be

When make is executed without arguments, the first goal encountered

will be built. In the top level Makefile the first goal present

is all:.

An architecture shall always, per default, build a bootable image.

In "make help", the default goal is highlighted with a '*'.

Add a new prerequisite to all: to select a default goal different

from vmlinux.

  In this example, there are 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 assigned all potential targets, by which kbuild knows

  the targets and will:

objcopy

  Copy binary. Uses OBJCOPYFLAGS usually specified in

  arch/$(SRCARCH)/Makefile.

  OBJCOPYFLAGS_$@ may be used to set additional options.

gzip

When the vmlinux image is built, the linker script

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

The script is a preprocessed variant of the file vmlinux.lds.S

located in the same directory.

kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`.

Example::

The assignment to extra-y is used to tell kbuild to build the

target vmlinux.lds.

The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the

specified options when building the target vmlinux.lds.

The directory include/asm-generic contains the header files

that may be shared between individual architectures.

The recommended approach how to use a generic header file is

to list the file in the Kbuild file.

See `generic-y`_ for further info on syntax etc.

Post-link pass

The kernel includes a set of headers that is exported to userspace.

Many headers can be exported as-is but other headers require a

minimal pre-processing before they are ready for user-space.

The pre-processing does:

- drop kernel-specific annotations

A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and

arch/<arch>/include/asm/ to list asm files coming from asm-generic.

See subsequent chapter for the syntax of the Kbuild file.

no-export-headers

  INSTALL_MOD_STRIP value will be used as the option(s) to the strip

  command.

Makefile language

=================