docs: add WSL2 build path and troubleshooting section by dinxsh · Pull Request #51 · flipperdevices/flipperone-linux-build-scripts

dinxsh · 2026-04-26T22:30:03Z

Summary

Adds ## Building on WSL2 (Windows) - one-time setup steps for Ubuntu 24.04 WSL2 (binfmt_misc, loop device nodes, fakemachine patch, IMG_OUT placement)
Adds ## Troubleshooting - 7 errors with confirmed one-line fixes, all encountered during a full build run
Adds ## Reusing the rootfs image - note explaining that build-images.sh can be re-run without repeating the expensive rootfs build

All content is additive to the new README being drafted in this PR.

Errors documented

Error	Fix
`execv(sh) failed: Exec format error`	`update-binfmts --enable`
`lstat .../linux_tmp: no such file or directory`	Use `IMG_OUT=out` (relative)
`fallocate: Operation not supported`	Keep `IMG_OUT`/`TMPDIR` on ext4, not NTFS
`fakemachine: command not found`	Patch kvm check to `if false`
`bmaptool: image size will not fit block device`	Set `IMGSIZE=8GiB` in both scripts
`No space left on device` during kernel install	Set `IMGSIZE=8GiB` in rootfs script
`cp: Input/output error` on 8 GiB image	Replace `cp` with `mv` in build-images.sh

Tested on: Ubuntu 24.04 WSL2, Windows 11, full build to debian-512-flipper-one-*.img.gz.

🤖 Generated with Claude Code

All 7 errors confirmed during a full build run on Ubuntu 24.04 WSL2 on Windows 11. WSL2 setup steps, error-specific fixes, and a note on reusing the rootfs image across build-images.sh runs without repeating the expensive rootfs build. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

alchark

Hi Dinesh, thanks for your contribution. There are several points I believe need to be addressed for this to be suitable for merging - please have a look at the detailed comments inside.

alchark · 2026-04-27T10:03:31Z

+# Register ARM binary handlers (required for rootfs build)
+mount -t binfmt_misc binfmt_misc /proc/sys/fs/binfmt_misc 2>/dev/null || true
+update-binfmts --enable


Please point to the required package qemu-user-binfmt instead and mention how to activate its respective systemd unit file.

alchark · 2026-04-27T10:05:09Z

+
+## Building on WSL2 (Windows)
+
+The build scripts work on Ubuntu 24.04 WSL2 with a few one-time setup steps. WSL2 does not pre-mount `binfmt_misc`, does not pre-create loop device nodes, and exposes `/dev/kvm` via Hyper-V even though `fakemachine` is not installed. Apply the following before running any build script.


If you followed existing instructions in the README you would have had fakemachine installed ;-) Please revisit those and amend the PR to make sure it's indeed incremental

alchark · 2026-04-27T10:05:52Z

+# Create loop device nodes (WSL2 does not create these automatically)
+for i in $(seq 0 32); do
+    [ -b /dev/loop$i ] || mknod /dev/loop$i b 7 $i
+done


Why? These are created on the fly when losetup runs

You're right — removed. I had hit a failure before losetup ran and thought the nodes were missing, but that was caused by a different issue.

alchark · 2026-04-27T10:07:37Z

+# Disable the fakemachine path - WSL2 exposes /dev/kvm but fakemachine is not installed
+sed -i 's/if \[ -c \/dev\/kvm -a -w \/dev\/kvm \]/if false/' build-rootfs-img.sh build-images.sh


NAK.

This breaks no-root builds for no reason: if you have KVM, you can use fakemachine

Agreed, removed. The correct fix when fakemachine isn't found is apt install fakemachine per the prerequisites, not patching out the detection.

alchark · 2026-04-27T10:08:07Z

+
+# Keep IMG_OUT on the WSL2 virtual disk (ext4), not a Windows-mounted path
+# NTFS does not support fallocate, which the image assembly step requires
+export IMG_OUT=out


This is already the default, no need to set explicitly

alchark · 2026-04-27T10:09:03Z

+# Keep IMG_OUT on the WSL2 virtual disk (ext4), not a Windows-mounted path
+# NTFS does not support fallocate, which the image assembly step requires
+export IMG_OUT=out
+export TMPDIR=/root/build-tmp


Won't work for non-root builds

alchark · 2026-04-27T10:09:41Z

+mkdir -p "$TMPDIR"
+```
+
+Both `binfmt_misc` registration and the loop device creation need to be repeated after each WSL2 session restart (or added to `/etc/rc.local` to persist).


Please refer to proper systemd actions, not rc.local

alchark · 2026-04-27T10:10:47Z

+
+### `lstat .../linux_tmp: no such file or directory`
+
+`IMG_OUT` is set to an absolute path. Internal scripts construct intermediate paths by appending relative suffixes, which breaks when the working directory changes mid-build.


Why would the working directory change mid-build in the first place? If you found such cases, please report them and let's find a way to fix.

I was running from outside the repo root — user error on my part, not a script bug. Removed the entry. If I find a genuine reproducible case I'll file it separately.

alchark · 2026-04-27T10:13:45Z

+WSL2 kernel bug: a large file written through a loop device triggers EIO on a subsequent `cp`. The data is intact. Use `mv` instead:
+
+```bash
+grep -n 'cp.*\.img' build-images.sh
+# Replace cp with mv on that line (N):
+sed -i 'Ns/\bcp\b/mv/' build-images.sh
+```
+
+`mv` is a rename and bypasses the page cache read path entirely.


What are the conditions when this happens? I routinely use WSL2 builds myself and never encountered anything like this. Replacing copies with moves is wrong (if a move was intended, it would have been used in the first place, but it was not).

Can't reproduce it reliably. I may have been hitting an NTFS-backed path issue that was masking as an I/O error on cp. Removed from docs.

alchark · 2026-04-27T10:15:59Z

+
+`build-rootfs-img.sh` produces `out/debian-rootfs.img.zst`. This step installs all Debian packages and takes 20-40 minutes. `build-images.sh` consumes it to assemble the final board images and is much faster.
+
+**If `build-images.sh` fails, you do not need to rerun `build-rootfs-img.sh`.** Fix the error and rerun `build-images.sh` directly as long as `out/debian-rootfs.img.zst` exists:


This also applies to all other steps (U-boot, kernel, ospack). If the artifacts from previous build stages are available, then they don't necessarily need to be regenerated.

- Replace update-binfmts with qemu-user-binfmt package + systemd-binfmt.service - Remove fakemachine-not-installed premise (it is installed per base README prereqs) - Remove manual loop device mknod block (losetup creates them on demand) - Remove sed hack that disabled KVM/fakemachine detection (breaks non-root builds) - Remove redundant IMG_OUT=out (it is already the default) - Remove TMPDIR=/root/build-tmp (scripts use mktemp internally; /root breaks non-root) - Replace rc.local mention with systemd-binfmt.service for persistence - Remove lstat/linux_tmp troubleshooting entry (working directory error, not WSL2 bug) - Remove cp→mv workaround (cp is intentional; mv would break multi-board image loop) - Expand reuse section to cover all four build stages (kernel, U-boot, ospack, rootfs) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dinxsh · 2026-05-03T02:23:32Z

Thanks for the detailed review. Updated in dinxsh/flipperone-linux-build-scripts@c76e98e:

Replaced update-binfmts with qemu-user-binfmt + systemctl enable --now systemd-binfmt
Rewrote the WSL2 intro to be incremental (assuming prereqs from the README above are done, including fakemachine)
Dropped IMG_OUT=out and TMPDIR=/root/build-tmp — the former is the default, the latter has no effect since the scripts use mktemp internally
Replaced the rc.local mention with systemd-binfmt.service
Expanded the reuse section to cover all four build stages (kernel, U-boot, ospack, rootfs) with a table

alchark requested changes Apr 27, 2026

View reviewed changes


		## Building on WSL2 (Windows)

		The build scripts work on Ubuntu 24.04 WSL2 with a few one-time setup steps. WSL2 does not pre-mount `binfmt_misc`, does not pre-create loop device nodes, and exposes `/dev/kvm` via Hyper-V even though `fakemachine` is not installed. Apply the following before running any build script.

		# Disable the fakemachine path - WSL2 exposes /dev/kvm but fakemachine is not installed
		sed -i 's/if \[ -c \/dev\/kvm -a -w \/dev\/kvm \]/if false/' build-rootfs-img.sh build-images.sh


		### `lstat .../linux_tmp: no such file or directory`

		`IMG_OUT` is set to an absolute path. Internal scripts construct intermediate paths by appending relative suffixes, which breaks when the working directory changes mid-build.


		`build-rootfs-img.sh` produces `out/debian-rootfs.img.zst`. This step installs all Debian packages and takes 20-40 minutes. `build-images.sh` consumes it to assemble the final board images and is much faster.

		If `build-images.sh` fails, you do not need to rerun `build-rootfs-img.sh`. Fix the error and rerun `build-images.sh` directly as long as `out/debian-rootfs.img.zst` exists:

Conversation

dinxsh commented Apr 26, 2026

Summary

Errors documented

Uh oh!

alchark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dinxsh commented May 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants