1

kbuild: doc: describe the -C option precisely for external module builds

Building external modules is typically done using this command:

  $ make -C <KERNEL_DIR> M=<EXTMOD_DIR>

Here, <KERNEL_DIR> refers to the output directory where the kernel was
built, not the kernel source directory.

When the kernel is built in the source tree, there is no ambiguity, as
the output directory and the source directory are the same.

If the kernel was built in a separate build directory, <KERNEL_DIR>
should be the kernel output directory. Otherwise, Kbuild cannot locate
necessary build artifacts. This has been the method for building
external modules against a pre-built kernel in a separate directory
for over 20 years. [1]

If you pass the kernel source directory to the -C option, you must also
specify the kernel build directory using the O= option. This approach
works as well, though it results in a slightly longer command:

  $ make -C <KERNEL_SOURCE_DIR> O=<KERNEL_BUILD_DIR> M=<EXTMOD_DIR>

Some people mistakenly believe that O= should specify a build directory
for external modules when used together with M=. This commit adds more
clarification to Documentation/kbuild/kbuild.rst.

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/commit/?id=e321b2ec2eb2993b3d0116e5163c78ad923e3c54

Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
Reviewed-by: Nicolas Schier <n.schier@avm.de>
This commit is contained in:
Masahiro Yamada 2024-09-20 02:37:17 +09:00
parent e873fb9482
commit 2eb5d7f242
2 changed files with 11 additions and 3 deletions

View File

@ -134,6 +134,11 @@ KBUILD_OUTPUT
------------- -------------
Specify the output directory when building the kernel. Specify the output directory when building the kernel.
This variable can also be used to point to the kernel output directory when
building external modules against a pre-built kernel in a separate build
directory. Please note that this does NOT specify the output directory for the
external modules themselves.
The output directory can also be specified using "O=...". The output directory can also be specified using "O=...".
Setting "O=..." takes precedence over KBUILD_OUTPUT. Setting "O=..." takes precedence over KBUILD_OUTPUT.

View File

@ -45,7 +45,7 @@ Command Syntax
The command to build an external module is:: The command to build an external module is::
$ make -C <path_to_kernel_src> M=$PWD $ make -C <path_to_kernel_dir> M=$PWD
The kbuild system knows that an external module is being built The kbuild system knows that an external module is being built
due to the "M=<dir>" option given in the command. due to the "M=<dir>" option given in the command.
@ -62,12 +62,15 @@ Command Syntax
Options Options
------- -------
($KDIR refers to the path of the kernel source directory.) ($KDIR refers to the path of the kernel source directory, or the path
of the kernel output directory if the kernel was built in a separate
build directory.)
make -C $KDIR M=$PWD make -C $KDIR M=$PWD
-C $KDIR -C $KDIR
The directory where the kernel source is located. The directory that contains the kernel and relevant build
artifacts used for building an external module.
"make" will actually change to the specified directory "make" will actually change to the specified directory
when executing and will change back when finished. when executing and will change back when finished.