Merge pull request #166 from FolkComputer/osnr/folk-live-build

Bring folk-live-build into this repo

Author: osnr

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "live-build/config/includes.chroot_after_packages/etc/skel/apriltag"]
+	path = live-build/config/includes.chroot_after_packages/home/folk/apriltag
+	url = https://github.com/FolkComputer/apriltag

README.md

@@ -37,7 +37,7 @@ See <https://folk.computer/pilot/>
 **Experimental:** If you have an amd64 PC, you can use the live USB
 image which has Folk and all dependencies pre-installed.
 
-**See <https://github.com/FolkComputer/folk-live-build/releases> to
+**See <https://github.com/FolkComputer/folk/releases> to
 get the Linux live USB image.**
 
 You can update Folk by running `git pull` in the `folk` subfolder of

live-build/.gitignore

@@ -0,0 +1,13 @@
+*.img
+*.img.zip
+chroot
+binary
+cache
+.build
+binary.modified_timestamps
+chroot.files
+chroot.packages.install
+chroot.packages.live
+live-image-amd64.contents
+live-image-amd64.files
+live-image-amd64.packages

live-build/Makefile

@@ -0,0 +1,13 @@
+IMG_FILENAME := folk-$(shell date -I)-$(shell git rev-parse HEAD | head -c 7)-live-amd64.img
+
+$(IMG_FILENAME).zip: $(IMG_FILENAME)
+	 zip $@ $<
+
+$(IMG_FILENAME): live-image-amd64.img
+	./make-folk-amd64-img.sh $< $@
+
+live-image-amd64.img:
+	sudo sh -c 'lb clean && lb config && lb build'
+
+clean:
+	rm -f *amd64.img

live-build/README.md

@@ -0,0 +1,116 @@
+# folk-live-build
+
+Builds a bootable Folk OS image.
+
+To run Folk on a PC, [download the latest pre-built Folk image for USB
+stick from the Releases
+page.](https://github.com/FolkComputer/folk-live-build/releases)
+Follow the instructions there.
+
+---
+
+Below are details on how the Folk OS image is constructed; **you don't
+need to worry about any of the below if you're just trying to install
+Folk.**
+
+## Key files
+
+- `folk-live/`: becomes writable partition on disk, including Folk repo
+- `config/package-lists/folk.list.chroot`: apt packages
+- `config/hooks/normal/9999-setup-folk.hook.chroot`: executed in
+  `/` chroot at image construction time
+- `config/includes.chroot_after_packages/`: copied into `/` at boot
+- `config/includes.chroot_after_packages/lib/live/config/9999-folk`:
+  executed at boot
+
+## How to build folk-amd64.img from scratch
+
+You need to build on a computer running amd64 Debian Bookworm. (Use a
+virtual machine if you need to. A Folk system built by folk-live-build
+itself should work, though, whether on a virtual or physical machine.)
+
+In this live-build/ subdirectory of the Folk repo:
+
+```
+# apt install live-build parted dosfstools zip
+$ git submodule update --init
+$ make -C config/includes.chroot_after_packages/home/folk/apriltag libapriltag.a libapriltag.so
+$ make
+```
+
+emits `folk-amd64.img`.
+
+(It runs from scratch each time -- can take 30 minutes or more.)
+
+## How it works
+
+Image (-> USB drive) contains Master Boot Record with:
+
+1. 'Binary' ext4 partition (~1.3GB)
+   - Contains a bunch of stuff (?), including the SquashFS file of
+     the chroot filesystem, which ultimately maps to / in the
+     running system
+   - Could be fat32 or iso9660 I think but ext4 is reliable
+
+2. EFI system partition (100MB)
+   - syslinux-efi bootloader
+   - Linux kernel image (annoying if you update kernel but this is a
+     sealed live USB so that shouldn't be an issue)
+
+3. Writable FAT32 partition (~500MB)
+   - Contains /folk with Folk evaluator code and virtual programs,
+     /folk-printed-programs, etc.
+   - Contains setup.folk which you can edit to set runtime settings
+     (Wi-Fi credentials)
+   - Designed to automount on all operating systems when the USB is
+     plugged in, to make it easy to configure Wi-Fi and other stuff
+     before boot
+
+Cannot have FAT32 partition be same as efi partition (and use iso
+loopback) because macOS (and probably other OSes?) won't automount an
+efi partition.
+
+#### Build process
+
+The build process uses Debian live-build to build a live image, then
+appends EFI system partition (to make it bootable on UEFI machines)
+and a writable partition (to make it easy for end-user to set config
+settings and update Folk).
+
+(live-build can make a complete bootable disk image on its own, but
+only in iso-hybrid mode, which doesn't let you modify the partition
+table to add the writable partition, so we instead use hdd mode and
+modify the partition table ourselves.)
+
+1. Run live-build, emit a disk image (with MBR with only a binary
+   partition. not bootable on many modern systems)
+
+2. Use parted to mutate the disk image to add EFI system partition
+
+3. Copy syslinux-efi bootloader and bootloader config and Linux kernel
+   etc onto EFI system partition
+
+4. Use parted to mutate the disk image to add the writable FAT32 partition
+
+## References
+
+- <https://ianlecorbeau.github.io/blog/debian-live-build.html>
+- <https://manpages.debian.org/testing/live-build/lb_config.1.en.html>
+- <https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html>
+
+## License
+
+Apache 2.0
+
+## TODO
+
+- ~~Replace "NO NAME" title of FAT32 writable partition with Folk name~~
+- Test MBR+EFI on various systems (BIOS, UEFI, Chromebook, Beelink,
+  NUC, UTM)
+- ~~Make fstab automount the writable partition (how do we know it's
+  /dev/sdb2?)~~
+- ~~Put Wi-Fi config on writable partition~~
+- Allow setting display and webcam from setup.folk
+- Figure out disk installation process
+- ~~Handle printed programs~~, ~~calibration (make folk prefix that goes to folk-live?)~~
+

live-build/config/binary

@@ -0,0 +1,119 @@
+# config/binary - options for live-build(7), binary stage
+
+# Set image type
+LB_IMAGE_TYPE="hdd"
+
+# Set image filesystem
+LB_BINARY_FILESYSTEM="ext4"
+
+# Set apt/aptitude generic indices
+LB_APT_INDICES="true"
+
+# Set boot parameters
+LB_BOOTAPPEND_LIVE="boot=live components hostname=folk-live username=folk live-config.user-default-groups=adm,dialout,cdrom,sudo,audio,video,plugdev,games,users,input,render,netdev,lpadmin,gpio,i2c,spi,lpadmin"
+
+# Set boot parameters
+LB_BOOTAPPEND_INSTALL=""
+
+# Set boot parameters
+LB_BOOTAPPEND_LIVE_FAILSAFE="boot=live components memtest noapic noapm nodma nomce nolapic nosmp nosplash vga=788"
+
+# Set BIOS bootloader
+LB_BOOTLOADER_BIOS="syslinux"
+
+# Set EFI bootloader
+LB_BOOTLOADER_EFI="grub-efi"
+
+# Set bootloaders
+LB_BOOTLOADERS=""
+
+# Set checksums
+LB_CHECKSUMS="sha256 md5"
+
+# Set compression
+LB_COMPRESSION="none"
+
+# Support dm-verity on rootfs
+LB_DM_VERITY=""
+
+# Support FEC on dm-verity rootfs
+LB_DM_VERITY_FEC_ROOTS=""
+
+# Set sign script for roothash for dm-verity rootfs
+LB_DM_VERITY_SIGN=""
+
+# Set zsync
+LB_ZSYNC="true"
+
+# Control if we build binary images chrooted
+# NEVER, *EVER*, *E*V*E*R* SET THIS OPTION to false.
+LB_BUILD_WITH_CHROOT="true"
+
+# Set debian-installer
+LB_DEBIAN_INSTALLER="live"
+
+# Set debian-installer suite
+LB_DEBIAN_INSTALLER_DISTRIBUTION="bookworm"
+
+# Set debian-installer preseed filename/url
+LB_DEBIAN_INSTALLER_PRESEEDFILE=""
+
+# Toggle use of GUI debian-installer
+LB_DEBIAN_INSTALLER_GUI="true"
+
+# Set hdd label
+LB_HDD_LABEL="DEBIAN_LIVE"
+
+# Set hdd filesystem size
+LB_HDD_SIZE="auto"
+
+# Set start of partition for the hdd target for BIOSes that expect a specific boot partition start (e.g. "63s"). If empty, use optimal layout.
+LB_HDD_PARTITION_START=""
+
+# Set iso author
+LB_ISO_APPLICATION="Debian Live"
+
+# Set iso preparer
+LB_ISO_PREPARER="live-build @LB_VERSION@; https://salsa.debian.org/live-team/live-build"
+
+# Set iso publisher
+LB_ISO_PUBLISHER="Debian Live project; https://wiki.debian.org/DebianLive; [email protected]"
+
+# Set iso volume (max 32 chars)
+LB_ISO_VOLUME="Debian bookworm @ISOVOLUME_TS@"
+
+# Set jffs2 eraseblock size
+LB_JFFS2_ERASEBLOCK=""
+
+# Set memtest
+LB_MEMTEST="none"
+
+# Set loadlin
+LB_LOADLIN="true"
+
+# Set win32-loader
+LB_WIN32_LOADER="false"
+
+# Set net tarball
+LB_NET_TARBALL="true"
+
+# Set onie
+LB_ONIE="false"
+
+# Set onie additional kernel cmdline options
+LB_ONIE_KERNEL_CMDLINE=""
+
+# Set inclusion of firmware packages in debian-installer
+LB_FIRMWARE_BINARY="true"
+
+# Set inclusion of firmware packages in the live image
+LB_FIRMWARE_CHROOT="true"
+
+# Set swap file path
+LB_SWAP_FILE_PATH=""
+
+# Set swap file size
+LB_SWAP_FILE_SIZE="512"
+
+# Enable/disable UEFI secure boot support
+LB_UEFI_SECURE_BOOT="auto"

live-build/config/bootstrap

@@ -0,0 +1,76 @@
+# config/bootstrap - options for live-build(7), bootstrap stage
+
+# Select architecture to use
+LB_ARCHITECTURE="amd64"
+
+# Select distribution to use
+LB_DISTRIBUTION="bookworm"
+
+# Select parent distribution to use
+LB_PARENT_DISTRIBUTION=""
+
+# Select distribution to use in the chroot
+LB_DISTRIBUTION_CHROOT="bookworm"
+
+# Select parent distribution to use in the chroot
+LB_PARENT_DISTRIBUTION_CHROOT="bookworm"
+
+# Select distribution to use in the final image
+LB_DISTRIBUTION_BINARY="bookworm"
+
+# Select parent distribution to use in the final image
+LB_PARENT_DISTRIBUTION_BINARY="bookworm"
+
+# Select parent distribution for debian-installer to use
+LB_PARENT_DEBIAN_INSTALLER_DISTRIBUTION="bookworm"
+
+# Select archive areas to use
+LB_ARCHIVE_AREAS="main contrib non-free non-free-firmware"
+
+# Select parent archive areas to use
+LB_PARENT_ARCHIVE_AREAS="main contrib non-free non-free-firmware"
+
+# Set parent mirror to bootstrap from
+LB_PARENT_MIRROR_BOOTSTRAP="http://deb.debian.org/debian/"
+
+# Set parent mirror to fetch packages from
+LB_PARENT_MIRROR_CHROOT="http://deb.debian.org/debian/"
+
+# Set security parent mirror to fetch packages from
+LB_PARENT_MIRROR_CHROOT_SECURITY="http://security.debian.org/"
+
+# Set parent mirror which ends up in the image
+LB_PARENT_MIRROR_BINARY="http://deb.debian.org/debian/"
+
+# Set security parent mirror which ends up in the image
+LB_PARENT_MIRROR_BINARY_SECURITY="http://security.debian.org/"
+
+# Set debian-installer parent mirror
+LB_PARENT_MIRROR_DEBIAN_INSTALLER="http://deb.debian.org/debian/"
+
+# Set mirror to bootstrap from
+LB_MIRROR_BOOTSTRAP="http://deb.debian.org/debian/"
+
+# Set mirror to fetch packages from
+LB_MIRROR_CHROOT="http://deb.debian.org/debian/"
+
+# Set security mirror to fetch packages from
+LB_MIRROR_CHROOT_SECURITY="http://security.debian.org/"
+
+# Set mirror which ends up in the image
+LB_MIRROR_BINARY="http://deb.debian.org/debian/"
+
+# Set security mirror which ends up in the image
+LB_MIRROR_BINARY_SECURITY="http://security.debian.org/"
+
+# Set debian-installer mirror
+LB_MIRROR_DEBIAN_INSTALLER="http://deb.debian.org/debian/"
+
+# Set architectures to use foreign bootstrap
+LB_BOOTSTRAP_QEMU_ARCHITECTURE=""
+
+# Set packages to exclude during foreign bootstrap
+LB_BOOTSTRAP_QEMU_EXCLUDE=""
+
+# Set static qemu binary for foreign bootstrap
+LB_BOOTSTRAP_QEMU_STATIC=""

live-build/config/chroot

@@ -0,0 +1,34 @@
+# config/chroot - options for live-build(7), chroot stage
+
+# Set chroot filesystem
+LB_CHROOT_FILESYSTEM="squashfs"
+
+# Set chroot squashfs compression level
+LB_CHROOT_SQUASHFS_COMPRESSION_LEVEL=""
+
+# Set chroot squashfs compression type
+LB_CHROOT_SQUASHFS_COMPRESSION_TYPE=""
+
+# Set union filesystem
+LB_UNION_FILESYSTEM="overlay"
+
+# Set interactive build
+LB_INTERACTIVE="false"
+
+# Set keyring packages
+LB_KEYRING_PACKAGES="debian-archive-keyring"
+
+# Set kernel flavour to use (with arch)
+LB_LINUX_FLAVOURS_WITH_ARCH="amd64"
+
+# Set kernel packages to use
+LB_LINUX_PACKAGES="linux-image"
+
+# Enable security updates
+LB_SECURITY="true"
+
+# Enable updates updates
+LB_UPDATES="true"
+
+# Enable backports updates
+LB_BACKPORTS="false"