# 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

```bash
# 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 -R`s 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`.