diskos/build/README-vendor.md

Vendored native tools - portability requirements

The installer bundles native binaries under vendor/<os>-<arch>/ and calls them via subprocess. For a distributable build these MUST be portable across the user's machines - not just copies of the build host's dynamically-linked binaries.

tool	why bundled	portability requirement
usbboot	Ingenic mask-ROM USB loader (the flasher)	Build static against libusb compiled --disable-udev (drops libudev + libcap; libusb falls back to sysfs enumeration). usbboot has no direct udev symbols - they were only transitive via libusb - so this yields a binary needing only libc. Prefer full-static (musl) or, at minimum, $ORIGIN/lib rpath + a bundled libusb-1.0.so in vendor/<tag>/lib/. Do not ship arbitrary host glibc .sos or rely on LD_LIBRARY_PATH as the primary strategy.
mksquashfs, unsquashfs	build/extract the rootfs image	Ship static squashfs-tools (with lzo support - the stock image uses -comp lzo).
my_write5_dram.bin	the DRAM NAND writer run on-device	Architecture-neutral blob (runs on the device, not the host). Copy as-is.
disc_spl_lpddr3.bin	X2000 SPL	Same - device blob, copy as-is.

Status

• vendor/linux-x86_64/ holds fully static usbboot, mksquashfs, and unsquashfs, produced by build/build-usbboot-static.sh and build/build-squashfs-static.sh (each verifies the binary is statically linked; the squashfs build additionally runs an LZO round-trip self-test). They are static against glibc (built with gcc -static), so no runtime .so is needed; note the static glibc/liblzo2/libusb licensing in ../NOTICE.md and the corresponding source in ../corresponding-source/. my_write5_dram.bin and disc_spl_lpddr3.bin are device blobs, copied as-is.
• vendor/macos-*/ is produced on a Mac by vendor/setup-macos.sh (compiles usbboot from src/usbboot/usbboot.c against Homebrew libusb, gathers lzo-capable squashfs-tools, copies the device blobs, and runs dylibbundler so every tool is self-contained under vendor/macos-<arch>/lib/ - no Homebrew at runtime). usbboot.c is a single libusb-only file (no udev / no Linux-isms), so it builds on macOS as-is. Then build/build-macos.sh packages the app.

macOS: Intel + Apple Silicon coverage

usbboot.c and pyusb are portable; only the build is per-arch. Options:

1. Native per-arch (most robust): run build/build-macos.sh on an Intel Mac and on an Apple Silicon Mac → two binaries. Recommended.
2. Single file via Rosetta: build x86_64 only (on an Intel Mac, or with an x86_64 Homebrew under arch -x86_64). The x86_64 app runs natively on Intel and under Rosetta 2 on M-series (macOS offers to install Rosetta on first run). One file covers both, at a small speed cost - fine for a flasher.
3. Universal2 (advanced): build both arches, lipo the vendor tools into fat binaries, and set target_arch='universal2' in the spec with a universal2 Python. One native file for both, most work.

Building portable usbboot (sketch)

1. Get the Ingenic usbboot source (the X2000 burn tool).
2. Build libusb static: ./configure --disable-udev --enable-static --disable-shared → libusb-1.0.a.
3. Link usbboot against the static libusb; confirm with ldd that libudev/libcap are gone and only libc (or nothing, if fully static) remains.
4. Verify it still enters mask-ROM and flashes on a real unit before shipping.