docs: add bilingual AXPR23 build guides
This commit is contained in:
sunfish-admin committed
1 parent
2c714d8d34
commit
0681842adc
3 files changed
+507
-21
No files matched your search
+225
@@ -0,0 +1,225 @@
|
||||
# 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)
|
||||
Reference in new issue
Block a user