# AXPR23 — user and build guide ## 1. Introduction AXPR23 is a finished ROM for the **Google Pixel 4a (`sunfish`)**, based on LineageOS 23.2 / Android 16. The goal was to recover AXP.OS behaviour on a maintainable LineageOS base, not to create an unrelated generic ROM. The validated final line integrates, depending on the ship variant: - AXP packaging and Magisk preroot; - release signing and the project AVB posture; - microG and Google-compatibility adaptations; - AOSmium as the primary WebView provider; - attributed privacy, hardening and kernel changes under `vendor/sunfish-a16/`; - project-defined product overlays and bundled applications. AXPR23 is **finished and EOL**. LineageOS no longer provides new 23.2 sunfish nightlies, so this must not be treated as a current-security release. AXPR24 / Android 17 is a separate line. ## 2. What this repository contains The repository contains project source, patches, overlays, build scripts, tests and documentation. It does not contain: - Android or AVB private signing keys; - proprietary Google, microG, Magisk or WebView APKs; - Google/Qualcomm proprietary blobs or firmware; - full Android trees, `.repo`, `out/` or ccache; - generated or signed ROM ZIPs. This is intentional. To build your own image, obtain the required inputs lawfully and sign it with your own keys. Never copy another installation's private keys or publish proprietary APKs in Git. ## 3. Main layout ```text vendor/sunfish-a16/ AXPR23 product files, overlays and patches scripts/009-*.sh build wrappers and postflight checks specs/009-axp-los23-port/ original scope and acceptance requirements docs/ runbooks, evidence and decisions tests/ automated project checks ``` The LineageOS source tree and build artifacts must stay outside this Git checkout, normally on a dedicated Linux build worker. ## 4. Build-host requirements A complete build needs Linux x86_64 with substantial disk, memory and CPU. The validated historical worker used 8 vCPUs, roughly 62 GiB RAM, ccache and a large Android source tree. A laptop is not a suitable place for a full ROM build. Install the official LineageOS Android 16 dependencies plus Git, Git LFS, `repo`, Python 3, OpenJDK 17, `ccache`, and `adb`/`fastboot` if you will test the device. Always consult the official `sunfish` build page: . ## 5. Prepare LineageOS The last official pin used by AXPR23 is LineageOS 23.2 nightly `20261008`: ```bash mkdir -p /srv/rom/src/lineage cd /srv/rom/src/lineage repo init \ -u https://github.com/LineageOS/android.git \ -b lineage-23.2 \ --git-lfs \ --no-clone-bundle repo sync -c -j8 ``` Prepare the `sunfish` proprietary blobs according to LineageOS. Without them, the ROM may partially compile but it will not contain the complete Pixel hardware stack. For an exact historical rebuild, use the official `build-manifest.xml` from the selected nightly and record its SHA-256. Do not call a build reproducible if you only used a floating `lineage-23.2` branch without comparing revisions. ## 6. Prepare AXPR23 inputs The maintainer must provide, outside Git, the APKs/blobs allowed by their licenses, the pinned Magisk/WebView versions and personal Android/AVB signing keys. The historical worker layout is: ```text /srv/rom/src/lineage LineageOS source tree /srv/rom/src/AXP_Resurection this repository /srv/rom/prebuilts/ untracked inputs /srv/rom/secrets/android-certs/ private keys, host-only /srv/rom/ccache/ compiler cache /srv/rom/artifacts/ generated ZIPs and manifests /srv/rom/logs/ build logs ``` Several historical wrappers assume this layout; review them before relocating the tree. ## 7. Run the build First make sure no other build uses the same `out/` directory. Never run two Ninja processes against one output tree: ```bash cd /srv/rom/src/AXP_Resurection git checkout 009-axp-los23-port git status --short export LINEAGE_TREE=/srv/rom/src/lineage export AXP_PROJECT_SOURCE=/srv/rom/src/AXP_Resurection export LOS_SYNC=0 export LOS_DATE=20261008 bash scripts/009-rebuild-from-los.sh ``` The canonical entry point verifies the tree, records the manifest, copies `vendor/sunfish-a16/`, applies the kernel/userspace/product/WebView layers, builds the required `hardened_malloc` components, runs the release bacon and executes the post-build gates. To resync and pin every project, provide an official manifest and opt in: ```bash export LOS_SYNC=1 export LOS_MANIFEST=/path/to/build-manifest.xml export LOS_DATE=20261008 bash scripts/009-rebuild-from-los.sh ``` `LOS_SYNC=1` cleans Android project worktrees before syncing. Do not use it over unsaved local changes. If the manifest is missing, the script must fail; do not replace the pin with a floating branch. ## 8. Run long builds safely Do not leave `mka` attached to a laptop SSH session. Use `tmux`, systemd or the worker's detach wrapper: ```bash tmux new -s axpr23-build cd /srv/rom/src/AXP_Resurection export AXP_PROJECT_SOURCE=/srv/rom/src/AXP_Resurection export LOS_SYNC=0 export LOS_DATE=20261008 bash scripts/009-rebuild-from-los.sh 2>&1 | tee /srv/rom/logs/axpr23-build.log ``` Detach with `Ctrl-b d` and reattach with `tmux attach -t axpr23-build`. The historical worker also used `/srv/rom/artifacts/bin/rom-detach`. ## 9. Verify the output Do not accept a build merely because it exits with code 0: ```bash find /srv/rom/artifacts/009-axp-los23-port -type f -name '*.zip' -print sha256sum /path/to/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip unzip -t /path/to/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip repo -C /srv/rom/src/lineage manifest -r \ -o /srv/rom/artifacts/009-axp-los23-port/manifest-final.xml ``` Check the ZIP name and SHA-256, `FLASH_READY`, release signing rather than test-keys, Magisk preroot, AOSmium WebView, microG/Phonesky, expected apps, SPL and build properties. There must be no patch errors, `.rej` files or silently omitted components. The full gate list is in [`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md). ## 10. Sideload to a test device Only do this on an unlocked Pixel with a backup, and never as the first step on a personal phone: ```bash adb devices adb reboot recovery ``` In recovery select **Apply update from ADB**, then run: ```bash adb sideload /path/to/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip ``` After the first boot: ```bash adb shell getprop ro.product.device adb shell getprop ro.lineage.version adb shell getprop ro.build.type adb shell getprop ro.build.tags adb shell pm list packages | grep -E 'gms|finsky|aosmium|jelly' ``` Complete the boot, radio/Wi-Fi, storage, Magisk, Island/work-profile, WebView and bundled-app smoke tests before accepting the ZIP. ## 11. Rollback and common failures Keep the last known-good ROM, the stock/rescue ZIP, the manifest and SHA-256 of each attempt, plus recovery and fastboot access. If a build does not boot, do not wipe data immediately: capture boot reason, A/B slot, available `logcat`, `dmesg` and verity/AVB state, then return to the known-good ZIP. | Symptom | Usual cause | Action | |---|---|---| | Release keys are missing | Keys are not distributed | Configure host-only keys of your own | | `vendor/sunfish-a16` is missing | `AXP_PROJECT_SOURCE` was not set | Run the wrapper from a valid checkout | | `repo sync` fails | Object-store drift or dirty worktree | Save changes and use `--force-sync` only on Android sources | | APK or JNI inputs are missing | Untracked prebuilts were not prepared | Check the worker inventory and reject corrupt files | | `.rej` files or missing markers | A patch no longer matches | Stop and port the patch explicitly | | ZIP uses test-keys | Release identity is absent | Do not flash it as a release; fix signing and rebuild | ## 12. References - [LineageOS — build sunfish](https://wiki.lineageos.org/devices/sunfish/build/) - [`docs/009-eol-20261026.md`](docs/009-eol-20261026.md) - [`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md) - [`scripts/009-rebuild-from-los.sh`](scripts/009-rebuild-from-los.sh) - [`specs/009-axp-los23-port/spec.md`](specs/009-axp-los23-port/spec.md)