Module complémentaire B2G installer

Le module complémentaire B2G installer contribue à résoudre un problème de longue date : l'impossibilité de redistribuer des builds du système complet à cause des blobs (composants propriétaires.) Cet article détaille comment le module fonctionne et comment l'installer.

Important : Ce module complémentaire en est encore à un stade expérimental et il a besoin d'un mainteneur. À l'heure actuelle, il est conseillé de ne l'utiliser qu'avec un appareil que vous savez comment reflasher en cas de problème. Il n'est supporté que sur Linux (32 et 64 bits) et OSX (64 bits) pour l'instant.

Important : En ce qui concerne la première version de ce module, il est important de comprendre que ses objectifs sont en réalité de prendre en charge le cas pratique de base suivant : flasher B2G sur un appareil supporté, fonctionnant sous le système Android (ou CyanogenMod). La gestion des mises à jour de B2G et l'obtention des Blobs à partir d'une source autre que l'appareil lui-même ne sont pas (encore) abordées.

Construire une distribution sans blob

Une solution au problème cité plus haut consiste à produire une distribution dite sans blob ou "blobfree" (voir le bug 1175934) qui englobe tout ce qui est nécessaire pour la compilation d'un appareil :

Système complet construit depuis les sources.
Informations sur la compatibilité de l'appareil.
Description des partitions.
Liste des Blobs nécessaires, avec les informations sur leurs destinations requises dans le build final.

Une telle distribution sans blob peut être construite en spécifiant la cible |blobfree| make lors de la compilation de B2G :

$ ./build.sh blobfree

Note : Plus de détails là-dessus figurent dans la section blobfree de la page sur la compilation de B2G.

Le module complémentaire B2G installer simplifie l'installation de ce type de distribution.

Ajout du support d'un nouvel appareil

Pour rendre un nouvel appareil disponible dans le module lorsque l'utilisateur branche un appareil compatible, quelques étapes sont requises :

Assurez-vous que la génération d'une distribution sans blob est prise en charge par votre appareil. Vérifiez la section blobfree de la page Compiler B2G.
Dès lors que votre appareil dispose de ce support, vous pouvez faire en sorte qu'il soit disponible à partir du module. Tout d'abord, clonez le dépôt des builds.
Enregistrez un bogue dans Bugzilla pour le composant Firefox OS :: B2GInstaller.
Enrichissez builds.json avec les informations relatives à votre nouvel appareil.
Envoyez un PR sur Github, joignez-le au bogue que vous avez créé et faîtes une demande de review :gerard-majax.

Le fichier builds.json contient un tableau d'objets, chacun décrivant un appareil compatible. Ces objets possèdent les propriétés suivantes :

id: Le nom de l'appareil tel qu'il est affiché à l'utilisateur.
builds: Un tableau des builds disponibles pour cet appareil. Chaque objet build du tableau doit avoir ces propriétés :
- name : La chaîne affichée lors de la sélection du build.
- description : Une description claire de ce qu'est ce build.
- url : URL du fichier de la distribution blobfree.
adb : Un ensemble de propriétés Android que l'appareil DOIT posséder pour être détecté comme compatible.
fastboot : Un ensemble de variables Fastboot auxquelles celles de l'appareil DOIVENT correspondre pour être détecté comme compatible.
requiresRoot : Valeur optionnelle qui définit si l'appareil doit être rootable pour pouvoir poursuivre l'installation. Par défaut, elle est définie à true.

Note : Chaque propriété Android ou variable Fastboot peut être comparée soit avec une chaîne de caractères (égalité stricte) soit avec un tableau (égalité stricte avec une des valeurs du tableau.)

Installation

Pour installer le module complémentaire B2G installer, il faut suivre ces étapes :

Assurez-vous d'être sous Firefox Desktop Nightly et d'avoir ADB Helper installé (v0.8.6 au minimum) — voir le lien en bas de la page fxos-simulator pour l'installation.
Créez un profil distinct
```
./firefox -P
```
outrepassez la signature des modules complémentaires (risque de sécurité : c'est la raison pour laquelle vous devriez utiliser un profil séparé dans ce cas) :
- Allez sur about:config (écrivez-le dans la barre de recherche).
- désactivez xpinstall.signatures.required en double-cliquant dessus (la valeur par défaut est true, et la modifier en false va faire passer la ligne en gras).
Installez le module complémentaire XPI B2G installer en utilisant une de ces méthodes :
- Installez-le depuis les pages Github (recommandé).
- Construisez-le vous-même — voir la section Hacking.
Vérifiez que vous disposez d'au moins 2Go d'espace disponible dans /tmp/.
Chargez la page about:b2g-installer (écrivez cela dans la barre de recherche). Vous pouvez avoir besoin de redémarrer le navigateur avant que cela ne marche pour la première fois.
Si vous souhaitez nous aider à améliorer le module, vous pouvez cocher la case pour collecter des informations directement à partir des sessions d'utilisation. Ce qui est collecté comme information est expliqué plus loin, dans la section Données.

Vous pouvez également faire usage d'une machine virtuelle préconçue sous la forme d'un paquet OVA. Elle offre une installation prête à l'emploi de B2G Installer qui prend en charge certains appareils automatiquement (udev, etc. déjà configurés.) Voir le bug 1204482 pour plus de détails.

https://drive.google.com/file/d/0B8Ju6ek0Knd6aE5RdUkwTnlUTjQ/view?usp=sharing
SHA1: 9cbf309fa48eb73d983150e6aab21f7facb4f327

Utilisation

Lorsque le module complémentaire démarre, il télécharge builds.json depuis Github pour obtenir la liste des builds disponibles. Il est toujours possible d'utiliser un fichier zip local.
Branchez votre appareil en USB et attendez qu'il soit détecté par le module.
Après que l'appareil ait été détecté comme étant supporté, une liste des builds sera proposée.
Sélectionnez le build que vous voulez, cliquez sur Flash et patientez.

Captures d'écran

Quand aucun appareil n'est branché :

First page, no device plugged

Quand un build est sélectionné :

Device plugged in and detected

Lors du flashage d'un appareil :

Device plugged in and flashing a device

Données

Dans le but d'améliorer le module, nous collectons certaines données lorsqu'il est utilisé. Le principal objectif est de s'assurer que le module fonctionne correctement chez tout le monde. Nous collectons également des données pour savoir quels appareils intéressent les utilisateurs, de manière à ajuster les builds supportés en conséquence. Aucun pistage n'est fait.

Nous envoyons deux pings de télémétrie externes pour collecter ces données :

Un lorsque l'appareil est détecté par le module après avoir été branché sur l'ordinateur (cela arrive à chaque fois que le module est actif *et* qu'un appareil avec ADB activé est branché.) À l'occasion de ce ping, nous enregistrons :
- Les variables d'identification de l'appareil (modèle, id du build, fabricant, bootloader.)
- Le fait qu'un build CyanogenMod est installé ou non sur cet appareil.
- Le fait qu'un build supporté a été détecté ou non sur l'appareil.
Exemple de données collectées lors du branchement d'un appareil supporté :
```
{
  "payload": {
    "buildid": "KOT49H",
    "isSupported": true,
    "model": "Xperia Z3 Compact (B2G)",
    "bootloader": "s1",
    "manufacturer": "Sony"
  }, [...]
}
```
Exemple de données collectées lors du branchement d'un appareil non supporté :
```
{
  "payload": {
    "buildid": "LVY48I",
    "isSupported": false,
    "model": "Xperia Z1 Compact (B2G)",
    "bootloader": "s1",
    "manufacturer": "Sony"
  }, [...]
}
```

Un à chaque fois qu'une procédure de flashage d'un appareil est exécutée. Cela se produit soit à la fin d'une procédure de flashage réussie, soit en cas d'échec. Pour ce ping, nous enregistrons :

Les mêmes variables que ci-dessus.
Si l'appareil fait déjà tourner un build B2G.
L'URL du build flashé (chemin complet pour un build public, nom du fichier sans le chemin complet pour un build local.)
Le fait que l'utilisateur conserve ses données ou non.
Le fait que le flashage ait réussi ou non.

Exemple de données collectées si le flashage a réussi :

{
  "payload": {
    "isSupported": true,
    "installResult": true,
    "runsB2G": true,
    "buildid": "KOT49H",
    "keepData": false,
    "buildURL": "https://index.taskcluster.net/v1/task/gecko.v1.mozilla-central.latest.linux.nexus-4-kk-user.opt/artifacts/public/build/mako.blobfree-dist.zip",
    "model": "AOSP on Mako",
    "bootloader": "MAKOZ30d",
    "manufacturer": "LGE"
  }, [...]
}

Exemple de données collectées en cas d'échec du flashage :

{
  "payload": {
    "isSupported": true,
    "installResult": false,
    "runsB2G": true,
    "buildid": "KOT49H",
    "keepData": false,
    "buildURL": "https://index.taskcluster.net/v1/task/gecko.v1.mozilla-central.latest.linux.nexus-4-kk-eng.opt/artifacts/public/build/mako.blobfree-dist.zip",
    "model": "AOSP on Mako",
    "bootloader": "MAKOZ30d",
    "manufacturer": "LGE"
  }, [...]
}

Hacking

Le code réside dans le dépôt b2g-installer. Vous devez appliquer le patch sur un clone de mozilla-central, puis créer un lien symbolique browser/extensions/b2g-installer vers votre clone du dépôt b2g-installer.
Pour le compiler, vous devez lancer |./mach build && ./mach build package|.
Le XPI résultant sera produit dans votre répertoire MOZ_OBJDIR/dist/xpi-stage/b2g-installer/.
Il contient une copie du code source des outils externes d'AOSP/CAF nécessaires à la construction des partitions.
Les tests sont écrits sous forme de tests mochitest/xpcshell.
Vérifiez également le méta-bogue et ses dépendances : Bogue 1166276

À FAIRE

Sortir de la branche mozilla-central pour la compilation. Cela va sans doute imposer la réécriture des tests avec autre chose que mochitests.
Convertir moz.build en Makefile pour la construction des outils.
Prendre en charge des sources externes de blobs (nécessaire pour gérer les cas de mise à jour).