diff --git a/README.md b/README.md index be562a1..ec8ac9f 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,15 @@ existing UEFI bootloader or booted by the hardware directly. Sprout is licensed under Apache 2.0 and is open to modifications and contributions. +## Documentation + +- [Fedora Setup Guide] +- [Development Guide] +- [Contributing Guide] +- [Sprout License] +- [Code of Conduct] +- [Security Policy] + ## Features NOTE: Currently, Sprout is experimental and is not intended for production use. For example, it doesn't currently @@ -116,3 +125,10 @@ chainload.path = "$boot\\$chainload" chainload.options = ["$options"] chainload.linux-initrd = "$boot\\$initrd" ``` + +[Fedora Setup Guide]: ./docs/fedora-setup.md +[Development Guide]: ./DEVELOPMENT.md +[Contributing Guide]: ./CONTRIBUTING.md +[Sprout License]: ./LICENSE +[Code of Conduct]: ./CODE_OF_CONDUCT.md +[Security Policy]: ./SECURITY.md diff --git a/docs/fedora-setup.md b/docs/fedora-setup.md new file mode 100644 index 0000000..5d57726 --- /dev/null +++ b/docs/fedora-setup.md @@ -0,0 +1,113 @@ +# Sprout on Fedora + +## Prerequisites + +- Modern Fedora release: tested on Fedora Workstation 42 and 43 +- EFI System Partition mounted on `/boot/efi` (the default) +- ext4 or FAT32/exFAT formatted `/boot` partition + +## Step 1: Base Installation + +Download the latest sprout.efi release from the [GitHub releases page](https://github.com/sprout-dev/sprout/releases). +For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file. +Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/BOOT/sprout.efi` on your EFI System Partition. + +Additionally, you will want to install the `edk2-ext4` package, which provides the ext4 filesystem support for Sprout. + +```bash +# Install the edk2-ext4 package which provides ext4 support for Sprout. +$ sudo dnf install edk2-ext4 +# Create a directory for sprout drivers. +$ sudo mkdir -p /boot/efi/sprout/drivers +# For x86_64 systems, copy the ext4x64.efi driver to the sprout drivers directory. +$ sudo cp /usr/share/edk2/drivers/ext4x64.efi /boot/efi/sprout/drivers/ext4.efi +# For ARM64 systems, copy the ext4aa64.efi driver to the sprout drivers directory. +$ sudo cp /usr/share/edk2/drivers/ext4aa64.efi /boot/efi/sprout/drivers/ext4.efi +``` + +## Step 2: Configure Sprout + +Since Fedora uses the BLS specification, you can use the `bls` generator to autoconfigure Sprout for Fedora. + +Write the following file to `/boot/efi/sprout.toml`: + +```toml +# sprout configuration: version 1 +version = 1 + +# load an EFI driver for ext4. +[drivers.ext4] +path = "\\sprout\\drivers\\ext4.efi" + +# extract the full path of the first filesystem +# that contains \loader\entries as a directory +# into the value called "boot" +[extractors.boot.filesystem-device-match] +has-item = "\\loader\\entries" + +# use the sprout bls module to scan a bls +# directory for entries and load them as boot +# entries in sprout, using the entry template +# as specified here. the bls action below will +# be passed the extracted values from bls. +[generators.boot.bls] +path = "$boot\\loader\\entries" +entry.title = "$title" +entry.actions = ["bls"] + +# the action that is used for each bls entry above. +[actions.bls] +chainload.path = "$boot\\$chainload" +chainload.options = ["$options"] +chainload.linux-initrd = "$boot\\$initrd" +``` + +## Step 3, Option 1: Configure GRUB to load Sprout (recommended) + +You can configure GRUB to add a boot entry for Sprout, so you can continue to use GRUB without interruption. + +You will need to find the UUID of your EFI System Partition. You can do this by running the following command: +```bash +$ grep "/boot/efi" /etc/fstab | awk '{print $1}' | awk -F '=' '{print $2}' +SAMPLE-VALUE +``` + +The GRUB configuration for Sprout is as follows, replace `SAMPLE-VALUE` with the UUID of your EFI System Partition: + +```grub +menuentry 'Sprout' $menuentry_id_option 'sprout' { + insmod part_gpt + insmod fat + search --no-floppy --fs-uuid --set=root SAMPLE-VALUE + chainloader /EFI/BOOT/sprout.efi +} +``` + +You can append this to `/etc/grub.d/40_custom` and run the following command to update your configuration: +```bash +$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg +``` + +To update your GRUB configuration. + +Make sure to update your GRUB environment to show the menu: + +```bash +$ sudo grub2-editenv - set menu_auto_hide=0 +``` + +You may now reboot your system and select Sprout from the GRUB menu. + +## Step 3, Option 2: Configure your EFI firmware for Sprout + +You can configure your EFI boot menu to show Sprout as an option. + +To do so, please find the partition device of your EFI System Partition and run the following: + +```bash +$ sudo efibootmgr -d /dev/esp_partition_here -C -L 'Sprout' -l '\EFI\BOOT\sprout.efi' +``` + +This will add a new entry to your EFI boot menu called `Sprout` that will boot Sprout with your configuration. + +Now if you boot into your UEFI firmware, you should see Sprout as an option to boot.