linux-kernel-module-cheat: a Buildroot and QEMU setup for kernel and baremetal work

What linux-kernel-module-cheat actually gives you

The problem this repository addresses is the setup work that comes before any kernel experiment. Building a kernel that boots under emulation, wiring a debugger to it, and keeping the root filesystem in sync is a multi-day chore if you do it by hand. linux-kernel-module-cheat packages that chore into scripts. The README describes the goal as an emulation setup for studying the Linux kernel, kernel modules, QEMU, gem5, and x86_64, ARMv7 and ARMv8 userland and baremetal assembly, with GDB and KGDB working. Everything is built from source, on top of Buildroot and crosstool-NG. The target audience is narrow: people who want to step through kernel code, write modules against a kernel they control, or run assembly on emulated hardware. If you want a tutorial that compiles one module against your distro kernel, this is the wrong size of tool.

Buildroot, crosstool-NG and the run wrapper

The mechanism is a set of top-level scripts that drive Buildroot and crosstool-NG. Buildroot produces the root filesystem and the cross toolchain, while crosstool-NG supplies the baremetal toolchain used by the baremetal targets. The repository layout shows the split: build-buildroot, build-crosstool-ng, build-qemu, build-gem5, build-linux, build-modules, build-baremetal and build-userland are separate entry points, and buildroot_config, buildroot_override, buildroot_packages and crosstool_ng_config hold the configuration those builds consume. A ./run wrapper starts the resulting system under QEMU or gem5, and ./build drives the individual components. The Python files cli_function.py, common.py and config.py appear to hold the shared command-line and configuration logic, with cli_function_test_config.py and cli_function_test_config_2.py as test fixtures. The practical consequence of this design is that the emulated system and the host stay separate: you build once, then run the image repeatedly. The cost is that the first build is long, because a kernel, QEMU and a toolchain are compiled rather than downloaded as binaries.

Installing it on Ubuntu and booting QEMU

The README gives a tested path for Ubuntu 24.04. It clones the repository, installs Docker, creates a Python virtual environment and runs the setup script, then enters a Docker shell with run-docker. The Dockerfile confirms the container side: it starts from ubuntu:20.04, copies setup and requirements.txt, sets LKMC_IN_DOCKER=true, and runs /setup -y. The requirements.txt pins pexpect, Cython and setuptools, and also pulls a china-dictatorship wheel from a GitHub release URL, which is an unusual dependency to see in a kernel lab and worth knowing about before you run setup.

git clone https://github.com/cirosantilli/linux-kernel-module-cheat
cd linux-kernel-module-cheat
sudo apt install docker
python3 -m venv .venv
. .venv/bin/activate
./setup
./run-docker create
./run-docker sh

Those commands leave you inside the Docker shell. The next two commands are run there, not on the host. The first builds the QEMU and Buildroot targets and downloads the dependencies; the second boots the result.

./build --download-dependencies qemu-buildroot
./run

After ./run completes, the README states you are in a Linux userland shell running on QEMU with everything built from source. Expect the build step to dominate the session; the README does not give a duration, and it depends on your machine.

Where the setup gets in your way

The first limitation is the entry cost. Building a kernel, QEMU and a toolchain from source takes a long time and substantial disk space, and the README does not document a rollback path or a way to abort a partial build cleanly. If your goal is to understand what a module init function does, this is a heavy way to learn it. The second limitation is the host assumption. The README says the setup is tested on Ubuntu 24.04 and the Dockerfile pins ubuntu:20.04, so the supported path is Linux with Docker. Nothing in the README describes a native macOS or Windows workflow, and the Docker requirement is stated as a sudo apt install step. The third is scope: the repository describes itself as a study and development setup, not a production build system, and the recent release tags are old, with v3.0 from 2019 and a sha-tagged release from 2019-06-30. The commit history is more recent than the tags, but anyone expecting a maintained release cadence should look at the commit log rather than the releases page.

How it compares with a plain Buildroot checkout

Buildroot on its own already builds a cross toolchain, a kernel and a root filesystem, and it is the upstream project this repository wraps. The difference is what sits on top. A plain Buildroot checkout gives you a configuration system and a build; it does not give you a ./run wrapper that boots the image under QEMU with the debugger attached, nor the gem5 targets, nor the baremetal and userland assembly examples. linux-kernel-module-cheat adds those layers and pins Buildroot and crosstool-NG configurations in buildroot_config and crosstool_ng_config so the result is reproducible. The trade-off runs the other way too: Buildroot is a general embedded build system with a wide package selection and its own documentation, while this repository is a curated lab with a fixed set of targets. If you need to ship a product image, use Buildroot directly. If you need to debug a kernel under an emulator, the wrapper scripts are the part you are actually buying.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-06-16. The release tags are much older: v3.0 dates from 2019-01-22 and the most recent tag is a sha-named release from 2019-06-30. That gap matters when you plan upgrades, because it suggests the tagged releases are not the channel the project uses. Upgrading means re-running the build against updated Buildroot and crosstool-NG configurations, and since everything is compiled from source, an upgrade is a full rebuild rather than a package update. The licence is GPL-3.0, per the repository metadata and LICENSE.txt. That is a copyleft licence, so if you plan to redistribute a modified version of the scripts, the obligations attach to what you distribute. This is a description of the licence identifier, not legal advice; read the licence text and talk to counsel if redistribution is on the table.

Editorial conclusion

Adopt it if you need a reproducible emulation lab for kernel modules, QEMU or baremetal assembly and you are willing to run a long first build inside Docker on Ubuntu. Do not adopt it if you only want a minimal hello-world module tutorial, since the setup cost is far larger than that task needs. Before committing, verify the disk space and time the first ./build --download-dependencies qemu-buildroot run takes on your machine, and confirm that your host can run Docker.

Frequently asked questions

Official sources

1. cirosantilli/linux-kernel-module-cheat on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases