Skip to main content

Operations

Toolbox setup​

Debian (as a WSL2 distro) is the preferred toolbox for extraction work:

apt-get update
apt-get install -y squashfs-tools zstd

unsquashfs and tar need to be available. A separate WSL-Toolbox (Ubuntu 24.04) also exists with the same tools, but Debian alone is sufficient for most conversions.

Example workflow (Clear Linux, as documented in clearlinux/PROCESS.md)​

# Mount the source ISO
Mount-DiskImage -ImagePath 'K:\clear-v1\clear-43800-live-server.iso'

# Copy out the SquashFS rootfs payload and hash it
Copy-Item -LiteralPath 'E:\images\rootfs.img' -Destination 'K:\clear-v1\clear-43800-rootfs.img'
Get-FileHash -Algorithm SHA256 -LiteralPath 'K:\clear-v1\clear-43800-rootfs.img'
# From the Debian toolbox distro — verify, then extract to WSL-native ext4
file /mnt/k/clear-v1/clear-43800-rootfs.img
unsquashfs -s /mnt/k/clear-v1/clear-43800-rootfs.img

rm -rf /root/clear-43800
mkdir -p /root/clear-43800
unsquashfs -f -d /root/clear-43800/rootfs /mnt/k/clear-v1/clear-43800-rootfs.img

:::warning Don't extract onto an NTFS-mounted path Clear Linux's image uses many hardlinks. Extracting directly to /mnt/k (or any Windows-mounted drive) through WSL fails with create_inode: failed to create hardlink, because Invalid argument. Extract to the WSL distro's own native ext4 filesystem instead, then move/tar the result afterward. :::

Packaging​

Once a working rootfs tar exists, packaging follows the shared capability set:

  • package_msix_with_winapp — package via the winapp CLI
  • build_launcher_exe_with_ps2exe — build a launcher EXE with Invoke-PS2EXE

Each child distro directory contains its own build-msix.ps1, launch.ps1, and AppManifest.xml (or AppxManifest) following the same pattern.

Evidence practice​

Clear Linux's PROCESS.md is the model to follow for other distros: it records SHA-256 for the source ISO, the extracted rootfs image, the WSL tar artifact, and the frozen first-working baseline — a full hash chain from source to shippable artifact.