Make & the Kernel Build System (Kbuild/Kconfig)

Imagine you have 10,000 C source files. You change one of them. Which object files need to be recompiled? Which need to be re-linked? If you recompile everything every time, a small edit might take 20 minutes. If you recompile nothing, your binary might be inconsistent and crash in mysterious ways.

This is the dependency problem: given a change to some set of inputs, compute the minimal set of outputs that must be regenerated.

A build system solves this by maintaining a dependency graph — a directed acyclic graph (DAG) where each node is a file (source, object, header, or binary) and each edge means 'this file depends on that file'. When you run the build, the system compares timestamps: if an output file is older than any of its inputs, it must be regenerated. Otherwise it can be skipped.

The genius is that this is compositional: if foo.o depends on foo.c and foo.h, and foo.h changed, then foo.o must be regenerated. If libfoo.a depends on foo.o, then libfoo.a must also be regenerated. The build system follows the chain automatically.

This is exactly what make does, and it is exactly why the Linux kernel build takes 20 seconds for a small change instead of 40 minutes.

# Without a build system, the naive approach:
# Recompile everything every time:
#   gcc -c foo.c bar.c baz.c && gcc -o app foo.o bar.o baz.o
# This is O(n) compile time per change.

# With a build system, only changed files are recompiled.
# The build system uses file timestamps to decide what to redo.

GNU Make reads a file called Makefile (or GNUmakefile) and executes it. The fundamental unit of a Makefile is the rule:

target: prerequisites
	recipe

• target: the file to be produced (or a phony name like all or clean).
• prerequisites: files that must exist and be up-to-date before the recipe runs. If any prerequisite is newer than the target, or the target does not exist, the recipe runs.
• recipe: shell commands to produce the target. Critically, each line of a recipe must start with a TAB character, not spaces. This is one of Make's most infamous quirks.

Make evaluates rules lazily: it starts from the goal (usually the first target in the file, or the one you specify on the command line) and works backward through prerequisites, building a dependency tree. It then executes leaves first, working toward the goal.

Variables in Make are set with = (lazily expanded — evaluated when used) or := (immediately expanded — evaluated when defined). The difference matters in complex Makefiles. You reference a variable with $(VAR).

Automatic variables are especially useful:

• $@ — the name of the target
• $< — the first prerequisite
• $^ — all prerequisites
• $* — the stem of a pattern rule match

Pattern rules let you write generic rules. %.o: %.c means 'to build any .o file, compile the corresponding .c file'. This is how a real project avoids writing one rule per source file.

# A minimal but complete Makefile
CC := gcc
CFLAGS := -Wall -O2

# Pattern rule: build any .o from the corresponding .c
%.o: %.c
	$(CC) $(CFLAGS) -c -o $@ $<

# Link rule
app: main.o util.o
	$(CC) -o $@ $^

# Phony target: doesn't correspond to a real file
.PHONY: clean
clean:
	rm -f *.o app

Pattern rules handle the easy case. But what about header files? If main.c includes util.h and util.h changes, main.o must be recompiled — but the simple pattern rule %.o: %.c doesn't know about util.h.

The solution is automatic dependency generation. GCC (and Clang) can emit a .d file alongside each .o file that lists all the headers that were included during compilation. You then include all those .d files in your Makefile so Make learns about the header dependencies automatically.

The flag -MMD tells GCC to generate a dependency file without including system headers. -MP adds phony targets for each header, preventing errors when a header is deleted.

This is exactly what Kbuild does internally. The kernel's build system generates .foo.o.d files for every object, and includes them to track header dependencies across the entire tree.

This is a beautiful example of using the build system to bootstrap its own dependency graph.

CC := gcc
CFLAGS := -Wall -MMD -MP

SRCS := main.c util.c
OBJS := $(SRCS:.c=.o)
DEPS := $(SRCS:.c=.d)

app: $(OBJS)
	$(CC) -o $@ $^

%.o: %.c
	$(CC) $(CFLAGS) -c -o $@ $<

# Include the auto-generated dependency files
# The '-' prefix means: don't error if they don't exist yet
-include $(DEPS)

.PHONY: clean
clean:
	rm -f $(OBJS) $(DEPS) app

The Linux kernel's build system is called Kbuild. It is not a replacement for Make — it is a sophisticated, convention-based layer on top of Make. Kbuild provides:

1. A uniform Makefile convention for every directory in the tree. Each subdirectory has a Makefile (sometimes called Kbuild) that only needs to say which objects to build, not how to build them. The 'how' is centralized in scripts/Makefile.build and related files.

2. Integration with Kconfig. Kbuild reads the .config file (produced by Kconfig) and makes its CONFIG_* symbols available as Make variables. If CONFIG_USB=m, Kbuild knows to build the USB subsystem as a module.

3. Cross-architecture support. The same make invocation, with ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-, builds for a completely different CPU. The architecture-specific logic lives in arch/<arch>/Makefile.

The key conventions in a directory-level Kbuild Makefile are:

• obj-y += foo.o — compile foo.c and link it statically into the kernel
• obj-m += bar.o — compile bar.c as a loadable module
• obj-$(CONFIG_FOO) += foo.o — include if CONFIG_FOO=y, as module if CONFIG_FOO=m, skip if CONFIG_FOO=n
• foo-objs := a.o b.o — foo.ko is built from multiple source files

This is how a simple three-line file in drivers/usb/core/Makefile can correctly build or skip the entire USB core depending on configuration.

# A real-world-style directory Makefile (e.g. drivers/mydriver/Makefile)

# Build mydriver as a module if CONFIG_MYDRIVER=m,
# or link it in if CONFIG_MYDRIVER=y
obj-$(CONFIG_MYDRIVER) += mydriver.o

# mydriver.ko is composed of two source files
mydriver-objs := mydriver_core.o mydriver_hw.o

# A helper library, always built if we're building the driver
obj-$(CONFIG_MYDRIVER) += mydriver_lib.o

Kconfig is a domain-specific language for describing configuration options — the 'what can be configured' layer. It answers: what choices exist, what are their types, what are their defaults, and what depends on what?

Every subsystem has a Kconfig file. The root Kconfig sources them all recursively. When you run make menuconfig, a tool reads all these Kconfig files and presents you with a menu-driven interface for setting your choices.

Key Kconfig constructs:

• bool: An option that is either y (built-in) or n (excluded).
• tristate: An option that can be y (built-in), m (module), or n (excluded). Most driver options are tristate.
• int / hex / string: For numeric or string parameters.
• depends on: This option is only available if the named option is enabled. This enforces a dependency DAG over the configuration space.
• select: If this option is enabled, automatically enable the named option. Use sparingly — it can create cycles.
• default: The default value if the user doesn't set it explicitly.
• help: Documentation string shown in menuconfig.

After running menuconfig (or any config frontend), the result is written to .config in the kernel source tree. Kconfig also generates include/generated/autoconf.h, which translates every CONFIG_FOO=y into #define CONFIG_FOO 1 and every CONFIG_FOO=m into #define CONFIG_FOO_MODULE 1. This is how C code does #ifdef CONFIG_USB — it is just reading a generated header.

# An example Kconfig entry (e.g. in drivers/mydriver/Kconfig)

config MYDRIVER
	tristate "My Example Hardware Driver"
	depends on PCI && HAS_IOMEM
	select DMA_ENGINE
	default n
	help
	  This driver supports the fictional MyHardware PCI device.
	  If unsure, say N.

config MYDRIVER_DEBUG
	bool "Enable debug output for MyDriver"
	depends on MYDRIVER
	default n
	help
	  Enables verbose debug logging. This has a performance cost
	  in production builds. Say N unless debugging.

The .config file is the single source of truth for a kernel build's configuration. It is a text file — one line per option — that looks like:

CONFIG_USB=y
CONFIG_USB_STORAGE=m
# CONFIG_USB_SERIAL is not set

You interact with .config through several frontends:

• make menuconfig: A full-screen ncurses TUI. Browse, search (/), and toggle options. This is the most common interactive method. The equivalent GUI is make xconfig (Qt) or make gconfig (GTK).
• make defconfig: Creates a default .config for the current architecture from arch/<arch>/configs/<arch>_defconfig. This is the standard starting point for a new build.
• make ARCH=arm64 defconfig: Creates a default config for ARM64 (which lives at arch/arm64/configs/defconfig).
• make allmodconfig: Enables every option that can be a module, as a module. Useful for build-coverage testing.
• make allyesconfig: Enables everything as built-in. The resulting kernel is enormous.
• make tinyconfig: Absolute minimum kernel. Good for understanding what the smallest possible kernel looks like.
• make oldconfig: Given an existing .config that may be outdated (e.g. from an older kernel version), prompts you only for the new options that were added. Essential when upgrading.
• make savedefconfig: Saves a minimal defconfig (only non-default values) to defconfig. Used to maintain arch/*/configs/ files.

The .config file is architecture-specific — a config for x86 cannot be used for ARM. Always specify ARCH= when cross-compiling.

# Generate a default config for x86_64
make defconfig

# Interactively tweak the config
make menuconfig

# Build the kernel
make -j$(nproc)

# Cross-compile for ARM64:
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- defconfig
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -j$(nproc)

When you type make, the kernel build performs a multi-stage pipeline. Understanding each stage demystifies 'where does the kernel image come from?'

Stage 1: Configuration The .config file is read. include/generated/autoconf.h is regenerated if .config changed. Any source file that includes <linux/autoconf.h> (indirectly, via <linux/config.h>) now sees the correct CONFIG_* definitions.

Stage 2: Compilation Every obj-y and obj-m in every Kbuild Makefile is compiled. This produces .o files. Header dependencies from .d files are respected. The C compiler is always invoked with the flags from Makefile top-level, arch/<arch>/Makefile, and whatever subsystem-specific ccflags-y variables are set.

Stage 3: Linking built-ins In each directory, all obj-y objects are linked into a built-in.a archive. These are then linked together up the directory hierarchy. At the top level, all built-in.a archives are combined into vmlinux — the fully linked, uncompressed ELF kernel binary. This is the 'true' kernel.

Stage 4: Generating the boot image vmlinux is then processed by architecture-specific tools:

• On x86: objcopy strips the ELF headers to produce arch/x86/boot/compressed/vmlinux.bin, which is then compressed and wrapped with a small decompressor stub to produce arch/x86/boot/bzImage. The 'bz' stands for 'big zImage', not bzip2; modern kernels use gzip, lz4, or zstd.
• On ARM64: arch/arm64/boot/Image is the uncompressed raw binary; Image.gz is the compressed form. There is no self-decompressing stub needed on ARM64 because the bootloader (U-Boot, UEFI) handles decompression.

Stage 5: Modules obj-m objects are linked into .ko (kernel object) files. make modules_install copies them to /lib/modules/$(uname -r)/.

# After 'make', the key output files on x86:
#
# vmlinux          -- ELF, fully linked, uncompressed, has debug symbols
#                     (~50-500 MB)
# arch/x86/boot/bzImage  -- the actual bootable image (~5-15 MB compressed)
#                           this is what GRUB loads
# drivers/usb/core/usbcore.ko  -- a loadable module

# Inspect the ELF structure of vmlinux:
readelf -h vmlinux

# See the sections:
readelf -S vmlinux | head -40

# Check the size breakdown of the kernel image:
nm --size-sort vmlinux | tail -20

You do not always want to patch the kernel source tree directly. When writing a new driver or experimenting, you can build a loadable kernel module (.ko) entirely outside the kernel source tree. This is called an out-of-tree or external module build.

The mechanism: Kbuild provides a special 'external module' mode. When you run make -C /lib/modules/$(uname -r)/build M=$(pwd) modules, you are telling Make to:

1. Change directory (-C) to the kernel build directory (which contains the Kbuild infrastructure and the .config for the running kernel).
2. Use the current directory (M=$(pwd)) as the external module source tree.
3. Build only the modules target for that external tree.

Your out-of-tree module needs only:

1. The source files (e.g. hello.c).
2. A minimal Makefile with obj-m := hello.o.
3. The kernel headers/build directory for the running kernel (usually installed by your distro as linux-headers-$(uname -r)).

This is how third-party drivers like NVIDIA's proprietary driver, VirtualBox's vboxdrv, and countless others work. It is also the standard way to develop and test kernel code without rebuilding the entire kernel.

/* hello.c — minimal out-of-tree kernel module */
#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/init.h>

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Your Name");
MODULE_DESCRIPTION("Minimal hello-world kernel module");

static int __init hello_init(void)
{
    pr_info("hello: module loaded\n");
    return 0;
}

static void __exit hello_exit(void)
{
    pr_info("hello: module unloaded\n");
}

module_init(hello_init);
module_exit(hello_exit);

The Makefile for an out-of-tree module uses a two-phase trick. When you run make from your module directory, the Makefile first checks if KERNELRELEASE is defined. It is not defined in the first invocation (you are not inside a Kbuild context). So it re-invokes make with -C $(KDIR) to enter the Kbuild context, passing M=$(shell pwd) to point back at your source.

In the second invocation, Make runs inside the kernel build directory. Kbuild sets KERNELRELEASE, reads your directory's Makefile again, sees obj-m, and compiles your module with the correct compiler flags, include paths, and symbol tables.

This two-phase dance is the standard pattern for all out-of-tree modules. Notice that the obj-m line is the same syntax as in-tree — from Kbuild's perspective, your module looks identical to any other module.

After building, insmod hello.ko inserts the module, dmesg | tail shows your message, and rmmod hello removes it. modinfo hello.ko shows the metadata from the MODULE_* macros.

# Makefile for an out-of-tree module
# Place this in the same directory as hello.c

# If KERNELRELEASE is defined, Kbuild called us.
# Otherwise, this is the top-level invocation.

obj-m := hello.o

KDIR := /lib/modules/$(shell uname -r)/build
PWD  := $(shell pwd)

.PHONY: all clean

all:
	$(MAKE) -C $(KDIR) M=$(PWD) modules

clean:
	$(MAKE) -C $(KDIR) M=$(PWD) clean

# Build and test:
# $ make
# $ sudo insmod hello.ko
# $ dmesg | tail -3
# $ sudo rmmod hello
# $ dmesg | tail -3

The Linux kernel runs on dozens of CPU architectures: x86-64, ARM (32-bit and 64-bit), RISC-V, PowerPC, MIPS, s390, and more. When you build a kernel for a CPU different from the one you are compiling on, that is cross-compilation.

Kbuild handles this through two Make variables:

• ARCH: The target architecture. Valid values are the directory names under arch/: x86, arm, arm64, riscv, powerpc, etc. Note that arm64 is the Kbuild name; some external tools call it aarch64.
• CROSS_COMPILE: The prefix of the cross-compiler toolchain. For example, aarch64-linux-gnu- means your compiler is aarch64-linux-gnu-gcc, your linker is aarch64-linux-gnu-ld, etc.

These can be set on the make command line or exported as environment variables. The arch/<ARCH>/Makefile then sets architecture-specific flags, selects the right linker script, and specifies which image format to produce.

Cross-compiler toolchains for Linux are available from your distribution (apt install gcc-aarch64-linux-gnu) or from Linaro's releases, which provide prebuilt toolchains for ARM/ARM64. The kernel's scripts/ directory also contains helpers.

A key insight: cross-compiling the kernel is much simpler than cross-compiling userspace, because the kernel has no external library dependencies — it carries all its own infrastructure.

# Cross-compile for 64-bit ARM (Raspberry Pi 4, etc.)
export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-

make defconfig          # uses arch/arm64/configs/defconfig
make menuconfig         # ARM64-specific options visible
make -j$(nproc)         # produces arch/arm64/boot/Image

# Cross-compile for 32-bit RISC-V
export ARCH=riscv
export CROSS_COMPILE=riscv32-unknown-linux-gnu-
make defconfig
make -j$(nproc)

When you are working with the kernel build system, knowing the right make targets and debugging techniques saves enormous time.

Common targets:

• make help — lists all available targets. Always start here.
• make V=1 — verbose mode: prints every compiler and linker command as it runs. Invaluable for debugging compiler flags or understanding what Kbuild is actually doing.
• make C=1 — run sparse (a kernel static analysis tool) on every recompiled file.
• make W=1 — enable extra compiler warnings.
• make dtbs — build device tree blobs (ARM/ARM64 embedded targets).
• make modules — build only the modules.
• make modules_install INSTALL_MOD_PATH=/tmp/staging — install modules to a staging directory rather than /.
• make mrproper — deep clean: removes .config, generated files, everything. Equivalent to git clean -fdx on the build outputs.
• make clean — removes most generated files but keeps .config.

Debugging tips:

• make -n (dry-run) prints what would be executed without actually doing it.
• make -d (debug) prints every decision Make makes about which targets need rebuilding — very verbose, but shows exactly why something is or is not being rebuilt.
• The kernel's scripts/kconfig/ directory contains the C source code for all the config frontends if you want to understand Kconfig at a deeper level.
• grep -r 'CONFIG_FOO' arch/ drivers/ is how you find where a given config symbol is used.

# See all targets
make help

# Verbose build — see every compiler invocation:
make V=1 2>&1 | head -50

# Build only a single file (useful for fast iteration):
make drivers/usb/core/usb.o

# Build with extra warnings:
make W=1 -j$(nproc)

# See what flags a specific file is compiled with:
make V=1 drivers/usb/core/usb.o 2>&1 | grep 'gcc.*usb.c'