linux/Documentation/kbuild
Masahiro Yamada 2eb5d7f242 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>
2024-09-24 03:07:21 +09:00
..
gcc-plugins.rst docs/core-api: expand Fedora instructions for GCC plugins 2022-09-27 13:21:44 -06:00
headers_install.rst Kbuild updates for v5.3 2019-07-12 16:03:16 -07:00
index.rst Kbuild updates for v5.7 2020-03-31 16:03:39 -07:00
issues.rst docs: kbuild: fix build with pdf and fix some minor issues 2019-07-15 11:03:04 -03:00
kbuild.rst kbuild: doc: describe the -C option precisely for external module builds 2024-09-24 03:07:21 +09:00
kconfig-language.rst Documentation: kconfig: explicitly document missing prompt 2024-09-07 17:24:01 +09:00
kconfig-macro-language.rst kconfig: doc: fix $(fileno) to $(filename) 2020-12-21 16:01:44 +09:00
Kconfig.recursion-issue-01 docs: kconfig: Fix grammar and formatting 2024-02-15 06:55:47 +09:00
Kconfig.recursion-issue-02 docs: use the lore redirector everywhere 2021-10-12 13:58:19 -06:00
kconfig.rst docs: kbuild/kconfig: reformat/cleanup 2024-02-19 18:20:39 +09:00
Kconfig.select-break
llvm.rst Documentation/llvm: turn make command for ccache into code block 2024-08-16 21:34:12 +09:00
makefiles.rst kbuild: doc: remove the description about shipped files 2024-09-24 03:07:21 +09:00
modules.rst kbuild: doc: describe the -C option precisely for external module builds 2024-09-24 03:07:21 +09:00
reproducible-builds.rst Documentation: kbuild: Add description of git for reproducible builds 2022-10-28 00:16:29 +09:00