AGENTS.md — builders_rubenslte

Build drivers + docs for TWRP recovery (recovery.img) and a LineageOS 14.1 ROM for the Samsung Tab Active SM-T365 (rubenslte, Qualcomm MSM8926 / msm8226, Linux kernel 3.4).

Layout

build_twrp.sh       TWRP  -> recovery.img   (omni twrp-5.1)
build_los-14.1.sh   LOS   -> boot.img / lineage_rubenslte-*.zip (cm-14.1, Jack)
common.sh           shared: apply_patches (idempotent patch application)
shell.nix           nix-shell FHS env for both builds (nixpkgs 22.11 pinned)
patches/twrp        post-sync fixes
local_manifests/    los-14.1.xml + twrp.xml
twrp-build/  los-build/  .ccache/  .jack-repository/   (gitignored workspaces)

Repos

Everything rubenslte lives on gitea, fetched anonymously over https: https://git.cfpi-fpsi.eu/rubenslte.

twrp_device_samsung_rubenslte — TWRP device tree, self-contained (own BoardConfig.mk / mkbootimg.mk / dtbtool, no platform imports).
android_kernel_samsung_msm8226-rubenslte — S3NEO msm8226 kernel fork, built from source
android_device_samsung_rubenslte — LOS device tree; inherits the shared msm8226-common / qcom-common platform layers (cm-14.1)
android_vendor_samsung_rubenslte — LOS proprietary blobs.

android_device_samsung_msm8226-common lives on gitea too (cm-14.1) — a mirror of the maintainer fork that produced the matisse family (LineageOS org has no cm-14.1 for it). The two qcom-common platform layers come straight from LineageOS (device/samsung/qcom-common, device/qcom/common, both cm-14.1).

Commands

Both scripts are console-style with getopts; the only flag is -h (usage). Every build runs a full repo sync first, so in-tree edits are always wiped and re-patched — there is no skip-sync mode.

./build_twrp.sh -h            # usage
./build_twrp.sh build         # full build -> recovery.img at repo root
./build_twrp.sh clean         # remove twrp-build/out and recovery.img
./build_twrp.sh prune         # remove all of twrp-build and recovery.img

./build_los-14.1.sh bootimage # build boot.img (kernel + dt.img + ramdisk, fast gate)
./build_los-14.1.sh bacon     # full build -> lineage_rubenslte-*.zip
./build_los-14.1.sh clean     # mka clean
./build_los-14.1.sh prune     # remove all of los-build

Cheap checks without nix: bash -n common.sh build_twrp.sh build_los.sh. Patch check: patch -p1 --dry-run -d <workspace> < patches/<dir>/<file>. Flashing / boot keys: README.md.

How the builds work

Env: everything runs inside the nix-shell FHS env (shell.nix). Run nix-shell first, then invoke the scripts.
TWRP sources: repo init of omni twrp-5.1 (platform_manifest_twrp_omni) + local_manifests/twrp.xml copied into .repo/local_manifests/ before repo sync -c -j$(nproc), then apply_patches patches/twrp.
LOS sources: repo init of cm-14.1 (LineageOS/android) + local_manifests/rubenslte.xml copied in before repo sync -c -j$(nproc).
Patches: common.sh::apply_patches dry-runs each patch with LC_ALL=C first. An already-applied patch makes GNU patch (2.8, from the nix env) report Reversed (or previously applied) patch detected on the forward dry run — that output, not the exit code, is what skips it. Warnings print the patch log but don't abort the build.
Toolchain (TWRP): arm-eabi-4.8 (gcc 4.8, matches stock) is checked out by repo sync — the omni twrp-5.1 manifest already declares prebuilts/gcc/linux-x86/arm/arm-eabi-4.8 at the default revision refs/tags/android-5.1.1_r28 (aosp remote). It lands at prebuilts/gcc/linux-x86/arm/arm-eabi-4.8 and is put on PATH (the sync fetches it). LOS uses the tree's own prebuilts.
Compiler (LOS): Jack only, in-process (JACK_SERVER=false JACK_NO_SERVER=1); the jack/jill jars are seeded into .jack-repository/ from prebuilts/sdk/tools/jacks/ with cp -n.
Kernel: built from source via the omni/lineage kernel build rules.
SEANDROIDENFORCE: build_los.sh appends the trailer to the LOS boot.img (append_seandroidenforce) — required by Samsung bootloaders.

Artifacts: recovery.img (repo root; build_twrp.sh checks it against RECOVERY_BUDGET=10485248 and errors if it exceeds the partition) and los-build/out/target/product/rubenslte/lineage_rubenslte-*.zip.

Invariants — do not "simplify"

BoardConfig.mk: INSTALLED_DTIMAGE_TARGET + BOARD_MKBOOTIMG_ARGS stay recursive (=, expanded after PRODUCT_OUT/KERNEL_OUT exist) — never :=.
mkbootimg.mk: the dt.img rule depends on INSTALLED_KERNEL_TARGET; the ramdisk must stay LZMA + trimmed or the image overflows the partition.
SEANDROIDENFORCE trailer + --dt are required for Samsung bootloaders (append_seandroidenforce appends it to LOS boot.img).
LOS is Jack-only and the ROM is bare (no GApps, /data ext4).

Gotchas

The env deliberately has no 64-bit host gcc: PATH gcc is the genuine 32-bit pkgsi686Linux.gcc9 from multiPkgs, because omni/TWRP host tools are compiled as obj32 (-m32) and only work against a real 32-bit compiler. Adding gcc to targetPkgs regresses the TWRP build with the classic gnu/stubs-32.h: No such file or directory (x86_64 nixpkgs gcc has no 32-bit multilib headers).
repo launcher warning: the nix-provided gitRepo launcher is read-only and warns that it can't auto-update to a newer repo version — harmless.
Don't switch LOS off Jack or re-enable the Jack server (host TLS breaks the server path and aborts the build).
repo sync wipes in-tree edits — expected. Prefer editing the device repos, not patching; patches are only for upstream 5.1/14.1 sources that can't live in the device tree.
Commit style: short lowercase-imperative subject, no body. Stage with git add -A (images and workspaces are gitignored).

Why local_manifests

repo auto-imports every .xml in .repo/local_manifests/ on top of the primary manifest, so both builds get their rubenslte bits without forking the whole manifest. (repo reads the copy the build script drops into twrp-build/ / los-build/.repo/local_manifests/ — edit the source files, every build re-copies them.)

Else

For depth: patches/README.md, twrp_device_samsung_rubenslte/README.md, local_manifests/rubenslte.xml.

6.2 KiB Raw Blame History