Linux Kernel Development setup for MacOS

Feb 10, 2025

Introduction
Prerequisites
Setup Docker
Setup QEMU
Generate config and initrd
Build Kernel
Test Build
Additional

Introduction

This repository serves as a guide to set up a development environment in MacOS for working on the Linux kernel. It includes essential tools, configurations, and practices to make my workflow efficient. My primary working machine is an M2 MacBook Air.

My username inside the Linux system is maoth. You can change this inside the Dockerfile provided above by replacing all instances of maoth with the username you want to use.

This is the second iteration of my setup. The previous iteration had issues with tracking git files. You can check the previous iteration on GitHub history.

Prerequisites

Install Docker.
This step is done because I want to use a shared volume between Docker and host system. This helps me in taking backups easily. It is not possible to build the kernel in the case-insensitive file system of MacOS. So, we need to create a new partition using Disk Utility if we wish to have a shared volume.
- Create a new partition of atleast 90GB.
- Set the formatting option of this partition to Mac OS Extended (Case-sensitive, Journaled).
- I gave the partition name as Linux. Make sure to change the symlink provided in the repo according to the partition name.
Install QEMU:
```
brew install qemu
```

Setup Docker

Build the docker image using dockerfile.
```
docker build -t ubuntu-dev .
```
Note: We are using ubuntu-dev as the image name.
Create container and mount home directory of username to the partition created above.
```
docker run --name kernel-dev -it -v /Volumes/Linux:/home/maoth ubuntu-dev /bin/bash
```
Note: I have maoth as the username. Make changes as required. We are using kernel-dev as the name for container.
After exiting from above, we may have to start the container:
```
docker start kernel-dev
```
Set sudo password for the user using root:
```
docker exec -u root -ti kernel-dev /bin/bash
```
Inside linux shell, use command given below to change password:
```
passwd maoth
```
We can exec normally now.
```
docker exec -it kernel-dev /bin/bash
```

Clone the Linux kernel source:

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

Setup QEMU

For testing changes, we use QEMU for virtualization. First download a Linux image (I use Ubuntu Server 24.04.1 arm64).

We need an UEFI firmware for booting QEMU, we can use the one provided with QEMU itself: /opt/homebrew/Cellar/qemu/9.2.0/share/qemu/edk2-aarch64-code.fd
Create a disk somewhere:
```
qemu-img create -f qcow2 ubuntu.img 30G
```

Launch the image and install it from the QEMU graphical window:

qemu-system-aarch64 \
   -monitor stdio \
   -display default,show-cursor=on \
   -M virt \
   -accel hvf \
   -cpu host \
   -smp 4 \
   -m 4G \
   -bios edk2-aarch64-code.fd \
   -device virtio-gpu-pci \
   -device qemu-xhci \
   -device usb-kbd \
   -device usb-tablet \
   -device intel-hda \
   -device hda-duplex \
   -device virtio-net-pci,netdev=net0 \
   -netdev user,id=net0,hostfwd=tcp::8022-:22 \
   -drive if=virtio,file=ubuntu.img,format=qcow2 \
   -cdrom /Volumes/Expansion/BACKUPS_Images/ubuntu-24.04.1-live-server-arm64.iso

Note: Provide the correct path to images above in file and -cdrom option.

Generate config and initrd

After installing the image, launch the raw disk image:

qemu-system-aarch64 \
   -nographic \
   -M virt \
   -accel hvf \
   -cpu host \
   -smp 4 \
   -m 4G \
   -bios edk2-aarch64-code.fd \
   -device virtio-gpu-pci \
   -device qemu-xhci \
   -device usb-kbd \
   -device usb-tablet \
   -device intel-hda \
   -device hda-duplex \
   -device virtio-net-pci,netdev=net0 \
   -netdev user,id=net0,hostfwd=tcp::8022-:22 \
   -drive if=virtio,file=ubuntu.img,format=qcow2

Run update:
```
sudo apt update && sudo apt upgrade
```
Copy the config file from /boot:
```
cp /boot/config* ~/.config
```
Generate the initrd file:
```
sudo mkinitramfs -o ~/initrd.img
```

Install and start SSH for file transfer:

sudo apt install openssh-server
sudo systemctl enable ssh
sudo systemctl start ssh

From MacOS shell, copy the files:

scp -P 8022 maoth@localhost:{.config,initrd.img} .

Move the config file into linux source directory:
```
mv .config /Volumes/Linux/linux/
```

Build Kernel

Get into the Docker shell:
```
docker exec -it kernel-dev /bin/bash
```
Navigate into the kernel source directory:
```
cd linux
```
Build the config file:
```
make olddefconfig
```

Run the following scripts to disbale errors regarding certificates:

scripts/config --disable SYSTEM_TRUSTED_KEYS
scripts/config --disable SYSTEM_REVOCATION_KEYS

Build the kernel:
```
make -j8
```

Build the modules:

mkdir -p ~/tmp_modules
make modules_install INSTALL_MOD_PATH=~/tmp_modules/

Give correct permissions:
```
sudo chown -R root:root ~/tmp_modules/
```

Copy files to QEMU machine:

cd ~/tmp_modules
tar cfp - * | ssh -p 8022 root@host.docker.internal '(cd / && tar xfp - -k)'

Test Build

Launch the installed image with newly built kernel:

qemu-system-aarch64 \
   -nographic \
   -M virt \
   -accel hvf \
   -cpu host \
   -smp 4 \
   -m 4G \
   -device virtio-gpu-pci \
   -device qemu-xhci \
   -device usb-kbd \
   -device usb-tablet \
   -device intel-hda \
   -device hda-duplex \
   -device virtio-net-pci,netdev=net0 \
   -netdev user,id=net0,hostfwd=tcp::8022-:22 \
   -drive if=virtio,file=ubuntu.img,format=qcow2 \
   -kernel linux/arch/arm64/boot/Image -initrd initrd.img \
   -append "root=/dev/mapper/ubuntu--vg-ubuntu--lv"

Additional

Linux Foundation - Beginner’s Guide
Kernel Newbies
kernel.org
VMWare Fusion - for kernel testing.
Running a full arm64 system stack under QEMU

Dhiraj Gagrai