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 — 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)
|
||||
Reference in new issue
Block a user