docs/kbuild/makefiles: unify quoting

People have four different relationships with the kernel Makefiles.

*Users* are people who build kernels.  These people type commands such as

"make menuconfig" or "make".  They usually do not read or edit

``make menuconfig`` or ``make``.  They usually do not read or edit

any kernel Makefiles (or any other source files).

*Normal developers* are people who work on features such as device

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'

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.

Section `Goal definitions`_ is a quick intro; further chapters provide

configuration.

Kbuild compiles all the $(obj-y) files.  It then calls

"$(AR) rcSTP" to merge these files into one built-in.a file.

``$(AR) rcSTP`` to merge these files into one built-in.a file.

This is a thin archive without a symbol table. It will be later

linked into vmlinux by scripts/link-vmlinux.sh

  #drivers/isdn/i4l/Makefile

  obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'

Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to "m"

If a kernel module is built from several source files, you specify

that you want to build a module in the same way as above; however,

In this example, the module name will be isdn.o. Kbuild will

compile the objects listed in $(isdn-y) and then run

"$(LD) -r" on the list of these files to generate isdn.o.

``$(LD) -r`` on the list of these files to generate isdn.o.

Due to kbuild recognizing $(<module_name>-y) for composite objects,

you can use the value of a `CONFIG_` symbol to optionally include an

you can use the value of a ``CONFIG_`` symbol to optionally include an

object file as part of a composite object.

Example::

In this example, xattr.o, xattr_user.o and xattr_trusted.o are only

part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)

evaluates to 'y'.

evaluates to "y".

Note: Of course, when you are building objects into the kernel,

the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,

See also `List directories to visit when descending`_.

Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.

Use of lib-y is normally restricted to ``lib/`` and ``arch/*/lib``.

Descending down in directories

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

  #fs/Makefile

  obj-$(CONFIG_EXT2_FS) += ext2/

If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)

If CONFIG_EXT2_FS is set to either "y" (built-in) or "m" (modular)

the corresponding obj- variable will be set, and kbuild will descend

down in the ext2 directory.

the directory, but also to decide whether or not to link objects from

the directory into vmlinux.

When Kbuild descends into the directory with 'y', all built-in objects

When Kbuild descends into the directory with "y", all built-in objects

from that directory are combined into the built-in.a, which will be

eventually linked into vmlinux.

When Kbuild descends into the directory with 'm', in contrast, nothing

When Kbuild descends into the directory with "m", in contrast, nothing

from that directory will be linked into vmlinux. If the Makefile in

that directory specifies obj-y, those objects will be left orphan.

It is very likely a bug of the Makefile or of dependencies in Kconfig.

Unlike obj-y/m, subdir-y/m does not need the trailing slash since this

syntax is always used for directories.

It is good practice to use a `CONFIG_` variable when assigning directory

It is good practice to use a ``CONFIG_`` variable when assigning directory

names. This allows kbuild to totally skip the directory if the

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

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

Non-builtin vmlinux targets - extra-y

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

$(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)

(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.

Kbuild tracks dependencies on the following:

1) All prerequisite files (both `*.c` and `*.h`)

2) `CONFIG_` options used in all prerequisite files

1) All prerequisite files (both ``*.c`` and ``*.h``)

2) ``CONFIG_`` options used in all prerequisite files

3) Command-line used to compile target

Thus, if you change an option to $(CC) all affected files will

$(kecho)

  echoing information to user in a rule is often a good practice

  but when execution "make -s" one does not expect to see any output

  but when execution ``make -s`` one does not expect to see any output

  except for warnings/errors.

  To support this kbuild defines $(kecho) which will echo out the

  text following $(kecho) to stdout except if "make -s" is used.

  text following $(kecho) to stdout except if ``make -s`` is used.

  Example::

    GEN     lib/crc32table.h

  will be displayed with "make KBUILD_VERBOSE=".

  will be displayed with ``make KBUILD_VERBOSE=``.

Command change detection

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

as-option

  as-option is used to check if $(CC) -- when used to compile

  assembler (`*.S`) files -- supports the given option. An optional

  assembler (``*.S``) files -- supports the given option. An optional

  second option may be specified if the first option is not supported.

  Example::

cc-option-yn

  cc-option-yn is used to check if gcc supports a given option

  and return 'y' if supported, otherwise 'n'.

  and return "y" if supported, otherwise "n".

  Example::

    cflags-$(biarch) += -m32

  In the above example, $(biarch) is set to y if $(CC) supports the -m32

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

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

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

  respectively.

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

done utilising the variable "hostprogs".

done utilising the variable ``hostprogs``.

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,

or utilise the variable "always-y".

or utilise the variable ``always-y``.

Both possibilities are described in the following.

Simple Host Program

  HOSTLDLIBS_qconf := -L$(QTDIR)/lib

When linking qconf, it will be passed the extra option

"-L$(QTDIR)/lib".

``-L$(QTDIR)/lib``.

When host programs are actually built

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

for the target architecture (i.e. the same architecture as you are building

the kernel for).

The syntax is quite similar. The difference is to use "userprogs" instead of

"hostprogs".

The syntax is quite similar. The difference is to use ``userprogs`` instead of

``hostprogs``.

Simple Userspace Program

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

Kbuild clean infrastructure

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

"make clean" deletes most generated files in the obj tree where the kernel

``make clean`` deletes most generated files in the obj tree where the kernel

is compiled. This includes generated files such as host programs.

Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m),

$(always-), $(extra-y), $(extra-) and $(targets). They are all deleted

during "make clean". Files matching the patterns "*.[oas]", "*.ko", plus

during ``make clean``. Files matching the patterns ``*.[oas]``, ``*.ko``, plus

some additional files generated by kbuild are deleted all over the kernel

source tree when "make clean" is executed.

source tree when ``make clean`` is executed.

Additional files or directories can be specified in kbuild makefiles by use of

$(clean-files).

  #lib/Makefile

  clean-files := crc32table.h

When executing "make clean", the file "crc32table.h" will be deleted.

When executing ``make clean``, the file ``crc32table.h`` will be deleted.

Kbuild will assume files to be in the same relative directory as the

Makefile.

To exclude certain files or directories from make clean, use the

$(no-clean-files) variable.

Usually kbuild descends down in subdirectories due to "obj-* := dir/",

Usually kbuild descends down in subdirectories due to ``obj-* := dir/``,

but in the architecture makefiles where the kbuild infrastructure

is not sufficient this sometimes needs to be explicit.

  subdir- := compressed

The above assignment instructs kbuild to descend down in the

directory compressed/ when "make clean" is executed.

directory compressed/ when ``make clean`` is executed.

Note 1: arch/$(SRCARCH)/Makefile cannot use "subdir-", because that file is

Note 1: arch/$(SRCARCH)/Makefile cannot use ``subdir-``, because that file is

included in the top level makefile. Instead, arch/$(SRCARCH)/Kbuild can use

"subdir-".

``subdir-``.

Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will

be visited during "make clean".

be visited during ``make clean``.

Architecture Makefiles

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

  The first example utilises the trick that a config option expands

  to 'y' when selected.

  to "y" when selected.

KBUILD_RUSTFLAGS

  $(RUSTC) compiler flags

  they are placed before the other objects.

KBUILD_VMLINUX_LIBS

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

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

  KBUILD_VMLINUX_LIBS together specify all the object files used to

  link vmlinux.

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

The archheaders: rule is used to generate header files that

may be installed into user space by "make header_install".

may be installed into user space by ``make header_install``.

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

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

architecture itself.

Add prerequisites to archprepare

  bzImage: vmlinux

          $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@

"$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke

``$(Q)$(MAKE) $(build)=<dir>`` is the recommended way to invoke

make in a subdirectory.

There are no rules for naming architecture-specific targets,

but executing "make help" will list all relevant targets.

but executing ``make help`` will list all relevant targets.

To support this, $(archhelp) must be defined.

Example::

is all:.

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

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

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

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

from vmlinux.

  #arch/x86/Makefile

  all: bzImage

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

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

Commands useful for building a boot image

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

  1) check for commandline changes

  2) delete target during make clean

  The ": %: %.o" part of the prerequisite is a shorthand that

  The ``: %: %.o`` part of the prerequisite is a shorthand that

  frees us from listing the setup.o and bootsect.o files.

  Note:

  It is a common mistake to forget the "targets :=" assignment,

  It is a common mistake to forget the ``targets :=`` assignment,

  resulting in the target file being recompiled for no

  obvious reason.

  in an init section in the image. Platform code *must* copy the

  blob to non-init memory prior to calling unflatten_device_tree().

  To use this command, simply add `*.dtb` into obj-y or targets, or make

  some other target depend on `%.dtb`

  To use this command, simply add ``*.dtb`` into obj-y or targets, or make

  some other target depend on ``%.dtb``

  A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`;

  A central rule exists to create ``$(obj)/%.dtb`` from ``$(src)/%.dts``;

  architecture Makefiles do no need to explicitly write out that rule.

  Example::

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`.

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

Example::

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

specified options when building the target vmlinux.lds.

When building the `*.lds` target, kbuild uses the variables::

When building the ``*.lds`` target, kbuild uses the variables::

  KBUILD_CPPFLAGS      : Set in top-level Makefile

  cppflags-y           : May be set in the kbuild makefile

                         Note that the full filename is used in this

                         assignment.

The kbuild infrastructure for `*lds` files is used in several

The kbuild infrastructure for ``*lds`` files is used in several

architecture-specific files.

Generic header files

- drop kernel-specific annotations

- drop include of compiler.h

- drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`)

- drop all sections that are kernel internal (guarded by ``ifdef __KERNEL__``)

All headers under include/uapi/, include/generated/uapi/,

arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/

  This variable specifies the directory in arch/ to build.

  ARCH and SRCARCH may not necessarily match. A couple of arch

  directories are biarch, that is, a single `arch/*/` directory supports

  directories are biarch, that is, a single ``arch/*/`` directory supports

  both 32-bit and 64-bit.

  For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86.

INSTALL_MOD_STRIP

  If this variable is specified, it will cause modules to be stripped

  after they are installed.  If INSTALL_MOD_STRIP is '1', then the

  after they are installed.  If INSTALL_MOD_STRIP is "1", then the

  default option --strip-debug will be used.  Otherwise, the

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

  command.

GNU Make supports elementary list-processing functions.  The kernel

Makefiles use a novel style of list building and manipulation with few

"if" statements.

``if`` statements.

GNU Make has two assignment operators, ":=" and "=".  ":=" performs

GNU Make has two assignment operators, ``:=`` and ``=``.  ``:=`` performs

immediate evaluation of the right-hand side and stores an actual string

into the left-hand side.  "=" is like a formula definition; it stores the

into the left-hand side.  ``=`` is like a formula definition; it stores the

right-hand side in an unevaluated form and then evaluates this form each

time the left-hand side is used.

There are some cases where "=" is appropriate.  Usually, though, ":="

There are some cases where ``=`` is appropriate.  Usually, though, ``:=``

is the right choice.

Credits