Gaia Build System: Grundlagen

Dieser Artikel beschreibt die grundlegende Funktionsweise des Gaia Build Systems inklusive make-Datei, Build-Prozess, Umgebungsvariablen und Anpassungsmöglichkeiten.

Die wichtigen Schritte eines Builds werden größtenteils von den im Gaia-Unterverzeichnis build/ liegenden Skripten erledigt. Augerufen werden diese mit make, node.js und XPCShell (auch bekannt als JS Shell), einer Laufzeitumgebung von XULRunner. Das Gaia Build System enthält viele Werkzeuge zum Installieren, Testen und Lokalisieren von Apps und um diese als Paket auf ein Gerät zu bringen. Zudem können Entwickler das Gaia-Paket anpassen, z.B. können Hintergrundbilder, Klingeltöne, Apps und Einstellungen geändert werden.

Hinweis: XPCShell ist ähnlich wie node.js, bietet aber zusätzlich die Möglichkeit zum Ausführen von Mozilla-spezifischen javascripts. Zudem können Gaia-Skripte mit Hilfe von XPCShell in einer Firefox Erweiterung laufen.

Die make-Datei

Die make-Datei enthält eine Menge nützlicher Funktionen. Dieses Kapitel bechreibt die nützlichsten davon.

install-gaia

Gestartet mit dieser Option installiert make alle Apps auf Deinem Gerät. Wenn Du nur eine bestimmte App installieren möchtest, dann starte make wie folgt mit der APP Option:

APP=calendar make install-gaia

Dieses Verzeichnis muss im Gaia-Verzeichnisbaum existieren (z.B. apps).

reset-gaia

Funktioniert genauso wie install-gaia mit dem Unterschied, dass zuerst alle Apps deinstalliert und anschließend wieder mit den Standard-Zugriffsrechten installiert werden. Die Apps befinden sich in /data/local wie bei den Entwickler-Builds. Test- und Debugging-Apps werden hier ebenfalls installiert.

Vorsicht: Wenn beim Aufruf von make mit der Option reset-gaia die Umgebungsvariable APP gesetzt ist, dann wird dies Dein Gerät in einen unbrauchbaren Zustand versetzen (das kann allerdings behoben werden durch Aufruf von make mit der Option reset-gaia ohne die APP Umgebungsvariable). Also mach das bitte nicht.

production

Genauso wie reset-gaia, aber der Quellcode wird optimiert. Das ermöglicht grundsätzlich die Emulation von User Builds (stabilen Builds). Mit dieser Option werden dieselben Apps installiert wie bei User Builds.

Vorsicht: Wenn beim Aufruf von make mit der Option production die Umgebungsvariable APP gesetzt ist, dann wird dies Dein Gerät in einen unbrauchbaren Zustand versetzen (das kann allerdings behoben werden durch Aufruf von make mit der Option production ohne die APP Umgebungsvariable). Also mach das bitte nicht.

reference workloads

Diese Option installiert unterschiedlich große Pakete für Laufzeittests auf dem Gerät, um eventuell auftretende Geschwindigkeits- und Skalierungsprobleme debuggen und beheben zu können. Diese Option akzeptiert die APP Umgebungsvariable und auch die APPS Umgebungsvariable mit mehreren durch Leerzeichen voneinander getrennten App-Namen, z.B.:

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

Hinweis: Weitere Informationen findest Du auf Hacking Gaia: Reference workloads.

Umgebungsvariablen

Mit einigen Umgebungsvariablen kannst Du den Build und die Installation auf dem Gerät steuern, z.B.:

P=1

Das ermöglicht parallele Build-Erzeugungen auf Multikern CPU Architekturen und verkürzt die Laufzeit von Build-Erzeugungen, der Standardwert ist 0.

Vorsicht: Parallele Build-Erzeugung ist noch in der Test-Phase und somit vielleicht nicht stabil.

GAIA_OPTIMIZE=1

Hiermit wird eine Optimierung der JavaScript Dateien angestossen. Diese Umgebungsvariable wird automatisch beim Ausführen von make production gesetzt. Die Variable kann für install-gaia und reset-gaia verwendet werden.

PRODUCTION=1

Das ist im Grunde ein Alias für make production.

DEBUG=1

Mit dieser Umgebungsvariablen wird eine Debugging-Umgebung aufgebaut, die Du für Gaia unit tests oder für die Entwicklung eigener Apps in Firefox OS nutzen kannst. Du musst ein bereits bestehendes Debugging-Profilverzeichnis löschen, bevor Du ein neues generieren kannst.

DEVICE_DEBUG=1

Deaktiviert die Bildschirmsperre auf dem Gerät.

GAIA_DEVICE_TYPE=phone

Diese Umgebungsvariable ermöglicht eine individuelle Installation mit mehreren 'app.list' Dateien. Alle 'app.list' Dateien müssen in /build/config/$(GAIA_DEVICE_TYPE)/ Verzeichnissen liegen.

Der Standardwert von GAIA_DEVICE_TYPE ist phone.

Hinweis: Weitere Details und optionen findest Du auf Hacking Gaia make options.

Build-Prozess

Das Ablaufdiagramm, wie ein Build für Gaia erzeugt wird:

pre-app.js, app.js & post-app.js werden von make gestartet und die meisten Build-Schritte werden in den xpcshell Skripten ausgeführt, make ermittelt das Betriebssystem und lädt den b2g-desktop herunter. Wir planen, mehr Build-Schritte von make in die xpcshell Skripte zu migrieren.

Vielleicht fragst Du Dich, warum wir pre-app, app and post-app nutzen. Das liegt daran, dass wir immer mehr Abhängigkeiten von make in die xpcshell Skripte verlagern. Deshalb entwickelten wir pre-app.js und post-app.js basierend auf bug 1021051, um den Großteil der Abhängigkeiten in die xpcshell Skripte zu verlagern. Am Ende werden dann app.js, pre-app.js und post-app.js auf Basis von bug 1053703 migriert.

Wir haben drei Typen von Verzeichnissen in einem Gaia Build System:

Source-Verzeichnisse: apps, dev_apps, gemeinsame Verzeichnisse
Stage-Verzeichnis: build_stage (stage = Plattform)
Profil-Verzeichnisse: profile, profile-debug oder profile-test

Unser Ziel ist es, keine Dateien in die Source-Verzeichnisse hinein zu generieren. Leider haben wir immer noch ein paar Stellen, an denen Dateien in die Source-Verzeichnisse generiert werden. Wir planen, diese Probleme zu beheben. Die folgende Tabelle listet auf, von welchen Modulen Dateien ins Source-, ins Stage- und in die Profil-Verzeichnisse generiert werden.

Der Build-Prozess führt bei Aufruf von make im Gaia-Verzeichnis die folgenden Schritte in der angegebenen Reihenfolge aus:

b2g_sdk: b2g-desktop startet die xpcshell Skripte in GAIA_DIR/build/.
svoperapps: Download der Apps und Generieren der Konfigurations-Dateien der App-Installation pro SIM-Karten-Anbieter und Land.
webapp-manifests: Generieren der Metadaten der Web-Apps für den Build.
keyboard-layouts: Generieren der Layout-Konfiguration der Standard-Tastatur.
settings.json (settings.js): Dieses JavaScript generiert die Standard-Einstellungen für Firefox OS, die von Gaia gelesen werden.
webapp-shared: Kopieren der von den Apps benötigten Dateien vom gemeinsamen Source-Verzeichnis ins Stage-Verzeichnis.
preferences: Generiert die Standard-Umgebung für Firefox OS; generiert die Datei user.js und kopiert diese auf das Gerät, wo sie von Gecko gelesen wird. Bitte beachte, dass die Standard-Umgebung abhängig von den Umgebungsvariablen (wie z.B. DEBUG=1) variieren kann.
app.js: make-Dateien in den jeweiligen app Verzeichnissen: Sie werden ausgeführt, wenn sie existieren. Für jede App ohne eigene make-Datei kopiert die Gaia make-Datei das App-Verzeichnis ins Stage-Verzeichnis build_stage und führt [app-directory]/build/build.js aus, falls vorhanden. Siehe Build script for apps für weitere Details.
test-agent-bootstrap & test-agent-config: Einrichten der zwei make Regeln test-agent-config & test-agent-bootstrap-apps, welche für den Aufbau von Test-Umgebungen pro App benötigt werden.
webapp-optimize: Dieses Skript enthält verschiedene Optimierungs-Prozeduren inklusive JavaScript Minimierung, Zusammenfügen von Lokalisierungs-Dateien in die JSON-Dateien und Generieren von HTML-Dateien für die Standard-Sprache, falls nötig.
webapp-zip: Hier wird jede App in eine eigene zip-Datei komprimiert und diese im Verzeichnis profile/ abgelegt.
optimize-clean: optimize-clean bereinigt die HTML-Dateien für die Standard-Sprache.
contacts: Kopiert eine vorgefertigte Kontakte-Datei in Dein Profil in GAIA_DISTRIBUTION_DIR, falls vorhanden.
extensions: Kopiert die in GAIA_DIR/tools/extensions liegenden Erweiterungen in Dein Profil-Verzeichnis; verschiedene Konfigurationen ermöglichen das Kopieren verschiedener Erweiterungen.
installed-extensions.json (additional-extensions.js): Zu guter Letzt: Dieses Skript kopiert per Download verschiedene zusätzliche Erweiterungen in Dein Profil-Verzeichnis.

Build-Skript für Apps

Standardmäßig wird als App Build Skript [app directory]/build/build.js von app.js ausgeführt, falls vorhanden. Wenn $APP/build/build.js nicht vorhanden ist, dann kopiert app.js die App ins Stage-Verzeichnis build_stage.

Die Dateien im App-Verzeichnis sollten vom App Build-Skript ins Stage-Verzeichnis build_stage kopiert werden; denn app.js kopiert sie nicht, wenn ein App Build-Skript existiert. Beispiel: Die App "Kalender" hat ein Skript build/build.js und utils.copyToStage() sollte in build.js für die "Kalender" App aufgerufen werden.

Hinweis: Sourcen, die nicht zu Deiner App gehören (wie in shared/) kannst Du in der index.html in den <head> Bereich einfügen, damit sie von shared/ in Deine App kopiert werden.

Build-Skripte für Apps benötigen möglicherweise alle Build Module im Verzeichnis $GAIA_DIR/build; speziell das utils Modul, ein sehr nützliches Modul für den Build von Apps, kannst Du require('utils') verwenden um das Modul einzubinden.

Anpassen der Voreinstellungen

Wenn Du eine eigene Konfiguration mit Einstellungen und Apps immer wieder beim Flashen Deines Gerätes benötigst, dann kannst Du eine Datei namens custom-prefs.js mit all Deinen Präferenzen im Verzeichnis build/config ablegen. Dort ist sie vor Überschreiben geschützt und unterliegt nicht der Source-Steuerung.

Hier sind einige sinnvolle Voreinstellungen:

// Aktivieren von marionette für Performance-Tests
// siehe https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_performance_tests
user_pref("marionette.defaultPrefs.enabled", true);

// Setzen des Ports für remote Debugging Deiner Anwendung auf Deinem Gerät
user_pref("devtools.debugger.remote-port", 60000);

// Aktivieren des remote Debuggers
user_pref("devtools.debugger.remote-enabled", true);

// Ausgeben der Debug-Meldungen über den Radio Interface Layer in logcat
user_pref("ril.debugging.enabled", true);

Diese Datei wird immer gelesen, wenn Du ein Profil generierst. Der sicherste Weg sicherzustellen, dass alles generiert wurde ist das vorherige Löschen des vorhandenen Profils:

rm -rf profile && make profile

Anschließend kannst Du beruhigt die install-gaia Option von make verwenden.

FAQ

Das Display bleibt Schwarz nach einem flash

Das kann manchmal passieren, wenn das Gerät im Ruhemodus geflasht wird. Um das Problem zu beheben starte B2G einfach durch das folgende Kommando neu:

adb shell stop b2g && adb shell start b2g