From 0082cc39b9c50f840a7355a2cd0b51ccd2e23877 Mon Sep 17 00:00:00 2001 From: Jeremy Davis Date: Fri, 29 May 2026 17:48:26 +1000 Subject: [PATCH 1/3] Refactoring; formatting and improved dependency checking and error message --- Makefile | 52 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/Makefile b/Makefile index 6ea914d..2721b87 100644 --- a/Makefile +++ b/Makefile @@ -1,44 +1,52 @@ #!/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)') + 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)') + 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 + $(error "Required packages missing - run: 'apt update && apt install -y $(MISSING)")) endif DISTRO ?= $(shell dirname $(RELEASE)) From b4b52fcfcc9e6c4b9bf3310ad51743440d0cbd02 Mon Sep 17 00:00:00 2001 From: Jeremy Davis Date: Fri, 29 May 2026 18:19:48 +1000 Subject: [PATCH 2/3] Only warn about missing deps for 'make help' and some output adjustment --- Makefile | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 2721b87..0ec2a9f 100644 --- a/Makefile +++ b/Makefile @@ -19,11 +19,13 @@ endif ifndef 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)') + $(info ) FAB_ARCH := $(HOST_ARCH) endif @@ -46,7 +48,13 @@ endif $(foreach cmd, $(REQUIRED_CMDS),\ $(if $(shell which $(cmd) 2>/dev/null),,$(eval MISSING += $(cmd)))) ifdef MISSING - $(error "Required packages missing - run: 'apt update && apt install -y $(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)) From 39230c2484695aa9ae5663fe8f1107c2734e1fe8 Mon Sep 17 00:00:00 2001 From: Jeremy Davis Date: Fri, 29 May 2026 22:26:00 +1000 Subject: [PATCH 3/3] Rewrite readme --- README.rst | 139 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 97 insertions(+), 42 deletions(-) diff --git a/README.rst b/README.rst index 26d6629..7c1869d 100644 --- a/README.rst +++ b/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 ``-$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