+ Docker as a way of building.

2026-06-13 13:28:32 +09:00 · 2026-05-30 20:26:39 -07:00
parent 9535404d7b
commit e085059fd5
4 changed files with 212 additions and 0 deletions
--- a/.dockerignore
+++ b/.dockerignore
@@ -0,0 +1,2 @@
+**
+!Dockerfile
--- a/58
+++ b/58
@@ -0,0 +1,58 @@
+# TOOLCHAIN_PLATFORM is pinned to linux/amd64 so the ARM cross-compilers and
+# qemu-user-static are always x86_64 binaries, matching the tested path.
+# Passing `--platform` through an ARG silences the Docker linter warning about
+# constant --platform values while keeping the behaviour identical.
+ARG TOOLCHAIN_PLATFORM=linux/amd64
+FROM --platform=${TOOLCHAIN_PLATFORM} debian:trixie
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Toolchain and utilities needed by build targets in this repository.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+    bc \
+    bison \
+    build-essential \
+    ca-certificates \
+    cpio \
+    debootstrap \
+    dosfstools \
+    e2fsprogs \
+    fdisk \
+    file \
+    flex \
+    gcc-arm-linux-gnueabi \
+    gcc-arm-linux-gnueabihf \
+    git \
+    kmod \
+    kpartx \
+    libncurses-dev \
+    libssl-dev \
+    libyaml-dev \
+    lzop \
+    make \
+    parted \
+    python3 \
+    python3-pyelftools \
+    python3-venv \
+    qemu-user-static \
+    rsync \
+    sudo \
+    unzip \
+    util-linux \
+    u-boot-tools \
+    wget \
+    xz-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# brainlilo requires arm-mingw32ce toolchain from cegcc-build releases.
+RUN wget -q -O /tmp/cegcc.zip https://github.com/brain-hackers/cegcc-build/releases/download/2022-04-11-133546/cegcc-2022-04-11-133546.zip \
+    && unzip -q /tmp/cegcc.zip -d /tmp \
+    && mkdir -p /opt \
+    && mv /tmp/cegcc /opt/cegcc \
+    && rm -rf /tmp/cegcc.zip
+
+WORKDIR /work
+
+# Keep entrypoint simple so callers can pass arbitrary make targets.
+CMD ["bash"]
--- a/66
+++ b/66
@@ -5,6 +5,9 @@ LINUX_CROSS=$(shell ./tools/getcross linux)
 ROOTFS_CROSS=$(shell ./tools/getcross rootfs)
 export ARCH=arm

+DOCKER_IMAGE := buildbrain-builder:local
+ROOTFS_VOLUME := buildbrain-brainux-rootfs
+
 .PHONY:
 setup:
 	@echo "Updating submodules"
@@ -213,3 +216,66 @@ aptcache:
 .PHONY:
 datetag:
 	git tag $(shell ./tools/version)
+
+# ========== Docker-based build targets (for macOS and other non-Linux hosts) ==========
+
+.PHONY:
+docker-build:
+	docker build --platform linux/amd64 -t $(DOCKER_IMAGE) -f Dockerfile .
+
+.PHONY:
+docker-uboot:
+	docker run --rm --platform linux/amd64 -v "$$PWD":/work -w /work $(DOCKER_IMAGE) \
+		bash -lc "make udefconfig-sh1 && make ubuild"
+
+# Build Linux kernel using brain defconfig.
+# mrproper wipes stale host-tool binaries (e.g. arm64 objects left from a
+# previous native build) so they are always recompiled for the container's
+# architecture before defconfig and the full build run.
+.PHONY:
+docker-kernel:
+	docker run --rm --platform linux/amd64 -v "$$PWD":/work -w /work $(DOCKER_IMAGE) \
+		bash -lc "make lclean; make ldefconfig && make lbuild"
+
+# Build Debian rootfs in container with debootstrap and qemu.
+# The rootfs is stored in a Docker named volume (Linux ext4 inside the Docker
+# Desktop VM) instead of the macOS APFS bind mount.  This is critical: APFS
+# cannot represent mknod device files or preserve all Linux permission bits,
+# which produces a rootfs that fails to boot despite appearing structurally
+# complete.  A named volume stores a true Linux filesystem and avoids all of
+# these issues.
+.PHONY:
+docker-rootfs: docker-volume-rm docker-volume-create
+	docker run --rm --platform linux/amd64 --privileged -e CI=true \
+		-v $(ROOTFS_VOLUME):/work/brainux \
+		-v "$$PWD":/work -w /work $(DOCKER_IMAGE) \
+		bash -lc "make brainux"
+
+# Assemble SD image from pre-built kernel and rootfs.
+# Requires privileged mode because make targets use loop devices, kpartx and mount.
+# Mounts the same named volume used by docker-rootfs so the rootfs copy into the
+# ext4 partition originates from the Linux-native volume, not from macOS APFS.
+.PHONY:
+docker-sd-image:
+	docker run --rm --platform linux/amd64 --privileged \
+		-v $(ROOTFS_VOLUME):/work/brainux \
+		-v "$$PWD":/work -w /work $(DOCKER_IMAGE) \
+		bash -lc "make -C nkbin_maker clean all && make IMG_BUILD_JOBS=1 image/sd.img"
+
+# Build complete SD image from scratch (stages: kernel, rootfs, then assembly).
+# We split the build into 3 phases to avoid overwhelming the daemon on macOS Docker Desktop.
+.PHONY:
+docker-sd-image-full: docker-kernel docker-rootfs docker-sd-image
+
+# --------------------- Docker named-volume helpers ---------------------
+# docker-rootfs already recreates the volume automatically; these targets are
+# provided for manual use (e.g. inspecting, wiping, or recreating between runs).
+.PHONY:
+docker-volume-create:
+	docker volume create $(ROOTFS_VOLUME)
+
+.PHONY:
+docker-volume-rm:
+	docker volume rm $(ROOTFS_VOLUME) 2>/dev/null || true
+
+# ==================== end of Docker-based build targets ====================
--- a/README.md
+++ b/README.md
@@ -14,7 +14,9 @@ Confirmed environments

 - Debian 10 (buster) amd64
 - Debian 11 (bullseye) amd64
+- macOS 26.5 (Tahoe) arm64-apple-darwin25.5.0 via Docker

+**Typical Runtime**: 3 hrs is typical on a M2 Max MacBook Pro via Docker.

 Getting Started
 ---------------
@@ -44,6 +46,7 @@ For Debian-based systems:
    - Follow [the instruction](https://github.com/NXPmicro/mfgtools#linux) and build `uuu` executable.
    - Put `uuu` where the PATH executable points to.

+For macOS, see [Docker build](#docker-build) section below.

 Build U-Boot
 ------------
@@ -120,6 +123,89 @@ If you want to customize the build of Buildroot, `cd` into `buildroot` and use t

 `image/sd_buildroot.img` target expects presence of the tarball at `buildroot/output/images/rootfs.tar`. You'll have to `clean` and rebuild every time you change the Buildroot's config before making the SD image.

+Docker build
+------------
+
+You can build everything in Docker instead of preparing native Linux cross toolchains on your host.
+
+### Prerequisites
+
+- Docker Desktop (or Docker Engine) with Linux containers enabled
+- A clone with submodules initialized
+
+### Steps
+
+1. Build the builder image.
+
+    ```sh
+    make docker-build
+    ```
+
+2. Build complete SD image in stages (recommended for macOS to avoid daemon crashes).
+
+    ```sh
+    make docker-sd-image-full
+    ```
+
+    This runs three separate containers in sequence, which distributes resource load and prevents Docker Desktop daemon from running out of memory. Alternatively, run each stage independently:
+
+    ```sh
+    make docker-kernel
+    make docker-rootfs
+    make docker-sd-image
+    ```
+
+    **Note:** On macOS Docker Desktop, the combined memory footprint of kernel compilation, rootfs staging, and loop device operations can exceed the default VM allocation (~2-4 GB). Breaking into stages allows the daemon to garbage collect between steps.
+
+    **Note:** `make docker-rootfs` (and thus `make docker-sd-image-full`) always deletes and recreates the named volume `buildbrain-brainux-rootfs` before building, so each rootfs build starts from a clean slate. To delete the volume manually between runs use `make docker-volume-rm`.
+
+### Direct Docker commands (advanced)
+
+For macOS, run in **stages** and use a **named volume** for the rootfs.
+
+> [!NOTE] Why a named volume for the rootfs?
+> macOS APFS (the host filesystem behind Docker bind mounts) cannot create device
+> files (`mknod`), may strip `setuid` bits, and does not faithfully preserve all
+> Linux filesystem attributes.  If the Debian rootfs is stored on APFS the result
+> looks complete but will fail to boot — systemd cannot exec as PID 1 because the
+> rootfs is subtly broken.  The `make docker-*` targets below store `brainux/` in a
+> Docker **named volume** (`buildbrain-brainux-rootfs`), which lives inside the
+> Docker Desktop Linux VM on an ext4 filesystem and supports full Linux semantics.
+
+```sh
+# Create a named volume for the rootfs (Linux ext4 inside the Docker Desktop VM)
+$ docker volume create buildbrain-brainux-rootfs
+
+# Stage 1: kernel (bind mount is fine for source + outputs)
+$ docker run --rm --platform linux/amd64 -v "$PWD":/work -w /work buildbrain-builder:local \
+    bash -lc "make ldefconfig && make lbuild"
+
+# Stage 2: rootfs (must use named volume, NOT a bind mount for brainux/)
+$ docker run --rm --platform linux/amd64 --privileged -e CI=true \
+    -v buildbrain-brainux-rootfs:/work/brainux \
+    -v "$PWD":/work -w /work buildbrain-builder:local \
+    bash -lc "make brainux"
+
+# Stage 3: image assembly (mount the same named volume so cp -a reads from Linux ext4)
+$ docker run --rm --platform linux/amd64 --privileged \
+    -v buildbrain-brainux-rootfs:/work/brainux \
+    -v "$PWD":/work -w /work buildbrain-builder:local \
+    bash -lc "make -C nkbin_maker clean all && make IMG_BUILD_JOBS=1 image/sd.img"
+```
+
+On Linux with sufficient resources, you can run all steps in one container (no named volume needed on a native Linux host):
+
+```sh
+$ docker run --rm --platform linux/amd64 --privileged -e CI=true -v "$PWD":/work -w /work buildbrain-builder:local \
+    bash -lc "make ldefconfig lbuild && make nkbin-maker && make brainux && make image/sd.img"
+```
+
+Other useful Docker recipes:
+
+- `make docker-uboot` to build U-Boot
+- `make docker-kernel` to build Linux kernel
+- `make docker-volume-create` to (re-)create the rootfs named volume
+- `make docker-volume-rm` to delete the rootfs named volume and reclaim its disk space

 Known issues
 ------------