RedBear-OS/local/docs/GRUB-INTEGRATION-PLAN.md

GRUB Integration Plan — Red Bear OS

Date: 2026-04-17 Status: Phase 1 — recipe builds successfully, post-build script ready, awaiting QEMU validation Approach: Option A — GRUB as boot manager, chainloading Redox bootloader

Overview

Add GNU GRUB as an optional boot manager for Red Bear OS. GRUB presents a menu at boot and chainloads the existing Redox bootloader, which then boots the kernel normally. This gives users:

• Multi-boot capability alongside Linux, Windows, or other OSes
• Boot menu with timeout and manual selection
• Familiar GRUB rescue shell for debugging
• No changes to the Redox kernel, RedoxFS, or existing boot flow

Architecture

UEFI firmware
  → EFI/BOOT/BOOTX64.EFI (GRUB standalone image)
    → grub.cfg: default entry chainloads Redox bootloader
      → EFI/REDBEAR/redbear.efi (Redox bootloader)
        → Reads RedoxFS partition
          → Loads kernel
            → Boots Red Bear OS

ESP Layout (GRUB mode)

EFI/
├── BOOT/
│   ├── BOOTX64.EFI      ← GRUB (primary, loaded by UEFI firmware)
│   └── grub.cfg          ← GRUB configuration
└── REDBEAR/
    └── redbear.efi       ← Redox bootloader (chainload target)

ESP Layout (default, no GRUB)

EFI/
└── BOOT/
    └── BOOTX64.EFI       ← Redox bootloader (unchanged)

Why GRUB?

1. GRUB does not support RedoxFS. Writing a GRUB filesystem module for RedoxFS is high-risk, GPL-licensing-sensitive work. Chainloading avoids it.
2. The Redox bootloader works. It reads RedoxFS directly and boots the kernel. No need to replicate that logic in GRUB.
3. GRUB is universally understood. System administrators know GRUB. A grub.cfg is easier to customize than a custom bootloader.
4. Multi-boot. GRUB can boot Linux, Windows, and other OSes alongside Red Bear OS without any changes to those systems.

GRUB Module Set

The standalone EFI image includes these modules:

Module	Purpose
part_gpt	GPT partition table support
part_msdos	MBR partition table support
fat	FAT32 filesystem (ESP)
ext2	ext2/3/4 filesystem
normal	Normal mode (menu, scripting)
configfile	Load configuration files
search	Search for files/volumes
search_fs_uuid	Search by filesystem UUID
search_label	Search by volume label
chain	Chainload other bootloaders
echo	Print messages
test	Conditional expressions
ls	List files and devices
cat	Display file contents
halt	Shut down
reboot	Reboot

No RedoxFS module is needed — GRUB chainloads the Redox bootloader instead.

GRUB Configuration

The default grub.cfg:

# Red Bear OS GRUB Configuration
set default=0
set timeout=5

menuentry "Red Bear OS" {
    chainloader /EFI/REDBEAR/redbear.efi
    boot
}

menuentry "Reboot" {
    reboot
}

menuentry "Shutdown" {
    halt
}

Users can customize grub.cfg to add entries for other operating systems, change the timeout, or add additional Red Bear OS entries (e.g., recovery mode with different kernel parameters, once supported).

ESP Size Requirements

Component	Measured Size
GRUB EFI binary (with modules)	540 KiB
Redox bootloader	100–200 KiB
grub.cfg	< 1 KiB
Total	~1 MiB

The default ESP is 1 MiB (too small for GRUB). Configs using GRUB must set:

[general]
efi_partition_size = 16   # 16 MiB, enough for GRUB + Redox bootloader + margin

Implementation — Phase 1: Post-Build Script

Phase 1 uses a post-build script to modify the ESP in an existing disk image. This approach requires no changes to the installer and works immediately.

Files

File	Purpose
local/recipes/core/grub/recipe.toml	Build GRUB from source, produce grub.efi
local/recipes/core/grub/grub.cfg	Default GRUB configuration
local/scripts/install-grub.sh	Post-build ESP modification script
local/scripts/fat_tool.py	Python FAT32 tool (no mtools dependency)
recipes/core/grub → local/recipes/core/grub	Symlink for recipe discovery

Workflow

# 1. Build GRUB recipe
make r.grub

# 2. Build Red Bear OS (with larger ESP)
make all CONFIG_NAME=redbear-full   # Must have efi_partition_size = 16

# 3. Install GRUB into disk image
./local/scripts/install-grub.sh build/x86_64/harddrive.img

# 4. Test
make qemu

Requirements

• Python 3 (for fat_tool.py — no mtools dependency)
• GRUB build dependencies: gcc, make, bison, flex, autoconf, automake
• ESP must be ≥ 8 MiB (set efi_partition_size = 16 in config)

Implementation — Phase 2: Installer-Native Support (Future)

Phase 2 adds GRUB awareness directly to the Redox installer, eliminating the post-build script step. This requires modifying the installer patch.

Changes Required

1. GeneralConfig: Add bootloader: Option<String> field ("redox" default, "grub" for GRUB)
2. DiskOption: Add bootloader_grub: Option<&[u8]>, grub_config: Option<&[u8]> fields
3. fetch_bootloaders: When bootloader = "grub", also install the grub package
4. with_whole_disk / with_whole_disk_ext4: When GRUB data present:
   • Create EFI/REDBEAR/ directory
   • Write GRUB as EFI/BOOT/BOOTX64.EFI
   • Write Redox bootloader as EFI/REDBEAR/redbear.efi
   • Write grub.cfg to EFI/BOOT/grub.cfg
   • Auto-set ESP size to 16 MiB if not configured
5. CLI: Add --bootloader grub flag to installer binary

Config Usage (Phase 2)

# config/redbear-full-grub.toml
include = ["redbear-full.toml"]

[general]
bootloader = "grub"
efi_partition_size = 16

GRUB Recipe Design

The GRUB recipe uses template = "custom" because GRUB must be built for the host machine (it's a build tool that produces EFI binaries), not for the Redox target. The cookbook's configure template cross-compiles for Redox, which is wrong for GRUB.

Key build steps:

1. Configure with --target=x86_64 --with-platform=efi (produces x86_64 EFI)
2. Disable unnecessary components (themes, mkfont, mount, device-mapper)
3. Run grub-mkimage to create standalone EFI binary with curated modules
4. Stage grub.efi and grub.cfg to /usr/lib/boot/

Build Notes

The recipe uses template = "custom" because the cookbook's default configure template sets --host="${GNU_TARGET}" for Redox cross-compilation, which is wrong for GRUB (a host build tool producing EFI binaries).

Two issues required workarounds:

1. Cross-compiler override. The cookbook sets CC, CXX, CFLAGS, etc. to the Redox cross-toolchain. GRUB must be built with the host compiler. Fix: unset CC CXX CPP LD AR NM RANLIB OBJCOPY STRIP PKG_CONFIG and unset CFLAGS CXXFLAGS CPPFLAGS LDFLAGS at the top of the script.

2. Missing extra_deps.lst. GRUB 2.12 release tarballs omit grub-core/extra_deps.lst (normally generated by autogen.sh from git). Fix: touch "${COOKBOOK_SOURCE}/grub-core/extra_deps.lst" before configure.

3. grub.cfg location. The config file lives in the recipe directory (${COOKBOOK_RECIPE}/grub.cfg), not in the extracted source tarball (${COOKBOOK_SOURCE}/). The copy step uses COOKBOOK_RECIPE.

Security Considerations

• GRUB configuration is on the ESP (FAT32), which is readable/writable by any OS
• Secure Boot: GRUB standalone images are not signed. Users needing Secure Boot must sign BOOTX64.EFI with their own key or use shim
• The chainload target (EFI/REDBEAR/redbear.efi) is also on the ESP
• No credentials or secrets are stored in the GRUB configuration

Limitations

• GRUB cannot read RedoxFS (no module exists)
• Cannot pass kernel parameters directly (chainloading bypasses this)
• BIOS boot is not supported in Phase 1 (only UEFI)
• Requires mtools on the host for Phase 1 post-build script
• ESP must be manually sized to ≥ 8 MiB in config

Testing

# Build GRUB recipe
make r.grub

# Verify GRUB binary was produced
find repo -name "grub.efi" -path "*/usr/lib/boot/*"

# Build full image with larger ESP
# (Add efi_partition_size = 16 to config first)
make all CONFIG_NAME=redbear-full

# Install GRUB
./local/scripts/install-grub.sh build/x86_64/harddrive.img

# Verify ESP contents
mdir -i build/x86_64/harddrive.img@1048576 -/ ::/

# Boot in QEMU
make qemu

# Expected: GRUB menu appears, "Red Bear OS" entry boots successfully

References

• GNU GRUB Manual: https://www.gnu.org/software/grub/manual/grub/grub.html
• GRUB EFI standalone image: grub-mkimage -O x86_64-efi ...
• UEFI boot specification: EFI/BOOT/BOOTX64.EFI is the fallback boot path
• Redox bootloader source: recipes/core/bootloader/source/
• Installer GPT layout: recipes/core/installer/source/src/installer.rs