| swissChili | e00e88a | 2021-05-30 17:54:26 -0700 | [diff] [blame] | 1 | Building Bluejay |
| 2 | ================ |
| 3 | |
| 4 | Bluejay uses the home-grown ``Jmk`` build system, which is basically just a GNU |
| 5 | m4 script that generates makefiles from ``Jmk`` files --- makefiles with some |
| 6 | custom macros. |
| 7 | |
| 8 | To build a fresh clone of Bluejay the first thing you will need to do is run |
| 9 | ``bin/jmk`` to generate your makefiles for you. You should get some output like |
| 10 | this: |
| 11 | |
| 12 | .. code-block:: |
| 13 | |
| 14 | Processing ./boot/initrd/Jmk |
| 15 | Processing ./src/kernel/dri/ata_pio/Jmk |
| 16 | Processing ./src/kernel/dri/ahci/Jmk |
| 17 | Processing ./src/kernel/dri/pci/Jmk |
| 18 | Processing ./src/kernel/Jmk |
| 19 | Processing ./src/mkinitrd/Jmk |
| 20 | Processing ./src/lisp/Jmk |
| 21 | |
| 22 | Then just build using ``src/kernel/Makefile``. There are a few additional |
| 23 | targets for your convenience: |
| 24 | |
| 25 | - ``qemu`` builds and launches the kernel using QEMU's SeaBIOS |
| 26 | - ``qemu-iso`` builds a GRUB ISO and launches using QEMU |
| 27 | - ``install`` builds a GRUB ISO and installs it to ``boot/bluejay.iso`` |
| 28 | - ``debug`` launches kernel in QEMU and launches GDB in the terminal. |
| 29 | - ``debug-wait`` launches kernel in QEMU and starts a GDB server on ``localhost:1234``. |
| 30 | This is recommended if you want to debug since you can connect to it from vscode or |
| 31 | any other IDE. ``.vscode/launch.json`` is set up to work with this so you can debug |
| 32 | the kernel very easily. |
| 33 | |
| 34 | In order to build Bluejay you will need the following dependencies:: |
| 35 | |
| 36 | gcc gcc-multilib nasm qemu-system-i386 make m4 python3 awk |
| 37 | |
| 38 | There are some additional dependencies for building a GRUB ISO but I don't |
| swissChili | 4418ca5 | 2021-06-14 17:36:00 -0700 | [diff] [blame] | 39 | remember them at the time of writing. |
| swissChili | caa2478 | 2021-07-19 14:29:58 -0700 | [diff] [blame] | 40 | |
| 41 | Common Issues |
| 42 | ------------- |
| 43 | |
| 44 | If when launching Bluejay in QEMU with ``make qemu`` you see the message :: |
| 45 | |
| 46 | [ DEBUG ] mb.mods_addr = <whatever>, 0x<whatever> |
| 47 | |
| 48 | Followed by a page fault (``#PF``), your QEMU is out of date. You can either run |
| 49 | the GRUB ISO (with ``make qemu-iso``), which is slower, or upgrade your QEMU to |
| 50 | at least version 6.0. |
| 51 | |
| 52 | This is because prior to 6.0 QEMU's integrated bootloader did not support |
| 53 | multiboot modules. This message is caused by the kernel attempting to read a |
| 54 | module that was loaded incorrectly. |