8.1 KiB
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
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:
https://wiki.lineageos.org/devices/sunfish/build/.
5. Prepare LineageOS
The last official pin used by AXPR23 is LineageOS 23.2 nightly 20261008:
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:
/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:
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:
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:
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:
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.
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:
adb devices
adb reboot recovery
In recovery select Apply update from ADB, then run:
adb sideload /path/to/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip
After the first boot:
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 |