linux.git/Documentation/kbuild, branch v5.5

kbuild: clarify the difference between obj-y and obj-m w.r.t. descending

2019-12-21T15:25:35+00:00

Kbuild descends into a directory by either 'y' or 'm', but there is an
important difference.

Kbuild combines the built-in objects into built-in.a in each directory.
The built-in.a in the directory visited by obj-y is merged into the
built-in.a in the parent directory. This merge happens recursively
when Kbuild is ascending back towards the top directory, then built-in
objects are linked into vmlinux eventually. This works properly only
when the Makefile specifying obj-y is reachable by the chain of obj-y.

On the other hand, Kbuild does not take built-in.a from the directory
visited by obj-m. This it, all the objects in that directory are
supposed to be modular. If Kbuild descends into a directory by obj-m,
but the Makefile in the sub-directory specifies obj-y, those objects
are just left orphan.

The current statement "Kbuild only uses this information to decide that
it needs to visit the directory" is misleading. Clarify the difference.

Reported-by: Johan Hovold 
Signed-off-by: Masahiro Yamada 
Reviewed-by: Johan Hovold

kconfig: remove ---help--- from documentation

2019-12-18T14:17:29+00:00

Since commit 84af7a6194e4 ("checkpatch: kconfig: prefer 'help' over
'---help---'"), scripts/checkpatch.pl warns the use of ---help---.

Kconfig still supports ---help---, but new code should avoid using it.
Let's stop advertising it in documentation.

Signed-off-by: Masahiro Yamada

kbuild: remove header compile test

2019-11-14T15:22:35+00:00

There are both positive and negative options about this feature.
At first, I thought it was a good idea, but actually Linus stated a
negative opinion (https://lkml.org/lkml/2019/9/29/227). I admit it
is ugly and annoying.

The baseline I'd like to keep is the compile-test of uapi headers.
(Otherwise, kernel developers have no way to ensure the correctness
of the exported headers.)

I will maintain a small build rule in usr/include/Makefile.
Remove the other header test functionality.

Signed-off-by: Masahiro Yamada

kbuild: do not read $(KBUILD_EXTMOD)/Module.symvers

2019-11-11T11:07:03+00:00

Since commit 040fcc819a2e ("kbuild: improved modversioning support for
external modules"), the external module build reads Module.symvers in
the directory of the module itself, then dumps symbols back into it.
It accumulates stale symbols in the file when you build an external
module incrementally.

The idea behind it was, as the commit log explained, you can copy
Modules.symvers from one module to another when you need to pass symbol
information between two modules. However, the manual copy of the file
sounds questionable to me, and containing stale symbols is a downside.

Some time later, commit 0d96fb20b7ed ("kbuild: Add new Kbuild variable
KBUILD_EXTRA_SYMBOLS") introduced a saner approach.

So, this commit removes the former one. Going forward, the external
module build dumps symbols into Module.symvers to be carried via
KBUILD_EXTRA_SYMBOLS, but never reads it automatically.

With the -I option removed, there is no one to set the external_module
flag unless KBUILD_EXTRA_SYMBOLS is passed. Now the -i option does it
instead.

Signed-off-by: Masahiro Yamada

Merge tag 'modules-for-v5.4-rc3' of git://git.kernel.org/pub/scm/linux/kernel/git/jeyu/linux

2019-10-11T17:19:24+00:00

Pull module fixes from Jessica Yu:
 "Code cleanups and kbuild/namespace related fixups from Masahiro.

  Most importantly, it fixes a namespace-related modpost issue for
  external module builds

   - Fix broken external module builds due to a modpost bug in
     read_dump(), where the namespace was not being strdup'd and
     sym->namespace would be set to bogus data.

   - Various namespace-related kbuild fixes and cleanups thanks to
     Masahiro Yamada"

* tag 'modules-for-v5.4-rc3' of git://git.kernel.org/pub/scm/linux/kernel/git/jeyu/linux:
  doc: move namespaces.rst from kbuild/ to core-api/
  nsdeps: make generated patches independent of locale
  nsdeps: fix hashbang of scripts/nsdeps
  kbuild: fix build error of 'make nsdeps' in clean tree
  module: rename __kstrtab_ns_* to __kstrtabns_* to avoid symbol conflict
  modpost: fix broken sym->namespace for external module builds
  module: swap the order of symbol.namespace
  scripts: add_namespace: Fix coccicheck failed

doc: move namespaces.rst from kbuild/ to core-api/

2019-10-08T15:40:01+00:00

We discussed a better location for this file, and agreed that
core-api/ is a good fit. Rename it to symbol-namespaces.rst
for disambiguation, and also add it to index.rst and MAINTAINERS.

Signed-off-by: Masahiro Yamada 
Acked-by: Matthias Maennich 
Signed-off-by: Jessica Yu

kheaders: make headers archive reproducible

2019-10-05T06:29:49+00:00

In commit 43d8ce9d65a5 ("Provide in-kernel headers to make
extending kernel easier") a new mechanism was introduced, for kernels
>=5.2, which embeds the kernel headers in the kernel image or a module
and exposes them in procfs for use by userland tools.

The archive containing the header files has nondeterminism caused by
header files metadata. This patch normalizes the metadata and utilizes
KBUILD_BUILD_TIMESTAMP if provided and otherwise falls back to the
default behaviour.

In commit f7b101d33046 ("kheaders: Move from proc to sysfs") it was
modified to use sysfs and the script for generation of the archive was
renamed to what is being patched.

Signed-off-by: Dmitry Goldin 
Reviewed-by: Greg Kroah-Hartman 
Reviewed-by: Joel Fernandes (Google) 
Signed-off-by: Masahiro Yamada

kbuild: two minor updates for Documentation/kbuild/modules.rst

2019-10-05T06:29:49+00:00

Capitalize the first word in the sentence.

Use obj-m instead of obj-y. obj-y still works, but we have no built-in
objects in external module builds. So, obj-m is better IMHO.

Signed-off-by: Masahiro Yamada

kbuild: correct formatting of header in kbuild module docs

2019-10-01T00:21:21+00:00

Minor formatting fixup.

Fixes: cd238effefa2 ("docs: kbuild: convert docs to ReST and rename to *.rst")
Signed-off-by: Alex Gaynor 
Signed-off-by: Matthew Garrett 
Signed-off-by: Masahiro Yamada

kbuild: remove ar-option and KBUILD_ARFLAGS

2019-10-01T00:20:33+00:00

Commit 40df759e2b9e ("kbuild: Fix build with binutils <= 2.19")
introduced ar-option and KBUILD_ARFLAGS to deal with old binutils.

According to Documentation/process/changes.rst, the current minimal
supported version of binutils is 2.21 so you can assume the 'D' option
is always supported. Not only GNU ar but also llvm-ar supports it.

With the 'D' option hard-coded, there is no more user of ar-option
or KBUILD_ARFLAGS.

Signed-off-by: Masahiro Yamada 
Reviewed-by: Nick Desaulniers 
Tested-by: Nick Desaulniers