system/linux
system/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux synced 2024-10-06 19:34:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs/kbuild/makefiles: unify quoting

Browse source 
Adding any rst quoting seems to be controversial, but at least try to
unify the existing quoting a bit, without adding new ones.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
This commit is contained in:
Jani Nikula 2023-01-17 11:59:46 +02:00 committed by Masahiro Yamada
parent 9f1fe2bba3
commit 2f0e2a39bb
1 changed files with 60 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

120
Documentation/kbuild/makefiles.rst
View file

@ -42,7 +42,7 @@ Who does what
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
@ -69,8 +69,8 @@ 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'
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
@ -111,7 +111,7 @@ in the $(obj-y) lists. These lists depend on the kernel
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
@ -148,7 +148,7 @@ Example::
#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,
@ -164,10 +164,10 @@ Example::
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::
@ -181,7 +181,7 @@ 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,
@ -217,7 +217,7 @@ shall be listed in libs-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
------------------------------
@ -237,7 +237,7 @@ Example::
#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.
@ -245,11 +245,11 @@ Kbuild uses this information not only to decide that it needs to visit
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.
@ -269,9 +269,9 @@ Examples::
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
-------------------------------------
@ -294,7 +294,7 @@ Example::
$(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.
@ -402,8 +402,8 @@ Dependency tracking
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
@ -451,10 +451,10 @@ $(obj)
$(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::
@ -484,7 +484,7 @@ $(kecho)
GEN lib/crc32table.h
will be displayed with "make KBUILD_VERBOSE=".
will be displayed with ``make KBUILD_VERBOSE=``.
Command change detection
------------------------
@ -543,7 +543,7 @@ available.
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::
@ -579,7 +579,7 @@ cc-option
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::
@ -589,7 +589,7 @@ cc-option-yn
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.
@ -700,11 +700,11 @@ 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
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
@ -820,7 +820,7 @@ Example::
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
-------------------------------------
@ -869,8 +869,8 @@ Just like host programs, Kbuild also supports building userspace executables
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
------------------------
@ -974,13 +974,13 @@ There are two ways to do this.
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).
@ -990,14 +990,14 @@ Example::
#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.
@ -1007,14 +1007,14 @@ Example::
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
======================
@ -1148,7 +1148,7 @@ KBUILD_CFLAGS
The first example utilises the trick that a config option expands
to 'y' when selected.
to "y" when selected.
KBUILD_RUSTFLAGS
$(RUSTC) compiler flags
@ -1227,7 +1227,7 @@ KBUILD_VMLINUX_OBJS
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.
@ -1235,9 +1235,9 @@ Add prerequisites to archheaders
--------------------------------
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
@ -1317,11 +1317,11 @@ Example::
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::
@ -1336,7 +1336,7 @@ 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 '*'.
In ``make help``, the default goal is highlighted with a ``*``.
Add a new prerequisite to all: to select a default goal different
from vmlinux.
@ -1346,7 +1346,7 @@ Example::
#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
-----------------------------------------
@ -1377,11 +1377,11 @@ ld
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.
@ -1406,10 +1406,10 @@ dtc
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::
@ -1426,7 +1426,7 @@ 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`.
kbuild knows .lds files and includes a rule ``*lds.S`` -> ``*lds``.
Example::
@ -1439,7 +1439,7 @@ target vmlinux.lds.
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
@ -1447,7 +1447,7 @@ When building the `*.lds` target, kbuild uses the variables::
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
@ -1488,7 +1488,7 @@ The pre-processing does:
- 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/
@ -1598,7 +1598,7 @@ SRCARCH
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.
@ -1622,7 +1622,7 @@ INSTALL_MOD_PATH, MODLIB
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.
@ -1636,15 +1636,15 @@ GNU extensions.
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