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

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

Uses the maintained airootfs/ overlay as-is
Adds Stormux repository GPG key to the build host's keyring
- Uses the included stormux_repo.pub file
- Key fingerprint: 52ADA49000F1FF0456F8AEEFB4CDE1CD56EF8E82
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
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
The UEFI systemd-boot menu enables its audible beep
Boot menu defaults to accessible entry
Service startup order ensures audio is ready before screen reader
First-login setup calibrates volume, selects the default speech engine and Fenrir keyboard layout, starts Fenrir, then checks networking and time before offering 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:

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%
First-login setup on tty1
- Calibrates volume using Speech Dispatcher
- Offers the default speech-engine selector
- Speaks the laptop-layout question using the selected engine
- Sets [keyboard] layout in /etc/fenrirscreenreader/settings/settings.toml, preserving comments, and validates the configuration
- Starts fenrirscreenreader.service with the selected settings
fenrirscreenreader.service - Screen reader with dependencies
- Configured to wait for user audio initialization and sound.target
- Uses speech-dispatcher for TTS output
- Disabled at boot in the live ISO; started by first-login setup

The old stormux-speech.service boot launcher is also disabled in the live ISO. The installed system still enables Fenrir at boot.

Live Setup and Installer Flow

On first login to tty1, setup calibrates volume, selects the default speech engine, and asks whether to use Fenrir's laptop layout. These prompts use Speech Dispatcher directly while Fenrir is stopped. Enter at the layout prompt selects desktop layout. Setup then starts Fenrir, presents the welcome prompt, checks for network access, updates the live environment clock, and 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

No ARM-specific packages - Uses x86_64 standard Linux kernel
Fenrir instead of speakup - More feature-rich screen reader
UEFI and BIOS support - Boots on both modern and legacy systems
ISO format - Live/install medium instead of disk image
No Pi hardware configs - Standard x86_64 PC configuration
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)

Before building, run the focused checks from this directory:

python3 tests/test-live-fenrir-setup.py
bash ../tests/test-select-speech-module.sh

For boot acceptance, confirm that Fenrir stays silent during volume calibration and voice selection, the laptop prompt uses the selected voice, and Fenrir starts once afterward. Test both desktop (Enter or N) and laptop (Y) bindings, voice selection with Enter and Escape, network setup with and without a connection, and declining the installer. After a test installation, confirm that the selected voice persists and Fenrir starts at boot. Automated checks do not establish audible speech, physical keyboard behavior, or installed-system acceptance.

For VM testing with audio:

./qemu-boot.sh

After installing to the test disk, boot the installed system with:

./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 efiboot/loader/loader.conf and entries under efiboot/loader/entries/

Adding Overlay Files

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

Default X Resources

Keep airootfs/etc/skel.stormux/.Xresources and airootfs/home/stormux/.Xresources identical. The home copy supplies the live user's defaults. During ISO creation, the skeleton copy is placed in /etc/skel; install-stormux copies it into the target's /etc/skel after package installation and before creating users. All users created with new home directories by the installer inherit ~/.Xresources, regardless of the selected desktop or partition layout. Users created later with useradd -m inherit it as well. Reused home directories keep their existing files.

Troubleshooting

Build fails with GPG errors

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

Check that x86_64/stormux_repo.pub exists
Manually add the key to your build host:

sudo pacman-key --add x86_64/stormux_repo.pub
sudo pacman-key --lsign-key 52ADA49000F1FF0456F8AEEFB4CDE1CD56EF8E82

Missing packages

Ensure the Stormux repository is accessible:

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.