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

GRUB Integration Plan — Red Bear OS

Date: 2026-04-17 Status: Fully implemented (build-tested, not yet runtime boot-tested). ESP formatted as FAT32 per UEFI spec. Both Phase 1 (post-build script) and Phase 2 (installer-native) are wired. Remaining: Runtime UEFI boot validation in QEMU (make all CONFIG_NAME=redbear-grub && make qemu). Prerequisite: The grub package is included in redbear-grub.toml for clean-tree builds. 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
echo	Print messages
test	Conditional expressions
ls	List files and devices
cat	Display file contents
halt	Shut down
reboot	Reboot

Note: chainloader is a built-in command in GRUB 2.12 (no separate module needed).

Red Bear policy now requires a local redoxfs.mod artifact for GRUB builds. The GRUB recipe resolves it in this order:

1. local/recipes/core/grub/modules/redoxfs.mod
2. ${COOKBOOK_SYSROOT}/usr/lib/grub/x86_64-efi/redoxfs.mod

If neither exists, the GRUB recipe fails fast.

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	Typical Size
GRUB EFI binary (with modules)	~500 KiB (varies with module list)
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

Linux-Compatible CLI

Red Bear OS provides grub-install and grub-mkconfig wrappers that match GNU GRUB command-line conventions. Users migrating from Linux can use familiar switches.

Linux Command	Red Bear OS Location
grub-install	local/scripts/grub-install
grub-mkconfig	local/scripts/grub-mkconfig

Add to PATH for convenience:

export PATH="$PWD/local/scripts:$PATH"

grub-install

# Install GRUB into a disk image
grub-install --target=x86_64-efi --disk-image=build/x86_64/harddrive.img

# Verbose mode
grub-install --target=x86_64-efi --disk-image=build/x86_64/harddrive.img --verbose

# Show help
grub-install --help

Supported options: --target=, --efi-directory=, --bootloader-id=, --removable, --disk-image=, --modules=, --no-nvram, --verbose, --help, --version.

Unsupported Linux options are accepted and ignored silently for script compatibility.

grub-mkconfig

# Preview generated config
grub-mkconfig

# Write to file
grub-mkconfig -o local/recipes/core/grub/grub.cfg

# Custom timeout
grub-mkconfig --timeout=10 -o /boot/grub/grub.cfg

Supported options: -o/--output=, --timeout=, --set-default=, --help, --version.

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/recipes/core/grub/modules/redoxfs.mod	Mandatory local GRUB RedoxFS module artifact
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

Phase 2 adds GRUB awareness directly to the Redox installer, eliminating the post-build script step. The installer reads bootloader = "grub" from config, fetches the GRUB package alongside the bootloader, and writes the chainload ESP layout automatically.

Changes Made

1. GeneralConfig (config/general.rs): Added bootloader: Option<String> field ("redox" default, "grub" for GRUB), with merge support.

2. DiskOption (installer.rs): Added grub_efi: Option<&[u8]> and grub_config: Option<&[u8]> fields for optional GRUB data.

3. fetch_bootloaders: When bootloader = "grub", installs the grub package alongside bootloader and returns grub.efi + grub.cfg data. Return type extended to (bios, efi, grub_efi, grub_cfg).

4. with_whole_disk / with_whole_disk_ext4: When grub_efi and grub_config are both present, writes the GRUB chainload layout:

   • EFI/BOOT/BOOTX64.EFI ← GRUB
   • EFI/BOOT/grub.cfg ← GRUB configuration
   • EFI/REDBEAR/redbear.efi ← Redox bootloader (chainload target)

5. install_inner: Passes GRUB data from fetch_bootloaders through DiskOption.

6. CLI (bin/installer.rs): Added --bootloader grub flag that sets config.general.bootloader.

7. TUI (bin/installer_tui.rs): Updated DiskOption construction with grub_efi: None, grub_config: None.

Config Usage

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

[general]
bootloader = "grub"
efi_partition_size = 16

Or via CLI (note: INSTALLER_OPTS replaces defaults, so --cookbook=. must be included):

./target/release/repo cook installer
make all CONFIG_NAME=redbear-full INSTALLER_OPTS="--cookbook=. --bootloader grub"

Note: The config file approach (redbear-grub.toml) is preferred over the CLI flag because INSTALLER_OPTS completely replaces the default value (--cookbook=.) rather than appending to it. Omitting --cookbook=. breaks local package resolution for GRUB.

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 (only UEFI)
• ESP must be sized to ≥ 8 MiB in config (16 MiB recommended)
• GRUB bootloader is incompatible with skip_partitions = true (requires GPT layout with ESP)
• TUI installer does not support GRUB mode (intentional — TUI is for live disk reinstall)
• Runtime UEFI boot test has not been performed yet (requires full make all build, ~hours)

Testing

Phase 1: Post-build script (standalone)

# Build GRUB recipe
make r.grub

# Build image (any config with efi_partition_size >= 16)
make all CONFIG_NAME=redbear-full

# Install GRUB into disk image (uses fat_tool.py, no mtools needed)
./local/scripts/install-grub.sh build/x86_64/harddrive.img

# Verify ESP contents
python3 local/scripts/fat_tool.py ls build/x86_64/harddrive.img 1048576 /

# Boot in QEMU
make qemu
# Expected: GRUB menu appears, "Red Bear OS" entry boots successfully

Phase 2: Installer-native (automatic)

# Build GRUB recipe (must be built before installer runs)
make r.grub

# Build image with GRUB config (installer fetches GRUB automatically)
make all CONFIG_NAME=redbear-grub

# Or via CLI flag
make all CONFIG_NAME=redbear-full INSTALLER_OPTS="--bootloader grub --cookbook=."

# Verify ESP contents
python3 local/scripts/fat_tool.py ls build/x86_64/harddrive.img 1048576 /

# Boot in QEMU
make qemu
# Expected: GRUB menu appears, "Red Bear OS" entry boots successfully

Unit tests (no full build required)

# Verify GRUB recipe builds
CI=1 ./target/release/repo cook grub

# Verify host-side installer accepts --bootloader flag
build/fstools/bin/redox_installer --bootloader=grub --config=config/redbear-grub.toml --list-packages

# Verify fat_tool.py operations
python3 local/scripts/fat_tool.py --help

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