From 57ec696e3fa3069c3e19f798569355ae96551279 Mon Sep 17 00:00:00 2001
From: satoshi <satoshi@bitcoin.com>
Date: Tue, 19 May 2026 03:01:46 +0300
Subject: [PATCH] Add multiarch build setup and build documentation

- Add `make setup` target to register qemu and create a multiplatform
  buildx builder for universal (x86_64 + aarch64) packages
- Use named builder with --progress=plain to avoid flickering output
- Conditionally depend on arch-specific Docker tars so single-arch
  builds don't require the other image
- Document prerequisites, build targets, and overrides in README
---
 Makefile  | 31 +++++++++++++++++++++++++------
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 65 insertions(+), 14 deletions(-)

diff --git a/Makefile b/Makefile
index 80d3c95..5a1c185 100644
--- a/Makefile
+++ b/Makefile
@@ -6,13 +6,16 @@ TS_FILES := $(shell find ./scripts -name \*.ts 2>/dev/null)
 # Where KamadoPool source lives (buildx passes it as a named context).
 KAMADO_SRC ?= ../KamadoPool
 
+# Buildx builder name. Must support linux/amd64 and linux/arm64.
+BUILDER ?= kamado-multiarch
+
 .DELETE_ON_ERROR:
 
 # Default: build both arches and verify a universal package.
 all: verify
 
-# Single-arch convenience targets — much faster if you don't have
-# qemu-user-static registered for cross-arch emulation.
+# Single-arch convenience targets — much faster when you don't need
+# cross-arch emulation.
 x86: ARCH = x86_64
 x86:
 	@rm -f docker-images/aarch64.tar
@@ -23,6 +26,14 @@ arm:
 	@rm -f docker-images/x86_64.tar
 	$(MAKE) ARCH=aarch64
 
+# Register qemu for cross-arch builds and create a multiplatform builder.
+setup:
+	docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
+	-docker buildx rm $(BUILDER) 2>/dev/null
+	docker buildx create --name $(BUILDER) --platform linux/amd64,linux/arm64 --use
+	docker buildx inspect --bootstrap $(BUILDER)
+	@echo "Ready. 'make' will now build universal packages."
+
 verify: $(PKG_ID).s9pk
 	start-sdk verify s9pk $(PKG_ID).s9pk
 	@echo "Package: $(PKG_ID).s9pk ($(shell du -h $(PKG_ID).s9pk | cut -f1))"
@@ -38,7 +49,7 @@ scripts/embassy.js: $(TS_FILES)
 docker-images/x86_64.tar: Dockerfile docker_entrypoint.sh
 ifneq ($(ARCH),aarch64)
 	mkdir -p docker-images
-	docker buildx build \
+	docker buildx build --builder $(BUILDER) --progress=plain \
 		--tag start9/$(PKG_ID)/main:$(PKG_VERSION) \
 		--platform linux/amd64 \
 		--build-arg ARCH=x86_64 \
@@ -50,7 +61,7 @@ endif
 docker-images/aarch64.tar: Dockerfile docker_entrypoint.sh
 ifneq ($(ARCH),x86_64)
 	mkdir -p docker-images
-	docker buildx build \
+	docker buildx build --builder $(BUILDER) --progress=plain \
 		--tag start9/$(PKG_ID)/main:$(PKG_VERSION) \
 		--platform linux/arm64 \
 		--build-arg ARCH=aarch64 \
@@ -60,9 +71,17 @@ ifneq ($(ARCH),x86_64)
 endif
 
 # ── Pack ─────────────────────────────────────────────────────────────
+ifeq ($(ARCH),x86_64)
+DOCKER_DEPS := docker-images/x86_64.tar
+else ifeq ($(ARCH),aarch64)
+DOCKER_DEPS := docker-images/aarch64.tar
+else
+DOCKER_DEPS := docker-images/x86_64.tar docker-images/aarch64.tar
+endif
+
 $(PKG_ID).s9pk: manifest.yaml instructions.md icon.png LICENSE \
                 scripts/embassy.js \
-                docker-images/x86_64.tar docker-images/aarch64.tar
+                $(DOCKER_DEPS)
 ifeq ($(ARCH),x86_64)
 	@echo "start-sdk: packing x86_64 only"
 else ifeq ($(ARCH),aarch64)
@@ -76,4 +95,4 @@ clean:
 	rm -rf docker-images
 	rm -f $(PKG_ID).s9pk image.tar scripts/embassy.js
 
-.PHONY: all x86 arm verify install clean
+.PHONY: all x86 arm verify install clean setup
diff --git a/README.md b/README.md
index 9736938..9a7c4f7 100644
--- a/README.md
+++ b/README.md
@@ -2,25 +2,57 @@
 
 StartOS 0.3.5.1 wrapper for [Kamado Pool](https://github.com/Relaxo143/KamadoPool), a modern solo Bitcoin mining pool built on a patched fork of CKPool-solo with a Go middleware API and Svelte real-time dashboard.
 
-## Build
+## Prerequisites
+
+- **Docker** with [buildx](https://docs.docker.com/build/buildx/) plugin
+- **deno** — bundles the TypeScript embassy procedures
+- **yq** — parses `manifest.yaml` for package metadata
+- **start-sdk** — packs and verifies the `.s9pk` (from the [StartOS SDK](https://docs.start9.com/latest/developer-docs/specification/))
+- **KamadoPool source** — local sibling checkout at `../KamadoPool` (override with `KAMADO_SRC=/path/to/KamadoPool`)
+
+## Building
+
+### Universal package (x86_64 + aarch64)
+
+A universal `.s9pk` runs on any StartOS machine regardless of architecture. This is the default and what you should ship.
+
+**One-time setup** (re-run after each reboot):
+
+```sh
+make setup
+```
+
+This registers qemu binfmt handlers for cross-architecture emulation and creates a multiplatform Docker buildx builder. The arm64 build runs under emulation on x86 hosts, so it is significantly slower (~5-10x) than native.
+
+**Build:**
 
 ```sh
 make
 ```
 
-This runs `deno` to bundle the embassy TypeScript procedures, builds a multi-arch OCI image via `docker buildx`, and packs everything into `kamado-pool.s9pk` using `start-sdk`.
+This bundles the TypeScript procedures, builds Docker images for both architectures, and packs `kamado-pool.s9pk`. The universal package is roughly double the size of a single-arch package since it contains two Docker images.
 
-The build pulls KamadoPool source from a **local sibling checkout** (`../KamadoPool` by default) via a docker buildx named build context — no GitHub clone, no pinned SHA. If your checkout lives elsewhere, override it:
+### Single-arch (development)
+
+For faster iteration when you only need one architecture:
 
 ```sh
+make x86    # x86_64 only
+make arm    # aarch64 only
+```
+
+These skip the other architecture entirely — no emulation overhead.
+
+### Overrides
+
+```sh
+# Use a different KamadoPool source directory
 make KAMADO_SRC=/path/to/KamadoPool
+
+# Use a different buildx builder
+make BUILDER=my-builder
 ```
 
-## Install
-
-```sh
-make install
-```
 
 ## License