SinLess GRUB Loader

A toxic-neon GRUB 2 theme for Ubuntu and Windows multiboot systems.

SinLess combines a high-contrast black-and-green interface, class-aware boot icons, a dynamic timeout bar, and an isolated QEMU preview workflow. The theme is authored at 1920×1080 and uses conservative percentage-based geometry so it remains readable at lower resolutions supported by GRUB.

Features

• 1920×1080 widescreen layout with scalable positioning
• Ubuntu, Windows, firmware, fallback, memtest, and GRUB terminal icons
• Native GRUB timeout text and progress-bar synchronization
• Build-composited character, frame glow, circuitry, grunge, particles, and vignette
• Configurable version label generated from one canonical setting
• Isolated preview ISO that never modifies the live bootloader
• Dist-only installation with automatic backup and rollback
• Interactive terminal configuration utility
• GRUB Command Line and safe SinLess Theme Configuration menu entries
• Deterministic build and comprehensive source/dist verification

Requirements

The project targets Ubuntu and Debian-family systems using GRUB 2. The build and preview workflow expects Bash, ImageMagick, GRUB utilities, QEMU, xorriso, mtools, and DejaVu fonts.

On Ubuntu, install the development and preview dependencies with:

sudo apt install \
  grub-common grub-pc-bin \
  imagemagick fonts-dejavu-core \
  qemu-system-x86 xorriso mtools

Quick start

Build the generated deployment bundle:

./scripts/build.sh

Validate the canonical source, generated assets, GRUB helper, script syntax, layout bounds, and dist/ synchronization:

./scripts/verify.sh

Launch the theme in an isolated QEMU window:

./scripts/preview.sh --window

Nothing in the build, verification, or preview workflow modifies /boot, /etc/default/grub, or /etc/grub.d.

Preview options

# Build the preview ISO without launching QEMU
./scripts/preview.sh --build-only

# Windowed or fullscreen display
./scripts/preview.sh --window
./scripts/preview.sh --fullscreen

# Override preview geometry or timeout
./scripts/preview.sh --width 1600 --height 900 --timeout 20

SDL software rendering is the default because some QEMU/GTK combinations show a black window at 1920×1080. GTK remains available when needed:

SINLESS_PREVIEW_BACKEND=gtk ./scripts/preview.sh --window

Generated preview files are written beneath dist/preview/.

Installation

Always build, verify, and preview before changing the live bootloader:

./scripts/build.sh
./scripts/verify.sh
./scripts/preview.sh --window
sudo ./scripts/install.sh

The installer:

1. Refuses to run unless the generated bundle passes verification.
2. Backs up the current GRUB defaults, theme, helper, and SinLess launcher.
3. Installs the theme to /boot/grub/themes/sinless.
4. Installs 42_sinless_tools to /etc/grub.d/.
5. Installs sinless-theme-config beneath /usr/local/.
6. Updates only the GRUB_THEME setting in /etc/default/grub.
7. Regenerates grub.cfg with update-grub or grub-mkconfig.

Backups are stored under:

/boot/grub/themes/.sinless-backups/

The installer does not modify /etc/grub.d/10_linux and is never invoked automatically by build or preview commands.

Uninstallation and rollback

Restore the latest pre-install state with:

sudo ./scripts/uninstall.sh

The uninstaller restores the previous GRUB defaults and any files that existed before installation, removes only SinLess-managed files, then regenerates the GRUB configuration.

Theme configuration

Open the interactive project-local utility:

./sinless-theme-config

It manages:

• Theme version
• Preview timeout
• Preview resolution
• Default windowed or fullscreen preview mode
• Build, verification, and preview actions

Display the current values non-interactively:

./sinless-theme-config --show

After installation, the configuration can also be viewed with:

sinless-theme-config

Source changes and rebuilding must be performed from a writable repository checkout. The utility never installs the theme or edits live GRUB files by itself.

Version configuration

The canonical version is stored in:

theme/sinless/config/version.txt

The clean-checkout default is:

THEME_VERSION="1.0"

Change only the quoted value, then rebuild and verify:

./scripts/build.sh
./scripts/verify.sh

The build safely parses the assignment without source or eval and generates the final version-label PNG beneath assets/generated/version/.

GRUB menu helpers

The canonical helper is:

theme/sinless/config/grub/42_sinless_tools

It emits two entries:

• GRUB Command Line
• SinLess Theme Configuration

The command-line entry retains the normal GRUB terminal behavior. A custom Ubuntu boot-to-configuration entry is only safe when the complete distro-generated kernel and initrd chain can be preserved. When that information cannot be derived reliably, the configuration entry uses the safe fallback and instructs the user to boot Ubuntu normally and run sinless-theme-config.

No kernel paths, initrds, root UUIDs, encryption settings, or recurring startup services are guessed or hardcoded.

GRUB animation limitation

GRUB 2.12 themes support static images, labels, menus, and timeout-driven progress components. They do not provide a general animation timer, mutable theme labels, or an image-frame sequencer.

The version display therefore renders the supported static final state:

>| VERSION 1.0

A perpetual blinking cursor and one-shot typewriter animation are intentionally not simulated with unsupported scripts or fake frame assets.

Repository layout

.
├── docs/                       Design, development, and image documentation
├── mockup/                     Original visual reference
├── scripts/
│   ├── build.sh                Deterministic dist build
│   ├── install.sh              Verified system installation and backup
│   ├── preview.sh              Isolated GRUB/QEMU preview
│   ├── theme-config.sh         Interactive configuration utility
│   ├── uninstall.sh            Restore and remove installed files
│   └── verify.sh               Source and generated-output validation
├── theme/sinless/
│   ├── assets/                 Canonical nested source assets
│   ├── config/                 Version, preview, and GRUB helper configuration
│   ├── fonts/                  GRUB PFF2 font
│   └── theme.txt               GRUB theme layout
├── dist/                       Generated deployment and preview output
└── sinless-theme-config        Project-local configuration launcher

dist/ and .cache/codex/ are generated and ignored by Git. GRUB requires class icons in icons/ beside theme.txt, so the build creates a deploy-only relative link from dist/sinless/icons to the canonical assets/icons folder.

Documentation

• Design system and layout
• Development and validation workflow
• Installation, rollback, and recovery

Safety notes

• Build, verification, and preview never modify the installed bootloader.
• Installation requires explicit root execution.
• A timestamped rollback backup is created before live files are changed.
• Failed installations attempt to restore the previous state automatically.
• Review the generated preview before rebooting after installation.