From bf54dfbf44a1b6805e299fb295f29a5c70d6a693 Mon Sep 17 00:00:00 2001 From: Mingyang Li Date: Sat, 6 Jun 2026 10:33:00 -0700 Subject: [PATCH] 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 < ${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}