From 0681842adc154bf4cbe1c2a34811bfd4aeccbfb6 Mon Sep 17 00:00:00 2001 From: sunfish-admin Date: Fri, 6 Nov 2026 21:29:16 +0100 Subject: [PATCH] docs: add bilingual AXPR23 build guides --- README.en.md | 225 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.es.md | 225 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 78 +++++++++++++----- 3 files changed, 507 insertions(+), 21 deletions(-) create mode 100644 README.en.md create mode 100644 README.es.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..6e336dc --- /dev/null +++ b/README.en.md @@ -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: +. + +## 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) diff --git a/README.es.md b/README.es.md new file mode 100644 index 0000000..9ed5c2e --- /dev/null +++ b/README.es.md @@ -0,0 +1,225 @@ +# AXPR23 — guía de usuario y compilación + +## 1. Introducción + +AXPR23 es una ROM terminada para el **Google Pixel 4a (`sunfish`)**, basada en +LineageOS 23.2 / Android 16. El objetivo fue recuperar el comportamiento de +AXP.OS sobre una base LineageOS mantenible, no crear una ROM genérica desde +cero. + +La línea final validada integra, según la variante de publicación: + +- empaquetado AXP y preroot Magisk; +- firma de release y configuración AVB del proyecto; +- adaptaciones de compatibilidad de microG y Google; +- AOSmium como proveedor principal de WebView; +- cambios de privacidad, hardening y kernel en `vendor/sunfish-a16/`; +- overlays de producto y aplicaciones incluidas por el proyecto. + +AXPR23 está **finalizado y en EOL**. LineageOS ya no mantiene una rama 23.2 +nueva para `sunfish`, por lo que no debe considerarse una ROM con parches de +seguridad actuales. AXPR24 / Android 17 es una línea separada. + +## 2. Qué contiene este repositorio + +Sí contiene código, parches, overlays, scripts, tests y documentación del +proyecto. No contiene: + +- claves privadas de firma o AVB; +- APK propietarios de Google, microG, Magisk o WebView; +- blobs propietarios de Google/Qualcomm ni firmware; +- árboles completos de Android, `.repo`, `out/` o ccache; +- ZIPs de ROM generados. + +Esto es intencionado. Para generar una imagen propia hay que conseguir los +insumos de forma legal y firmarla con claves propias. No se deben copiar claves +de otra instalación ni publicar APK propietarios en Git. + +## 3. Estructura principal + +```text +vendor/sunfish-a16/ overlays, product files y parches AXPR23 +scripts/009-*.sh wrappers de build y postflight +specs/009-axp-los23-port/ alcance funcional y aceptación +docs/ runbooks, evidencias y decisiones +tests/ comprobaciones automáticas del proyecto +``` + +El árbol LineageOS y sus artefactos deben vivir fuera del checkout, en un +worker Linux dedicado. + +## 4. Requisitos del build host + +La compilación completa necesita Linux x86_64, mucho espacio libre, memoria y +CPU. La configuración histórica validada usaba 8 vCPU, unos 62 GiB de RAM, +ccache y un árbol Android grande. Un portátil no es un buen lugar para el build +completo. + +Instala las dependencias oficiales de LineageOS para Android 16 y Git, Git LFS, +`repo`, Python 3, OpenJDK 17, `ccache` y las herramientas `adb`/`fastboot` si +vas a probar el dispositivo. Consulta siempre la guía oficial de `sunfish`: +. + +## 5. Preparar LineageOS + +El último pin oficial usado por AXPR23 corresponde al nightly `20261008` de +LineageOS 23.2: + +```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 +``` + +Prepara después los blobs propietarios de `sunfish` siguiendo LineageOS. Sin +ellos la ROM puede compilar parcialmente, pero no tendrá el stack completo de +hardware del Pixel. + +Para una reconstrucción histórica exacta, usa el `build-manifest.xml` oficial +del nightly elegido y conserva su SHA-256. No llames reproducible a un build +basado solo en una rama flotante sin comparar revisiones. + +## 6. Preparar los insumos AXPR23 + +El maintainer debe proporcionar fuera de Git los APK/blobs permitidos por sus +licencias, las versiones fijadas de Magisk/WebView y sus propias claves de +firma Android y AVB. El layout histórico del worker es: + +```text +/srv/rom/src/lineage árbol LineageOS +/srv/rom/src/AXP_Resurection este repositorio +/srv/rom/prebuilts/ insumos no versionados +/srv/rom/secrets/android-certs/ claves privadas, solo host +/srv/rom/ccache/ ccache +/srv/rom/artifacts/ ZIPs y manifiestos generados +/srv/rom/logs/ logs de build +``` + +Varios wrappers históricos asumen este layout; revísalos antes de moverlo. + +## 7. Ejecutar el build + +Comprueba primero que no haya otro build usando el mismo `out/`. Desde el +checkout del proyecto: + +```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 +``` + +La entrada canónica comprueba el árbol, captura el manifiesto, copia +`vendor/sunfish-a16/`, aplica kernel/userspace/product/WebView, compila los +componentes necesarios de `hardened_malloc`, ejecuta el bacon de release y +corre los gates post-build. + +Para sincronizar y pinnear todos los proyectos se necesita un manifest oficial: + +```bash +export LOS_SYNC=1 +export LOS_MANIFEST=/ruta/al/build-manifest.xml +export LOS_DATE=20261008 +bash scripts/009-rebuild-from-los.sh +``` + +`LOS_SYNC=1` limpia los worktrees Android antes de sincronizar. No lo uses sobre +cambios locales sin guardar. Si falta el manifiesto, el script debe fallar; no +lo sustituyas por una rama flotante. + +## 8. Builds largos + +No dejes un `mka` unido a una sesión SSH del portátil. Usa `tmux`, systemd o el +wrapper de detach del worker: + +```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 +``` + +Desconecta con `Ctrl-b d` y vuelve a entrar con `tmux attach -t axpr23-build`. +El worker histórico también usaba `/srv/rom/artifacts/bin/rom-detach`. + +## 9. Verificar el resultado + +No aceptes un build solo porque termine con código 0: + +```bash +find /srv/rom/artifacts/009-axp-los23-port -type f -name '*.zip' -print +sha256sum /ruta/al/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip +unzip -t /ruta/al/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 +``` + +Revisa nombre y SHA-256, `FLASH_READY`, firma de release, Magisk preroot, +AOSmium WebView, microG/Phonesky, aplicaciones esperadas, SPL y propiedades de +build. Debe haber cero errores de patch, `.rej` o componentes omitidos. La +lista completa está en [`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md). + +## 10. Sideload de prueba + +Hazlo solo en un Pixel desbloqueado, con copia de seguridad y nunca como primer +paso en un teléfono personal: + +```bash +adb devices +adb reboot recovery +``` + +En recovery selecciona **Apply update from ADB** y ejecuta: + +```bash +adb sideload /ruta/al/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip +``` + +Tras arrancar: + +```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' +``` + +Completa el smoke test de boot, radio/Wi-Fi, almacenamiento, Magisk, +Island/perfil de trabajo, WebView y aplicaciones antes de aceptar el ZIP. + +## 11. Rollback y fallos frecuentes + +Conserva la última ROM que arrancaba, el ZIP stock/rescue, el manifiesto y el +SHA-256 de cada intento, además del acceso a recovery y fastboot. Si no arranca, +no borres datos inmediatamente: captura boot reason, slot A/B, `logcat`, +`dmesg` disponible y estado de verity/AVB; después vuelve al ZIP conocido como +bueno. + +| Síntoma | Causa habitual | Acción | +|---|---|---| +| Faltan claves de release | No se distribuyen con el proyecto | Configura claves propias solo en el host | +| Falta `vendor/sunfish-a16` | No se definió `AXP_PROJECT_SOURCE` | Ejecuta el wrapper desde un checkout válido | +| Falla `repo sync` | Drift u worktree sucio | Guarda cambios y usa `--force-sync` solo en el árbol Android | +| Faltan APK o JNI | Prebuilts no preparados | Revisa el inventario del worker y rechaza archivos corruptos | +| `.rej` o marcador ausente | El parche no coincide | Detén el build y adapta el parche explícitamente | +| ZIP con test-keys | Identidad de release ausente | No lo flashees como release; corrige y repite | + +## 12. Referencias + +- [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) diff --git a/README.md b/README.md index 108becb..3759f09 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,65 @@ -# AXP_Resurection +# AXP Resurrection — AXPR23 -Personal **AXP.OS resurrection** on LineageOS 23.2 / Android 16 for Google -Pixel 4a (`sunfish`): Magisk like GOLDEN, full AXP capability set, Spec Kit -feature `009-axp-los23-port`. +**AXPR23** is a finished Android 16 ROM project for the Google Pixel 4a +(`sunfish`). It recreates the AXP.OS user experience on top of LineageOS 23.2, +while preserving the parts that matter on real hardware: Magisk preroot, +release signing, AXP-style packaging, hardened userspace/kernel changes, +microG/Google compatibility, AOSmium WebView and the bundled application +surface. -This tree is a **parallel product track** to `sunfish-a16-rom` (KernelSU / -split-roadmap standby). Same Spec Kit / docs home pattern; **not** a -SSYSTEMS / buildout-saar project. +This is an **archive and reference implementation**. AXPR23 is EOL: LineageOS +23.2 no longer receives new sunfish nightlies. New Android work belongs to the +separate AXPR24 / Android 17 line and must not be mixed into this branch. -## Project locations +## Read this first -- Public canonical repository: `https://gitea.vbits.me/sunfish-admin/AXP-Resurection` -- Builds stay on the A16 `rom-dev01` worker; local checkouts are used for - development and device tooling. -- The sibling KernelSU/split-roadmap tree remains a separate track. +| Language | Guide | +|---|---| +| Español | [`README.es.md`](README.es.md) | +| English | [`README.en.md`](README.en.md) | -## Active feature +The language guides explain what the project is, what is and is not included, +how to prepare a build host, how to run the reproducible build wrapper, how to +verify the resulting ZIP and how to sideload or recover safely. -- Spec: `specs/009-axp-los23-port/spec.md` -- Plan: `specs/009-axp-los23-port/plan.md` +## Repository and architecture -## Quick links +- Canonical public repository: +- Final branch: `009-axp-los23-port` +- Target device: Pixel 4a / `sunfish` +- Base: LineageOS 23.2 / Android 16 +- Build worker: a dedicated Linux host; do not build the full ROM on a laptop +- Android source tree and build output: kept outside this Git repository +- The sibling KernelSU/split-roadmap tree is a separate project -- Constitution: `.specify/memory/constitution.md` -- Agent rules: `AGENTS.md` -- Specs: `specs/README.md` -- Device roles (GOLDEN vs LAB): `docs/device-roles.md` -- AXP Pro parity matrix (non-normative): `docs/axp-pro-parity.md` +## Important limitations + +The public repository contains source, patches, scripts and documentation. It +does **not** contain release keys, proprietary APKs, Google/Qualcomm blobs, +build output, `out/`, ccache, device dumps or signed ROM ZIPs. A clean clone is +therefore not, by itself, sufficient to reproduce the shipped binary: the +builder must supply those inputs legally and use its own signing keys. + +AXPR23 is not a current-security release. Use it for preservation, study and +the already validated reference device; use the AXPR24 project for new Android +17 work. + +## Key documentation + +- [`docs/009-eol-20261026.md`](docs/009-eol-20261026.md) — final artifact and + verified state +- [`docs/003-build-notes.md`](docs/003-build-notes.md) — vanilla Lineage build + background +- [`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md) — + maintainer preflight and postflight gates +- [`scripts/009-rebuild-from-los.sh`](scripts/009-rebuild-from-los.sh) — + canonical AXPR23 rebuild entry point +- [`specs/009-axp-los23-port/spec.md`](specs/009-axp-los23-port/spec.md) — + functional scope and acceptance requirements + +## License and upstream work + +This repository is a project layer over LineageOS/AOSP and other upstream +components. Each upstream component retains its own license. Do not assume +that the project repository grants redistribution rights for proprietary blobs, +Google applications, firmware or signing material.