Documentation/kbuild/modules.rst

Source file repositories/reference/linux-study-clean/Documentation/kbuild/modules.rst

File Facts

System
Linux kernel
Corpus path
Documentation/kbuild/modules.rst
Extension
.rst
Size
16434 bytes
Lines
514
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: exported/initcall integration point
Status
integration implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=========================
Building External Modules
=========================

This document describes how to build an out-of-tree kernel module.

Introduction
============

"kbuild" is the build system used by the Linux kernel. Modules must use
kbuild to stay compatible with changes in the build infrastructure and
to pick up the right flags to the compiler. Functionality for building modules
both in-tree and out-of-tree is provided. The method for building
either is similar, and all modules are initially developed and built
out-of-tree.

Covered in this document is information aimed at developers interested
in building out-of-tree (or "external") modules. The author of an
external module should supply a makefile that hides most of the
complexity, so one only has to type "make" to build the module. This is
easily accomplished, and a complete example will be presented in
section `Creating a Kbuild File for an External Module`_.


How to Build External Modules
=============================

To build external modules, you must have a prebuilt kernel available
that contains the configuration and header files used in the build.
Also, the kernel must have been built with modules enabled. If you are
using a distribution kernel, there will be a package for the kernel you
are running provided by your distribution.

An alternative is to use the "make" target "modules_prepare." This will
make sure the kernel contains the information required. The target
exists solely as a simple way to prepare a kernel source tree for
building external modules.

NOTE: "modules_prepare" will not build Module.symvers even if
CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be
executed to make module versioning work.

Command Syntax
--------------

	The command to build an external module is::

		$ make -C <path_to_kernel_dir> M=$PWD

	The kbuild system knows that an external module is being built
	due to the "M=<dir>" option given in the command.

	To build against the running kernel use::

		$ make -C /lib/modules/`uname -r`/build M=$PWD

	Then to install the module(s) just built, add the target
	"modules_install" to the command::

		$ make -C /lib/modules/`uname -r`/build M=$PWD modules_install

	Starting from Linux 6.13, you can use the -f option instead of -C. This
	will avoid unnecessary change of the working directory. The external
	module will be output to the directory where you invoke make.

		$ make -f /lib/modules/`uname -r`/build/Makefile M=$PWD

Options
-------

Annotation

Implementation Notes