AGENTS.md — builders_rubenslte

What this repo is: build drivers + documentation for producing TWRP recovery (recovery.img) and a LineageOS 14.1 ROM for the Samsung Galaxy Tab Active SM-T365 (codename rubenslte, Qualcomm MSM8926, Linux kernel 3.4).

Layout / getting your bearings

build_twrp.sh          TWRP driver -> recovery.img (omni twrp-5.1)
build_los.sh           LOS driver -> boot.img / lineage zip (cm-14.1, Jack)
shell.nix              nix-shell FHS env for the TWRP build
shell_los.nix          same package set + host gcc (kernel kconfig `conf`)
lib/common.sh          shared: env re-entry, patch apply, trailer, image check
patches/
  twrp/                omni 5.1 workspace fixes  (applied by build_twrp.sh)
  kernel/              kernel fixes, shared by BOTH builds
  los/                 cm-14.1 workspace fixes   (applied by build_los.sh)
local_manifests/       rubenslte.xml -> device/vendor/kernel/@ gitea
important_files/       webview.apk restore point (do not delete)
twrp-build/  los-build/  .ccache/  .jack-repository/   (gitignored workspaces)

Five cooperating repos each build consumes (device/vendor/kernel from gitea via local_manifests/rubenslte.xml for LOS; device tree + kernel shallow clones for TWRP): twrp_device_samsung_rubenslte, android_kernel_samsung_rubenslte (shared), device_samsung_rubenslte, android_vendor_samsung_rubenslte, plus the shared millet forks those LOS trees pull in (device/samsung/millet-common, kernel/samsung/millet-common etc.).

Commands

# TWRP recovery
./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

# LineageOS 14.1
./build_los.sh                 # boot.img (kernel + dt.img + ramdisk), fast gate
./build_los.sh bacon           # full build -> lineage_rubenslte-*.zip
./build_los.sh clean           # mka clean
./build_los.sh env             # interactive shell inside the build env
# RB_CMD=<cmd> overrides the subcommand (used by relaunch helpers)

Verification without nix (cheap): bash -n lib/common.sh build_twrp.sh build_los.sh. For patch-level verification: patch -p1 --dry-run -d los-build < patches/los/0001-*.patch etc.

How to work here

Builds only run inside the nix-shell FHS environments (shell.nix, shell_los.nix). The scripts re-enter via a stdin pipe (reenter_build_env); 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 (repo sync downloads GBs; kernel + recovery / bacon compile takes a while). Iterate with ./build_twrp.sh --no-sync against the existing twrp-build/ tree; ./build_los.sh bootimage gates the kernel fast.
Prefer editing the device tree repos (BoardConfig.mk / mkbootimg.mk / device tree mk) over patching trees post-sync. Only use patches/ for fixes to upstream 5.1/14.1 sources that cannot live in the device tree. Kernel fixes go in patches/kernel/ (shared by both builds); tree-specific fixes in patches/twrp/ or patches/los/. Add a row to patches/README.md.
repo sync and clone_or_update wipe in-tree edits — patches are re-applied idempotently each full build; on --no-sync iters only the twrp-build/ tree state matters.
LOS builds use Jack only and in-process (JACK_SERVER=false JACK_NO_SERVER=1 with jars seeded into .jack-repository/). Do not try to switch to the javac fallback — it is broken on cm-14.1 (dangling with-local/classes.dex, inspect build/core/java.mk), and do not re-enable the Jack server — the host curl/OpenSSL cannot TLS- handshake with the Java 8 jack server, and the mandatory server ninja edge aborts the whole build.
Console log noise: the old warning: command substitution: ignored null byte should not appear anymore (trailer is appended via a pipeline, see append_seandroidenforce). If it returns, the trailer check was changed.
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/recovery-stock.img and the workspaces are intentionally untracked (gitignored).

Invariants — do not "simplify" these

TWRP:

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 (append_seandroidenforce in lib/common.sh appends it to LOS boot.img).

LOS:

Jack is the only compile path for the dex phases (see above).
Kernel patches are shared: anything touching android_kernel_samsung_* goes in patches/kernel/ and must apply in both twrp-build/ and los-build/ workspaces. Verify with patch -p1 --dry-run in each.
The ROM is bare — no GApps, /data ext4. Don't add GApps packaging.

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_*.
Jack "not readable" jar error — re-seed .jack-repository/ from los-build/prebuilts/sdk/tools/jacks/ (and jills) — see seed_jack_repository.
Bacon JVM SIGSEGV in host/linux-x86/lib64/libconscrypt_openjdk_jni.so (OpenSSLX509Certificate.fromX509PemInputStream) — host OpenSSL ABI mismatch in the FHS env; known non-trivial, unrelated to the scripts here.

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

7.4 KiB Raw Blame History