<!-- working title -->
# lumine

cheapskate x86_64/aarch64 UEFI bootloader

## features

> [!WARNING]
> - lumine is yet somewhat incomplete, for a bootloader with a similar concept, see [limine](https://github.com/Limine-Bootloader/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](./res/lumine.zon) for reference.
see [installation](#installation) for instructions on where to put config file.

TODO: config documentation

## compiling

lumine uses the [zig build system](https://ziglang.org/learn/build-system/) version `0.16.0`, which
you can download [here](https://ziglang.org/download/).

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

available build/run options:

```sh
-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](https://codeberg.org/dragsbruh/minimux) which supports
both x86_64 and aarch64 architectures, or [tinycorelinux](http://tinycorelinux.net/) 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.

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

## license

this project is licensed under [BSD-2-Clause](./LICENSE) license