From e085059fd5575e526de5cc56bf388cb948648a34 Mon Sep 17 00:00:00 2001 From: Mingyang Li Date: Sat, 30 May 2026 20:26:39 -0700 Subject: [PATCH] + Docker as a way of building. --- .dockerignore | 2 ++ Dockerfile | 58 ++++++++++++++++++++++++++++++++++ Makefile | 66 +++++++++++++++++++++++++++++++++++++++ README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 212 insertions(+) create mode 100644 .dockerignore create mode 100644 Dockerfile diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..4d9b1a2 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,2 @@ +** +!Dockerfile diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..74322a2 --- /dev/null +++ b/Dockerfile @@ -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"] diff --git a/Makefile b/Makefile index f09e510..75db5d2 100644 --- a/Makefile +++ b/Makefile @@ -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 ==================== diff --git a/README.md b/README.md index f96ee83..9fa5b27 100644 --- 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 ------------