Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
407 lines (286 loc) · 10.5 KB

DEVELOPMENT.md

File metadata and controls

407 lines (286 loc) · 10.5 KB
Raw

SinLess GRUB Loader — Development Guide

This guide covers the repository workflow, build pipeline, validation, preview, and maintenance conventions. Read DESIGN.md before changing theme geometry or visual layering.

Supported environment

Development is tested on Ubuntu and Debian-family systems with GRUB 2. The scripts use Bash strict mode and standard GNU utilities.

Install the expected tools on Ubuntu with:

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

Important commands include:

  • convert and identify for deterministic PNG generation and validation
  • grub-script-check for generated GRUB syntax
  • grub-mkrescue and xorriso for the isolated preview ISO
  • qemu-system-x86_64 for preview execution
  • mformat from mtools for GRUB rescue-image generation

Repository model

There are three distinct layers:

theme/sinless/   Canonical source and configuration
dist/            Clean generated deployment/preview output
.cache/codex/    Generated task and validation state

Never treat dist/ as source. scripts/build.sh removes and recreates it on every build.

Canonical source structure

theme/sinless/
├── assets/
│   ├── backgrounds/
│   ├── characters/
│   ├── generated/version/
│   ├── icons/
│   ├── menu/
│   │   ├── branding/
│   │   └── selected/
│   ├── overlays/
│   └── progress/
├── config/
│   ├── grub/42_sinless_tools
│   ├── preview.conf
│   └── version.txt
├── fonts/
└── theme.txt

No PNG may be placed directly under theme/sinless/.

Standard workflow

After changing source code, configuration, or assets, run:

./scripts/build.sh
./scripts/verify.sh
./scripts/preview.sh --build-only
./scripts/preview.sh --window

Do not run install.sh as part of normal development. Installation is a separate, explicit system operation.

Build pipeline

scripts/build.sh performs a clean deterministic build.

1. Resolve paths

The script derives the repository root from its own location. It does not depend on the caller's working directory.

2. Validate canonical inputs

Required configuration, fonts, character, branding, icons, menu slices, progress slices, and overlays must exist. The canonical GRUB helper must be executable.

3. Parse the version safely

theme/sinless/config/version.txt must contain exactly one assignment in this form:

THEME_VERSION="1.0"

The parser does not execute or source the file. Values are limited to a short, safe version character set.

4. Generate the version label

ImageMagick creates the static final version label and embeds the configured version in PNG metadata. The output is forced to true RGBA for GRUB compatibility.

5. Compose heavy visual layers

Full-screen overlays are merged into the deployment background. Menu and character glows are composited beneath their subjects into true RGBA outputs. This keeps the number of live GRUB transparency layers low and avoids indexed alpha rendering defects.

6. Recreate dist/

The build creates:

dist/
├── grub/42_sinless_tools
├── preview/
└── sinless/

Directories receive mode 0755, normal files 0644, and the GRUB helper 0755.

7. Create the icon compatibility link

GRUB requires icons/ beside theme.txt. The build creates:

dist/sinless/icons -> assets/icons

Do not replace this with duplicated canonical icon files.

Verification

Run:

./scripts/verify.sh

The verifier checks:

  • Canonical and generated directory structure
  • Required nested source and dist files
  • Safe non-empty version configuration
  • Valid source and generated PNGs when ImageMagick is available
  • No root-level theme PNGs
  • Exact overlay inventory and build consumption
  • Theme references against existing nested files
  • Progress frame/fill declarations and layering
  • Character/menu geometry and declaration order
  • Generated version metadata
  • GRUB helper output with sh and grub-script-check
  • Both required custom menu entries
  • Configuration wrapper behavior and script syntax
  • Dist synchronization and generated glow composition
  • Absence of the obsolete foreground-character asset

Verification exits nonzero on any failure. Do not install a failing build.

Preview workflow

The preview script always uses dist/sinless/; it never reads deployable assets directly from source.

Build only

./scripts/preview.sh --build-only

This writes an isolated ISO to:

dist/preview/sinless-grub-preview.iso

Window and fullscreen

./scripts/preview.sh --window
./scripts/preview.sh --fullscreen

SDL software output is the default because GTK zoom/scaling can produce a black window on some systems. To test GTK explicitly:

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

Override preview settings

./scripts/preview.sh --width 1600 --height 900 --timeout 20

Equivalent environment variables are supported for width, height, and timeout:

SINLESS_PREVIEW_WIDTH=1600 \
SINLESS_PREVIEW_HEIGHT=900 \
SINLESS_PREVIEW_TIMEOUT=20 \
./scripts/preview.sh --window

The preview menu contains Ubuntu, Windows 11 Pro, Advanced Options, BIOS/UEFI Settings, GRUB Command Line, and SinLess Theme Configuration. Preview entries do not boot real operating systems; dummy entries reload the isolated preview menu.

Interactive configuration

Run:

./sinless-theme-config

The utility manages version, timeout, resolution, preview mode, build, verification, and preview actions. It validates input and writes configuration through temporary files without eval.

Show current values without entering the menu:

./sinless-theme-config --show

The utility never invokes install.sh.

Editing the theme

The main layout is theme/sinless/theme.txt.

When changing geometry:

  1. Preserve the 51% menu-text right boundary.
  2. Keep the character at or beyond 52%.
  3. Keep timeout text above the progress frame.
  4. Keep branding centered on the menu frame's 30% horizontal center.
  5. Check image declaration ordering in the real preview.
  6. Test at 1920×1080 and at least one smaller resolution.

Use only properties documented by the installed GRUB manual. Unsupported CSS, JavaScript, background loops, or animation syntax do not belong in a GRUB theme.

Working with assets

Background and overlays

Canonical full-screen sources should be 1920×1080. Keep detailed effects away from the left-side menu text region. Every overlay must be referenced by theme.txt or consumed by build.sh.

Character

The sole canonical character is:

assets/characters/hooded-character.png

It must remain a transparent true-RGBA PNG. Do not recreate hooded-character-foreground.png.

The matching glow is assets/overlays/character-glow.png. Its canvas dimensions must match the character because the build composites them directly.

Menu selection and progress slices

GRUB uses nine-slice filenames ending in _c, _n, _s, _e, _w, _ne, _nw, _se, and _sw. Do not rename or omit these files.

Progress fill pixels must remain inside the visible frame at both partial and full states. Keep highlight_overlay = "false" unless a real GRUB preview proves a replacement behaves correctly.

Icons

Add canonical class icons under assets/icons/. Use a square RGBA PNG and match the existing 64×64 icon convention. Add the path to build and verification lists when the icon becomes required.

Fonts

GRUB uses PFF2 fonts, not TTF/OTF files directly. If replacing the font, generate the PFF2 asset with grub-mkfont, update the internal font name in theme.txt, and verify it in QEMU.

GRUB helper development

The canonical source is:

theme/sinless/config/grub/42_sinless_tools

Test its emitted configuration with:

temporary_file="$(mktemp)"
sh theme/sinless/config/grub/42_sinless_tools >"${temporary_file}"
grub-script-check "${temporary_file}"
rm -f "${temporary_file}"

Do not hardcode a kernel path, initrd path, root UUID, boot disk, encryption mapping, ZFS pool, resume device, or distro-specific boot chain. If a safe Ubuntu boot-to-configuration chain cannot be derived, retain the informational fallback.

Shell conventions

  • Use #!/usr/bin/env bash for Bash scripts.
  • Enable set -Eeuo pipefail for mutating workflows.
  • Derive the project root from BASH_SOURCE.
  • Use arrays for required file sets.
  • Quote paths and variables.
  • Avoid eval and sourcing user-editable configuration.
  • Fail before making partial output when prerequisites are missing.
  • Keep build, verify, and preview isolated from live GRUB paths.
  • Keep installation and uninstallation explicitly root-gated.

Run syntax checks after script changes:

bash -n scripts/*.sh sinless-theme-config

If ShellCheck is installed:

shellcheck scripts/*.sh sinless-theme-config

Generated progress state

Long-running refactor and validation state is recorded under:

.cache/codex/theme-refactor-progress.md

The directory is generated and ignored by Git. It is not part of the deployable theme.

Troubleshooting

Preview window is black

Use the default SDL backend:

./scripts/preview.sh --window

If SINLESS_PREVIEW_BACKEND=gtk is set in the environment, unset it before launching.

Theme changes do not appear

Rebuild before previewing:

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

The preview reads dist/, not canonical source files directly.

Transparent image becomes a rectangle

Convert the GRUB-facing output to true RGBA (PNG32) and prefer build-time compositing. Indexed PNG transparency is unreliable on some GRUB video backends.

Verify reports stale output

Run ./scripts/build.sh and repeat verification. Do not manually patch dist/.

Version label does not animate

That is expected. GRUB 2.12 has no supported timer or mutable theme-label mechanism for blinking and typewriter effects.

Pre-commit checklist

  • Canonical paths contain no root-level PNGs.
  • No obsolete or unconsumed overlays remain.
  • ./scripts/build.sh passes.
  • ./scripts/verify.sh passes with zero failures.
  • ./scripts/preview.sh --build-only passes.
  • The 1920×1080 preview is visually inspected.
  • Progress fill remains within its frame.
  • Character does not cover menu text.
  • Version label is visible.
  • No live GRUB files were modified during development.