woof - the Puppy builder

This is a fork of woof-CE, the build system used to produce Puppy Linux releases.

The goal is to build something similar to DebianDog, a highly Debian-compatible "live" distro with a layered file system, but with core features of Puppy Linux, a distro that -

• Provides a lightweight desktop environment and a variety of applications
• Provides a fully functional package manager, Flatpak and support for extra read-only layers (sfs_load)
• Supports non-persistent, fully persistent or "persistent-on-demand" sessions where the user can decide whether or not to save, and when
• Provides the features that make Puppy great, but without losing compatibility with Debian, breaking updates or creating a big maintenance burden

Features

Simplicity

• SFSs don't need to be "queued" by the user for loading at boot time: instead, the init script loads all SFSs under psubdir (if specified) and the partition root, under both the save partition or the boot partition. SFSs are sorted numerically before loading, so 2something.sfs is loaded before 10something.sfs. This allows loading of extra SFSs without persistency and allows the user to control the stacking order. The stacking order of the traditional *drv SFS is retained, for backward compatibility.
• Support for PUPMODEs other than 5 (live), 12 (automatic persistency) and 13 (on-demand persistency) is gone.
• Support PUPMODE 13 with periodic saving is gone. The user can run save2flash to save now, or save at shutdown.
• Support for the devx SFS is gone and development packages can be installed individually, without having to download the entire devx.
• busybox init, /etc/inittab, plogin, autologin, etc' are replaced with a simple init implementation (see woof-code/rootfs-petbuilds/init).
• The bootable images produced by woof-CE contain an empty save folder and Bootflash creates an empty save folder if possible, to reduce the number of questions users need to answer.
• pdrv is gone: the partition containing Puppy files can be specified only using pupsfs=$UUID.
• SAVEMARK and SAVESPEC are gone: the partition containing the save file/folder can be specified only using psave=$UUID.
• Rarely-used boot codes like pimod and pwireless are gone.

Compatibility

• coreutils, util-linux, etc' are not replaced with symlinks to busybox, because this breaks compatibility with the upstream distro.
• Some core Puppy scripts that override the upstream distro (including run-as-spot wrappers created by setup-spot) are moved to /usr/local/{,s}bin and PATH makes the shell prefer them. This makes package updates safe, because they no longer remove Puppy's hooks.
• The Puppy way of doing things is replaced with the upstream distro way of doing things. For example, rc.country is gone, and so is the hack of exporting LANG in /etc/profile. Instead, one should use /etc/default/locale, /etc/locale.gen, locale-gen, etc'.
• Themes are supported, but not included by default: themes break applications, they're hard to maintain and non-native widgets in modern browsers or Flatpak applications make theming consistency nearly impossible.
• petget provides limited support for .pet packages.

Resource Consumption

• Copying of SFSs is enabled automatically only if Puppy files reside on storage that doesn't support TRIM and assumed to be a slow device, like a hard drive, a memory card, a flash drive or a DRAM-less SSD.
• SFSs are not copied to a ramdisk (pfix=ram|copy or automatic) but locked in page cache (see woof-code/rootfs-petbuilds/sfslock) instead, freeing ramdisk space.
• The RAM occupied by cached SFSs is freed automatically (using OOM score adjustment) if needed.
• SFSs are prioritized and lower priority SFSs are not cached when cached SFSs occupy half of available RAM.
• If possible, save files are created as sparse files, to reduce writing to disk and retain usable free space in the partition.

Speed

• The init script (/etc/rc.d/rc.sysinit) is shorter and much faster.
• Caching of SFSs in RAM (pfix=ram|copy or automatic) happens in the background while the boot process continues.
• Most of 0setup, 1download, 2createpackages and 3builddistro is reimplemented using debootstrap. Build times are much shorter than upstream's.

Security

• The Landlock-based sandbox that restricts file system access for applications running as spot is stricter and also prevents spot from reading or writing files under the save partition. The sandbox blocks access to /root even if permissions are 777, but without this new restriction, spot can access /initrd/mnt/dev_save/*save/upper/root instead, to bypass the sandbox. This breaks compatibility with Puppy, because spot can only run applications installed to / and can't run "portable" applications that reside on the save partition.
• Most legacy X11 applications work thanks to Xwayland, which is unprivileged and sandboxed.

Modernization

• Only dpup (Debian or Devuan based Puppy) is supported.
• Only Wayland is supported: support for X.Org and tools that modify xorg.conf is gone.
• Only PipeWire is supported: support for plain ALSA and PulseAudio is gone.
• Support for ROX-Filer is gone, and the "source of truth" regarding file associations and default applications is xdg-utils. /usr/local/bin/default* are provided for backward compatibility with Puppy.
• usrmerge is mandatory: support for the deprecated file system layout with separate /lib and /usr/lib, is gone.
• Only overlay is supported: support for aufs is gone.
• PPM is gone: packages in the build come from the upstream distro, rootfs-packages or rootfs-petbuilds (built from source).
• Support for kernel package types other than the "huge" one is gone.
• kernel-kit's firmware picker is gone: fdrv is built by moving /usr/lib/firmware out of the main SFS.
• ISO images are gone: the woof-CE build output is a bootable flash drive image and isoboot is gone.
• ntfs-3g is replaced with ntfs3.
• ext2 and ext3 save files are gone: all save files (including encrypted ones) use ext4, with or without journaling, and Bootflash supports ext4.
• initrd is zstd-compressed and built from rootfs binaries instead of a prebuilt, outdated and unmaintained set of static executables.

Directory Structure

• initrd-progs/ contains the initramfs skeleton
  • initrd-progs/0initrd/init is the early init script, which searches for Puppy files, sets up an overlay file system and switch_roots into it
• kernel-kit/ contains a tool that builds Puppy-compatible kernels
• woof-distro/ contains configuration files
  • woof-distro/x86_64/debian/trixie64 builds a Debian 13 based Puppy, featuring dwl with the snail layout and yambar, or labwc with sfwbar
    • woof-distro/x86_64/debian/trixie64/DISTRO_SPECS contains the distro name and version
    • woof-distro/x86_64/debian/trixie64/DISTRO_PKGS_SPECS-debian-trixie contains a list of Debian 13 package sto include
    • woof-distro/x86_64/debian/trixie64/_00build.conf contains a list of packages to build from source (PETBUILDS) and other settings
• woof-code/ contains most of woof-CE itself and the Puppy skeleton (minus initramfs)
  • woof-code/rootfs-skeleton contains the Puppy root file system skeleton
    • rootfs-skeleton/etc/rc.d/rc.sysinit is the init script
    • rootfs-skeleton/usr/sbin/shutdownconfig implements the save/no save prompt shown when shutting down under PUPMODE 5
    • rootfs-skeleton/usr/sbin/{save2flash,snapmergepuppy.overlay} implement saving under PUPMODE 13
    • rootfs-skeleton/etc/rc.d/rc.shutdown takes care of saving on shutdown
    • rootfs-skeleton/usr/local/sbin/{reboot,poweroff} run /etc/rc.d/rc.shutdown, then pass control to /sbin/$0
    • rootfs-skeleton/root/.profile starts the graphical desktop
  • woof-code/rootfs-petbuilds contains recipes for building Puppy-specific packages or packages with Puppy-specific customization, from source
    • woof-code/rootfs-petbuilds/init provides a simple init implementation that runs /etc/rc.d/rc.sysinit and a login shell
    • woof-code/rootfs-petbuilds/spot-pkexec implements a sandbox for unprivileged applications
    • woof-code/rootfs-petbuilds/ram-saver changes the memory allocator settings to reduce RAM consumption
    • woof-code/rootfs-petbuilds/sfslock locks a file into the page cache to speed up reading from it
  • woof-code/rootfs-packages contains Puppy-specific tools
  • woof-code/1download builds:
    • sandbox3/rootfs, a basic root file system template
    • sandbox3/devx, a copy of rootfs with development packages on top
  • woof-code/3builddistro builds the packages specified in $PETBUILDS inside sandbox3/devx, then adds them and packages under rootfs-packages/ to sandbox3/rootfs, then builds bootable distro images

Usage

sudo apt-get install -y --no-install-recommends dc debootstrap librsvg2-bin zstd xml2 syslinux-utils extlinux

Then:

export DISTRO_VARIANT=labwc

Or:

export DISTRO_VARIANT=dwl

Then:

./merge2out woof-distro/x86_64/debian/trixie64
cd ../woof-out_*
./1download
./3builddistro