From 9cffed54bd396f2a3f3163592e104426a6431359 Mon Sep 17 00:00:00 2001 From: William Petit Date: Mon, 31 Jul 2023 13:24:04 -0600 Subject: [PATCH] doc: add firmware compilation tutorial --- doc/README.md | 8 +++ doc/tutorials/firmware-compilation.md | 78 ++++++++++++++++++++++++--- 2 files changed, 79 insertions(+), 7 deletions(-) diff --git a/doc/README.md b/doc/README.md index df9f9cb..626f288 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,5 +1,13 @@ # Documentation +## Structure du projet + +```shell +doc/ # Documentation technique +install/ # Tâches Make d'installation spécifiques aux différentes cibles de construction +misc/ # Fichiers spécifiques aux différentes cibles de construction +targets/ # Tâches Make de définition des différentes cibles de construction +``` ## Tutoriels - [Premiers pas](./tutorials/first-steps.md) diff --git a/doc/tutorials/firmware-compilation.md b/doc/tutorials/firmware-compilation.md index 7599023..c48c133 100644 --- a/doc/tutorials/firmware-compilation.md +++ b/doc/tutorials/firmware-compilation.md @@ -1,16 +1,80 @@ # Compiler un firmware -> TODO +## Compiler un firmware préconfiguré + +L'ensemble des cibles de construction préconfigurés sont disponibles dans le répertoire `targets/`. + +Par exemple: ```shell -# Exemple: construire un firmware OpenWRT - -# Pour le routeur Linksys WRT1200AC +# Pour le routeur Linksys WRT1200AC... make linksys-wrt1200ac -# Pour le routeur Linksys WRT1900AC +# ... ou pour le routeur Linksys WRT1900AC make linksys-wrt1900ac -# Pourt le router Linksys WRT3200ACM +# ... ou pour le routeur Linksys WRT3200ACM make linksys-wrt3200acm -``` \ No newline at end of file +``` +## 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. Lancer la compilation du firmware + + ```shell + make bpi-r3 + ``` + + Les fichiers du firmware seront générés dans le répertoire `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). \ No newline at end of file