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