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 builtdue 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. Thiswill avoid unnecessary change of the working directory. The externalmodule will be output to the directory where you invoke make.

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

($KDIR refers to the path of the kernel source directory, or the pathof the kernel output directory if the kernel was built in a separatebuild directory.)

You can optionally pass MO= option if you want to build the modules ina separate directory.

make -C $KDIR M=$PWD [MO=$BUILD_DIR]

-C $KDIR

The directory that contains the kernel and relevant buildartifacts used for building an external module.“make” will actually change to the specified directorywhen executing and will change back when finished.

M=$PWD

Informs kbuild that an external module is being built.The value given to “M” is the absolute path of thedirectory where the external module (kbuild file) islocated.

MO=$BUILD_DIR

Specifies a separate output directory for the external module.

When building an external module, only a subset of the “make”targets are available.

make -C $KDIR M=$PWD [target]

The default will build the module(s) located in the currentdirectory, so a target does not need to be specified. Alloutput files will also be generated in this directory. Noattempts are made to update the kernel source, and it is aprecondition that a successful “make” has been executed for thekernel.

modules

The default target for external modules. It has thesame functionality as if no target was specified. Seedescription above.

modules_install

Install the external module(s). The default location is/lib/modules/<kernel_release>/updates/, but a prefix maybe added with INSTALL_MOD_PATH (discussed in sectionModule Installation).

clean

Remove all generated files in the module directory only.

help

List the available targets for external modules.

It is possible to build single files that are part of a module.This works equally well for the kernel, a module, and even forexternal modules.

Example (The module foo.ko, consist of bar.o and baz.o):

make -C $KDIR M=$PWD bar.lstmake -C $KDIR M=$PWD baz.omake -C $KDIR M=$PWD foo.komake -C $KDIR M=$PWD ./

An external module always includes a wrapper makefile thatsupports building the module using “make” with no arguments.This target is not used by kbuild; it is only for convenience.Additional functionality, such as test targets, can be includedbut should be filtered out from kbuild due to possible nameclashes.

Example 1:

--> filename: Makefileifneq ($(KERNELRELEASE),)# kbuild part of makefileobj-m  := 8123.o8123-y := 8123_if.o 8123_pci.oelse# normal makefileKDIR ?= /lib/modules/`uname -r`/builddefault:        $(MAKE) -C $(KDIR) M=$$PWDendif

The check for KERNELRELEASE is used to separate the two partsof the makefile. In the example, kbuild will only see the twoassignments, whereas “make” will see everything except thesetwo assignments. This is due to two passes made on the file:the first pass is by the “make” instance run on the commandline; the second pass is by the kbuild system, which isinitiated by the parameterized “make” in the default target.

Kbuild will first look for a file named “Kbuild”, and if it is notfound, it will then look for “Makefile”. Utilizing a “Kbuild” fileallows us to split up the “Makefile” from example 1 into two files:

Example 2:

--> filename: Kbuildobj-m  := 8123.o8123-y := 8123_if.o 8123_pci.o--> filename: MakefileKDIR ?= /lib/modules/`uname -r`/builddefault:        $(MAKE) -C $(KDIR) M=$$PWD

The split in example 2 is questionable due to the simplicity ofeach file; however, some external modules use makefilesconsisting of several hundred lines, and here it really paysoff to separate the kbuild part from the rest.

Linux 6.13 and later support another way. The external module Makefilecan include the kernel Makefile directly, rather than invoking sub Make.

Example 3:

--> filename: Kbuildobj-m  := 8123.o8123-y := 8123_if.o 8123_pci.o--> filename: MakefileKDIR ?= /lib/modules/$(shell uname -r)/buildexport KBUILD_EXTMOD := $(realpath $(dir $(lastword $(MAKEFILE_LIST))))include $(KDIR)/Makefile

kbuild supports building multiple modules with a single buildfile. For example, if you wanted to build two modules, foo.koand bar.ko, the kbuild lines would be:

obj-m := foo.o bar.ofoo-y := <foo_srcs>bar-y := <bar_srcs>

It is that simple!

To include a header file located under include/linux/, simplyuse:

#include <linux/module.h>

kbuild will add options to the compiler so the relevant directoriesare searched.

External modules tend to place header files in a separateinclude/ directory where their source is located, although thisis not the usual kernel style. To inform kbuild of thedirectory, use either ccflags-y or CFLAGS_<filename>.o.

Using the example from section 3, if we moved 8123_if.h to asubdirectory named include, the resulting kbuild file wouldlook like:

--> filename: Kbuildobj-m := 8123.occflags-y := -I $(src)/include8123-y := 8123_if.o 8123_pci.o

kbuild can handle files that are spread over several directories.Consider the following example:

.|__ src|   |__ complex_main.c|   |__ hal|       |__ hardwareif.c|       |__ include|           |__ hardwareif.h|__ include        |__ complex.h

To build the module complex.ko, we then need the followingkbuild file:

--> filename: Kbuildobj-m := complex.ocomplex-y := src/complex_main.ocomplex-y += src/hal/hardwareif.occflags-y := -I$(src)/includeccflags-y += -I$(src)/src/hal/include

As you can see, kbuild knows how to handle object files locatedin other directories. The trick is to specify the directoryrelative to the kbuild file’s location. That being said, thisis NOT recommended practice.

For the header files, kbuild must be explicitly told where tolook. When kbuild executes, the current directory is always theroot of the kernel tree (the argument to “-C”) and therefore anabsolute path is needed. $(src) provides the absolute path bypointing to the directory where the currently executing kbuildfile is located.

Above are the default directories but as always some level ofcustomization is possible. A prefix can be added to theinstallation path using the variable INSTALL_MOD_PATH:

$ make INSTALL_MOD_PATH=/frodo modules_install=> Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/

INSTALL_MOD_PATH may be set as an ordinary shell variable or,as shown above, can be specified on the command line whencalling “make.” This has effect when installing both in-treeand out-of-tree modules.

External modules are by default installed to a directory under/lib/modules/$(KERNELRELEASE)/updates/, but you may wish tolocate modules for a specific functionality in a separatedirectory. For this purpose, use INSTALL_MOD_DIR to specify analternative name to “updates.”:

$ make INSTALL_MOD_DIR=gandalf -C $KDIR \       M=$PWD modules_install=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/

During a kernel build, a file named Module.symvers will begenerated. Module.symvers contains all exported symbols fromthe kernel and compiled modules. For each symbol, thecorresponding CRC value is also stored.

The syntax of the Module.symvers file is:

<CRC>       <Symbol>         <Module>                         <Export Type>     <Namespace>0xe1cc2a05  usb_stor_suspend drivers/usb/storage/usb-storage  EXPORT_SYMBOL_GPL USB_STORAGE

The fields are separated by tabs and values may be empty (e.g.if no namespace is defined for an exported symbol).

For a kernel build without CONFIG_MODVERSIONS enabled, the CRCwould read 0x00000000.

Module.symvers serves two purposes:

1. It lists all exported symbols from vmlinux and all modules.

2. It lists the CRC if CONFIG_MODVERSIONS is enabled.

Exported symbols have information stored in __ksymtab or __ksymtab_gplsections. Symbol names and namespaces are stored in __ksymtab_strings,using a format similar to the string table used for ELF. IfCONFIG_MODVERSIONS is enabled, the CRCs corresponding to exportedsymbols will be added to the __kcrctab or __kcrctab_gpl.

If CONFIG_BASIC_MODVERSIONS is enabled (default withCONFIG_MODVERSIONS), imported symbols will have their symbol name andCRC stored in the __versions section of the importing module. Thismode only supports symbols of length up to 64 bytes.

If CONFIG_EXTENDED_MODVERSIONS is enabled (required to enable bothCONFIG_MODVERSIONS and CONFIG_RUST at the same time), imported symbolswill have their symbol name recorded in the __version_ext_namessection as a series of concatenated, null-terminated strings. CRCs forthese symbols will be recorded in the __version_ext_crcs section.

When building an external module, the build system needs accessto the symbols from the kernel to check if all external symbolsare defined. This is done in the MODPOST step. modpost obtainsthe symbols by reading Module.symvers from the kernel sourcetree. During the MODPOST step, a new Module.symvers file will bewritten containing all exported symbols from that external module.

Sometimes, an external module uses exported symbols fromanother external module. Kbuild needs to have full knowledge ofall symbols to avoid spitting out warnings about undefinedsymbols. Two solutions exist for this situation.

NOTE: The method with a top-level kbuild file is recommendedbut may be impractical in certain situations.

Use a top-level kbuild file

If you have two modules, foo.ko and bar.ko, wherefoo.ko needs symbols from bar.ko, you can use acommon top-level kbuild file so both modules arecompiled in the same build. Consider the followingdirectory layout:

./foo/ <= contains foo.ko./bar/ <= contains bar.ko

The top-level kbuild file would then look like:

#./Kbuild (or ./Makefile):        obj-m := foo/ bar/

And executing:

$ make -C $KDIR M=$PWD

will then do the expected and compile both modules withfull knowledge of symbols from either module.

Use “make” variable KBUILD_EXTRA_SYMBOLS

If it is impractical to add a top-level kbuild file,you can assign a space separated listof files to KBUILD_EXTRA_SYMBOLS in your build file.These files will be loaded by modpost during theinitialization of its symbol tables.

Modules often need to check for certainCONFIG_ options todecide if a specific feature is included in the module. Inkbuild this is done by referencing theCONFIG_ variabledirectly:

#fs/ext2/Makefileobj-$(CONFIG_EXT2_FS) += ext2.oext2-y := balloc.o bitmap.o dir.oext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o