Mostly cosmetic improvements

Makefile

@@ -1,44 +1,60 @@
 #!/usr/bin/make -f
-# Copyright (c) 2020-2025 TurnKey GNU/Linux - https://www.turnkeylinux.org
+# Copyright (c) 2020-2026 TurnKey GNU/Linux - https://www.turnkeylinux.org
 
 HOST_DISTRO := $(shell lsb_release -si | tr [A-Z] [a-z])
 HOST_CODENAME := $(shell lsb_release -sc)
 HOST_RELEASE := $(HOST_DISTRO)/$(HOST_CODENAME)
 HOST_ARCH := $(shell dpkg --print-architecture)
 
-REQUIRED_CMDS := fab pool
-$(foreach cmd,$(REQUIRED_CMDS),\
-  $(if $(shell which $(cmd) 2>/dev/null),,\
-  $(error "Required package missing - run: 'apt update && apt install -y $(cmd)")))
-
 ifndef BOOTSTRAPS_PATH
-ifndef FAB_PATH
-ifdef SUDO_USER
-$(info running via sudo - BOOTSTAPS_PATH or FAB_PATH need to be set)
-endif
-$(error neither BOOTSTAPS_PATH or FAB_PATH are set)
-else
-BOOTSTRAPS_PATH := $(FAB_PATH)/bootstraps
-endif
+  ifndef FAB_PATH
+    ifdef SUDO_USER
+      $(info running via sudo - BOOTSTAPS_PATH or FAB_PATH need to be set)
+    endif
+    $(error neither BOOTSTAPS_PATH or FAB_PATH are set)
+  else
+    BOOTSTRAPS_PATH := $(FAB_PATH)/bootstraps
+  endif
 endif
 
 ifndef RELEASE
-$(info RELEASE not defined - falling back to system: '$(HOST_RELEASE)')
-RELEASE := $(HOST_RELEASE)
+  $(info RELEASE not defined - falling back to system: '$(HOST_RELEASE)')
+  $(info )
+  RELEASE := $(HOST_RELEASE)
 endif
 
 ifndef FAB_ARCH
-$(info FAB_ARCH not defined - falling back to system: '$(HOST_ARCH)')
-FAB_ARCH := $(HOST_ARCH)
+  $(info FAB_ARCH not defined - falling back to system: '$(HOST_ARCH)')
+  $(info )
+  FAB_ARCH := $(HOST_ARCH)
 endif
 
 ifneq ($(FAB_ARCH),$(HOST_ARCH))
-$(info building $(FAB_ARCH) on $(HOST_ARCH))
-ifeq ($(HOST_ARCH),arm64)
-$(error amd64 bootstrap can not be built on arm64)
+  $(info building $(FAB_ARCH) on $(HOST_ARCH))
+  ifeq ($(HOST_ARCH),arm64)
+    $(error amd64 bootstrap can not be built on arm64)
+  else
+  ARM_ON_AMD := y
+  endif
+endif
+
+REQUIRED_CMDS := fab pool
+ifdef ARM_ON_AMD
+  REQUIRED_CMDS += qemu-debootstrap qemu-system-arm qemu-user-static binfmt-support
 else
-ARM_ON_AMD := y
+  REQUIRED_CMDS += debootstrap
 endif
+
+$(foreach cmd, $(REQUIRED_CMDS),\
+  $(if $(shell which $(cmd) 2>/dev/null),,$(eval MISSING += $(cmd))))
+ifdef MISSING
+  MISSING_MSG := Dendencies missing - run: 'apt update && apt install -y $(MISSING)'
+  ifneq ($(MAKECMDGOALS),help)
+    $(error $(MISSING_MSG))
+  else
+    $(info *** $(MISSING_MSG))
+    $(info )
+  endif
 endif
 
 DISTRO ?= $(shell dirname $(RELEASE))

README.rst

@@ -1,69 +1,124 @@
 About
 =====
 
-This project builds a Debian ``bootstrap`` for use as a base for
-building TurnKey GNU/Linux appliances.
+This project builds a Debian ``bootstrap`` for use as the build base for
+TurnKey GNU/Linux appliances.
 
 A ``bootstrap`` is the minimal root filesystem in which packages can
-be installed. TurnKey uses ``debootstrap`` to build a default
-"minbase" variant Debian bootstrap, with the addition of a couple of
-packages.
-
-For further info please run::
-
-    make help
+be installed. TurnKey uses the default Debian ``debootstrap`` tool to build a
+"minbase" variant Debian bootstrap, with the addition of a couple of packages.
 
 Current supported architectures are:
 
 - amd64 - aka x86_64
 - arm64 - aka aarch64
 
-An amd64 host can build both amd64 & arch64; an arm64 host can only build
-arm64.
+An amd64 host can build both amd64 & arch64 bootstraps; an arm64 host can only
+build arm64.
 
-Build & copy to bootstraps directory
-====================================
+Install
+=======
 
-If you are building a bootstrap for local use only, then it is not necessary
-to do a complete ``make`` (which will generate a tarball as noted below).
-Instead you can just build to the ``install`` target.
+Requirements
+------------
 
-That will build the bootstrap, remove the pre-set list of files noted
-within the removelist file and copy the bootstrap to
-``$FAB_PATH/bootstraps/$(basename $RELEASE-$ARCH)``::
+An internet connection is required to download the Debian packages when building
+the bootstrap. There are also some dependencies that can be installed via apt.
+If running on a non-TurnKey system you will need to add the TurnKey apt repo
+to install the 2 TurnKey dependencies.
 
-    make clean
-    make install
 
-Build arm64 bootstrap on amd64
-==============================
+* TurnKey packages (from TurnKey apt repo):
+    - fab
+    - pool
 
-The default action is to build a bootstrap with the same architecture as the
-host. However, it is possible to build an arm64 (aka aarch64) bootstrap on an
-amd64 (aka x86_64) system.
+* Debian packages - native arch builds - amd64 on amd64 / arm64 on arm64:
+    - debootstrap
 
-Dependencies
-------------
+* Debian packages - arm64 built on amd64:
+    - qemu-debootstrap
+    - qemu-system-arm
+    - qemu-user-static
+    - binfmt-support
+
+When building an arm64 bootstrap on amd64, the fab ``install-arm-on-amd-deps``
+script can be used to install all deps.
 
-To build a bootstrap for an architechture the same as the host, ``debootstrap``
-is the only package required.
+** ``debootstrap`` Debian release transition note **
 
-To build arm64 bootstrap on amd64, the following packages are required:
+During a transition to a new Debian release occasionally you may need a newer
+version of `debootstrap`` than the one packaged for your host system. If the
+bootstrap fails to build for a Debian release newer than the host system, try
+upgrading to the ``debootstrap`` version of the bootstrap you are building.
+Installing a newer ``debootstrap`` deb is fine as it is a collection of shell
+scripts with minimal dependencies.
 
-- qemu-system-arm
-- qemu-user-static
-- binfmt-support
+Download the newer deb and install with apt. E.g. to install the Debian
+14/Forky ``debootstrap`` package on a v19.x TKLDev (Debian 13/Trixie)::
 
-Assuming fab is installed (as it is by default on TKLDev), an
-``install-arm-on-amd-deps`` contib script will check that they are installed
-and install them if needed.
+    # where XXXX is the debootstrap version
+
+    wget http://deb.debian.org/debian/pool/main/d/debootstrap/debootstrap_XXXX_all.deb
+    apt update
+    apt install ./debootstrap/debootstrap_XXXX_all.deb
+
+Clone this repo
+---------------
+
+Once dependencies are installed, then simply clone this repo::
+
+    cd /turnkey
+    git clone https://github.com/turnkeylinux/bootstrap.git
 
 Usage
------
+=====
+
+This project uses a Makefile so building is as simple as running ``make``. A
+few common usage scenarios are covered below, but for full details about the
+possible env vars that can be used to control the process can be viewed via::
+
+    make help
 
-By default ``make`` will build the architecture of the host system. To build
-arm64 on amd64, set ``FAB_ARCH=arm64``
+Build and copy bootstrap
+------------------------
 
-E.g.::
+When building a bootstrap for local use build to the ``install`` target. I.e.::
 
-    FAB_ARCH=arm64 make install
+    make clean
+    make install
+
+That will build the bootstrap, remove the paths noted in the ``removelist``
+and copy to a directory named ``<DEBIAN_CODENAME>-$ARCH`` in
+``BOOTSTRAPS_PATH``. The default value of ``BOOTSTRAPS_PATH`` is
+``$FAB_PATH/bootstraps/`` (usually ``/turnkey/fab/bootstraps/``) so the full
+path of a trixie amd64 bootstrap will be
+``/turnkey/fab/bootstraps/trixie-amd64/``
+
+Build tarball
+-------------
+
+If you wish to share your bootstrap, do not specify a make target. With no
+target noted, it will generate a tarball of the bootstrap as an additional
+step. I.e.::
+
+    make clean
+    make
+
+Build an alternate release bootstrap
+------------------------------------
+
+To build a bootstrap for a Debian release other than the host, set the value
+of ``RELEASE``. E.g. to build a Debian forky release on a v19.x (trixie)
+TKLDev::
+
+    make clean
+    RELEASE=debian/forky make install
+
+Build arm64 bootstrap on amd64
+------------------------------
+
+To build a non-native arch bootstrap, set the value of ``FAB_ARCH``. E.g.
+to build an arm64 forky bootstrap on v19.x TKLDev::
+
+    make clean
+    FAB_ARCH=arm64 RELEASE=debian/forky make install