design/fedora-grub2-theme
15
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
GRUB2 theme for Fedora
15 commits 1 branch 0 tags 5.1 MiB
  • Shell 62.5%
  • Meson 25.1%
  • Makefile 12.4%
Find a file
Exact
Luya Tshimbalanga 4333976411 Symlink /boot/grub2/theme to /usr/share/grub/theme
2026-04-21 22:39:49 -07:00
.copr Add .copr/Makefile 2026-04-21 01:41:25 -07:00
assets Update screenshot 2026-04-20 17:14:15 -07:00
completions Add .copr/Makefile 2026-04-21 01:41:25 -07:00
docs Symlink /boot/grub2/theme to /usr/share/grub/theme 2026-04-21 22:39:49 -07:00
systemd Update the repository 2026-04-19 13:42:51 -07:00
themes/default Symlink /boot/grub2/theme to /usr/share/grub/theme 2026-04-21 22:39:49 -07:00
tools Symlink /boot/grub2/theme to /usr/share/grub/theme 2026-04-21 22:39:49 -07:00
fedora-grub2-theme.spec Add man and bash completion for script 2026-04-20 17:11:50 -07:00
LICENSE Revamp structure of the repository 2026-04-07 08:35:21 -07:00
meson.build Symlink /boot/grub2/theme to /usr/share/grub/theme 2026-04-21 22:39:49 -07:00
meson_options.txt Add man and bash completion for script 2026-04-20 17:11:50 -07:00
packit.yaml Add man and bash completion for script 2026-04-20 17:11:50 -07:00
README.md Symlink /boot/grub2/theme to /usr/share/grub/theme 2026-04-21 22:39:49 -07:00

README.md

Build Copr build License: MIT Fedora

fedora-grub2-theme

A minimal, Fedora-aligned GRUB2 theme designed for a clean and consistent boot experience integrated with Fedora's BGRT-style Plymouth boot flow.

It provides a single canonical theme (fedora) with safe, reproducible configuration management and full Fedora packaging automation support (Meson + RPM + Packit + COPR + CI).

✨ Features

  • Single GRUB theme: fedora
  • Single visual variant: default
  • Safe GRUB configuration updates
  • Optional Noto Sans GRUB font support (PF2 generated)
  • Idempotent CLI tool (grub2-theme-switch)
  • Systemd boot marker integration
  • GRUB2-aware design: Symlink in /boot/grub2/themes/ ensures theme works even when /usr is on a separate partition
  • BGRT-optimized: Seamless transition from Plymouth to GRUB with framebuffer persistence
  • Enhanced selection highlighting: Professional blue highlight background on menu items
  • Zero image dependencies: Pure GRUB rendering, no external assets required
  • Fully Fedora packaging compliant (2026 standards)

📦 Installation (Fedora)

Once packaged:

sudo dnf install fedora-grub2-theme

🚀 Activation

Apply the theme safely:

sudo grub2-theme-switch --auto

This will:

  • Set the GRUB theme (using the symlink in /boot/grub2/themes/)
  • Detect and enable Noto Sans font (if available)
  • Optimize GRUB for smooth BGRT/Plymouth transition
  • Rebuild GRUB configuration safely

🧰 CLI Usage

All commands that modify system configuration require root privileges (use sudo).
The --status and --help commands can be run as a normal user.

Apply full configuration

sudo grub2-theme-switch --auto

Only set theme

sudo grub2-theme-switch --set

Rebuild GRUB2 only

sudo grub2-theme-switch --rebuild

Show current configuration

grub2-theme-switch --status

Show help

grub2-theme-switch --help

📘 Documentation

Man page

man grub2-theme-switch

Bash completion

Tab-completion is automatically enabled via:

/usr/share/bash-completion/completions/grub2-theme-switch

🎨 Theme Layout

Installed paths:

/usr/share/grub/themes/fedora/          # Actual theme files
/boot/grub2/themes/fedora -> (symlink)  # GRUB2-accessible symlink

Structure:

theme.txt          # Main theme configuration

Only one theme variant exists: default. The theme uses pure GRUB rendering with no external image dependencies.

🔤 Font Support (Noto Sans)

If google-noto-sans-fonts is installed:

  • The system detects Noto Sans via fontconfig
  • Converts it into a GRUB-compatible .pf2 font
  • Automatically sets GRUB_FONT

If unavailable, GRUB falls back safely to the default font (Unifont).

🎯 BGRT Transition Optimizations

The theme automatically configures GRUB for seamless transition from Plymouth:

Setting Purpose
GRUB_GFXPAYLOAD_LINUX="keep" Preserves framebuffer, no flicker
GRUB_GFXMODE="auto" Matches native resolution
GRUB_TERMINAL_OUTPUT="gfxterm" Uses graphical terminal
GRUB_TIMEOUT_STYLE="menu" Shows menu (not hidden)

🎨 Selection Highlighting

The theme features professional selection highlighting:

  • Background highlight: Fedora blue (#3a8cbb) behind selected item
  • Text color: Bright white (#fcfcfc) on selected items
  • Muted items: Grey (#8c8c8c) for unselected entries
  • Visual separators: Subtle lines between menu items

⚙️ How It Works

Component Purpose
meson.build install layout (no compilation)
fedora-grub2-theme.spec RPM packaging
grub2-theme-switch runtime configuration tool
man page CLI documentation
bash completion shell UX
systemd unit boot marker
packit.yaml Fedora automation

🔄 Maintainer Workflow

1. Develop and commit on Forge
2. (Optional) Mirror to GitHub for CI/Packit
3. Build SRPM locally or via COPR
4. Validate in COPR
5. Submit/update Fedora package
6. Koji build → Bodhi update

☁️ COPR Build

copr-cli build fedora-grub2-theme ./out/*.src.rpm

🤖 Packit Integration

Packit handles:

  • SRPM generation
  • Fedora dist-git synchronization
  • Pull request automation
  • Rawhide + stable builds
  • CI validation in Fedora environments

🧪 CI Validation

GitHub Actions ensures:

  • Meson builds successfully
  • Installation layout is correct
  • Script syntax is valid
  • Fedora container build compatibility

📦 Source Tarball Format

Required format:

.tar.xz

Generate:

git archive \
  --format=tar \
  --prefix=fedora-grub2-theme-1.0/ \
  HEAD | xz -T0 -9 -e > fedora-grub2-theme-1.0.tar.xz

🧱 Repository Structure

fedora-grub2-theme/
├── meson.build
├── fedora-grub2-theme.spec
├── packit.yaml
├── README.md
├── LICENSE
├── tools/
│   └── grub2-theme-switch
├── docs/
│   └── grub2-theme-switch.1
├── completions/
│   └── grub2-theme-switch
├── themes/
│   └── default/
│       └── theme.txt
└── systemd/
    └── bootux-success.service

⚠️ Design Principles

  • Single theme only (default)
  • No runtime bootloader hacks
  • No distro-specific branching
  • Fully idempotent operations
  • No compiler required (true noarch package)
  • Clean separation: build (Meson) vs packaging (RPM)
  • GRUB2-aware: Symlink ensures theme works with separate /usr partition
  • BGRT-aligned: Visual consistency with Fedora's Plymouth theme

🔧 Troubleshooting

Theme not applied

sudo grub2-theme-switch --rebuild

Check GRUB configuration

cat /etc/default/grub | grep -E 'GRUB_THEME|GRUB_GFX'

Verify symlink exists

ls -la /boot/grub2/themes/fedora

Should show: /boot/grub2/themes/fedora -> /usr/share/grub/themes/fedora

Check BGRT transition settings

grep -E 'GRUB_GFXMODE|GRUB_GFXPAYLOAD_LINUX|GRUB_TERMINAL_OUTPUT' /etc/default/grub

Font not working

Install Noto fonts:

sudo dnf install google-noto-sans-fonts

Then reapply:

sudo grub2-theme-switch --auto

👨‍🔧 Maintainer Notes

Why Meson?

  • Clean upstream install logic
  • Reproducible builds
  • Fedora-friendly modern tooling

Why Packit?

  • Automates Fedora dist-git sync
  • Enables PR-based workflow
  • Integrates with Fedora CI

Why single theme?

  • Reduces maintenance overhead
  • Avoids reviewer complexity
  • Ensures consistent UX

Why the symlink?

  • GRUB2 runs before /usr may be mounted
  • Symlink in /boot/grub2/themes/ ensures theme is always accessible
  • Actual files stay in /usr/share/ for package management compliance
  • Best of both worlds: FHS compliance + GRUB2 accessibility

Why BGRT optimization?

  • Matches Fedora's default Plymouth theme
  • Eliminates flicker during boot transition
  • Provides cohesive visual experience from boot loader to desktop

📜 License

MIT License

🏁 Summary

fedora-grub2-theme is a minimal, safe, and Fedora-native GRUB2 theming system with:

  • ✅ Zero image dependencies (pure GRUB rendering)
  • ✅ Professional selection highlighting
  • ✅ Seamless Plymouth-to-GRUB transition
  • ✅ GRUB2 early-boot accessibility via symlink
  • ✅ Full automation support and reproducible builds