From f83787bac4a775f4b49f71ccb32d774ea1622a70 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 09:36:52 -0700
Subject: [PATCH 01/14] fix: UID reference in `override.sh`.

`sudo -u#1000` requires UID 1000 to exist in passwd, but the build container only has `root`. Fixed by replacing those two `sudo -u#1000 -g#1000 mkdir -p` calls with `install -d -o 1000 -g 1000 -m 0755` in override.sh.
---
 os-brainux/override.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/os-brainux/override.sh b/os-brainux/override.sh
index e28c617..9efb4d2 100755
--- a/os-brainux/override.sh
+++ b/os-brainux/override.sh
@@ -14,8 +14,8 @@ install -g root -o root -m 0644 $SRC/etc/X11/Xsession.d/96calibrate $DST/etc/X11
 install -g root -o root -m 0644 -D $SRC/etc/xdg/weston/weston.ini $DST/etc/xdg/weston/weston.ini
 
 install -g 1000 -o 1000 -m 0644 $SRC/home/user/.xprofile $DST/home/user/.xprofile
-sudo -u#1000 -g#1000 mkdir -p $DST/home/user/.config/fcitx
+install -d -o 1000 -g 1000 -m 0755 $DST/home/user/.config/fcitx
 install -g 1000 -o 1000 -m 0644 $SRC/home/user/.config/fcitx/profile $DST/home/user/.config/fcitx/profile
-sudo -u#1000 -g#1000 mkdir -p $DST/home/user/lxterminal
+install -d -o 1000 -g 1000 -m 0755 $DST/home/user/lxterminal
 install -g 1000 -o 1000 -m 0644 $SRC/home/user/lxterminal/lxterminal.conf $DST/home/user/lxterminal/lxterminal.conf
 install -g root -o root -m 0644 -D $SRC/etc/jwm/system.jwmrc $DST/etc/jwm/system.jwmrc

From 113edbbdb1b9a2821e58cc3cfb15efe216a77f51 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 09:37:48 -0700
Subject: [PATCH 02/14] chore: ignore `.exe` and all `.img` files.

---
 .gitignore | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index d43a944..9aca68b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,5 +3,6 @@ brainux
 cache/*
 !cache/.gitkeep
 nk.bin
-image/sd.img
+image/sd*.img
+*.exe
 image/work

From ee779d6be7303c36f300b1d6df1640c9ab55a2df Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 09:57:45 -0700
Subject: [PATCH 03/14] doc: update build_image.sh help message and default
 arguments

---
 image/build_image.sh | 73 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 55 insertions(+), 18 deletions(-)

diff --git a/image/build_image.sh b/image/build_image.sh
index 71aff81..7e0fe5f 100755
--- a/image/build_image.sh
+++ b/image/build_image.sh
@@ -1,14 +1,37 @@
 #!/bin/bash
 set -uex -o pipefail
 
-JOBS=$(nproc)
+show_help() {
+    cat << 'EOF'
+Usage: ./build_image.sh ROOTFS IMG_NAME SIZE_M
+
+Build a bootable image for Brainux.
+
+Arguments:
+  ROOTFS       Path to the root filesystem directory to include in the image (default: "rootfs").
+  IMG_NAME     Name of the output image file (default: brainux.img).
+  SIZE_M       Size of the output image in megabytes (default: 1024).
+EOF
+}
+
+# Trigger help if requested or if no arguments are passed
+if [[ "$1" == "-h" || "$1" == "--help" || -z "$1" ]]; then
+    show_help
+    exit 0
+fi
+
+# JOBS is used to control the number of parallel jobs when building u-boot.
+# By default, it uses the number of CPU cores. This can be overridden by
+# setting the IMG_BUILD_JOBS environment variable before running the script,
+# handy for Docker environments or when you want to limit resource usage.
+JOBS=${IMG_BUILD_JOBS:-$(nproc)}
 REPO=$(git rev-parse --show-toplevel)
 WORK=${REPO}/image/work
 LINUX=${REPO}/linux-brain
-ROOTFS=$1
-IMG_NAME=$2
+ROOTFS=${1:-rootfs} # Default to "rootfs" if not specified
+IMG_NAME=${2:-brainux.img}
 IMG=${REPO}/image/${IMG_NAME}
-SIZE_M=$3
+SIZE_M=${3:-1024} # Default to 1GB if not specified
 export CROSS_COMPILE=arm-linux-gnueabi-
 
 mkdir -p ${WORK}
@@ -16,35 +39,44 @@ mkdir -p ${WORK}/lilobin
 
 for i in "a7200" "a7400" "sh1" "sh2" "sh3" "sh4" "sh5" "sh6" "sh7"; do
     NUM=$(echo $i | sed -E 's/sh//g')
+    BUILD_DIR=${WORK}/uboot-build-${i}
 
-    make -C ${REPO}/u-boot-brain distclean pw${i}_defconfig
-    make -j${JOBS} -C ${REPO}/u-boot-brain u-boot.bin
-    ${REPO}/nkbin_maker/bsd-ce ${REPO}/u-boot-brain/u-boot.bin
+    # Build per-board from isolated source copies to avoid fragile clean rules.
+    rm -rf ${BUILD_DIR}
+    rsync -a --exclude '.git' ${REPO}/u-boot-brain/ ${BUILD_DIR}/
+    make -C ${BUILD_DIR} pw${i}_defconfig
+    make -j${JOBS} -C ${BUILD_DIR} u-boot.bin
+    ${REPO}/nkbin_maker/bsd-ce ${BUILD_DIR}/u-boot.bin
 
     case $i in
         "a7200")
             mv ${REPO}/nk.bin ${WORK}/edna3exe.bin
-            mv ${REPO}/u-boot-brain/u-boot.bin ${WORK}/lilobin/gen2.bin;;
+            mv ${BUILD_DIR}/u-boot.bin ${WORK}/lilobin/gen2.bin;;
         "a7400")
-            mv ${REPO}/u-boot-brain/u-boot.bin ${WORK}/lilobin/gen2_7400.bin;;
+            mv ${BUILD_DIR}/u-boot.bin ${WORK}/lilobin/gen2_7400.bin;;
         "sh1" | "sh2" | "sh3")
             mv ${REPO}/nk.bin ${WORK}/edsa${NUM}exe.bin
-            mv ${REPO}/u-boot-brain/u-boot.bin ${WORK}/lilobin/gen3_${NUM}.bin;;
+            mv ${BUILD_DIR}/u-boot.bin ${WORK}/lilobin/gen3_${NUM}.bin;;
         "sh4" | "sh5" | "sh6" | "sh7")
             mv ${REPO}/nk.bin ${WORK}/edsh${NUM}exe.bin
-            mv ${REPO}/u-boot-brain/u-boot.bin ${WORK}/lilobin/gen3_${NUM}.bin;;
+            mv ${BUILD_DIR}/u-boot.bin ${WORK}/lilobin/gen3_${NUM}.bin;;
         *)
             echo "WTF: $i"
             exit 1;;
     esac
 done
 
+# Create an empty image file of the specified size.
 dd if=/dev/zero of=${IMG} bs=1M count=${SIZE_M}
 
-START1=2048
-SECTORS1=$((1024 * 1024 * 64 / 512))
-START2=$((2048 + ${SECTORS1}))
+# We want to partition the image with two partitions:
+# * a 64MB FAT32 partition for the bootloader and kernel, and
+# * the rest of the space as an ext4 partition for the root filesystem.
+START1=2048 # Start at 1MB (2048 sectors of 512 bytes) to align with typical partitioning schemes and avoid issues with some bootloaders.
+SECTORS1=$((1024 * 1024 * 64 / 512)) # 64MB in sectors (512 bytes per sector)
+START2=$((START1 + SECTORS1)) # Start the second partition immediately after the first
 
+# We use sfdisk to create the partition table. The first partition is type 'b' (W95 FAT32), and the second is type '83' (Linux).
 cat <<EOF > ${WORK}/part.sfdisk
 ${IMG}1 : start=${START1}, size=${SECTORS1}, type=b
 ${IMG}2 : start=${START2}, type=83
@@ -52,9 +84,12 @@ EOF
 
 sfdisk ${IMG} < ${WORK}/part.sfdisk
 
-sudo kpartx -av ${IMG}
-
-LOOPDEV=$(losetup -l | grep ${IMG_NAME} | grep -o 'loop.' | tail -n 1)
+# We want to format and write to the partitions. To do so, we use kpartx to create device mappings for the partitions in the image.
+KPARTX_OUTPUT=$(sudo kpartx -av ${IMG})
+# Extract the loop device name from kpartx output. It looks like:
+# "add map loop0p1 (252:0): 0 131072 linear /dev/loop0 2048"
+# We want to extract "loop0" from this line.
+LOOPDEV=$(echo "${KPARTX_OUTPUT}" | sed -n 's/^add map \(loop[0-9]\+\)p1.*/\1/p' | head -n 1)
 
 sudo mkfs.fat -n boot -F32 -v -I /dev/mapper/${LOOPDEV}p1
 sudo mkfs.ext4 -L rootfs /dev/mapper/${LOOPDEV}p2
@@ -63,13 +98,14 @@ mkdir -p ${WORK}/p1 ${WORK}/p2
 sudo mount -o utf8=true /dev/mapper/${LOOPDEV}p1 ${WORK}/p1
 sudo mount /dev/mapper/${LOOPDEV}p2 ${WORK}/p2
 
-echo ${BRAINUX_VERSION} > ${WORK}/brainux_version
+echo ${BRAINUX_VERSION:-unknown} > ${WORK}/brainux_version
 sudo cp ${WORK}/brainux_version ${WORK}/p1/
 sudo cp ${LINUX}/arch/arm/boot/zImage ${WORK}/p1/
 sudo cp ${LINUX}/arch/arm/boot/dts/imx28-pw*.dtb ${WORK}/p1/
 sudo mkdir -p ${WORK}/p1/nk
 sudo cp ${WORK}/*.bin ${WORK}/p1/nk/
 
+# Prepare the WinCE application "Launch Linux". "LILO" stands for "Linux Loader".
 make -C ${REPO}/brainlilo
 
 LILO="${WORK}/p1/アプリ/Launch Linux"
@@ -86,6 +122,7 @@ sudo cp ${WORK}/lilobin/*.bin ${WORK}/p1/loader/
 
 sudo cp -ra ${REPO}/${ROOTFS}/* ${WORK}/p2/
 
+# Clean up: unmount the partitions and remove the device mappings.
 sudo umount ${WORK}/p1 ${WORK}/p2
 sudo kpartx -d ${IMG}
 

From 2b4eea9fc6d253dc2aff2031595f8e3a45847082 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 10:08:22 -0700
Subject: [PATCH 04/14] fix: Mount `proc` and `sys` AFTER the first stage of
 debootstrap.

---
 Makefile | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index d159a98..44568ea 100644
--- a/Makefile
+++ b/Makefile
@@ -141,16 +141,21 @@ brainux:
 		exit 1; \
 	fi
 	mkdir -p brainux
-	sudo mkdir -p brainux/proc brainux/sys
-	sudo mount -t proc none $(shell pwd)/brainux/proc
-	sudo mount --rbind /sys $(shell pwd)/brainux/sys
-	
 	@if [ "$(CI)" = "true" ]; then \
 		echo "I'm in CI and debootstrap without cache."; \
 		sudo debootstrap --arch=$(ROOTFS_CROSS) --foreign trixie brainux/; \
 	else \
 		sudo debootstrap --arch=$(ROOTFS_CROSS) --foreign trixie brainux/ http://localhost:65432/debian/; \
 	fi
+
+	# Mount proc and sys to allow debootstrap to run the second stage in the chroot.
+	# Keep the mounting commands AFTER the first stage of debootstrap, because
+	# debootstrap's cleanup code/trap tries to clean up the target directory
+	# (`rm -rf /work/brainux/proc`) and fails because proc virtual files can't be removed.
+	sudo mkdir -p brainux/proc brainux/sys
+	sudo mount -t proc none $(shell pwd)/brainux/proc
+	sudo mount --rbind /sys $(shell pwd)/brainux/sys
+
 	sudo cp /usr/bin/qemu-arm-static brainux/usr/bin/
 	sudo cp ./os-brainux/setup_brainux.sh brainux/
 	sudo ./os-brainux/override-pre.sh ./os-brainux/override ./brainux

From c9b912bfab8b534f9b20d5569d93c09a356aa4ae Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 10:10:47 -0700
Subject: [PATCH 05/14] Fix: set `vm.mmap_min_addr=0` in the `--privileged`
 container before the chroot.

`sqv` (the ARM OpenPGP verifier used by apt) needs to mmap at address `0x1000`, but `vm.mmap_min_addr` is too high.
---
 Makefile | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Makefile b/Makefile
index 44568ea..61aad5b 100644
--- a/Makefile
+++ b/Makefile
@@ -159,6 +159,12 @@ brainux:
 	sudo cp /usr/bin/qemu-arm-static brainux/usr/bin/
 	sudo cp ./os-brainux/setup_brainux.sh brainux/
 	sudo ./os-brainux/override-pre.sh ./os-brainux/override ./brainux
+
+	# Allow qemu-arm-static to reserve the guest address space at low virtual
+	# addresses (0x1000).  On Linux hosts vm.mmap_min_addr defaults to 65536
+	# which blocks the reservation, causing armel binaries like sqv (apt's
+	# OpenPGP verifier) to fail.  This requires --privileged in Docker.
+	sudo sh -c 'echo 0 > /proc/sys/vm/mmap_min_addr'
 	sudo -E chroot brainux /setup_brainux.sh
 	sudo rm brainux/setup_brainux.sh
 	sudo ./os-brainux/override.sh ./os-brainux/override ./brainux

From 26aeca29264bad26f4743e68b8cade70f887b481 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 10:11:56 -0700
Subject: [PATCH 06/14] Register qemu-arm-static binfmt handler if not already
 present.

---
 Makefile | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 61aad5b..4afb54b 100644
--- a/Makefile
+++ b/Makefile
@@ -159,7 +159,11 @@ brainux:
 	sudo cp /usr/bin/qemu-arm-static brainux/usr/bin/
 	sudo cp ./os-brainux/setup_brainux.sh brainux/
 	sudo ./os-brainux/override-pre.sh ./os-brainux/override ./brainux
-
+	# Register qemu-arm-static binfmt handler if not already present.
+	# The F (fixed) flag makes the kernel resolve the interpreter from the
+	# host filesystem so it works inside the chroot even without qemu in it.
+	# This is a no-op if the entry already exists (e.g. in CI or native Linux).
+	sudo bash -c 'mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc 2>/dev/null; test -e /proc/sys/fs/binfmt_misc/qemu-arm || echo ":qemu-arm:M::\x7fELF\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x28\x00:\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/usr/bin/qemu-arm-static:F" > /proc/sys/fs/binfmt_misc/register'
 	# Allow qemu-arm-static to reserve the guest address space at low virtual
 	# addresses (0x1000).  On Linux hosts vm.mmap_min_addr defaults to 65536
 	# which blocks the reservation, causing armel binaries like sqv (apt's

From 9ca325180607adb7f20562b543a26c0587f53f40 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 10:12:26 -0700
Subject: [PATCH 07/14] doc: + comment "Copy qemu-arm-static and setup script"

---
 Makefile | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Makefile b/Makefile
index 4afb54b..c07aaf2 100644
--- a/Makefile
+++ b/Makefile
@@ -156,6 +156,8 @@ brainux:
 	sudo mount -t proc none $(shell pwd)/brainux/proc
 	sudo mount --rbind /sys $(shell pwd)/brainux/sys
 
+	# Copy qemu-arm-static and setup script to allow running the second stage of
+	# debootstrap in the chroot on an x86 host.
 	sudo cp /usr/bin/qemu-arm-static brainux/usr/bin/
 	sudo cp ./os-brainux/setup_brainux.sh brainux/
 	sudo ./os-brainux/override-pre.sh ./os-brainux/override ./brainux

From 703671b16aef0cfe980659b00a142a27ea4a2f7c Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 10:13:40 -0700
Subject: [PATCH 08/14] chore: + `.PHONY` at target `brainux`. Just to be safe.

---
 Makefile | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index c07aaf2..f09e510 100644
--- a/Makefile
+++ b/Makefile
@@ -135,7 +135,8 @@ lilobuild:
 liloclean:
 	make -C ./brainlilo clean
 
-brainux:
+.PHONY: brainux brainux-umount-special brainux-clean
+brainux: 
 	@if [ "$(shell uname)" != "Linux" ]; then \
 		echo "Debootstrap is only available in Linux!"; \
 		exit 1; \

From 823dd221a369dfe37a8d3e9c28f0c51369246ddd Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 10:43:15 -0700
Subject: [PATCH 09/14] doc: cosmetic changes to README

---
 README.md | 51 +++++++++++++++++++++++++++------------------------
 1 file changed, 27 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 1ed3fb3..f96ee83 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,13 @@
 buildbrain
 ==========
 
-This repository includes:
+Scripts for building [Brainux](https://brainux.org/), a custom Linux distribution for the [Sharp Brain](https://jp.sharp/edictionary/) series of electronic dictionaries.
 
- - linux-brain, u-boot-brain, nkbin_maker and boot4u as submodules
- - Useful build targets in Makefile
- - r3build.toml to watch changes that occur in submodules
+This meta-repository includes:
 
+- linux-brain, u-boot-brain, nkbin_maker and boot4u as submodules
+- Useful build targets in Makefile
+- `r3build.toml` to watch changes that occur in submodules
 
 Confirmed environments
 ----------------------
@@ -18,32 +19,34 @@ Confirmed environments
 Getting Started
 ---------------
 
+For Debian-based systems:
+
 1. Install dependencies.
 
-    ```
-    $ sudo apt install build-essential bison flex libncurses5-dev gcc-arm-linux-gnueabi gcc-arm-linux-gnueabihf libssl-dev bc lzop qemu-user-static debootstrap kpartx libyaml-dev python3-pyelftools
+    ```sh
+    sudo apt install build-essential bison flex libncurses5-dev gcc-arm-linux-gnueabi gcc-arm-linux-gnueabihf libssl-dev bc lzop qemu-user-static debootstrap kpartx libyaml-dev python3-pyelftools
     ```
 
-1. Clone this repository with recursive clone enabled.
+2. Clone this repository recursively.
 
-    ```
-    $ git clone --recursive git@github.com:brain-hackers/buildbrain.git
+    ```sh
+    git clone --recursive git@github.com:brain-hackers/buildbrain.git
     ```
 
     - If you've cloned it without `--recursive`, run following command:
 
-    ```
-    $ git submodule update --init --recursive
+    ```sh
+    git submodule update --init --recursive
     ```
 
-1. Install uuu.
+3. Install `uuu`.
 
     - Follow [the instruction](https://github.com/NXPmicro/mfgtools#linux) and build `uuu` executable.
     - Put `uuu` where the PATH executable points to.
 
 
 Build U-Boot
------------------------
+------------
 
 1. Run `make udefconfig-sh*` to generate `.config`.
 
@@ -55,9 +58,9 @@ Build U-Boot
 
     - i.MX283 loads a packed U-Boot executable called `u-boot.sb`.
 
-
 Inject U-Boot into i.MX283 in recovery mode
 -----------------------
+
 1. Follow `Build U-Boot` procedure to make U-Boot binary.
 
 1. Run `make uuu`
@@ -83,7 +86,6 @@ Build and deploy boot4u
     - `touch /path/to/your/sd/1st/partition/App/boot4u/index.din`
     - `cp boot4u/AppMain.bin  /path/to/your/sd/1st/partition/App/boot4u/`
 
-
 Build Linux
 -----------
 
@@ -93,7 +95,6 @@ Build Linux
 
 1. Confirm that `linux-brain/arch/arm/boot/zImage` exists.
 
-
 Build a Debian rootfs
 ---------------------
 
@@ -107,7 +108,6 @@ Build a Debian rootfs
 
 1. Confirm that `image/sd.img` is built and burn it to an SD card.
 
-
 Build a Buildroot rootfs
 ------------------------
 
@@ -115,14 +115,15 @@ Buildroot rootfs aims to be the most lightweight rootfs for experimental use. `m
 
 If you want to customize the build of Buildroot, `cd` into `buildroot` and use the following targets:
 
- - `make menuconfig` to change the configuration
- - `make` to build the rootfs (`-j` option might give you extra speed)
+- `make menuconfig` to change the configuration
+- `make` to build the rootfs (`-j` option might give you extra speed)
 
 `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.
 
 
 Known issues
-----------------------------------------
+------------
+
 If you use GCC 10 for the host compiler, `make ubuild` may fail.
 To complete build, open `/u-boot-brain/scripts/dtc/dtc-lexer.lex.c` or `/u-boot-brain/scripts/dtc/dtc-parser.tab.c` then comment out `YYLTYPE yylloc;`
 
@@ -134,10 +135,12 @@ Watch changes in submodules & auto-build
     - Python 3 venv in `env`
     - r3build command in the env
 
-1. Run `r3build`. It'll detect the changes you make and builds the corresponding executable automatically.
+2. Run `r3build`. It'll detect the changes you make and build the corresponding executable automatically.
 
+> [!NOTE] What's r3build?
+> [r3build](https://github.com/puhitaku/r3build) is a smart file watcher that aims to provide hot-reloading feature like Web frontend development.
 
-What's r3build?
----------------
+Disclaimer
+----------
 
-[r3build](https://github.com/puhitaku/r3build) is a smart file watcher that aims to provide hot-reloading feature like Web frontend development.
+This repository is not affiliated with Sharp Corporation. The content is provided "as is" without any warranties. Use at your own risk.

From 524aeda448a48f603bc3e725ecfdb6bad3d96bf8 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 10:47:51 -0700
Subject: [PATCH 10/14] Speed up `ly` compilation by enabling parallelism.

---
 os-brainux/setup_brainux.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/os-brainux/setup_brainux.sh b/os-brainux/setup_brainux.sh
index 22c90c2..c4b36c9 100755
--- a/os-brainux/setup_brainux.sh
+++ b/os-brainux/setup_brainux.sh
@@ -102,7 +102,7 @@ DEBIAN_FRONTEND=noninteractive \
 cd /
 git clone --recurse-submodules -b master-24f017e https://github.com/brain-hackers/ly.git
 cd ly
-make
+make -j$(nproc)
 make install
 make installsystemd
 cd /

From 667735f915f697527b7151a76009ef4d356f6118 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 11:03:01 -0700
Subject: [PATCH 11/14] chore: ignore common artifacts from the big-3 OSes

---
 .gitignore | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/.gitignore b/.gitignore
index 9aca68b..b60ce8f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,82 @@ nk.bin
 image/sd*.img
 *.exe
 image/work
+
+# Created by https://www.toptal.com/developers/gitignore/api/macos,linux,windows
+# Edit at https://www.toptal.com/developers/gitignore?templates=macos,linux,windows
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# End of https://www.toptal.com/developers/gitignore/api/macos,linux,windows

From 9535404d7bdbd18e165e7b80fc4e5b627a0c6350 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 11:17:53 -0700
Subject: [PATCH 12/14] perf: merge `apt install apt-transport-https` into the
 curl/gnupg call, reducing one full apt resolver invocation

---
 os-brainux/setup_brainux.sh | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/os-brainux/setup_brainux.sh b/os-brainux/setup_brainux.sh
index c4b36c9..af74618 100755
--- a/os-brainux/setup_brainux.sh
+++ b/os-brainux/setup_brainux.sh
@@ -57,12 +57,9 @@ echo "brain" > /etc/hostname
 
 # curl, ca-certificates: downloads the GPG key from packagecloud
 # gnupg, debian-archive-keyring: packagecloud verification dependency
+# apt-transport-https: needed before we can add the HTTPS packagecloud source
 DEBIAN_FRONTEND=noninteractive \
-    apt install -y curl ca-certificates gnupg debian-archive-keyring
-
-# apt-transport-https can be installed after debian-archive-keyring being installed
-DEBIAN_FRONTEND=noninteractive \
-    apt install -y apt-transport-https
+    apt install -y curl ca-certificates gnupg debian-archive-keyring apt-transport-https
 
 # Install GPG key and packagecloud repository config
 mkdir -p /etc/apt/keyrings

From e085059fd5575e526de5cc56bf388cb948648a34 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 30 May 2026 20:26:39 -0700
Subject: [PATCH 13/14] + 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
 ------------

From bf54dfbf44a1b6805e299fb295f29a5c70d6a693 Mon Sep 17 00:00:00 2001
From: Mingyang Li <tslmy@outlook.com>
Date: Sat, 6 Jun 2026 10:33:00 -0700
Subject: [PATCH 14/14] Address review comments from puhitaku

- image/build_image.sh: fix IMG_NAME default to sd.img, SIZE_M to 3072
- image/build_image.sh: revert START2 to original form; remove all unnecessary inline comments
- Makefile: remove 'Mount proc and sys' comment; keep the 'Keep mounting commands AFTER' note
- Makefile: remove 'Copy qemu-arm-static' comment; simplify binfmt and mmap_min_addr comments
- Makefile: replace verbose Docker target comment blocks with clean targets per reviewer suggestion
- README.md: revert all unrelated changes; keep only the macOS environment line and Docker build section

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 Makefile             | 30 ------------------------
 README.md            | 55 +++++++++++++++++++++-----------------------
 image/build_image.sh | 32 +++++++-------------------
 3 files changed, 34 insertions(+), 83 deletions(-)

diff --git a/Makefile b/Makefile
index 75db5d2..dfced8e 100644
--- a/Makefile
+++ b/Makefile
@@ -152,7 +152,6 @@ brainux:
 		sudo debootstrap --arch=$(ROOTFS_CROSS) --foreign trixie brainux/ http://localhost:65432/debian/; \
 	fi
 
-	# Mount proc and sys to allow debootstrap to run the second stage in the chroot.
 	# Keep the mounting commands AFTER the first stage of debootstrap, because
 	# debootstrap's cleanup code/trap tries to clean up the target directory
 	# (`rm -rf /work/brainux/proc`) and fails because proc virtual files can't be removed.
@@ -160,15 +159,10 @@ brainux:
 	sudo mount -t proc none $(shell pwd)/brainux/proc
 	sudo mount --rbind /sys $(shell pwd)/brainux/sys
 
-	# Copy qemu-arm-static and setup script to allow running the second stage of
-	# debootstrap in the chroot on an x86 host.
 	sudo cp /usr/bin/qemu-arm-static brainux/usr/bin/
 	sudo cp ./os-brainux/setup_brainux.sh brainux/
 	sudo ./os-brainux/override-pre.sh ./os-brainux/override ./brainux
 	# Register qemu-arm-static binfmt handler if not already present.
-	# The F (fixed) flag makes the kernel resolve the interpreter from the
-	# host filesystem so it works inside the chroot even without qemu in it.
-	# This is a no-op if the entry already exists (e.g. in CI or native Linux).
 	sudo bash -c 'mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc 2>/dev/null; test -e /proc/sys/fs/binfmt_misc/qemu-arm || echo ":qemu-arm:M::\x7fELF\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x28\x00:\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/usr/bin/qemu-arm-static:F" > /proc/sys/fs/binfmt_misc/register'
 	# Allow qemu-arm-static to reserve the guest address space at low virtual
 	# addresses (0x1000).  On Linux hosts vm.mmap_min_addr defaults to 65536
@@ -217,8 +211,6 @@ aptcache:
 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 .
@@ -228,22 +220,11 @@ 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 \
@@ -251,10 +232,6 @@ docker-rootfs: docker-volume-rm docker-volume-create
 		-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 \
@@ -262,14 +239,9 @@ docker-sd-image:
 		-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)
@@ -277,5 +249,3 @@ docker-volume-create:
 .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 9fa5b27..8f4805f 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,12 @@
 buildbrain
 ==========
 
-Scripts for building [Brainux](https://brainux.org/), a custom Linux distribution for the [Sharp Brain](https://jp.sharp/edictionary/) series of electronic dictionaries.
+This repository includes:
 
-This meta-repository includes:
+ - linux-brain, u-boot-brain, nkbin_maker and boot4u as submodules
+ - Useful build targets in Makefile
+ - r3build.toml to watch changes that occur in submodules
 
-- linux-brain, u-boot-brain, nkbin_maker and boot4u as submodules
-- Useful build targets in Makefile
-- `r3build.toml` to watch changes that occur in submodules
 
 Confirmed environments
 ----------------------
@@ -16,40 +15,36 @@ Confirmed environments
 - 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
 ---------------
 
-For Debian-based systems:
-
 1. Install dependencies.
 
-    ```sh
-    sudo apt install build-essential bison flex libncurses5-dev gcc-arm-linux-gnueabi gcc-arm-linux-gnueabihf libssl-dev bc lzop qemu-user-static debootstrap kpartx libyaml-dev python3-pyelftools
+    ```
+    $ sudo apt install build-essential bison flex libncurses5-dev gcc-arm-linux-gnueabi gcc-arm-linux-gnueabihf libssl-dev bc lzop qemu-user-static debootstrap kpartx libyaml-dev python3-pyelftools
     ```
 
-2. Clone this repository recursively.
+1. Clone this repository with recursive clone enabled.
 
-    ```sh
-    git clone --recursive git@github.com:brain-hackers/buildbrain.git
+    ```
+    $ git clone --recursive git@github.com:brain-hackers/buildbrain.git
     ```
 
     - If you've cloned it without `--recursive`, run following command:
 
-    ```sh
-    git submodule update --init --recursive
+    ```
+    $ git submodule update --init --recursive
     ```
 
-3. Install `uuu`.
+1. Install uuu.
 
     - 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
-------------
+-----------------------
 
 1. Run `make udefconfig-sh*` to generate `.config`.
 
@@ -61,9 +56,9 @@ Build U-Boot
 
     - i.MX283 loads a packed U-Boot executable called `u-boot.sb`.
 
+
 Inject U-Boot into i.MX283 in recovery mode
 -----------------------
-
 1. Follow `Build U-Boot` procedure to make U-Boot binary.
 
 1. Run `make uuu`
@@ -89,6 +84,7 @@ Build and deploy boot4u
     - `touch /path/to/your/sd/1st/partition/App/boot4u/index.din`
     - `cp boot4u/AppMain.bin  /path/to/your/sd/1st/partition/App/boot4u/`
 
+
 Build Linux
 -----------
 
@@ -98,6 +94,7 @@ Build Linux
 
 1. Confirm that `linux-brain/arch/arm/boot/zImage` exists.
 
+
 Build a Debian rootfs
 ---------------------
 
@@ -111,6 +108,7 @@ Build a Debian rootfs
 
 1. Confirm that `image/sd.img` is built and burn it to an SD card.
 
+
 Build a Buildroot rootfs
 ------------------------
 
@@ -118,11 +116,12 @@ Buildroot rootfs aims to be the most lightweight rootfs for experimental use. `m
 
 If you want to customize the build of Buildroot, `cd` into `buildroot` and use the following targets:
 
-- `make menuconfig` to change the configuration
-- `make` to build the rootfs (`-j` option might give you extra speed)
+ - `make menuconfig` to change the configuration
+ - `make` to build the rootfs (`-j` option might give you extra speed)
 
 `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
 ------------
 
@@ -207,9 +206,9 @@ Other useful Docker recipes:
 - `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
-------------
 
+Known issues
+----------------------------------------
 If you use GCC 10 for the host compiler, `make ubuild` may fail.
 To complete build, open `/u-boot-brain/scripts/dtc/dtc-lexer.lex.c` or `/u-boot-brain/scripts/dtc/dtc-parser.tab.c` then comment out `YYLTYPE yylloc;`
 
@@ -221,12 +220,10 @@ Watch changes in submodules & auto-build
     - Python 3 venv in `env`
     - r3build command in the env
 
-2. Run `r3build`. It'll detect the changes you make and build the corresponding executable automatically.
+1. Run `r3build`. It'll detect the changes you make and builds the corresponding executable automatically.
 
-> [!NOTE] What's r3build?
-> [r3build](https://github.com/puhitaku/r3build) is a smart file watcher that aims to provide hot-reloading feature like Web frontend development.
 
-Disclaimer
-----------
+What's r3build?
+---------------
 
-This repository is not affiliated with Sharp Corporation. The content is provided "as is" without any warranties. Use at your own risk.
+[r3build](https://github.com/puhitaku/r3build) is a smart file watcher that aims to provide hot-reloading feature like Web frontend development.
diff --git a/image/build_image.sh b/image/build_image.sh
index 7e0fe5f..66eb18b 100755
--- a/image/build_image.sh
+++ b/image/build_image.sh
@@ -9,8 +9,8 @@ Build a bootable image for Brainux.
 
 Arguments:
   ROOTFS       Path to the root filesystem directory to include in the image (default: "rootfs").
-  IMG_NAME     Name of the output image file (default: brainux.img).
-  SIZE_M       Size of the output image in megabytes (default: 1024).
+  IMG_NAME     Name of the output image file (default: sd.img).
+  SIZE_M       Size of the output image in megabytes (default: 3072).
 EOF
 }
 
@@ -20,18 +20,14 @@ if [[ "$1" == "-h" || "$1" == "--help" || -z "$1" ]]; then
     exit 0
 fi
 
-# JOBS is used to control the number of parallel jobs when building u-boot.
-# By default, it uses the number of CPU cores. This can be overridden by
-# setting the IMG_BUILD_JOBS environment variable before running the script,
-# handy for Docker environments or when you want to limit resource usage.
 JOBS=${IMG_BUILD_JOBS:-$(nproc)}
 REPO=$(git rev-parse --show-toplevel)
 WORK=${REPO}/image/work
 LINUX=${REPO}/linux-brain
-ROOTFS=${1:-rootfs} # Default to "rootfs" if not specified
-IMG_NAME=${2:-brainux.img}
+ROOTFS=${1:-rootfs}
+IMG_NAME=${2:-sd.img}
 IMG=${REPO}/image/${IMG_NAME}
-SIZE_M=${3:-1024} # Default to 1GB if not specified
+SIZE_M=${3:-3072}
 export CROSS_COMPILE=arm-linux-gnueabi-
 
 mkdir -p ${WORK}
@@ -41,7 +37,6 @@ for i in "a7200" "a7400" "sh1" "sh2" "sh3" "sh4" "sh5" "sh6" "sh7"; do
     NUM=$(echo $i | sed -E 's/sh//g')
     BUILD_DIR=${WORK}/uboot-build-${i}
 
-    # Build per-board from isolated source copies to avoid fragile clean rules.
     rm -rf ${BUILD_DIR}
     rsync -a --exclude '.git' ${REPO}/u-boot-brain/ ${BUILD_DIR}/
     make -C ${BUILD_DIR} pw${i}_defconfig
@@ -66,17 +61,12 @@ for i in "a7200" "a7400" "sh1" "sh2" "sh3" "sh4" "sh5" "sh6" "sh7"; do
     esac
 done
 
-# Create an empty image file of the specified size.
 dd if=/dev/zero of=${IMG} bs=1M count=${SIZE_M}
 
-# We want to partition the image with two partitions:
-# * a 64MB FAT32 partition for the bootloader and kernel, and
-# * the rest of the space as an ext4 partition for the root filesystem.
-START1=2048 # Start at 1MB (2048 sectors of 512 bytes) to align with typical partitioning schemes and avoid issues with some bootloaders.
-SECTORS1=$((1024 * 1024 * 64 / 512)) # 64MB in sectors (512 bytes per sector)
-START2=$((START1 + SECTORS1)) # Start the second partition immediately after the first
+START1=2048
+SECTORS1=$((1024 * 1024 * 64 / 512))
+START2=$((2048 + ${SECTORS1}))
 
-# We use sfdisk to create the partition table. The first partition is type 'b' (W95 FAT32), and the second is type '83' (Linux).
 cat <<EOF > ${WORK}/part.sfdisk
 ${IMG}1 : start=${START1}, size=${SECTORS1}, type=b
 ${IMG}2 : start=${START2}, type=83
@@ -84,11 +74,7 @@ EOF
 
 sfdisk ${IMG} < ${WORK}/part.sfdisk
 
-# We want to format and write to the partitions. To do so, we use kpartx to create device mappings for the partitions in the image.
 KPARTX_OUTPUT=$(sudo kpartx -av ${IMG})
-# Extract the loop device name from kpartx output. It looks like:
-# "add map loop0p1 (252:0): 0 131072 linear /dev/loop0 2048"
-# We want to extract "loop0" from this line.
 LOOPDEV=$(echo "${KPARTX_OUTPUT}" | sed -n 's/^add map \(loop[0-9]\+\)p1.*/\1/p' | head -n 1)
 
 sudo mkfs.fat -n boot -F32 -v -I /dev/mapper/${LOOPDEV}p1
@@ -105,7 +91,6 @@ sudo cp ${LINUX}/arch/arm/boot/dts/imx28-pw*.dtb ${WORK}/p1/
 sudo mkdir -p ${WORK}/p1/nk
 sudo cp ${WORK}/*.bin ${WORK}/p1/nk/
 
-# Prepare the WinCE application "Launch Linux". "LILO" stands for "Linux Loader".
 make -C ${REPO}/brainlilo
 
 LILO="${WORK}/p1/アプリ/Launch Linux"
@@ -122,7 +107,6 @@ sudo cp ${WORK}/lilobin/*.bin ${WORK}/p1/loader/
 
 sudo cp -ra ${REPO}/${ROOTFS}/* ${WORK}/p2/
 
-# Clean up: unmount the partitions and remove the device mappings.
 sudo umount ${WORK}/p1 ${WORK}/p2
 sudo kpartx -d ${IMG}