Il sistema di build di Gaia

Questo articolo spiega il funzionamento del sistema di build di Gaia, incluso il Makefile, il processo di build, le variabili di ambiente e le potenziali personalizzazioni.

Gran parte del lavoro significativo degli step di build sono eseguiti dagli script presenti all'interno della cartella build/ di Gaia, che vengono eseguiti tramite make, node.js e XPCShell (conosciuto anche col nome di JS Shell), un ambiente di runtime per XULRunner. Il sistema di build di Gaia contiene molti tool a supporto per l'installazione, il testing, la localizzazione e per il packaging delle app su dispositivi reali. Consentono agli sviluppatori di personalizzare Gaia, per esempio cambiando lo sfondo di default, le suonerie, le app e le configurazioni di base.

Nota: XPCShell è simile a node.js ma con la possibilità di eseguire alcuni javascript personalizzati da Mozilla. Permette agli script di build di Gaia di essere eseguiti all'interno di un'estensione di Firefox.

Il Makefile

Il Makefile contiene un insieme di obiettivi (di operazioni da compiere). Questa sezione descrive le più significative.

install-gaia

Vengono installate tutte le app di Gaia sul tuo device. Se vuoi installarne una specifica, puoi utilizzare la variabile di ambiente APP come mostrato di seguito:

APP=calendar make install-gaia

Calendar deve esistere come cartella all'interno di una delle cartelle di app di Gaia (ad esempio all'interno della cartella apps).

reset-gaia

Analogamente a install-gaia, ma con la seguente sequenza di azioni: rimuove le app dal device, installa le app sul device e configura i permessi di default. Le app verranno installate sul device nella cartella /data/local. Verranno installate su device anche le app di testing e debugging.

Fai attenzione: Utilizzando la variabile di ambiente APP con reset-gaia porterà il tuo telefono in una stoto inutilizzabile (puoi ripristinarlo eseguendo nuovamente questa opzione senza APP). Pertanto non farlo.

production

Analogamente a reset-gaia ma il codice sorgente verrà ottimizzato. Questa opzione permette di emulare le build utente. Verranno installate tutte le app previste dalle build utente.

Fai attenzione: Utilizzando la variabile di ambiente APP con production porterà il tuo telefono in una stoto inutilizzabile (puoi ripristinarlo eseguendo nuovamente questa opzione senza APP). Pertanto non farlo.

reference workloads

Questi obiettivi caricheranno sul dispositivo workload (carichi di lavoro) di differente dimensione, aiutandoci nelle attività di debugging e fixing di problematiche inerenti le prestazioni. Accettano la variabile APP o APPS (contenente più nomi di app separati da uno spazio), ad esempio:

APP=sms make reference-workload-light
APPS="sms communications/contacts" make reference-workload-heavy

Nota: Per ulteriori informazioni leggi l'articolo Hacking Gaia: workload di riferimento.

Variabili di ambiente

Alcune variabili d'ambiente ti permettono di controllare alcuni aspetti della costruzione e della installazione sul dispositivo, per esempio:

P=1

Abilita un grado di parallelismo nel processo di build e consente di trarre vantaggio da CPU multicore riducendo le tempistiche di build. Il valore di default è 0.

Fai attenzione: la funzionalità di parallelismo è sperimentale e può essere instabile.

GAIA_OPTIMIZE=1

Innesca un processo di ottimizzazione sui file JavaScript. Viene valorizzata automaticamente quando si esegue il comando make production. Può essere utilizzata anche con con install-gaia o reset-gaia.

PRODUCTION=1

E' un alias di make production.

DEBUG=1

Ti consente di creare un profilo di debug da utilizzare negli unit testing di Gaia oppure nello sviuppo di app di Firefox OS in Firefox. Il nuovo profilo viene creato all'interno della cartella di Gaia (ad esempio profile-debug). Dovresti eliminare la precedente cartella prima di generare un nuovo profilo.

DEVICE_DEBUG=1

Disabilita il blocco dello schermo sul dispositivo.

GAIA_DEVICE_TYPE=phone

Consente di differenziare la lista delle app da installare in funzione del device. Le liste di app (app-*.list) sono presenti nella cartella /build/config/$(GAIA_DEVICE_TYPE)/ .

Il valore di default per questa variabile è phone.

Nota: Per maggiori dettagli e ulteriori opzioni, consultate la guida Hacking Gaia opzioni di make.

Il processo di build

Segue un diagramma che illustra il processo di build di Gaia:

pre-app.js, app.js & post-app.js vengono eseguite dal Makefile, di cui gran parte dei task tramite script xpcshell. Tramite Makefile viene anche identificato l'OS e scaricato il b2g-desktop specifico. Verranno migrati sempre più task da Makefile a script xpcshell.

Sono state create pre-app, app e post-app per agevolare il passaggio delle dipendenze da Makefile a script xpcshell. Pre-app.js e post-app.js sul bug 1021051, mentre app.js, pre-app.js e post-app.js sul bug 1053703.

Esistono tre tipologie di cartelle per il sistema di build di Gaia:

     1. cartelle con i sorgenti: apps, dev_apps, shared directories
     2. cartelle di appoggio: build_stage
     3. cartelli con i profili: profile, profile-debug o cartelle di profile-test

L'obiettivo è quello di non produrre più file all'interno di cartelle con i sorgenti. Sebbene esistono ancora dei moduli che non rispettano questa regola, ne è stato pianificato l'adeguamento quanto prima. Segue una tabella che illustra quali moduli producono file nelle cartelle con i sorgenti, in quelle di appoggio e in quelle con i profili:

Segue il processo di build da quando viene eseguito il comando make nella cartella di Gaia. Le seguenti regole vengono eseguite in ordine:

b2g_sdk: b2g-desktop è usato per eseguire gli script xpcshell nella cartella GAIA_DIR/build/.
svoperapps: vengono scaricate le app e generati i file di configurazione per l'installazione delle app su base operatore telefonico e Paese.
webapp-manifests: vengono generati i metadati delle webapp richiesti per il processo di build.
keyboard-layouts: viene generata la configurazione di default del layout della tastiera.
webapp-shared: vengono prelevati i file utilizzati da ciascuna app presenti nella cartella shared e copiati nella cartella build_stage.
preferences: vengono generate le preferenze di default per Firefox OS; viene generato il file user.js, che istallato sul dispositivo verrà letto da Gecko. Nota che i valori possono essere cambiati tramite variabili di ambiente quali DEBUG=1.
app-makefiles: vengono eseguiti i makefile presenti nelle cartelle delle singole app. Se il makefile non è presente, l'app (intesa come cartella completa) verrà copiata nella cartella build_stage e verrà eseguito [app-directory]/build/build.js se esiste. Vedi Build script for apps per maggiori dettagli.
app.js: se esistono, vengono eseguiti i Makefile nelle cartelle delle app. Altrimenti, il Makefile di Gaia copierà la cartella della app nall'interno di build_stage ed eseguirà [app-directory]/build/build.js se esiste. Vedi Build script for apps per maggiori dettagli.
test-agent-bootstrap & test-agent-config: l'ambiente di test per ciascuna app prevede l'esecuzione di due regole di make: test-agent-config & test-agent-bootstrap-apps.
webapp-optimize: questo script contiene alcune procedure di ottimizzazione e include le procedure di minimizzazione di JavaScript (JavaScript minification), la concatenazione delle risorse di localizzazione all'interno di file JSON e la generazione degli HTML per il linguaggio di default se necessario.
webapp-zip: ciascuna app viene compressa in un file .zip e spostata nella cartella profile/. I file nella cartella shared/ dichiarati nei file HTML delle webapp verranno inclusi in questo step.
optimize-clean: optimize-clean pulisce i fle HTML per la lingua di default.
contacts: se esiste, vene copiata la lista predefinita dei contatti dalla cartella GAIA_DISTRIBUTION_DIR in quella del nuovo profilo.
extensions: vengono copiate le estensioni dalla cartella GAIA_DIR/tools/extensions in quella del nuovo profilo; differenti configurazioni di setup consentono di copiare differenti estensioni.
installed-extensions.json (additional-extensions.js): infine, questo script scarica alcune estensioni addizionali nella cartella del nuovo profilo.

Script di build per le app

Di default, il makefile di Gaia copierà tutte la app nelle cartelle build_stage ed eseguirà [app directory]/build/build.js, se presente.

Per esempio, per costruire l'app Camera viene richiesto r.js (come ottimizzatore RequireJS) e viene eseguito uno script JavaScript per personalizzare la massima risoluzione, pertanto nella cartella sono presenti sia un Makefile che un build/build.js per personalizzare il suo processo di build.

Segue un diagramma di flusso per illustrare i principali step di un makefile per le app:

Personalizzare le preferenze

Se hai delle preferenze specifiche le devi impostare ogni qualvolta reinstalli il software sul tuo dispositivo. Lo puoi fare creando un file chiamato custom-prefs.js all'interno della cartella build/config.

Seguono alcune preferenze utili:

// this enables marionette which lets you run performance tests
// see https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_performance_tests
user_pref("marionette.defaultPrefs.enabled", true);

// this sets the port for remote debugging your application on the device
user_pref("devtools.debugger.remote-port", 60000);

// this enables the remote debugger
user_pref("devtools.debugger.remote-enabled", true);

// this outputs debug information about the Radio Interface Layer in logcat
user_pref("ril.debugging.enabled", true);

Questo file viene letto ogni qualvolta viene generato un profilo. Per sicurezza ti conviene eliminare il precedente profilo prima di generarne uno nuovo.

rm -rf profile && make profile

Quindi puoi utilizzare in sicurezza l'opzione install-gaia.

FAQ

Il dispositivo rimane nero dopo una reinstallazione

Può capitare se installi un device mentre è idle. Per rimediare riavvia B2G utilizzando il seguente comando:

adb shell stop b2g && adb shell start b2g