Building Bluejay

Bluejay uses the home-grown Jmk build system, which is basically just a GNU m4 script that generates makefiles from Jmk files — makefiles with some custom macros.

To build a fresh clone of Bluejay the first thing you will need to do is run bin/jmk to generate your makefiles for you. You should get some output like this:

Processing ./boot/initrd/Jmk
Processing ./src/kernel/dri/ata_pio/Jmk
Processing ./src/kernel/dri/ahci/Jmk
Processing ./src/kernel/dri/pci/Jmk
Processing ./src/kernel/Jmk
Processing ./src/mkinitrd/Jmk
Processing ./src/lisp/Jmk

Then just build using src/kernel/Makefile. There are a few additional targets for your convenience:

  • qemu builds and launches the kernel using QEMU’s SeaBIOS

  • qemu-iso builds a GRUB ISO and launches using QEMU

  • install builds a GRUB ISO and installs it to boot/bluejay.iso

  • debug launches kernel in QEMU and launches GDB in the terminal.

  • debug-wait launches kernel in QEMU and starts a GDB server on localhost:1234. This is recommended if you want to debug since you can connect to it from vscode or any other IDE. .vscode/launch.json is set up to work with this so you can debug the kernel very easily.

In order to build Bluejay you will need the following dependencies:

gcc gcc-multilib nasm qemu-system-i386 make m4 python3 awk

There are some additional dependencies for building a GRUB ISO but I don’t remember them at the time of writing.

Common Issues

If when launching Bluejay in QEMU with make qemu you see the message

[ DEBUG ] mb.mods_addr = <whatever>, 0x<whatever>

Followed by a page fault (#PF), your QEMU is out of date. You can either run the GRUB ISO (with make qemu-iso), which is slower, or upgrade your QEMU to at least version 6.0.

This is because prior to 6.0 QEMU’s integrated bootloader did not support multiboot modules. This message is caused by the kernel attempting to read a module that was loaded incorrectly.