builders_rubenslte/AGENTS.md

AGENTS.md — builders_rubenslte

What this repo is: the build driver + documentation for producing a TWRP recovery (recovery.img) for the Samsung Galaxy Tab Active SM-T365 (codename rubenslte, Qualcomm MSM8926, Android 5.1.1 / omni twrp-5.1).

Three repos cooperate:

Repo	Role
builders_rubenslte (this)	build_twrp.sh (driver), shell.nix (env), patches/, docs
rubenslte/twrp_device_samsung_rubenslte	device tree (BoardConfig.mk, mkbootimg.mk, dtbtool)
rubenslte/android_kernel_samsung_rubenslte	Samsung msm8226 stock kernel, built from source

This drive builds from source: kernel, dt.img and ramdisk are all produced, never prebuilt. The artifact is recovery.img (currently 10,479,632 bytes with the full 19-language pack set, TWRP 3.7.0_9-0) and has passed on-device tests on real hardware.

Commands

./build_twrp.sh                # full build -> recovery.img at repo root
./build_twrp.sh --no-sync      # iteration: skip repo sync / tree refresh / patches
./build_twrp.sh clean          # remove twrp-build/ and recovery.img
./build_twrp.sh env            # interactive shell inside the nix-shell FHS env

Verification without nix (cheap): bash -n build_twrp.sh.

How to work here

• The build only runs inside the nix-shell FHS environment (shell.nix). build_twrp.sh re-enters it via a stdin pipe; do not rely on nix-shell --run (the exec android-env shellHook swallows it) and do not run two nix-shells at once (nix store lock deadlock).
• A full build is slow (first run downloads ~2-3 GB via repo sync; kernel + recovery compile takes a while). For source edits, iterate with ./build_twrp.sh --no-sync against the existing twrp-build/ tree.
• Prefer editing the device tree repo (BoardConfig.mk / mkbootimg.mk) over patching the omni tree post-sync. Only use patches/ for fixes to the upstream 5.1 sources that cannot live in the device tree.
• Commit style in this repo: short lowercase-imperative subject, no body (Refactor build_twrp.sh and document the recovery build). Stage with git add -A; recovery.img and recovery-stock.img are intentionally untracked (gitignored).

Invariants — do not "simplify" these

• BoardConfig.mk: INSTALLED_DTIMAGE_TARGET and BOARD_MKBOOTIMG_ARGS must stay recursive (=, never :=). They are expanded after PRODUCT_OUT/KERNEL_OUT exist; see the mkbootimg.mk header comment for the include-order reasoning.
• mkbootimg.mk: the dt.img rule depends on INSTALLED_KERNEL_TARGET (not TARGET_PREBUILT_INT_KERNEL), and the recovery-ramdisk override (drop tzdata + f2fs tools, LZMA compression) is what keeps the image under the 10,485,248-byte partition. All 19 common TWRP language packs are shipped as-is (10,479,632 packed). Changing compression or adding twres//system/ files can overflow it — always re-check image size.
• F2FS is off. The kernel has no F2FS driver. Never re-add TARGET_USERIMAGES_USE_F2FS. mkbootimg.mk also deletes the f2fs tools from the ramdisk (the format menu hides the option automatically when /sbin/mkfs.f2fs is absent — see gui/action.cpp:944 in the omni tree).
• dt.img is EUR-only (CONFIG_MACH_RUBENSLTE_OPEN). Other hardware variants (T365Y/AUS, T365M/KOR) need their CONFIG_MACH_RUBENSLTE_* enabled + rebuild.
• SEANDROIDENFORCE trailer and --dt are required on boot/recovery images for Samsung bootloaders; the stock core rules don't add them.

Troubleshooting the image

• adb shell fails with CANNOT LINK EXECUTABLE DEPENDENCIES: library "libc.so" not found — normal: /system is not mounted in recovery; the ramdisk has no Android root. Mount System in TWRP, or use the in-TWRP terminal.
• make: ... [/dt.img] Błąd 255 — the lazy-variable/INSTALLED_KERNEL_TARGET dependency is broken; restore it per the invariants above.
• f2fs tools reappear in the ramdisk — stale copies under out/target/product/rubenslte/root/sbin/ from a past f2fs-enabled build; the core recovery rule cp -Rs that directory without wiping. Delete the binaries (and recovery/root.ts); mkbootimg.mk strips them anyway.
• Multi-variant boot failures — dt.img lacks the device's DTB; rebuild with the right CONFIG_MACH_RUBENSLTE_*.

For the full background: README.md (this repo), patches/README.md, and twrp_device_samsung_rubenslte/README.md.