What You Will Learn

• How kbuild decides which files to compile using obj-y and obj-m rules
• The difference between vmlinux, Image, zImage, bzImage, and uImage
• How to cross-compile a kernel image for ARM and ARM64 targets
• Why building a uImage for a multi-platform ARM kernel needs LOADADDR
• How to inspect a build with verbose output and check the final binary with size

Prerequisites

• A downloaded and extracted kernel source tree (see our earlier lecture on getting kernel source)
• A cross-compilation toolchain installed for your target architecture
• A working .config file — see our Kconfig/menuconfig lectures if you don’t have one yet

What Kbuild Actually Does

Kbuild is not one program — it’s a collection of Makefiles and shell scripts layered on top of GNU Make. When you type make at the top of the kernel tree, the top-level Makefile reads your .config file, then walks into every subdirectory that has buildable code, reading a local Makefile in each one. Those local Makefiles don’t compile things directly — they list files using two special variables, obj-y and obj-m, and let Kconfig decide which of those variables each file lands in.

Here’s an original, simplified example. Imagine a fictional driver directory drivers/ep_demo/ with two source files, and a Kconfig option called CONFIG_EP_SENSOR:

obj-y                  += ep_core.o
obj-$(CONFIG_EP_SENSOR) += ep_sensor.o

ep_core.o is built unconditionally every time, because obj-y always resolves to “yes.” ep_sensor.o is conditional: if you set CONFIG_EP_SENSOR=y in your .config, it becomes part of the final kernel binary. If you set it to m, kbuild compiles it as a separate loadable module (ep_sensor.ko) instead of linking it into the kernel image. If the option is unset, the file is skipped entirely — it never even gets compiled. This single mechanism is how a kernel with tens of thousands of possible drivers ends up producing one image containing only what you asked for.

Running A Full Build

For most targets, a single command handles everything — configuring dependencies, compiling every selected object file, and linking the result:

$ make -j $(nproc) ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

ARCH tells kbuild which architecture-specific code under arch/ to pull in, and CROSS_COMPILE is prefixed onto every toolchain command (gcc, ld, objcopy, and so on) so the build uses your cross-compiler instead of your host compiler. The -j flag controls parallel jobs; matching it to your CPU core count is the usual guidance, since kbuild’s dependency graph parallelizes well.

Kernel Image Formats: What’s The Difference

A plain build produces vmlinux at the top of the source tree — the kernel as a full ELF binary, potentially containing debug symbols if CONFIG_DEBUG_INFO is enabled. Almost no real bootloader can load an ELF file directly, so kbuild post-processes vmlinux into a boot-ready format under arch/$ARCH/boot/. Which format you need depends entirely on your bootloader:

Building any of them uses the same pattern — just swap the make target:

$ make -j $(nproc) ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage
$ make -j $(nproc) ARCH=x86_64 bzImage
$ make -j $(nproc) ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- Image

The uImage And Multi-Platform LOADADDR Problem

Modern 32-bit ARM kernels almost always use multi-platform support, meaning one kernel binary can run on several different SoC families and picks the right one at boot time using the device tree. This creates a real complication for uImage specifically: the uImage header bakes in a fixed relocation address (where in physical RAM the kernel expects to be loaded), but different SoCs can have different RAM base addresses. A single multi-platform build has no one correct answer to bake in.

The fix is to tell mkimage explicitly which load address to target using LOADADDR, which you can find by checking the platform’s boot Makefile fragment under arch/arm/mach-*/ for the zreladdr-y value:

$ make -j $(nproc) ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
    LOADADDR=0x40008000 uImage

If you skip LOADADDR on a multi-platform build, mkimage will fail rather than guess — which is the correct behavior, since guessing wrong would produce a kernel that silently fails to boot.

Watching And Debugging The Build

By default kbuild prints a short summary line per file (CC for compile, LD for link, CHK for a generated header check). That’s fine when the build succeeds, but when it fails you usually need the real command line. Add V=1 to see it in full:

$ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- V=1 Image
[...]
aarch64-linux-gnu-gcc -Wp,-MMD,drivers/ep_demo/.ep_core.o.d -nostdinc \
  -I./arch/arm64/include -Iinclude -D__KERNEL__ -O2 -Wall \
  -c -o drivers/ep_demo/ep_core.o drivers/ep_demo/ep_core.c

This is often the fastest way to spot a missing include path, an accidentally-wrong CROSS_COMPILE prefix, or a stray warning-as-error flag.

Inspecting The Final Binary

Once the build finishes, it’s worth checking what you actually got. vmlinux is a standard ELF file, so ordinary binutils tools work on it — for example, checking section sizes with the cross-toolchain’s size command:

$ aarch64-linux-gnu-size vmlinux
   text    data     bss     dec     hex filename
7345120  612480 6210048 14167648  d84fe0 vmlinux

Alongside vmlinux, the build also produces System.map — a plain-text symbol table mapping kernel addresses to function and variable names. It’s what tools like kallsyms and crash-analysis utilities use to turn a raw address in an oops trace back into a readable function name.

Real-World Use Case: Switching Image Formats Mid-Project

A common situation on embedded boards: you inherit a board support package built around an old U-Boot that only understands uImage, but you’d rather move to a newer U-Boot with bootz support so you can drop the LOADADDR bookkeeping entirely. Knowing that zImage and uImage are the same compressed payload with only a small header difference means you can build both from the same tree, test zImage with a U-Boot upgrade, and keep uImage as a fallback — without touching a single line of kernel or driver code.

Common Mistakes And Troubleshooting

Best Practices

• Always match -j to your available CPU cores for faster iteration during driver development
• Keep a note of your board’s exact LOADADDR so you’re not re-deriving it every time you rebuild uImage
• Prefer newer U-Boot with bootz/booti support where possible — it removes an entire class of LOADADDR mistakes
• Check size vmlinux after enabling new drivers to catch unexpected bloat before flashing

Performance Considerations

Parallel builds scale close to linearly with core count up to a point, but disk I/O and available RAM (object files, ccache if used) can become the bottleneck on large trees. Using a tmpfs build directory or ccache is a common way to cut repeated build times significantly during active driver iteration.

Summary And Key Takeaways

• Kbuild decides what to compile using obj-y/obj-m rules driven by your .config
• vmlinux is the raw ELF output; Image/zImage/bzImage/uImage are bootloader-ready post-processed formats
• Multi-platform ARM uImage builds require an explicit LOADADDR
• V=1 and size are your first tools when a build fails or looks unexpectedly large

Conclusion

Once you see kbuild as “Kconfig decides the file list, Make compiles it, arch-specific scripts repackage the result for your bootloader,” the whole system stops feeling like a black box. That mental model is the foundation for everything else in this free linux kernel development course — from writing your own drivers to debugging boot failures on real hardware. In the next lecture, we’ll cover compiling device trees, the other artifact your bootloader needs alongside the kernel image itself.

Frequently Asked Questions