138 lines
7.4 KiB
Markdown
138 lines
7.4 KiB
Markdown
# 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`. |