emissary-firmware/doc/tutorials/firmware-compilation.md

# Compiler un firmware

## Compiler un firmware préconfiguré

L'ensemble des cibles de construction préconfigurés sont disponibles dans le répertoire `targets/`.

Par exemple:

```shell
# Télécharger localement les dernières archive du projet emissary
make download-emissary-release

# Puis...

# ... pour le routeur Linksys WRT1200AC
make linksys-wrt1200ac

# ... ou pour le routeur Linksys WRT1900AC
make linksys-wrt1900ac

# ... ou pour le routeur Linksys WRT3200ACM
make linksys-wrt3200acm
```

## Créer une nouvelle cible de construction

Dans ce tutoriel, nous allons voir comment créer une nouvelle cible de construction pour un nouvel appareil, ici un [Banana Pi R3](https://wiki.banana-pi.org/Banana_Pi_BPI-R3).

### Créer la nouvelle tâche Make

1. Dans le répertoire `targets/`, créer le fichier `bananapi.mk`

    ```shell
    touch targets/bananapi.mk
    ```

2. Éditer le fichier `targets/bananapi.mk` pour créer la nouvelle tâche Make

    ```makefile
    # On ajoute notre nouvelle tâche "bpi-r3" en dépendance de la tâche
    # principale "all"
    all: bpi-r3

    # On créait une nouvelle tâche "bpi-r3" permettant de construire le
    # firmware pour notre BananaPi R3
    bpi-r3:
        $(MAKE) \
            OPENWRT_VERSION="snapshot" \
            IMAGEBUILDER_URL="https://downloads.openwrt.org/snapshots/targets/mediatek/filogic/openwrt-imagebuilder-mediatek-filogic.Linux-x86_64.tar.xz" \
            ADDITIONAL_INSTALL="" \
            OPENWRT_TARGET="mediatek/filogic" \
            EMISSARY_ARCH="arm64" \
            OPENWRT_PROFILE="bananapi_bpi-r3" \
            build
    ```

    **Explication des variables**

    - `OPENWRT_VERSION`: Version d'OpenWRT à utiliser. _Normalement prédéfinie par le fichier `Makefile` principal mais ill est ici nécessaire de surcharger la variable car il n'existe à ce jour pas de version stable d'OpenWRT pour la BananaPi R3._
    - `IMAGEBUILDER_URL`: URL à utiliser pour télécharger le "builder" OpenWRT. _Normalement prédéfinie par le fichier `Makefile` principal mais ill est ici nécessaire de surcharger la variable car il n'existe à ce jour pas de version stable d'OpenWRT pour la BananaPi R3._
    - `ADDITIONAL_INSTALL`: Tâches Make d'installation supplémentaires à exécuter. Voir section suivante.
    - `OPENWRT_TARGET`: "Cible" OpenWRT associée à l'appareil
    - `EMISSARY_ARCH`: Architecture du binaire Emissary à déployer dans le firmware
    - `OPENWRT_PROFILE`: "Profil" OpenWRT associé à l'appareil

3. Préparation.

    Lancer la commande suivante pour télécharger (ou mettre à jours) les fichiers tar.gz nécessaire à la construction du firmware. Si cette commande n'a pas été exécutée au moins une fois, vous ne serez pas en mesure de construire le ou les firmwares nécessaires.

    ```shell
    make download-emissary-release
    ```

4. Lancer la compilation du firmware

    ```shell
    make bpi-r3
    ```

    Les fichiers du firmware seront générés dans le répertoire `depot/bin/snapshot/mediatek/filogic/bananapi_bpi-r3/`

> 🛈 **Comment trouver les valeurs des variables `OPENWRT_TARGET` et `OPENWRT_PROFILE` ?**
>
> Après avoir trouvé votre appareil sur la [liste de compatibilité d'OpenWRT](https://openwrt.org/toh/start), rechercher l'URL de téléchargement du fichier du firmware, qui devrait ressembler à `https://downloads.openwrt.org/snapshots/targets/mediatek/filogic/openwrt-mediatek-filogic-bananapi_bpi-r3-sdcard.img.gz`.
>
> La valeur de `OPENWRT_TARGET` est la chaîne comprenant les 2 répertoires juste après `targets/`, ici `mediatek/filogic`.
>
> La valeur de `OPENWRT_PROFILE` est la chaîne comprise entre la cible OpenWRT et le type/extension dans le nom de fichier, ici `bananapi_bpi-r3`.

### Personnaliser votre firmware

Afin de personnaliser votre firmware, vous pouvez déclarer des nouvelles tâches Make dans le répertoire `install/` et ensuite les référencer dans la variable `ADDITIONAL_INSTALL`.

Vous pouvez prendre exemple sur le ficher `install/raspberrypi.mk` qui par exemple déploie des fichiers de configuration UCI par défaut ainsi que des scripts [`uci-defaults`](https://openwrt.org/docs/guide-developer/uci-defaults).