Overview/X Linux (distro)

Building the ISO

This guide explains how to build the X live ISO from this repository with xbuild.sh, and summarizes the separate WSL rootfs build scripts.

Prerequisites

• A Linux environment with the ArchISO tooling available (Arch Linux or a compatible distribution).
• sudo access.
• The archiso package.
• Enough disk space (several GB) and network access to download packages.

Install the dependency:

sudo pacman -S archiso

Build command

Run from the repository root:

./xbuild.sh

What xbuild.sh does

1. Validates that pacman.conf and profiledef.sh exist in the current directory.
2. Attempts a lazy unmount of stale mount points under work/x86_64/airootfs (avoids "target is busy" errors from previous runs).
3. Removes the previous work/ and out/ directories.
4. Runs sudo mkarchiso -C pacman.conf -v -w ./work -o ./out ., teeing all output into a timestamped log file.
5. Verifies that at least one ISO was produced and prints the artifact path and size; otherwise it prints a message and exits with a non-zero status.

A minimal one-liner equivalent, x.sh, performs the same mkarchiso build but without the cleanup and verification steps. xbuild.sh is the recommended entry point.

Outputs

• ISO artifact: out/x-YYYY.MM.DD-x86_64.iso (the version date comes from profiledef.sh).
• Build log: build-YYYYMMDD-HHMM.log in the repository root.

Both work/ and out/ are recreated on each build and are gitignored, as are the build-*.log files.

Profile facts

profiledef.sh defines the ISO metadata used by mkarchiso:

• iso_name: x
• iso_version: YYYY.MM.DD (date-based)
• iso_label: x_YYYYMM
• iso_publisher: Xscriptor <https://xscriptor.io/x>
• iso_application: X Live/Rescue DVD
• Boot modes: bios.syslinux and uefi.grub
• Root filesystem image: squashfs, xz-compressed
• File permissions for sensitive/live files (for example /etc/shadow, the airootfs/root scripts, and the /usr/local/bin live helpers including xinstall).

Packages and repositories used by the build

• packages.x86_64 is the full package manifest for the live ISO. It includes the base system plus recovery/live tooling, fonts, a browser (Firefox), the X packages x-release and x-dev (from the [x] repository), and gum (used by the text installer UI).

• bootstrap_packages.x86_64 is the minimal set (base, arch-install-scripts) used by archiso for the bootstrap root.

• pacman.conf adds the custom repository:

  [x]
  SigLevel = Never
  Server = https://equislinux.github.io/x-repo/repo/x86_64
  

  The build host uses Never (it may not have the project key). The live ISO and the installed target use SigLevel = Required: the public key ships at /etc/pacman.d/x-repo.pub; in the live environment pacman-init.service recreates the keyring on tmpfs and x-keyring.service imports and locally signs the project key, while install.sh prepares the target keyring the same way.

• The provisioning payload (x-scripts, current version 0.1.0-30) is shipped offline inside the ISO at airootfs/root/x-installer/packages/x-scripts-*.pkg.tar.zst, so the installer does not need to fetch it from the network during installation. The installer uses it to provision the target and to record generation 0001 at the end of the installation.

Troubleshooting

• If no ISO is generated, inspect the build log first (build-*.log).
• Common failure causes:
  • insufficient disk space;
  • errors in profile customization logic;
  • invalid profile configuration in profiledef.sh;
  • stale mounts under work/x86_64/airootfs (the script tries to clean them; unmount with sudo umount -R work/x86_64/airootfs if needed).

WSL builds (dedicated repositories)

WSL is not built from this repository. The canonical flow lives in:

The two repositories above are the source of truth for building and provisioning X on WSL.

Edit this page on GitHub