Android Guía de la Plataforma

El backend de Android incorpora un pipeline completo que convierte un proyecto del IDE en un APK firmado y en ejecución sobre un emulador o dispositivo real, con controles nativos android.widget.*. El mismo código Harbour que alimenta Windows, macOS y Linux ahora también apunta a Android — sin WebView, sin UI pintada, sin dependencias de ejecución.

Visión arquitectónica

Android es el 4º backend GUI nativo de HarbourBuilder. El mismo classes.prg que usa cada plataforma despacha a android_core.c en lugar del bridge Win32/Cocoa/GTK3, y las llamadas JNI se convierten en widgets Android reales dentro de un FrameLayout de MainActivity.

Cada backend de HarbourBuilder implementa la misma familia de HB_FUNCs UI_*; el de Android vive en source/backends/android/android_core.c y refleja, HB_FUNC a HB_FUNC, el puente Win32 (source/cpp/hbbridge.cpp) y el puente Cocoa (source/backends/cocoa/cocoa_core.m).

Pipeline de compilación

El menú Run → Run on Android… dispara un pipeline de 8 etapas que produce un APK firmado listo para instalar. El mismo pipeline está disponible como script independiente en source/backends/android/build-apk-gui.sh.

1. harbour.exe — el compilador Harbour anfitrión traduce .prg a C portable.
2. clang (NDK) — compila cruzado a objetos aarch64-linux-android24.
3. clang --shared — enlaza libapp.so con todas las librerías estáticas de harbour/core (hbvm, hbrtl, hblang, hbcpage, hbrdd, hbmacro, hbpp, hbcommon, hbpcre, hbzlib, hbnulrdd, hbdebug, hbcplr, rddntx/cdx/fpt/nsx, gtstd/trm/cgi/pca, hbsix, hbhsx).
4. aapt2 compile — compila los recursos Android (res/).
5. aapt2 link — enlaza recursos + manifest en base.apk; genera R.java.
6. javac — compila MainActivity.java contra el SDK de Android.
7. d8 — transforma los .class en classes.dex.
8. zipalign + apksigner — alinea y firma v2 el APK con un keystore de depuración.

API UI_* en Android

Superficie invocable desde Harbour expuesta por el backend Android. Todas las coordenadas son en píxeles del diseñador, idénticas a Win32/Cocoa/GTK3 — ver manejo de densidad.

Puente JNI

Cada HB_FUNC UI_* obtiene el JNIEnv del hilo que llama e invoca un method id cacheado sobre la referencia global a MainActivity. En Java la creación real del widget se ejecuta en el hilo de UI con runOnUiThread. Los clicks viajan en sentido inverso: Button.setOnClickListener → nativeOnClick(controlId) → hb_evalBlock0.

// android_core.c — despacho de UI_ButtonNew
HB_FUNC( UI_BUTTONNEW )
{
    int id = create_widget( m_createButton,
                             HB_ISCHAR(2) ? hb_parc(2) : "",
                             hb_parni(3), hb_parni(4),
                             hb_parni(5), hb_parni(6) );
    hb_retni( id );
}

// Java llamado desde el código nativo:
public void createButton( final int id, final String text,
                          final int x, final int y, final int w, final int h ) {
    runOnUiThread( new Runnable() { public void run() {
        Button b = new Button( MainActivity.this );
        b.setText( text );
        b.setOnClickListener( v -> nativeOnClick( id ) );
        root.addView( b, lp( x, y, w, h ) );
        ctrls.put( id, b );
    }});
}

Los handles de control son enteros pequeños (1..255) devueltos por cada UI_*New. En Java un HashMap<Integer, View> los indexa; en C un PHB_ITEM g_click_handlers[256] paralelo guarda los codeblocks registrados con UI_OnClick.

Coordenadas conscientes de la densidad

Las coordenadas del diseñador son 1:1 con píxeles de Windows Desktop. En Android esos mismos valores se multiplican por DisplayMetrics.density, de modo que un botón de 100 px se ve consistente en pantallas mdpi (×1.0), hdpi (×1.5), xhdpi (×2.0), xxhdpi (×3.0) y xxxhdpi (×4.0).

// MainActivity.java — multiplicador de densidad
private int dp( int formPx ) { return Math.round( formPx * density ); }

private FrameLayout.LayoutParams lp( int x, int y, int w, int h ) {
    FrameLayout.LayoutParams p = new FrameLayout.LayoutParams( dp(w), dp(h) );
    p.leftMargin = dp(x);
    p.topMargin  = dp(y);
    return p;
}

Bucle de eventos (invertido)

En Win32, Cocoa y GTK la llamada oForm:Run() bloquea en una cola de mensajes. En Android el SO posee el bucle: UI_FormRun() es un no-op. El onCreate() de la Activity invoca nativeInit(), que arranca la VM de Harbour y llama a Main() — Main() crea los widgets mediante UI_*New y retorna. A partir de ahí el ciclo de vida de la Activity dirige todo; las interacciones del usuario disparan nativeOnClick, que despacha el codeblock almacenado.

Ejecutar desde el IDE

En Windows el IDE añade un menú Run → Run on Android…. Al pulsarlo:

1. Guarda el proyecto activo (SaveActiveFormCode).
2. Escribe el contenido de Project1.prg en el directorio fuente del build Android.
3. Abre un diálogo de progreso e invoca build-apk.sh vía Git Bash.
4. En caso de fallo: muestra el build-apk.log completo en un diálogo de error.
5. En caso de éxito: lanza run-on-emulator.sh en segundo plano — arranca el AVD si hace falta, instala el APK, lanza la Activity y guarda logcat en un fichero.

// hbbuilder_win.prg — cableado del menú
DEFINE POPUP oRun PROMPT "&Run" OF oIDE
   MENUITEM "&Run"              OF oRun ACTION TBRun()
   MENUITEM "&Debug"            OF oRun ACTION TBDebugRun()
   MENUSEPARATOR OF oRun
   MENUITEM "Run on &Android..." OF oRun ACTION TBRunAndroid()

Requisitos del toolchain

El target Android depende de cuatro toolchains externos. El Setup Wizard (Run → Android Setup Wizard…) los descarga e instala automáticamente en una ventana terminal propia, así que en una máquina limpia sólo tienes que hacer clic y esperar. Las rutas de abajo son las que usa el wizard (y los scripts de build).

Ocupa ≈4 GB de disco. Las instalaciones son autocontenidas — sin entradas de registro ni cambios de PATH: los scripts exportan PATH internamente.

Setup Wizard

Menú Run → Android Setup Wizard… abre un diálogo que reporta cada componente como OK o MISSING. Si falta algo, un Yes lanza source/backends/android/setup-android-toolchain.sh en una terminal nueva. El script es idempotente — detecta lo que ya está y baja sólo lo que falta:

El script redirige yes a sdkmanager --licenses para que el install no se pare en prompts de licencia, y aplica automáticamente el tweak NDK (ar/ranlib/strip) que los mk files de Harbour esperan. Total ~2.8 GB de descarga en una máquina limpia. Git Bash es el único prerequisito que el wizard no puede instalar por ti.

Hola Android — ejemplo completo

El fichero source/backends/android/hello_gui.prg usa la API UI_* del backend Android directamente:

PROCEDURE Main()

   LOCAL hForm, hLabel, hEdit, hBtn

   hForm  := UI_FormNew( "Hola Android", 400, 600 )
   hLabel := UI_LabelNew(  hForm, "Escribe tu nombre:", 20, 20,  300, 30 )
   hEdit  := UI_EditNew(   hForm, "",                   20, 60,  300, 50 )
   hBtn   := UI_ButtonNew( hForm, "Saludar",            20, 130, 300, 50 )

   UI_OnClick( hBtn, ;
      {|| UI_SetText( hLabel, "Hola, " + UI_GetText( hEdit ) + " !" ) } )

   UI_FormRun( hForm )   // no-op en Android; la Activity posee el bucle

RETURN

Compilar y desplegar:

# compilar el APK
bash source/backends/android/build-apk-gui.sh

# instalar y lanzar en el emulador
adb install -r C:/HarbourAndroid/apk-gui/harbour-gui.apk
adb shell am start -n com.harbour.builder/.MainActivity

Limitaciones conocidas

Hoja de ruta

Ficheros fuente