# Stormux x86_64 ISO Build

This directory contains the archiso profile for building a Stormux x86_64 live/install ISO image.

## Overview

The x86_64 build uses archiso (Arch Linux ISO build system) and is configured for accessibility with the Fenrir screen reader. The `airootfs/` tree is maintained as the x86_64 live-system overlay; shared behavior may mirror the Pi image, but files are not copied from `pi4/files/` during the build.

## Directory Structure

```
x86_64/
├── build.sh                    # Main build script
├── profiledef.sh               # Archiso profile definition
├── pacman.conf                 # Pacman config with Stormux repository
├── packages.x86_64             # Package list for installation
├── grub/                       # UEFI boot configuration
│   ├── grub.cfg
│   └── loopback.cfg
├── syslinux/                   # BIOS boot configuration
│   ├── archiso_head.cfg
│   ├── archiso_pxe.cfg
│   ├── archiso_pxe-linux.cfg
│   ├── archiso_sys.cfg
│   ├── archiso_sys-linux.cfg
│   ├── archiso_tail.cfg
│   ├── splash.png
│   └── syslinux.cfg
└── airootfs/                   # Live system overlay files
    ├── etc/                    # Live-system configuration
    ├── root/                   # x86_64-specific scripts
    ├── usr/                    # Live-system utilities and installer
    └── var/                    # Live-system variable data
```

## Overlay Maintenance

Edit files directly under `airootfs/` using the final filesystem path they should have in the live ISO. For example, live-system scripts belong under `airootfs/usr/local/bin/`, and systemd units belong under `airootfs/etc/systemd/system/`.

Some files intentionally match the Pi overlay, such as shell defaults, Fenrir support scripts, and shared Stormux helper behavior. Keep both trees in sync when a change is meant to affect both image families.

Pi hardware files remain Pi-only and should not be added to the x86_64 profile unless there is a specific PC use for them:

- `boot/cmdline.txt` - Pi boot command line
- `boot/config.txt` - Pi hardware configuration
- `etc/modprobe.d/brcmfmac.conf` - Pi wireless driver config

## Prerequisites

Building requires an Arch Linux host system with:

- `archiso` package installed
- Root privileges
- Internet connection for package downloads and build-time helper installs

## Building the ISO

```bash
cd x86_64
sudo ./build.sh
```

### Build Options

- `-o <dir>` - Output directory (default: `./out`)
- `-w <dir>` - Work directory (default: `./work`)
- `-h` - Show help

### Build Process

1. Uses the maintained `airootfs/` overlay as-is
2. Adds Stormux repository GPG key to the build host's keyring
   - Uses the included `stormux_repo.pub` file
   - Key fingerprint: 52ADA49000F1FF0456F8AEEFB4CDE1CD56EF8E82
3. Runs `mkarchiso` to build the ISO
   - Packages from Stormux repo can be installed during build
   - The latest `sas` helper is installed into the live environment during image creation
4. Renames the ISO to `stormux-x86_64-YYYY-MM-DD.iso` when possible and writes a matching `.sha1sum`

The Stormux repository key is also embedded in the ISO at `/usr/share/stormux/stormux_repo.pub` and automatically imported on first boot via the `stormux-repo-init.service`, ensuring the live environment can install additional packages from the Stormux repository.

## Key Features

### Accessibility

- **Fenrir screen reader** starts automatically (not speakup)
- **Pipewire audio** properly initialized before Fenrir starts
- **Speech-dispatcher** integration for speech synthesis
- GRUB plays an audible tune on boot for accessibility
- Boot menu defaults to accessible entry
- Service startup order ensures audio is ready before screen reader
- First-login live-environment setup calibrates volume, checks networking and time, then offers to run the installer

### Package Management

- Stormux repository configured with priority over Arch repos
- Custom packages from Stormux repo: fenrir, w3m-git, yay, etc.

### Default Configuration

- Default user: `stormux` / Password: `stormux`
- Root password: `root`
- NetworkManager for network configuration
- Braille terminal support (brltty)
- Multiple speech synthesizers (espeak-ng, rhvoice)

## Audio and Speech Initialization

The live environment uses a carefully orchestrated startup sequence to ensure Fenrir has working audio:

1. **stormux-audio-setup.service** - Runs after sound hardware is detected
   - Enables systemd user linger for the stormux user
   - Starts pipewire user services
   - Unmutes audio and sets volume to 70%

2. **stormux-speech.service** - Runs after audio setup
   - Waits 2 seconds for pipewire to fully initialize
   - Starts fenrirscreenreader.service

3. **fenrirscreenreader.service** - Screen reader with dependencies
   - Configured to wait for pipewire, speech-dispatcher, and sound.target
   - Uses speech-dispatcher for TTS output

This ensures Fenrir never starts without working audio, preventing system freezes or silent boot.

## Live Setup and Installer Flow

On first login to tty1, the live environment runs a short setup script. It calibrates speech volume, checks for network access, updates the live environment clock, copies the detected timezone into the installer defaults, and then asks whether to run `install-stormux`.

The installer gives one last chance to accept or change the timezone before installation. The live setup changes are for the temporary live environment only; the installed system is configured by `install-stormux`.

## Differences from Pi4 Build

1. **No ARM-specific packages** - Uses x86_64 standard Linux kernel
2. **Fenrir instead of speakup** - More feature-rich screen reader
3. **UEFI and BIOS support** - Boots on both modern and legacy systems
4. **ISO format** - Live/install medium instead of disk image
5. **No Pi hardware configs** - Standard x86_64 PC configuration
6. **Different audio startup** - Pipewire user services instead of system-wide

## Testing

After building, test the ISO with:

- QEMU/KVM virtual machine
- VirtualBox
- Physical hardware (USB/CD)

For VM testing with audio:
```bash
./qemu-boot.sh
```

After installing to the test disk, boot the installed system with:
```bash
./qemu-boot.sh -i
```

## Customization

### Adding Packages

Edit `packages.x86_64` and add package names (one per line).

### Modifying Boot Configuration

- BIOS: Edit `syslinux/archiso_sys-linux.cfg`
- UEFI: Edit `grub/grub.cfg`

### Adding Overlay Files

Place files in `airootfs/` following the target filesystem structure.
The x86_64 build uses this overlay directly.

## Troubleshooting

### Build fails with GPG errors

The build script should automatically add the Stormux repository key. If it fails:

1. Check that `x86_64/stormux_repo.pub` exists
2. Manually add the key to your build host:
```bash
sudo pacman-key --add x86_64/stormux_repo.pub
sudo pacman-key --lsign-key 52ADA49000F1FF0456F8AEEFB4CDE1CD56EF8E82
```

### Missing packages

Ensure the Stormux repository is accessible:
```bash
curl -I https://packages.stormux.org/x86_64/
```

### Disk space issues

The build requires significant space:
- Work directory: ~3-4 GB
- Output ISO: ~1-2 GB

Ensure adequate free space in work and output directories.