Éléments de base sur le système de construction de Gaia

Le travail le plus important durant les étapes de construction est effectué par les scripts contenus dans le sous-répertoire build/ de Gaia, qui sont exécutés grâce à make, node.js et XPCShell (aussi appelé JS Shell), qui est un environnement d'exécution de XULRunner. Le système de construction de Gaia contient plusieurs utilitaires pour aider à installer, tester, localiser et empaqueter les applications web sur un vrai appareil. Il permet également aux développer de personnaliser et d'adapter Gaia (par exemple en changeant le fond d'écran par défaut, les sonneries, les applications et les réglages).

Le fichier makefile

Le fichier makefile est composé de plusieurs buts (goals). Cette section explique les buts les plus utiles.

install-gaia

Ce but enverra toutes les applications Gaia sur votre appareil. Si vous souhaitez n'envoyer qu'une application en particulier, vous devrez utiliser le drapeau (flag) APP comme suit :

APP=calendar make install-gaia

Ce répertoire doit être présent au sein d'un des répertoires de Gaia pour les applications (ex : apps).

reset-gaia

Ce but fonctionne de la même façon que install-gaia mais commence par purger puis remet les permissions par défaut après avoir installé toutes les applications. Les applications seront situées sous /data/local (comme lorsque Gaia est construit en mode engineering). Cela enverra également les tests et les applications de débogage.

production

Ce but correspond à reset-gaia avec une optimisation du source code. Ce but permet généralement d'émuler les versions communiquées aux utilisateurs (user builds). Il enverra les mêmes applications qui sont installées pour les versions communiquées aux utilisateurs.

reference-workloads

Ces buts envoient des volumes de données de différentes tailles sur l'appareil, aidant ainsi à déboguer et à corriger les problèmes de montées en charge. Ces buts gèrent la variable d'environnement APP ou une variable d'environnement APPS qui contient les noms d'applications séparées par des espaces :

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

Les variables d'environnement

Certaines variables d'environnement permettent de contrôler certains aspects de la construction et de l'installation sur l'appareil. Par exemple :

P=1

Celà active la compilation en parallèle dans le but de tirer avantage des processeurs multi-coeurs, et d'accélérer le temps nécessaire à une compilation. La valeur par défaut est 0.

GAIA_OPTIMIZE=1

Cela déclenche une passe d'optimisation des fichiers JavaScript. Cette optimisation a lieu de façon automatique lorsqu'on utilise make production. Cela peut également être utilisé pour install-gaia ou reset-gaia.

PRODUCTION=1

Cette variable est un alias pour make production.

DEBUG=1

Cette variable vous permet de générer un profil de débogage à utilliser pour les tests unitaires de Gaia ou lorsque vous développer votre application Firefox OS dans Firefox. Vous devez supprimer le profil existant avant d'essayer d'en générer un nouveau.

DEVICE_DEBUG=1

Cette variable désactive l'écran de vérouillage de l'appareil.

GAIA_DEVICE_TYPE=phone

Cette variable vous permet de construire différemment en fonction du type d'appareil avec une 'app.list' différente. Tous les fichiers 'app.list' sont situés sous les dossiers /build/config/$(GAIA_DEVICE_TYPE)/ .

Par défaut, la valeur de GAIA_DEVICE_TYPE est phone (pour un téléphone).

Processus de construction

Voici un diagramme de séquence de la construction de Gaia :

pre-app.js, app.js et post-app.js seront exécutés par le Makefile les tâches de constructions ont, pour la plupart, lieu dans des scrips xpchsell, le fichier Makefile est utilisé pour détecter le système d'exploitation et pour télécharger b2g-desktop. Pour la suite, il est prévu qu'il y ait des tâches qui soient exécutées par des scripts xpcshell plutôt que par le Makefile.

Si vous vous demandez pourquoi il y a les scripts pre-app, app et post-app : c'est parce que nous migrons des dépendances du Makefile vers les scripts xpcshell. C'est pourquoi nous avons créé  pre-app.js et post-app.js pour le bug 1021051 afin de déplacer la plupart des dépendances sur les scripts xpcshell. Au final, app.js, pre-app.js et post-app.js seront fusionnés avec le bug 1053703.

Il existe trois types de répertoires utilisés pour le système de construction de Gaia :

1. les répertoires sources : apps, dev_apps qui sont des répertoires partagés
2. le répertoire d'étape (stage directory) : build_stage
3. les répertoires de profil : profile, profile-debug ou profile-test

Notre objectif est de ne générer aucun fichier dans les répertoires sources. Malheureusement, certains des modules génèrent des fichiers dans les répertoires sources, ce qu'il est prévu de corriger. Voici un tableau qui illustre quels modules génèrent des fichiers dans les dossiers sources, le dossier d'étape et/ou les dossiers de profil :

Voici les règles exécutées (et l'ordre dans lequel elles le sont) lorsque la construction est lancée depuis le répertoire de Gaia :

1. b2g_sdk : b2g-desktop est utilisé pour lancer les scripts xpcshell contenus dans GAIA_DIR/build/.
2. svoperapps : on télécharge les applcations et on génère les fichiers de configuration pour l'installation des applications, par opérateur téléphonie et par pays.
3. webapp-manifests : on génère des méta-données sur les applications web pour le processus de construction.
4. keyboard-layouts : on génère l'agencement par défaut du clavier.
5. settings.json (settings.js): ce fichier JavaScript génère les paramètres par défaut pour Firefox OS, qui sont lus par Gaia.
6. webapp-shared : on copie les fichiers des répertoires partagés qui sont utilisés pour chaque application vers le répertoire d'étape.
7. preferences : on génère les réglages utilisateurs par défaut pour Firefox OS ; cela génèrera un fichier user.js, l'enverra sur l'appareil afin qu'il soit lu par Gecko. Les valeurs peuvent être différentes en fonction des variables d'environnement (par exemple avec DEBUG=1).
8. app.js : les fichiers de construction du répertoire app sont exécutés s'ils existent. Pour chaque application, s'il n'y a pas de fichier Makefile pour l'application, le fichier Makefile de Gaia copiera le répertoire de l'application dans build_stage puis exécutera [app-directory]/build/build.js s'il existe. VoirScript de construction pour les applications pour plus d'informations.
9. test-agent-bootstrap & test-agent-config : la préparation des agents de test est divisée en deux règles test-agent-config et test-agent-bootstrap-apps, ces règles permettent de paramétrer des environnements de test pour chaque application.
10. webapp-optimize : Ce script contient diverses procédures d'optimisation comme la minification du JavaScript, la concaténation des fichiers de localisation en fichiers JSON, la génération de fichiers HTML dans la langue par défaut (si nécessaire).
11. webapp-zip : On compresse chaque application dans un fichier zip distinct puis on les place dans le répertoire profile/.
12. optimize-clean : optimize-clean nettoie les fichiers HTML pour la langue par défaut.
13. contacts : Copie le fichier de contacts pré-chargé dans le profil, s'il existe dans GAIA_DISTRIBUTION_DIR.
14. extensions : Copie les extensions (contenues dans GAIA_DIR/tools/extensions) dans votre répertoire de profil. Suivant les configurations utilisées, vous pouvez définir quelles extensions sont copiées.
15. installed-extensions.json (additional-extensions.js) : Enfin, ce script télécharge certaines extensions supplémentaires dans votre répertoire de profil.

Script de construction pour les applications

Par défaut, le script de construction de l'application [répertoire app]/build/build.js sera exécuté par app.js si le script de construction existe. Si $APP/build/build.js n'existe pas, app.js copiera l'application dans build_stage.

Les fichiers contenus dans le répertoire de l'application devrait être copiés dans le répertoire d'étape build_stage par le script de construction de l'application s'il existe. En effet, si le script existe, app.js ne copiera pas les fichiers. Par exemple, l'application du calendrier (calendar) possède un script build/build.js et fait appel à utils.copyToStage().

Les scripts de constructions des applications peuvent requérir n'importe quel module construit dans $GAIA_DIR/build, en particulier le module utils qui est très utile pour la construction des applications. Vous pouvez ainsi utiliser require('utils') pour bénéficier du module.

Personnaliser les réglages utilisateurs

Si vous avez un ensemble de préférences utilisateur que vous utilisez à chaque fois que vous chargez (flashez) l'appareil, vous pouvez créer un fichier appelé custom-prefs.js dans le répertoire build/config et les stocker à cet emplacement. Cela évite que les préférences soient écrasées et en dehors du gestionnaire de versions (source control).

Voici quelques réglages utilisateurs qui peuvent être utiles :

// on permet à marionette de lancer les tests de performance
// voir https://developer.mozilla.org/fr/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_performance_tests
user_pref("marionette.defaultPrefs.enabled", true);

// on définit le port à utiliser pour déboguer l'application à distance sur l'appareil
user_pref("devtools.debugger.remote-port", 60000);

// on active le débogueur à distance
user_pref("devtools.debugger.remote-enabled", true);

// on affiche les informations de debug sur le Radio Interface Layer dans logcat
user_pref("ril.debugging.enabled", true);

Ce fichier est lu à chaque fois que vous générez un profil. La façon la plus certaine d'être sûr que tout soit généré est de commencer par supprimer votre profil :

rm -rf profile && make profile

Vous pouvez ensuite utiliser le but install-gaia sans danger.

FAQ

L'appareil reste  avec l'écran noir après avoir été flashé

Ceci peut parfois arriver si vous flashez l'appareil lorsqu'il est en veille. Pour régler le problème, il suffit de redémarrrer B2G en utilisant la ligne de commande suivante :

adb shell stop b2g && adb shell start b2g