Android aplicaciones con seed

Esta guía describe cómo utilizar la versión actual. Android seed plataforma y marco. El soporte implementado combina una seed biblioteca (mobile), un Android anfitrión basado en Gradle/Kotlin/CMake y un puente JNI que carga el nativo seed biblioteca.

Estado actual: Android es la plataforma móvil activa. El marco proporciona una Superficie del lienzo retenida impulsada por comandos de marco, entrada básica, ciclo de vida, inserciones, métricas de pantalla y múltiples ABI embalaje. Aún no es completo kit de herramientas de widgets.

¿Qué es compatible?

Lo siguiente no son afirmaciones de soporte actual: un catálogo completo de widgets, TalkBack para dispositivos físicos, completo IME selection/composition, configuración de texto, recarga en caliente, una amplia matriz de dispositivos, publicación en tienda o preparación para producción.

Arquitectura

seed app (.sd)
    │  integrated build: .so + .a per ABI
    ▼
libseed_app.so ─► JNI bridge (preferred packaged dependency)
libseed_app.a  ─► separate static artifact
    │  C ABI
    ▼
JNI bridge + SeedSurfaceView
    │
    ▼
Activity Android / Canvas / adb / Gradle

el seed la aplicación aún no reemplaza Activity. el Android El host sigue siendo responsable del proceso, la ventana, Canvas, JNI y la integración con el SDK. el mobile La biblioteca proporciona las importaciones portátiles del segmento implementado y solo debe usarse con un Android objetivo.

Requisitos

Debes tener:

El instalador oficial del proyecto utiliza $HOME/Android/Sdk, no requiere sudoe instala la línea base completa:

./seed mobile android setup
./seed mobile android doctor

Opciones útiles:

./seed mobile android setup --sdk "$HOME/Android/Sdk" --start
./seed mobile android setup --skip-avd
./seed mobile android setup --dry-run

uso --api, --abi, --image-flavor, --ndk, --avd, y --device para personalizar la instalación. --skip-gradle deja la instalación de Gradle en manos del usuario. Para utilizar un NDK distinto de la línea base, declara explícitamente SEED_ANDROID_NDK_REVISION y confirmar la compatibilidad con el proyecto.

Los diagnósticos deben mostrar Android 37.0, build-tools 37.0.0, Gradle 9.5.0, platform-tools, NDK y las raíces del sistema API 21 de aarch64-linux-android y x86_64-linux-android:

./seed mobile android doctor

Tutorial 1: primera aplicación

Crear app.sd:

fn main() -> i64 {
    0
}

pub fn seed_mobile_entry() -> i64 {
    0
}

Cree un host copiando la plantilla versionada:

cp -R seed/compiler/llvm/mobile/android my-android

Compile ambas ABI, prepare y genere el APK:

./seed mobile android build app.sd my-android \
  --package-name seed_app \
  --application-id com.example.seedapp \
  --package

El comando genera libseed_app.so y libseed_app.a para arm64-v8a y x86_64, copia los artefactos en my-android/app/src/main/jniLibs/, vincula el objeto compartido seed como una dependencia de puente JNI empaquetada y ejecuta assembleDebug; el archivo permanece disponible por separado para los consumidores nativos. El archivo my-android/seed-android.properties registra el nombre nativo y el ID de la aplicación utilizados por los comandos posteriores.

Tutorial 2: dibuja una pantalla

Importe la biblioteca mobile Android al código de su aplicación. Un ejemplo completo está en compiler/llvm/tests/mobile/android_framework.sd. La devolución de llamada del marco recibe el ancho, alto y tiempo en nanosegundos:

use "mobile"

pub fn seed_mobile_entry() -> i64 { 0 }

pub fn seed_mobile_on_frame(width: i32, height: i32, time_nanos: i64) {
    mobile.frame_clear()
    mobile.frame_color(4278190335 as i64) // ARGB: opaque blue
    mobile.frame_rect(1000, 1000, 2000, 2000, 4294902015 as i64)
    mobile.frame_text("Hello, Android", 1500, 4500, 2400, 4294967295 as i64)
}

Las coordenadas y el tamaño de fuente se expresan en milipíxeles. Los colores son números enteros ARGB. El anfitrión limita cada cuadro a 256 rectángulos, 32 elementos de texto, 128 nodos semánticos y 256 UTF-8 bytes por etiqueta o elemento. El texto es dibujado por el Android lienzo; La selección de fuentes y la configuración avanzada aún no forman parte del contrato.

Tutorial 3: Consumir Touch, Teclado y IME

La biblioteca mantiene una cola delimitada de 128 eventos. Lea los campos antes de eliminar un evento:

use "mobile"

fn read_input() {
    while mobile.input_available() {
        let kind = mobile.input_kind()
        let a = mobile.input_a()
        let b = mobile.input_b()
        let c = mobile.input_c()

        // kind 1: touch; a=action, b=x in millipixels, c=y in millipixels.
        // kind 2: key; a=action, b=Android key code, c=Unicode code point.
        // kind 3: text committed by the IME.
        if kind == 3 {
            let length = mobile.input_text_length()
            // input_text_byte(index) exposes the committed text's UTF-8 bytes.
            let _ = length
        }
        mobile.input_pop()
    }
}

input_pop debe llamarse una vez por evento. Si los productores exceden la capacidad, la cola conserva los eventos más recientes. La región de selección y composición aún no está expuesta.

Tutorial 4: Ciclo de vida y recursos

Defina sólo los ganchos necesarios. Se ejecutan en el subproceso Activity y no deben bloquear, retener objetos JNI ni crear tareas sin un grupo estructurado:

pub fn seed_mobile_on_create() {}
pub fn seed_mobile_on_start() {}
pub fn seed_mobile_on_resume() {}
pub fn seed_mobile_on_pause() {}
pub fn seed_mobile_on_stop() {}
pub fn seed_mobile_on_destroy() {}

seed_mobile_entry está protegido contra ejecuciones repetidas en el mismo proceso; La recreación de Activity no reinicia la aplicación. La destrucción cancela trabajos pendientes en el puente; La muerte del proceso es el límite final de la limpieza.

Las aplicaciones con capacidades persistentes entre marcos pueden exportar seed_mobile_context_create, seed_mobile_context_on_event, seed_mobile_context_on_frame, y seed_mobile_context_destroy. El anfitrión mantiene como máximo un contexto por generación de Activity, deja de reenviar devoluciones de llamada cuando esta generación se invalida y destruye el contexto exactamente una vez. Los ganchos heredados siguen siendo la alternativa.

Utilice mobile.window_focused() para pausar el trabajo visual durante la pérdida de enfoque y mobile.memory_pressure() para vaciar los cachés después de onTrimMemory. No trate estas señales como una garantía de que el proceso permanecerá vivo.

Tutorial 5: distribución, zona segura y almacenamiento

Los recuadros son píxeles físicos: 0=left, 1=top, 2=right, 3=bottom.

use "mobile"

fn content_top() -> i64 {
    mobile.window_inset(1)
}

fn text_size() -> i64 {
    // scaled_density_milli is the font density multiplied by 1000.
    16000 * mobile.scaled_density_milli() / 1000
}

mobile.density_dpi() y mobile.scaled_density_milli() le permite adaptar el diseño y la tipografía. mobile.app_files_* y mobile.app_cache_* devolver vistas delimitadas de los caminos privados proporcionados por Activity; Úselos para almacenamiento interno y almacenamiento en caché. No hay acceso automático al almacenamiento externo. El permiso de red declarado por la plantilla cubre el actual net segmento, pero los permisos adicionales siguen siendo responsabilidad del anfitrión.

Construir flujos

Construcción manual

seed --emit-shared libseed_app.so \
  --target android-arm64 --runtime-profile android \
  --sysroot "$ANDROID_NDK_SYSROOT" --soname libseed_app.so app.sd

seed --emit-shared libseed_app.so \
  --target android-x86_64 --runtime-profile android \
  --sysroot "$ANDROID_NDK_SYSROOT" --soname libseed_app.so app.sd

./seed mobile android stage my-android arm64.so x86_64.so \
  seed_app com.example.seedapp
./seed mobile android package my-android

Construcción integrada

./seed mobile android build app.sd my-android \
  --ndk "$ANDROID_NDK_HOME" \
  --package-name seed_app \
  --application-id com.example.seedapp

build busca el NDK en ANDROID_NDK_HOME cuando no se proporciona --ndk y genera pares shared/static para las dos ABI; el anfitrión prefiere el objeto compartido empaquetado y mantiene el archivo como un artefacto separado. stage continúa aceptando bibliotecas compartidas ELF, valida artefactos y rechaza ID de aplicaciones no válidas. El nombre del paquete nativo no puede contener / o ...

Si el paquete de semillas que contiene app.sd tiene un assets/ carpeta, la compilación integrada también copia sus archivos planos normales en la Android anfitrión. Los nombres están limitados a letras y dígitos ASCII, ., _, y -; Se rechazan las subcarpetas, los archivos ocultos y las colisiones con la sonda del host. Al inicio, el host lee el generado seed-mobile-assets.list indexa y extrae exactamente esos archivos (como máximo 256 archivos y 64 MiB) a la raíz privada de solo lectura ya expuesta a Seed. Activos de marco o superposición también enumerados por AssetManager no ingrese al paquete Seed. Por lo tanto, el mismo manifiesto y los mismos recursos de imagen, fuente, WAV y Ogg pueden seguir al escritorio y al Android sin lógica de copia específica de la aplicación.

Las dependencias directas en audio-vorbis y grove-game-assets hacen que la compilación integrada incluya los backends stb correspondientes en ambas ABI. El puente JNI proporciona el contrato de audio compartido sobre OpenSL ES, con transmisiones limitadas, identificadores con etiquetas de generación, una cola PCM estéreo de 48 kHz, consultas de bytes pendientes, pause/resume, limpieza y cierre exactamente una vez.

Depuración, lanzamiento y ejecución.

./seed mobile android package my-android
./seed mobile android package my-android --release
./seed mobile android run my-android
./seed mobile android run my-android --release
./seed mobile android run my-android --serial emulator-5554
./seed mobile android doctor --serial ZF524P7D2T

run empaqueta, instala, fuerza la detención de la instancia anterior y ejecuta .MainActivity a través de adb, lo que requiere Status: ok. ANDROID_SERIAL también puede seleccionar el dispositivo.

Para iniciar el AVD instalado mediante la configuración:

emulator -avd seed-api37 -no-snapshot
adb wait-for-device
./seed mobile android run my-android

El nombre real del AVD se puede consultar con avdmanager list avd.

matriz AVD

La matriz implementada mantiene la system-images instalado y crea un estado AVD efímero por ejecución. Cada línea usa temporal ANDROID_AVD_HOME, inicialización sin instantáneas y datos limpios; Después de la prueba, cierre y elimine solo el AVD. Las imágenes del SDK, el NDK, Gradle y las cachés de compilación permanecen instaladas. La preparación nativa y Gradle se ejecutan en una copia temporal del host; la matriz no se reescribe seed-android.properties, jniLibs o resultados en el proyecto original.

Fast Smoke declara AVD del teléfono ARM64 en las API 21, 29 y 37. El conjunto de versiones utiliza estable API 37 con páginas de tableta de 16 KB, perfil plegable, memoria limitada y ocho ciclos de vida. No hay nivel nocturno ni requisito de ejecución x86_64; android-x86_64 permanece cubierto por compile/link contratos únicamente.

El corredor crea el APK una vez y lo reutiliza. Cada línea valida el arranque, doctor --serial, install/cold lanzamiento, accesibilidad, básico touch/key/IME, insets/density/focus, lifecycle/rotation, Logcat y apagado. La suite de lanzamiento repite el ciclo de vida según la línea e inyecta RUNNING_CRITICAL en el escenario de memoria limitada. Los fallos preservan la configuración, Logcat, dumpsys, gfxinfo, meminfo, árbol de accesibilidad y captura de pantalla en compiler/llvm/build/android-avd-matrix/.

make -C seed/compiler/llvm android-avd-matrix-check
make -C seed/compiler/llvm android-avd-smoke
make -C seed/compiler/llvm android-avd-release
make -C seed/compiler/llvm game-seed-garden-android-avd-check
SEED_ANDROID_AVD_API=37.0 \
  SEED_ANDROID_AVD_RUNNER_POLICY=required \
  make -C seed/compiler/llvm android-avd-smoke

La política auto (predeterminada) registra SKIP en busca de herramientas o imágenes faltantes; required falla; off deshabilita la ejecución. --install-images, en llamada directa a scripts/android_avd_matrix.sh, instala imágenes seleccionadas. SEED_ANDROID_ADB_TIMEOUT y SEED_ANDROID_AVD_BOOT_TIMEOUT limitan las llamadas de arranque y adb; SEED_ANDROID_AVD_VERBOSE=true conserva la salida detallada del emulador. Los tres escenarios de lanzamiento de humos y cuatro ARM64 pasan por el Apple M4.

El contrato Garden utiliza la misma infraestructura efímera. Valida las 64 celdas semánticas en retrato y paisaje durante ocho rotaciones, movimiento con animación reducida, pause/resume, eliminación de sesiones de audio durante el desmontaje, inicio, frames/jank y retención de PSS. Estas mediciones son la línea de base AVD; no reemplazan Android LeakSanitizer o mediciones de rendimiento, térmicas y de latencia en un dispositivo físico.

Esta matriz sólo amplía la evidencia en el emulador. Motorola registrado en ANDROID_TARGET_BASELINE.md sigue siendo todo reclamo físico. La política completa y el orden de implementación se encuentran en roadmap-mobile.md.

Pruebas y validación

Valide contratos sin SDK completo con:

make -C seed/compiler/llvm android-target-test
make -C seed/compiler/llvm android-host-check
make -C seed/compiler/llvm android-package-check
make -C seed/compiler/llvm android-build-check
make -C seed/compiler/llvm android-run-check
make -C seed/compiler/llvm android-doctor-check

Para una validación real, ejecute doctor, ejecute build, instálelo en AVD o dispositivo y ejecute run. La base de evidencia se encuentra en ANDROID_TARGET_BASELINE.md. doctor --serial <adb-serial> también valida el modelo, API, ABI, el parche de seguridad y el estado de autorización del dispositivo seleccionado.

Diagnóstico de problemas

Límites y próximos pasos

El puente actual es una base operativa, no una promesa de compatibilidad con todo el Android SDK. En la hoja de ruta permanecen un catálogo de widgets, un diseño conservado, navegación, un editor de texto completo, TalkBack para dispositivos físicos, complementos estables, un inspector, un generador de perfiles, recarga en caliente, una amplia matriz de dispositivos, publicación en tienda y firma de producción. iOS está activo en el simulador a través del compilador, el tiempo de ejecución, el host Swift y XCFramework; La ejecución, el aprovisionamiento, la firma y la publicación en la tienda del dispositivo físico permanecen abiertos.

Referencias