lumine

cheapskate x86_64/aarch64 UEFI bootloader

features

[!WARNING]

• lumine is yet somewhat incomplete, for a bootloader with a similar concept, see limine
• docs are written primarily for x86_64, just replace BOOTX64 with BOOTAA64 and the rest should be equivalent.
• linux kernels should be built with efi stub, as linux boot protocol is not yet implemented. this should be enabled by default on most distributions.

• boot linux kernels
• chainload efi executables

config

config for lumine is currently written in zig object notation, see default config for reference. see installation for instructions on where to put config file.

TODO: config documentation

compiling

lumine uses the zig build system version 0.16.0, which you can download here.

zig build -Doptimize=ReleaseSafe -Darch=x86_64
# efi executable is now in `zig-out/build/BOOTX64.efi` 

available build/run options:

-Darch=[enum]                cpu architecture
                               Supported Values:
                                 x86_64
                                 aarch64
-Dqemu=[string]              override qemu executable
-Dno-serial=[bool]           dont add stdio serial commands
-Dovmf=[lazy_path]           override ovmf firmware dependency
-Dovmf-dep=[bool]            use ovmf dependency instead
-Dlinux=[string]             dir containing `vmlinuz` and `initrd`
-Dconfig=[string]            path to config file

installation

i dont want installation or setup or usage to be something convoluted or "hidden" away like grub does, so that you can literally do it manually and it works fine, or maybe automate finding of installations like grub's os-prober or whatever.

therefore, lumine is only two files:

• efi executable: can be placed anywhere, partition default /EFI/BOOT/BOOTX64.EFI or really any location like /lumine/lumine.efi etc etc, you have the freedom.
• config file: must be placed in any of these paths in the same partition as lumine's EFI, checked in the same order. i do plan to add support for path relative to lumine's efi.
  • /lumine/config.zon
  • /lumine/lumine.zon
  • /lumine.zon

emulation

edk2 ovmf firmware will be downloaded as a zig dependency lazily when needed. otherwise, to specify a custom ovmf firmware binary, use -Dovmf= flag with path to binary, which is used in qemu. to get them from dependency, use -Dovmf-dep flag. qemu binary used can be overridden by -Dqemu= flag.

for testing purposes, you can use the somewhat purpose-built minimux which supports both x86_64 and aarch64 architectures, or tinycorelinux which only supports x86_64 (that i tested). both "distributions" are designed to have initramfs as root filesystem, and are what i tested extensively.

put the initramfs and vmlinuz kernel image in the res/<ARCH>/ directory, and the build system will automatically use it. to specify a custom directory, use -Dlinux= flag. vmlinuz and initrd files from this directory are copied /linux/ directory in the qemu virtual machine.

config file copied to /lumine.zon is res/lumine.zon, this can be overriden by -Dconfig= flag.

# starts in serial console
zig build -Darch=x86_64 -Dovmf-dep run

license

this project is licensed under BSD-2-Clause license