226 lines
8.1 KiB
Markdown
226 lines
8.1 KiB
Markdown
# 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:
|
|
<https://wiki.lineageos.org/devices/sunfish/build/>.
|
|
|
|
## 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)
|