Cette section explique comment de nouveaux packages (bibliothèques ou applications de l'espace utilisateur) peuvent être intégrés dans Buildroot. Il montre également comment les packages existants sont intégrés, ce qui est nécessaire pour résoudre les problèmes ou ajuster leur configuration.

Lorsqu'on ajoute un nouveau paquet, il faut le tester dans diverses conditions (voir Section « Comment tester un paquet ») et vérifier également son style de codage (voir Section « Comment vérifier le codage style“).

Tout d'abord, créer un répertoire sous le répertoire du package pour le logiciel, par exemple libfoo.

Certains packages ont été regroupés par thème dans un sous-répertoire : x11r7, qt5 et gstreamer. Si le package appartient à l'une de ces catégories, créer le répertoire de packages dans celles-ci. Les nouveaux sous-répertoires sont toutefois déconseillés.

Pour que le package s'affiche dans l'outil de configuration, créer un fichier de configuration dans le répertoire de package. Il existe deux types : Config.in et Config.in.host.

Pour les packages utilisés sur la cible, créer un fichier nommé Config.in. Ce fichier contiendra les descriptions des options liées à notre logiciel libfoo qui seront utilisées et affichées dans l'outil de configuration. Il doit essentiellement contenir :

config BR2_PACKAGE_LIBFOO
        bool "libfoo"
        help
          This is a comment that explains what libfoo is. The help text
          should be wrapped.

          http://foosoftware.org/libfoo/

La ligne bool, la ligne help et les autres informations de métadonnées sur l'option de configuration doivent être mises en retrait avec un onglet. Le texte d'aide lui-même doit être en retrait avec une tabulation et deux espaces, les lignes doivent être enveloppées pour contenir 72 colonnes, où la tabulation compte pour 8, donc 62 caractères dans le texte lui-même. Le texte d'aide doit mentionner l'URL amont du projet après une ligne vide.

En tant que convention spécifique à Buildroot, l'ordre des attributs est le suivant :

• Le type d'option : bool, string… avec le prompt
• Si nécessaire, la ou les valeurs par défaut
• Toute dépendance sur la cible
• Toutes les dépendances sur la chaîne d'outils
• Toute dépendance à d'autres packages
• Toute dépendance du formulaire de sélection
• Le mot-clé help et le texte d'aide.

on peut ajouter d'autres sous-options dans une instruction if BR2_PACKAGE_LIBFOO…endif pour configurer des éléments particuliers dans le logiciel. on peut consulter des exemples dans d'autres packages. La syntaxe du fichier Config.in est la même que celle du fichier Kconfig du noyau. La documentation de cette syntaxe est disponible sur http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt

Enfin, ajouter le nouveau libfoo/Config.in à package/Config.in (ou dans un sous-répertoire de catégorie si on a décidé de mettre le paquet dans l'une des catégories existantes). Les fichiers qui y sont inclus sont triés par ordre alphabétique par catégorie et ne sont censés contenir que le nom du package.

source "package/libfoo/Config.in"

Certains packages doivent également être compilés pour le système hôte. Il y a deux options ici:

• Le package hôte n'est requis que pour satisfaire les dépendances au moment de la construction d'un ou plusieurs packages cibles. Dans ce cas, ajouter host-foo à la variable BAR_DEPENDENCIES du package cible. Aucun fichier Config.in.host ne doit être créé.
• Le package hôte doit être explicitement sélectionnable par l'utilisateur à partir du menu de configuration. Dans ce cas, créer un fichier Config.in.host pour ce package hôte :

config BR2_PACKAGE_HOST_FOO
        bool "host foo"
        help
          This is a comment that explains what foo for the host is.

          http://foosoftware.org/foo/

• Le même style de codage et les mêmes options que pour le fichier Config.in sont valides.
• Enfin, ajouter le nouveau libfoo/Config.in.host à package/Config.in.host. Les fichiers qui y sont inclus sont triés par ordre alphabétique et ne sont censés contenir que le nom du package.

    source "paquet/foo/Config.in.host"

• Le package hôte sera alors disponible dans le menu Utilitaires de l'hôte.

Le fichier Config.in du package doit également garantir que les dépendances sont activées. Généralement, Buildroot utilise les règles suivantes :

• Utiliser un type de dépendance sélectionné pour les dépendances sur les bibliothèques. Ces dépendances ne sont généralement pas évidentes et il est donc logique que le système kconfig s'assure que les dépendances sont sélectionnées. Par exemple, le package libgtk2 utilise select BR2_PACKAGE_LIBGLIB2 pour s'assurer que cette bibliothèque est également activée. Le mot-clé select exprime la dépendance avec une sémantique inversée.
• Utiliser un dépend du type de dépendance lorsque l'utilisateur a vraiment besoin d'être conscient de la dépendance. Typiquement, Buildroot utilise ce type de dépendance pour les dépendances sur l'architecture cible, le support MMU et les options de la chaîne d'outils (voir Section « Dépendances sur les options de la cible et de la chaîne d'outils »), ou pour les dépendances sur les « grandes » choses, comme le X. orgsystème. Le mot clé depend on exprime la dépendance avec une sémantique directe.

Un exemple illustre à la fois l'utilisation de select et de depend on.

config BR2_PACKAGE_RRDTOOL
        bool "rrdtool"
        depends on BR2_USE_WCHAR
        select BR2_PACKAGE_FREETYPE
        select BR2_PACKAGE_LIBART
        select BR2_PACKAGE_LIBPNG
        select BR2_PACKAGE_ZLIB
        help
          RRDtool is the OpenSource industry standard, high performance
          data logging and graphing system for time series data.

          http://oss.oetiker.ch/rrdtool/

comment "rrdtool needs a toolchain w/ wchar"
        depends on !BR2_USE_WCHAR

Cela signifie, dans l'exemple suivant :

config BR2_PACKAGE_A
        bool "Package A"

config BR2_PACKAGE_B
        bool "Package B"
        depends on BR2_PACKAGE_A

config BR2_PACKAGE_C
        bool "Package C"
        depends on BR2_PACKAGE_B

config BR2_PACKAGE_D
        bool "Package D"
        select BR2_PACKAGE_B

config BR2_PACKAGE_E
        bool "Package E"
        select BR2_PACKAGE_D

• La sélection du package C sera visible si le package B a été sélectionné, qui à son tour n'est visible que si le package A a été sélectionné.
• La sélection du package E sélectionnera le package D, qui sélectionnera le package B, il ne vérifiera pas les dépendances du package B, il ne sélectionnera donc pas le package A.
• Puisque le package B est sélectionné mais que le package A ne l'est pas, cela viole la dépendance du package B sur le package A. Par conséquent, dans une telle situation, la dépendance transitive doit être ajoutée explicitement :

config BR2_PACKAGE_D
        bool "Package D"
        select BR2_PACKAGE_B
        depends on BR2_PACKAGE_A

config BR2_PACKAGE_E
        bool "Package E"
        select BR2_PACKAGE_D
        depends on BR2_PACKAGE_A

Dans l'ensemble, pour les dépendances de la bibliothèque de packages, select doit être préféré.

De nombreux packages dépendent de certaines options de la chaîne d'outils : le choix de la bibliothèque C, la prise en charge de C++, la prise en charge des threads, la prise en charge RPC, la prise en charge de wchar ou la prise en charge de la bibliothèque dynamique. Certains packages ne peuvent être construits que sur certaines architectures cibles, ou si une MMU est disponible dans le processeur.

Ces dépendances doivent être exprimées avec les instructions depend on appropriées dans le fichier Config.in. De plus, pour les dépendances sur les options de la chaîne d'outils, un commentaire doit être affiché lorsque l'option n'est pas activée, afin que l'utilisateur sache pourquoi le package n'est pas disponible. Les dépendances sur l'architecture cible ou le support MMU ne doivent pas être rendues visibles dans un commentaire : puisqu'il est peu probable que l'utilisateur puisse choisir librement une autre cible, cela n'a aucun sens de montrer ces dépendances explicitement.

Le commentaire ne doit être visible que si l'option de configuration elle-même est visible lorsque les dépendances de l'option de la chaîne d'outils sont remplies. Cela signifie que toutes les autres dépendances du package (y compris les dépendances sur l'architecture cible et la prise en charge de la MMU) doivent être répétées dans la définition de commentaire. Pour que ce soit clair, l'instruction depend de pour ces options non liées à la chaîne d'outils doit être séparée de l'instruction depend de pour les options de la chaîne d'outils. S'il existe une dépendance sur une option de configuration dans ce même fichier (généralement le package principal), il est préférable d'avoir une construction globale if … endif plutôt que de répéter l'instruction depend on sur le commentaire et d'autres options de configuration.

Le format général d'un commentaire de dépendance pour le paquet foo est :

foo a besoin d'une chaîne d'outils avec featA, featB, featC

par exemple:

mpd a besoin d'une chaîne d'outils avec C++, threads, wchar

ou

crda a besoin d'une chaîne d'outils avec des threads

Le reste de cette section énumère les différentes options de cible et de chaîne d'outils, les symboles de configuration correspondants dont il faut dépendre et le texte à utiliser dans le commentaire.

Certains packages ont besoin d'un noyau Linux pour être construits par buildroot. Il s'agit généralement de modules de noyau ou de micrologiciels. Un commentaire doit être ajouté dans le fichier Config.in pour exprimer cette dépendance, similaire aux dépendances sur les options de la chaîne d'outils. Le format général est :

foo needs a Linux kernel to be built

S'il existe une dépendance à la fois sur les options de la chaîne d'outils et sur le noyau Linux, utiliser ce format :

foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built

Si un paquet nécessite une gestion udev /dev, il doit dépendre du symbole BR2_PACKAGE_HAS_UDEV, et le commentaire suivant doit être ajouté :

foo needs udev /dev management

S'il existe une dépendance à la fois sur les options de la chaîne d'outils et sur la gestion udev /dev, utiliser ce format :

foo needs udev /dev management and a toolchain w/ featA, featB, featC

Certaines fonctionnalités peuvent être fournies par plusieurs packages, comme les bibliothèques openGL.

Voir Section « Infrastructure pour les packages virtuels » pour plus d'informations sur les packages virtuels.

Enfin, voici la partie la plus difficile. Créer un fichier nommé libfoo.mk. Il décrit comment le paquet doit être téléchargé, configuré, construit, installé, etc.

Selon le type de package, le fichier .mk doit être écrit de manière différente, en utilisant différentes infrastructures :

• Makefiles pour les packages génériques (n'utilisant pas les autotools ou CMake) : ils sont basés sur une infrastructure similaire à celle utilisée pour les packages basés sur les autotools, mais nécessitent un peu plus de travail de la part du développeur. Ils spécifient ce qui doit être fait pour la configuration, la compilation et l'installation du paquet. Cette infrastructure doit être utilisée pour tous les packages qui n'utilisent pas les autotools comme système de construction. À l'avenir, d'autres infrastructures spécialisées pourraient être écrites pour d'autres systèmes de construction. buildroot les couvrons dans un tutoriel et une référence.
• Makefiles pour les logiciels basés sur les autotools (autoconf, automake, etc.) : buildroot fournit une infrastructure dédiée pour de tels packages, car les autotools sont un système de construction très courant. Cette infrastructure doit être utilisée pour les nouveaux packages qui s'appuient sur les autotools comme système de construction. buildroot les couvrons à travers un tutoriel et une référence.
• Makefiles pour les logiciels basés sur cmake: buildroot fournit une infrastructure dédiée pour de tels packages, car CMake est un système de construction de plus en plus utilisé et a un comportement standardisé. Cette infrastructure doit être utilisée pour les nouveaux packages qui reposent sur CMake. buildroot les couvrons à travers un tutoriel et une référence.
• Makefiles pour les modules Python: buildroot a une infrastructure dédiée pour les modules Python qui utilisent soit le distutils ou le mécanisme setuptools. buildroot les couvrons à travers un tutoriel et une référence.
• Makefiles pour les modules Lua : buildroot a une infrastructure dédiée pour les modules Lua disponible sur le site Web LuaRocks. buildroot les couvrons à travers un tutoriel et une référence.

Plus de précisions sur la mise en forme : voir les règles d'écriture.

Lorsque cela est possible, ajouter un troisième fichier, nommé libfoo.hash, qui contient les hachages des fichiers téléchargés pour le paquet libfoo. La seule raison de ne pas ajouter de fichier .hash est lorsque la vérification du hachage n'est pas possible en raison de la façon dont le package est téléchargé.

Lorsqu'un paquet a un choix de sélection de version, le fichier de hachage peut être stocké dans un sous-répertoire nommé d'après la version, par ex. package/libfoo/1.2.3/libfoo.hash. Ceci est particulièrement important si les différentes versions ont des termes de licence différents, mais qu'elles sont stockées dans le même fichier. Sinon, le fichier de hachage doit rester dans le répertoire du package.

Les hachages stockés dans ce fichier sont utilisés pour valider l'intégrité des fichiers téléchargés et des fichiers de licence.

Le format de ce fichier est d'une ligne pour chaque fichier pour lequel vérifier le hachage, chaque ligne avec les trois champs suivants séparés par deux espaces :

• le type de hachage, l'un des suivants :
  • md5, sha1, sha224, sha256, sha384, sha512, aucun
• le hash du fichier :
  • pour aucun, un ou plusieurs caractères sans espace, généralement juste la chaîne xxx
  • pour md5, 32 caractères hexadécimaux
  • pour sha1, 40 caractères hexadécimaux
  • pour sha224, 56 caractères hexadécimaux
  • pour sha256, 64 caractères hexadécimaux
  • pour sha384, 96 caractères hexadécimaux
  • pour sha512, 128 caractères hexadécimaux
• le nom du fichier :
  • pour une archive source : le nom de base du fichier, sans élément de répertoire,
  • pour un fichier de licence : le chemin tel qu'il apparaît dans FOO_LICENSE_FILES.

Les lignes commençant par un signe # sont considérées comme des commentaires et ignorées. Les lignes vides sont ignorées.

Il peut y avoir plusieurs hachages pour un même fichier, chacun sur sa propre ligne. Dans ce cas, tous les hachages doivent correspondre.

Le type de hachage none est réservé aux archives téléchargées depuis un référentiel, comme un clone git, un checkout subversion…

L'exemple ci-dessous définit un sha1 et un sha256 publiés par l'amont pour l'archive principale libfoo-1.2.3.tar.bz2, un md5 de l'amont et un hachage sha256 calculé localement pour un blob binaire, un sha256 pour un patch téléchargé, et une archive sans hachage :

# Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
sha1  486fb55c3efa71148fe07895fd713ea3a5ae343a  libfoo-1.2.3.tar.bz2
sha256  efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369  libfoo-1.2.3.tar.bz2

# md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
md5  2d608f3c318c6b7557d551a5a09314f03452f1a1  libfoo-data.bin
sha256  01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b  libfoo-data.bin

# Locally computed:
sha256  ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9  libfoo-fix-blabla.patch

# No hash for 1234:
none  xxx  libfoo-1234.tar.gz

# Hash for license files:
sha256  a45a845012742796534f7e91fe623262ccfb99460a2bd04015bd28d66fba95b8  COPYING
sha256  01b1f9f2c8ee648a7a596a1abe8aa4ed7899b1c9e5551bda06da6e422b04aa55  doc/COPYING.LGPL

Si le fichier .hash est présent et qu'il contient un ou plusieurs hachages pour un fichier téléchargé, le ou les hachages calculés par Buildroot (après le téléchargement) doivent correspondre au(x) hachage(s) stocké(s) dans le fichier .hash. Si un ou plusieurs hachages ne correspondent pas, Buildroot considère qu'il s'agit d'une erreur, supprime le fichier téléchargé et abandonne.

Si le fichier .hash est présent, mais qu'il ne contient pas de hachage pour un fichier téléchargé, Buildroot considère qu'il s'agit d'une erreur et abandonne. Cependant, le fichier téléchargé est laissé dans le répertoire de téléchargement car cela indique généralement que le fichier .hash est erroné mais que le fichier téléchargé est probablement correct.

Les hachages sont actuellement vérifiés pour les fichiers extraits des serveurs http/ftp, des référentiels Git, des fichiers copiés à l'aide de scp et des fichiers locaux. Les hachages ne sont pas vérifiés pour les autres systèmes de contrôle de version (tels que Subversion, CVS, etc.) car Buildroot ne génère actuellement pas de fichiers reproductibles.tarballs lorsque le code source est extrait de ces systèmes de contrôle de version.

Les hachages ne doivent être ajoutés dans les fichiers .hash que pour les fichiers dont la stabilité est garantie. Par exemple, les correctifs générés automatiquement par Github ne sont pas garantis stables et, par conséquent, leurs hachages peuvent changer au fil du temps. Ces correctifs ne doivent pas être téléchargés, mais plutôt ajoutés localement au dossier du package.

Si le fichier .hash est manquant, aucune vérification n'est effectuée.

Tous les packages dont le système de construction n'est pas l'un des systèmes standard, tels que autotools ou CMake, peuvent être inclus avec l'infrastructure pour les packages Génériques. Cela inclut généralement les packages dont le système de construction est basé sur des Makefiles écrits à la main ou des scripts shell.

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_LICENSE = GPL-3.0+
11: LIBFOO_LICENSE_FILES = COPYING
12: LIBFOO_INSTALL_STAGING = YES
13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
15:
16: define LIBFOO_BUILD_CMDS
17:     $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
18: endef
19:
20: define LIBFOO_INSTALL_STAGING_CMDS
21:     $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
22:     $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
23:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
24: endef
25:
26: define LIBFOO_INSTALL_TARGET_CMDS
27:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
28:     $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
29: endef
30:
31: define LIBFOO_USERS
32:     foo -1 libfoo -1 * - - - LibFoo daemon
33: endef
34:
35: define LIBFOO_DEVICES
36:     /dev/foo c 666 0 0 42 0 - - -
37: endef
38:
39: define LIBFOO_PERMISSIONS
40:     /bin/foo f 4755 foo libfoo - - - - -
41: endef
42:
43: $(eval $(generic-package))

Le Makefile commence:

• Aux lignes 7 à 11 avec des informations de métadonnées : la version du paquet (LIBFOO_VERSION), le nom de l'archive contenant le paquet (LIBFOO_SOURCE) (archive xz-ed recommandée) l'emplacement Internet à partir duquel l'archive peut être téléchargée à partir de (LIBFOO_SITE), la licence (LIBFOO_LICENSE) et le fichier avec le texte de la licence (LIBFOO_LICENSE_FILES). Toutes les variables doivent commencer par le même préfixe, LIBFOO_ dans ce cas. Ce préfixe est toujours la version majuscule du nom du package (voir ci-dessous pour comprendre où le nom du package est défini).
• À la ligne 12, on spécifie que ce paquet veut installer quelque chose dans l'espace de staging. Ceci est souvent nécessaire pour les bibliothèques, car elles doivent installer des fichiers d'en-tête et d'autres fichiers de développement dans l'espace de staging. Cela garantira que les commandes répertoriées dans la variable LIBFOO_INSTALL_STAGING_CMDS seront exécutées.
• À la ligne 13, on spécifie qu'il y a des corrections à apporter à certains des fichiers libfoo-config qui ont été installés pendant la phase LIBFOO_INSTALL_STAGING_CMDS. Ces fichiers *-config sont des fichiers de script shell exécutables situés dans le répertoire $(STAGING_DIR)/usr/bin et sont exécutés par d'autres packages tiers pour connaître l'emplacement et les indicateurs de liaison de ce package particulier.

Le problème est que tous ces fichiers *-config donnent par défaut des drapeaux de liaison au système hôte erronés qui ne conviennent pas à la compilation croisée.

Par exemple : -I/usr/include instead of -I$(STAGING_DIR)/usr/include ou: -L/usr/lib instead of -L$(STAGING_DIR)/usr/lib

Donc, un peu de magie sed est faite à ces scripts pour leur faire donner des drapeaux corrects. L'argument à donner à LIBFOO_CONFIG_SCRIPTS est le ou les noms de fichier du ou des scripts shell à corriger. Tous ces noms sont relatifs à $(STAGING_DIR)/usr/bin et si nécessaire plusieurs noms peuvent être donnés.

De plus, les scripts répertoriés dans LIBFOO_CONFIG_SCRIPTS sont supprimés de $(TARGET_DIR)/usr/bin, car ils ne sont pas nécessaires sur la cible.

Le package divine installe le script shell $(STAGING_DIR)/usr/bin/divine-config.

Donc, sa correction serait:

DIVINE_CONFIG_SCRIPTS = divine-config

Le package imagemagick installe les scripts suivants : $(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config

Donc, sa correction serait:

IMAGEMAGICK_CONFIG_SCRIPTS = \
   Magick-config Magick++-config \
   MagickCore-config MagickWand-config Wand-config

• À la ligne 14, buildroot spécifie la liste des dépendances sur lesquelles repose ce paquet. Ces dépendances sont répertoriées en termes de noms de packages en minuscules, qui peuvent être des packages pour la cible (sans le préfixe host-) ou des packages pour l'hôte (avec le préfixe host-). Buildroot s'assurera que tous ces packages sont construits et installés avant que le package actuel ne démarre sa configuration.

Le reste du Makefile, lignes 16..29, définit ce qui doit être fait aux différentes étapes de la configuration, de la compilation et de l'installation du paquet. LIBFOO_BUILD_CMDS indique les étapes à suivre pour construire le package. LIBFOO_INSTALL_STAGING_CMDS indique les étapes à suivre pour installer le package dans l'espace de staging. LIBFOO_INSTALL_TARGET_CMDS indique les étapes à suivre pour installer le package dans l'espace cible.

Toutes ces étapes reposent sur la variable $(@D), qui contient le répertoire où le code source du package a été extrait.

• Aux lignes 31..33, buildroot définit un utilisateur qui est utilisé par ce paquet (par exemple pour exécuter un démon en tant que non root) (LIBFOO_USERS).
• Aux lignes 35..37, buildroot définit un fichier de nœud de périphérique utilisé par ce paquet (LIBFOO_DEVICES).
• À la ligne 39..41, buildroot définit les autorisations à définir sur des fichiers spécifiques installés par ce package (LIBFOO_PERMISSIONS).
• A la ligne 43, buildroot appelons la fonction generic-package, qui génère, selon les variables définies précédemment, tout le code Makefile nécessaire au fonctionnement du package.

Il existe deux variantes de la cible générique. La macro generic-package est utilisée pour les packages à compiler de manière croisée pour la cible. La macro host-generic-package est utilisée pour les packages hôtes, compilés nativement pour l'hôte. Il est possible d'appeler les deux dans un seul fichier .mk : une fois pour créer les règles pour générer un package cible et une fois pour créer les règles pour générer un package hôte :

$(eval $(generic-package))
$(eval $(host-generic-package))

Cela peut être utile si la compilation du package cible nécessite l'installation de certains outils sur l'hôte. Si le nom du package est libfoo, alors le nom du package pour la cible est également libfoo, tandis que le nom du package pour l'hôte est host-libfoo. Ces noms doivent être utilisés dans les variables DEPENDENCIES des autres packages, s'ils dépendent de libfoo ou host-libfoo.

L'appel à la macro generic-package et/ou host-generic-package doit se trouver à la fin du fichier .mk, après toutes les définitions de variables. L'appel à host-generic-package doit être après l'appel à generic-package, le cas échéant.

Pour le package cible, le package-générique utilise les variables définies par le fichier .mk et préfixées par le nom du package en majuscule : LIBFOO_. host-generic-package utilise les variables HOST_LIBFOO_. Pour certaines variables, si la variable préfixée HOST_LIBFOO_ n'existe pas, l'infrastructure du package utilise la variable correspondante préfixée par LIBFOO_. Ceci est fait pour les variables susceptibles d'avoir la même valeur pour les packages cible et hôte. Voir ci-dessous pour plus de détails.

La liste des variables pouvant être définies dans un fichier .mk pour fournir des informations sur les métadonnées est (en supposant que le nom du package est libfoo) :

Les variables LIBFOO_CPE_ID_ sont un ensemble de variables permettant au package de définir son identifiant CPE. Les variables disponibles sont :

• Si l'une de ces variables est définie, l'infrastructure de package générique suppose que le package fournit des informations CPE valides. Dans ce cas, l'infrastructure de package générique définira LIBFOO_CPE_ID.
• Pour un package hôte, si ses variables LIBFOO_CPE_ID_* ne sont pas définies, il hérite de la valeur de ces variables du package cible correspondant.

La méthode recommandée pour définir ces variables consiste à utiliser la syntaxe suivante :

LIBFOO_VERSION = 2.32

Maintenant, les variables qui définissent ce qui devrait être performé aux différentes étapes du processus de construction.

La meilleure façon de définir ces variables est :

define LIBFOO_CONFIGURE_CMDS
        action 1
        action 2
        action 3
endef

Dans les définitions d'action, on peut utiliser les variables suivantes :

• $(LIBFOO_PKGDIR) contient le chemin d'accès au répertoire contenant les fichiers libfoo.mk et Config.in. Cette variable est utile lorsqu'il est nécessaire d'installer un fichier fourni dans Buildroot, comme un fichier de configuration d'exécution, une image de splashscreen…
• $(@D), qui contient le répertoire dans lequel le code source du package a été décompressé.
• $(LIBFOO_DL_DIR) contient le chemin d'accès au répertoire dans lequel tous les téléchargements effectués par Buildroot pour libfoo sont stockés.
• $(TARGET_CC), $(TARGET_LD), etc. pour obtenir les utilitaires de compilation croisée cibles
• $(TARGET_CROSS) pour obtenir le préfixe de la chaîne d'outils de compilation croisée
• Bien sûr les variables $(HOST_DIR), $(STAGING_DIR) et $(TARGET_DIR) pour installer correctement les packages. Ces variables pointent vers les répertoires global host, staging et target, sauf si la prise en charge des répertoires par package est utilisée, auquel cas elles pointent vers les répertoires hôte, staging et target du package actuel. Dans les deux cas, cela ne fait aucune différence de tdu point de vue du package : il doit simplement utiliser HOST_DIR, STAGING_DIR et TARGET_DIR.

Enfin, on peut également utiliser des hooks. Voir Section « hooks disponibles dans les différentes étapes de construction » pour plus d'informations.

Voyons d'abord comment écrire un fichier .mk pour un package basé sur autotools, avec un exemple :

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_INSTALL_STAGING = YES
11: LIBFOO_INSTALL_TARGET = NO
12: LIBFOO_CONF_OPTS = --disable-shared
13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
14:
15: $(eval $(autotools-package))

• A la ligne 7, on déclare la version du package.
• Aux lignes 8 et 9, on déclare le nom du tarball (xz-ed tarball recommandé) et l'emplacement du tarball sur le Web. Buildroot téléchargera automatiquement l'archive tar depuis cet emplacement.
• À la ligne 10, on dit à Buildroot d'installer le package dans le répertoire intermédiaire. Le répertoire staging, situé dans output/staging/ est le répertoire où tous les packages sont installés, y compris leurs fichiers de développement, etc. Par défaut, les packages ne sont pas installés dans le répertoire staging, car généralement, seules les bibliothèques doivent être installées dans le répertoire intermédiaire : leurs fichiers de développement sont nécessaires pour compiler d'autres bibliothèques ou applications qui en dépendent. De plus, par défaut, lorsque l'installation intermédiaire est activée, les packages sont installés à cet emplacement à l'aide de la commande make install.
• À la ligne 11, on dit à Buildroot de ne pas installer le package dans le répertoire cible. Ce répertoire contient ce qui deviendra le système de fichiers racine exécuté sur la cible. Pour les bibliothèques purement statiques, il n'est pas nécessaire de les installer dans le répertoire cible car elles ne seront pas utilisées à l'exécution. Par défaut, l'installation cible est activée ; définir cette variable sur NO n'est presque jamais nécessaire. Par défaut également, les packages sont installés à cet emplacement à l'aide de la commande make install.
• À la ligne 12, on dit à Buildroot de transmettre une option de configuration personnalisée, qui sera transmise au script ./configure avant de configurer et de construire le package.
• À la ligne 13, on déclare les dépendances, afin qu'elles soient construites avant le démarrage du processus de construction de notre paquet.
• A la ligne ligne 15, on invoque la macro autotools-package qui génère toutes les règles Makefile qui permettent réellement de construire le package.

La macro principale de l'infrastructure du package autotools est autotools-package. Elle est similaire à la macro de package générique. La possibilité d'avoir des packages cible et hôte est également disponible, avec la macro host-autotools-package.

Tout comme l'infrastructure générique, l'infrastructure autotools fonctionne en définissant un certain nombre de variables avant d'appeler la macro autotools-package.

Tout d'abord, toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure générique existent également dans l'infrastructure des autotools : LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

Quelques variables supplémentaires, spécifiques à l'infrastructure des autotools, peuvent également être définies. Beaucoup d'entre eux ne sont utiles que dans des cas très spécifiques, les packages typiques n'en utiliseront donc que quelques-uns.

Avec l'infrastructure autotools, toutes les étapes requises pour créer et installer les packages sont déjà définies, et elles fonctionnent généralement bien pour la plupart des packages basés sur autotools. Cependant, si nécessaire, il est toujours possible de personnaliser ce qui est fait à une étape particulière :

• En ajoutant un hook post-opération (après extraction, patch, configuration, compilation ou installation). Voir Section « hooks disponibles dans les différentes étapes de construction » pour plus de détails.
• En remplaçant l'une des étapes. Par exemple, même si l'infrastructure autotools est utilisée, si le fichier .mk du package définit sa propre variable LIBFOO_CONFIGURE_CMDS, elle sera utilisée à la place de celle par défaut des autotools. Cependant, l'utilisation de cette méthode doit être limitée à des cas très spécifiques. Ne pas l'utiliser dans le cas général.

Voyons d'abord comment écrire un fichier .mk pour un package basé sur CMake, avec un exemple :

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_INSTALL_STAGING = YES
11: LIBFOO_INSTALL_TARGET = NO
12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
14:
15: $(eval $(cmake-package))

• A la ligne 7, on déclare la version du package.
• Aux lignes 8 et 9, on déclare le nom du tarball (xz-ed tarball recommandé) et l'emplacement du tarball sur le Web. Buildroot téléchargera automatiquement l'archive tar depuis cet emplacement.
• À la ligne 10, on dit à Buildroot d'installer le package dans le répertoire intermédiaire. Le répertoire staging, situé dans output/staging/ est le répertoire où tous les packages sont installés, y compris leurs fichiers de développement, etc. Par défaut, les packages ne sont pas installés dans le répertoire staging, car généralement, seules les bibliothèques doivent être installées dans le répertoire intermédiaire : leurs fichiers de développement sont nécessaires pour compiler d'autres bibliothèques ou applications qui en dépendent. De plus, par défaut, lorsque l'installation intermédiaire est activée, les packages sont installés à cet emplacement à l'aide de la commande make install.
• À la ligne 11, on dit à Buildroot de ne pas installer le package dans le répertoire cible. Ce répertoire contient ce qui deviendra le système de fichiers racine exécuté sur la cible. Pour les bibliothèques purement statiques, il n'est pas nécessaire de les installer dans le répertoire cible car elles ne seront pas utilisées à l'exécution. Par défaut, l'installation cible est activée ; définir cette variable sur NO n'est presque jamais nécessaire. Par défaut également, les packages sont installés à cet emplacement à l'aide de la commande make install.
• À la ligne 12, on dit à Buildroot de transmettre des options personnalisées à CMake lors de la configuration du package.
• À la ligne 13, on déclare les dépendances, afin qu'elles soient construites avant le démarrage du processus de construction de notre paquet.
• A la ligne ligne 15, on invoque la macro cmake-package qui génère toutes les règles Makefile qui permettent réellement de construire le package.

La macro principale de l'infrastructure de package CMake est cmake-package. Elle est similaire à la macro de package générique. La capacité à avoir des packages cible et hôte est également disponible, avec la macro host-cmake-package.

Tout comme l'infrastructure générique, l'infrastructure CMake fonctionne en définissant un certain nombre de variables avant d'appeler la macro cmake-package.

Tout d'abord, toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure générique existent également dans l'infrastructure CMake : LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

Quelques variables supplémentaires, spécifiques à l'infrastructure CMake, peuvent également être définies. Beaucoup d'entre eux ne sont utiles que dans des cas très spécifiques, les packages typiques n'en utiliseront donc que quelques-uns.

Avec l'infrastructure CMake, toutes les étapes nécessaires pour créer et installer les packages sont déjà définies et fonctionnent généralement bien pour la plupart des packages basés sur CMake. Cependant, si nécessaire, il est toujours possible de personnaliser ce qui est fait à une étape particulière :

• En ajoutant un hook post-opération (après extraction, patch, configuration, compilation ou installation). Voir Section « hooks disponibles dans les différentes étapes de construction » pour plus de détails.
• En remplaçant l'une des étapes. Par exemple, même si l'infrastructure CMake est utilisée, si le fichier .mk du package définit sa propre variable LIBFOO_CONFIGURE_CMDS, elle sera utilisée à la place de celle par défaut de CMake. Cependant, l'utilisation de cette méthode doit être limitée à des cas très spécifiques. Ne pas l'utiliser dans le cas général.

Cette infrastructure s'applique aux packages Python qui utilisent le mécanisme standard Python setuptools comme système de construction, généralement reconnaissable à l'utilisation d'un script setup.py.

Voyons d'abord comment écrire un fichier .mk pour un package Python, avec un exemple :

01: ################################################################################
02: #
03: # python-foo
04: #
05: ################################################################################
06:
07: PYTHON_FOO_VERSION = 1.0
08: PYTHON_FOO_SOURCE = python-foo-$(PYTHON_FOO_VERSION).tar.xz
09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
10: PYTHON_FOO_LICENSE = BSD-3-Clause
11: PYTHON_FOO_LICENSE_FILES = LICENSE
12: PYTHON_FOO_ENV = SOME_VAR=1
13: PYTHON_FOO_DEPENDENCIES = libmad
14: PYTHON_FOO_SETUP_TYPE = distutils
15:
16: $(eval $(python-package))

• A la ligne 7, buildroot déclarer la version du package.
• Sur la ligne 8 et 9, on déclare le nom du tarball (xz-ed tarball recommandé) et l'emplacement du tarball sur le Web. Buildroot téléchargera automatiquement l'archive tar depuis cet emplacement.
• Aux lignes 10 et 11, on donne des détails de licence sur le paquet (sa licence à la ligne 10 et le fichier contenant le texte de la licence à la ligne 11).
• À la ligne 12, on dit à Buildroot de transmettre des options personnalisées au script Python setup.py lors de la configuration du package.
• À la ligne 13, on déclare les dépendances, afin qu'elles soient construites avant le démarrage du processus de construction de notre paquet.
• À la ligne 14, on déclare le système de construction Python spécifique utilisé. Dans ce cas, le système de construction Python distutils est utilisé. Les deux pris en charge sont distutils et setuptools.
• A la ligne 16, on invoque la macro python-package qui génère toutes les règles Makefile qui permettent réellement de construire le package.

En règle générale, les packages qui fournissent simplement des modules Python doivent tous être nommés python-<something> dans Buildroot. D'autres packages qui utilisent le système de construction Python, mais ne sont pas des modules Python, peuvent choisir librement leur nom (les exemples existants dans Buildroot sont scons et superviseur).

Les packages qui ne sont compatibles qu'avec une seule version de Python (comme dans : Python 2 ou Python 3) doivent dépendre explicitement de cette version dans leur fichier Config.in (BR2_PACKAGE_PYTHON pour Python 2, BR2_PACKAGE_PYTHON3 pour Python 3). Les packages compatibles avec les deux versions ne doivent pas en dépendre explicitement dans leur fichier Config.in, puisque cette condition est déjà exprimée pour tout le menu “External python modules”.

La macro principale de l'infrastructure de packages Python est python-package. Elle est similaire à la macro de package générique. Il est également possible de créer des packages hôtes Python avec la macro host-python-package.

Tout comme l'infrastructure générique, l'infrastructure Python fonctionne en définissant un certain nombre de variables avant d'appeler les macros python-package ou host-python-package.

Toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure de package générique existent également dans l'infrastructure Python : PYTHON_FOO_VERSION, PYTHON_FOO_SOURCE, PYTHON_FOO_PATCH, PYTHON_FOO_SITE, PYTHON_FOO_SUBDIR, PYTHON_FOO_DEPENDENCIES, PYTHON_FOO_LICENSE, PYTHON_FOO_LICENSE_FILES, PYTHON_FOO_INSTALL, etc.

Une variable spécifique à l'infrastructure Python est obligatoire :

Quelques variables supplémentaires, spécifiques à l'infrastructure Python, peuvent éventuellement être définies, en fonction des besoins du package. Beaucoup d'entre eux ne sont utiles que dans des cas très spécifiques, les packages typiques n'en utiliseront donc que quelques-uns, voire aucun.

Avec l'infrastructure Python, toutes les étapes requises pour créer et installer les packages sont déjà définies et fonctionnent généralement bien pour la plupart des packages basés sur Python. Cependant, si nécessaire, il est toujours possible de personnaliser ce qui est fait à une étape particulière :

• En ajoutant un hook post-opération (après extraction, patch, configuration, compilation ou installation). Voir Section « hooks disponibles dans les différentes étapes de construction » pour plus de détails.
• En remplaçant l'une des étapes. Par exemple, même si l'infrastructure Python est utilisée, si le fichier .mk du package définit sa propre variable PYTHON_FOO_BUILD_CMDS, elle sera utilisée à la place de celle Python par défaut. Cependant, l'utilisation de cette méthode doit être limitée à des cas très spécifiques. Ne pas l'utiliser dans le cas général.

Si le package Python pour lequel on souhaite créer un package Buildroot est disponible sur PyPI, on peut utiliser l'outil scanpypi situé dans utils/ pour automatiser le processus.

on peut trouver la liste des packages PyPI existants ici.

scanpypi nécessite que le package setuptools de Python soit installé sur l'hôte.

Lorsqu'on est à la racine du répertoire buildroot, faire simplement :

utils/scanpypi foo bar -o paquet

Cela générera les packages python-foo et python-bar dans le dossier du package s'ils existent sur https://pypi.python.org.

Trouver le menu des modules python externes et insérer le package à l'intérieur (les éléments d'un menu doivent être classés par ordre alphabétique).

Il faudra très probablement vérifier manuellement le paquet pour toute erreur car il y a des choses qui ne peuvent pas être devinées par le générateur (par exemple, des dépendances sur l'un des modules de base python tels que BR2_PACKAGE_PYTHON_ZLIB). La licence et les fichiers de licence sont devinés et doivent être vérifiés. Il faut également ajouter manuellement le package au fichier package/Config.in.

Si le package Buildroot n'est pas dans l'arborescence officielle Buildroot mais dans une arborescence externe br2, utiliser l'indicateur -o comme suit :

utils/scanpypi foo bar -o other_package_dir

Cela générera des packages python-foo et python-bar dans other_package_directory au lieu de package.

L'option -h listera les options disponibles :

utils/scanpypi -h

C Foreign Function Interface for Python (CFFI) fournit un moyen pratique et fiable d'appeler du code C compilé à partir de Python à l'aide de déclarations d'interface écrites en C. Les packages Python reposant sur ce backend peuvent être identifiés par l'apparition d'une dépendance cffi dans le champ install_requires de leur fichier setup.py.

Un tel paquet nécessite :

• ajout python-cffi en tant que dépendance d'exécution afin d'installer le wrapper de la bibliothèque C compilée sur la cible. Ceci est réalisé en ajoutant select BR2_PACKAGE_PYTHON_CFFI au package Config.in.

config BR2_PACKAGE_PYTHON_FOO
        bool "python-foo"
        select BR2_PACKAGE_PYTHON_CFFI # runtime

• ajout host-python-cffi en tant que dépendance au moment de la construction afin de cross-compiler le wrapper C. Ceci est réalisé en ajoutant host-python-cffi à la variable PYTHON_FOO_DEPENDENCIES.

################################################################################
#
# python-foo
#
################################################################################

...

PYTHON_FOO_DEPENDENCIES = host-python-cffi

$(eval $(python-package))

Voyons d'abord comment écrire un fichier .mk pour un package basé sur LuaRocks, avec un exemple :

01: ################################################################################
02: #
03: # lua-foo
04: #
05: ################################################################################
06:
07: LUA_FOO_VERSION = 1.0.2-1
08: LUA_FOO_NAME_UPSTREAM = foo
09: LUA_FOO_DEPENDENCIES = bar
10:
11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
13: LUA_FOO_LICENSE = luaFoo license
14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
15:
16: $(eval $(luarocks-package))

• A la ligne 7, on déclare la version du paquet (la même que dans la rockspec, qui est la concaténation de la version amont et de la révision rockspec, séparées par un trait d'union -).
• A la ligne 8, on déclare que le paquet s'appelle “foo” sur LuaRocks. Dans Buildroot, buildroot donnons aux packages liés à Lua un nom qui commence par “lua”, de sorte que le nom Buildroot est différent du nom en amont. LUA_FOO_NAME_UPSTREAM fait le lien entre les deux noms.
• À la ligne 9, on déclare les dépendances vis-à-vis des bibliothèques natives, afin qu'elles soient construites avant le démarrage du processus de construction de notre paquet.
• Aux lignes 11-12, on dit à Buildroot de transmettre les options personnalisées à LuaRocks lors de la construction du package.
• Aux lignes 13 et 14, on spécifie les conditions de licence du package.
• A la ligne 16, on invoque la macro luarocks-package qui génère toutes les règles Makefile qui permettent réellement de construire le package.

La plupart de ces détails peuvent être récupérés à partir de la roche et de la roche. Ainsi, ce fichier et le fichier Config.in peuvent être générés en exécutant la commande luarocks buildroot foo lua-foo dans le répertoire Buildroot. Cette commande exécute un addon Buildroot spécifique de luarocks qui générera automatiquement un package Buildroot. Le résultat doit encore être inspecté manuellement et éventuellement modifié.

• Le fichier package/Config.in doit être mis à jour manuellement pour inclure les fichiers Config.in générés.

LuaRocks est un système de déploiement et de gestion pour les modules Lua, et prend en charge divers build.type : builtin, make et cmake. Dans le contexte de Buildroot, l'infrastructure luarocks-package ne prend en charge que le mode intégré. Les packages LuaRocks qui utilisent les mécanismes de construction make ou cmake doivent plutôt être empaquetés à l'aide des infrastructures generic-package et cmake-package dans Buildroot, respectivement.

La macro principale de l'infrastructure de paquets LuaRocks est luarocks-package : comme generic-package, elle fonctionne en définissant un certain nombre de variables fournissant des informations de métadonnées sur le paquet, puis en appelant luarocks-package.

Tout comme l'infrastructure générique, l'infrastructure LuaRocks fonctionne en définissant un certain nombre de variables avant d'appeler la macro luarocks-package.

Tout d'abord, toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure générique existent également dans l'infrastructure LuaRocks : LUA_FOO_VERSION, LUA_FOO_SOURCE, LUA_FOO_SITE, LUA_FOO_DEPENDENCIES, LUA_FOO_LICENSE, LUA_FOO_LICENSE_FILES.

Deux d'entre eux sont peuplés par l'infrastructure LuaRocks (pour l'étape de téléchargement). Si le package n'est pas hébergé sur le miroir LuaRocks $(BR2_LUAROCKS_MIRROR), on peut les remplacer :

Quelques variables supplémentaires, spécifiques à l'infrastructure LuaRocks, sont également définies. Ils peuvent être annulés dans des cas spécifiques.

Voyons d'abord comment écrire un fichier .mk pour un package Perl/CPAN, avec un exemple :

01: ################################################################################
02: #
03: # perl-foo-bar
04: #
05: ################################################################################
06:
07: PERL_FOO_BAR_VERSION = 0.02
08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
13: PERL_FOO_BAR_DISTNAME = Foo-Bar
14:
15: $(eval $(perl-package))

• A la ligne 7, on déclare la version du package.
• Aux lignes 8 et 9, on déclare le nom du tarball et l'emplacement du tarball sur un serveur CPAN. Buildroot téléchargera automatiquement l'archive tar depuis cet emplacement.
• À la ligne 10, on déclare les dépendances, afin qu'elles soient construites avant le démarrage du processus de construction de notre paquet.
• Aux lignes 11 et 12, on donne des détails de licence sur le paquet (sa licence à la ligne 11 et le fichier contenant le texte de la licence à la ligne 12).
• A la ligne 13, le nom de la distribution tel que requis par le script utils/scancpan (afin de régénérer/mettre à jour ces fichiers de package).
• A la ligne 15, on invoque la macro perl-package qui génère toutes les règles Makefile qui permettent réellement de construire le paquet.

La plupart de ces données peuvent être récupérées sur https://metacpan.org/. Ainsi, ce fichier et le Config.in peuvent être générés en exécutant le script utils/scancpan Foo-Bar dans le répertoire Buildroot (ou dans une arborescence externe br2). Ce script crée un fichier Config.in et un fichier foo-bar.mk pour le package demandé, ainsi que de manière récursive pour toutes les dépendances spécifiées par CPAN. Il faut toujours modifier manuellement le résultat. En particulier, les éléments suivants doivent être vérifiés.

• Si le module perl est lié à une bibliothèque partagée fournie par un autre package (non-perl), cette dépendance n'est pas ajoutée automatiquement. Il a à ajouter manuellement à PERL_FOO_BAR_DEPENDENCIES.
• Le fichier package/Config.in doit être mis à jour manuellement pour inclure les fichiers Config.in générés. À titre indicatif, le script scancpan imprime les instructions source “…” requises, triées par ordre alphabétique.

En règle générale, les packages qui fournissent des modules Perl/CPAN doivent tous être nommés perl-<quelque chose> dans Buildroot.

Cette infrastructure gère différents systèmes de build Perl : ExtUtils-MakeMaker (EUMM), Module-Build (MB) et Module-Build-Tiny. Build.PL est préféré par défaut lorsqu'un package fournit un Makefile.PL et un Build.PL.

La macro principale de l'infrastructure de paquets Perl/CPAN est perl-package. Elle est similaire à la macro de package générique. La possibilité d'avoir des packages cible et hôte est également disponible, avec la macro host-perl-package.

Tout comme l'infrastructure générique, l'infrastructure Perl/CPAN fonctionne en définissant un certain nombre de variables avant d'appeler la macro perl-package.

Tout d'abord, toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure générique existent également dans l'infrastructure Perl/CPAN : PERL_FOO_VERSION, PERL_FOO_SOURCE, PERL_FOO_PATCH, PERL_FOO_SITE, PERL_FOO_SUBDIR, PERL_FOO_DEPENDENCIES, PERL_FOO_INSTALL_TARGET.

Quelques variables supplémentaires, spécifiques à l'infrastructure Perl/CPAN, peuvent également être définies. Beaucoup d'entre eux ne sont utiles que dans des cas très spécifiques, les packages typiques n'en utiliseront donc que quelques-uns.

Dans Buildroot, un package virtuel est un package dont les fonctionnalités sont fournies par un ou plusieurs packages, appelés fournisseurs. La gestion virtuelle des paquets est un mécanisme extensible permettant à l'utilisateur de choisir le fournisseur utilisé dans le rootfs.

Par exemple, OpenGL ES est une API pour les graphiques 2D et 3D sur les systèmes embarqués. L'implémentation de cette API est différente pour les plates-formes Allwinner Tech Sunxi et Texas Instruments OMAP35xx. Ainsi libgles sera un package virtuel et sunxi-mali et ti-gfx seront les fournisseurs.

Dans l'exemple suivant, buildroot expliquerons comment ajouter un nouveau paquet virtuel (something-virtual) et un fournisseur pour celui-ci (some-provider).

Commençons par créer le package virtuel.

Le fichier Config.in du package virtuel Something-Virtual doit contenir :

01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
02:     bool
03:
04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
05:     depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
06:     string

Dans ce fichier, on déclare deux options, BR2_PACKAGE_HAS_SOMETHING_VIRTUAL et BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL, dont les valeurs seront utilisées par les fournisseurs.

Le .mk du package virtuel doit juste évaluer la macro du package virtuel :

01: ################################################################################
02: #
03: # something-virtual
04: #
05: ################################################################################
06:
07: $(eval $(virtual-package))

La possibilité d'avoir des packages cible et hôte est également disponible, avec la macro host-virtual-package.

Lors de l'ajout d'un package en tant que fournisseur, seul le fichier Config.in nécessite quelques modifications.

Le fichier Config.in du package some-provider, qui fournit les fonctionnalités de Something-Virtual, doit contenir :

01: config BR2_PACKAGE_SOME_PROVIDER
02:     bool "some-provider"
03:     select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
04:     help
05:       This is a comment that explains what some-provider is.
06:
07:       http://foosoftware.org/some-provider/
08:
09: if BR2_PACKAGE_SOME_PROVIDER
10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
11:     default "some-provider"
12: endif

• À la ligne 3, buildroot sélectionnons BR2_PACKAGE_HAS_SOMETHING_VIRTUAL, et * à la ligne 11, buildroot définit la valeur de BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL sur le nom du fournisseur, mais uniquement s'il est sélectionné.

Le fichier .mk doit également déclarer une variable supplémentaire SOME_PROVIDER_PROVIDES pour contenir les noms de tous les packages virtuels dont il est une implémentation :

01: SOME_PROVIDER_PROVIDES = something-virtual

Bien sûr, il faut d'ajouter les dépendances de construction et d'exécution appropriées pour ce paquet !

Lors de l'ajout d'un package qui nécessite une certaine FEATURE fournie par un package virtuel, utiliser depend on BR2_PACKAGE_HAS_FEATURE, comme ceci :

config BR2_PACKAGE_HAS_FEATURE
    bool

config BR2_PACKAGE_FOO
    bool "foo"
    depends on BR2_PACKAGE_HAS_FEATURE

Si le paquet nécessite vraiment un fournisseur spécifique, alors il faut faire en sorte que le paquet dépende de ce fournisseur ; on ne peut pas sélectionner un fournisseur.

Prenons un exemple avec deux fournisseurs pour une FEATURE :

config BR2_PACKAGE_HAS_FEATURE
    bool

config BR2_PACKAGE_FOO
    bool "foo"
    select BR2_PACKAGE_HAS_FEATURE

config BR2_PACKAGE_BAR
    bool "bar"
    select BR2_PACKAGE_HAS_FEATURE

Et on ajoute un paquet qui a besoin de FEATURE comme fourni par foo, mais pas comme fourni par bar.

Si on devait utiliser select BR2_PACKAGE_FOO, l'utilisateur pourrait toujours sélectionner BR2_PACKAGE_BAR dans le menuconfig. Cela créerait une incohérence de configuration, dans laquelle deux fournisseurs de la même FEATURE seraient activés à la fois, l'un défini explicitement par l'utilisateur, l'autre implicitement par la sélection.

Au lieu de cela, utiliser depends on BR2_PACKAGE_FOO, ce qui évite toute incohérence de configuration implicite.

Un moyen populaire pour un progiciel de gérer la configuration spécifiée par l'utilisateur est kconfig. Entre autres, il est utilisé par le noyau Linux, Busybox et Buildroot lui-même. La présence d'un fichier .config et d'une cible menuconfig sont deux symptômes bien connus de l'utilisation de kconfig.

Buildroot propose une infrastructure pour les packages qui utilisent kconfig pour leur configuration. Cette infrastructure fournit la logique nécessaire pour exposer la cible menuconfig du package en tant que foo-menuconfig dans Buildroot et pour gérer correctement la copie dans les deux sens du fichier de configuration.

L'infrastructure du package kconfig est basée sur l'infrastructure du package générique. Toutes les variables prises en charge par generic-package sont également disponibles dans kconfig-package. Voir Section « référence de paquetage générique » pour plus de détails.

Afin d'utiliser l'infrastructure kconfig-package pour un package Buildroot, les lignes minimales requises dans le fichier .mk, en plus des variables requises par l'infrastructure de package générique, sont :

FOO_KCONFIG_FILE = reference-to-source-configuration-file

$(eval $(kconfig-package))

Cet extrait crée les cibles make suivantes :

• foo-menuconfig, qui appelle la cible menuconfig du paquet
• foo-update-config, qui copie la configuration dans le fichier de configuration source. Il n'est pas possible d'utiliser cette cible lorsque des fichiers fragmentés sont définis.
• foo-update-defconfig, qui copie la configuration dans le fichier de configuration source. Le fichier de configuration répertorie uniquement les options qui diffèrent des valeurs par défaut. Il n'est pas possible d'utiliser cette cible lorsque des fichiers fragmentés sont définis.
• foo-diff-config, qui affiche les différences entre la configuration actuelle et celle définie dans la configuration Buildroot pour ce package kconfig. La sortie est utile pour identifier les changements de configuration qui peuvent devoir être propagés aux fragments de configuration par exemple.

et s'assure que le fichier de configuration source est copié dans le répertoire de construction au bon moment.

Il existe deux options pour spécifier un fichier de configuration à utiliser, soit FOO_KCONFIG_FILE (comme dans l'exemple ci-dessus) ou FOO_KCONFIG_DEFCONFIG. Il est obligatoire de fournir soit, mais pas les deux :

• FOO_KCONFIG_FILE spécifie le chemin d'accès à un fichier defconfig ou full-config à utiliser pour configurer le package.
• FOO_KCONFIG_DEFCONFIG spécifie la règle de defconfig make à appeler pour configurer le package.

En plus de ces lignes minimalement requises, plusieurs variables facultatives peuvent être définies pour répondre aux besoins du package considéré :

Voyons d'abord comment écrire un fichier .mk pour un package basé sur les erlang, avec un exemple :

01: ################################################################################
02: #
03: # erlang-foobar
04: #
05: ################################################################################
06:
07: ERLANG_FOOBAR_VERSION = 1.0
08: ERLANG_FOOBAR_SOURCE = erlang-foobar-$(ERLANG_FOOBAR_VERSION).tar.xz
09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download
10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb
11:
12: $(eval $(rebar-package))

• A la ligne 7, on déclare la version du package.
• Aux lignes 8 et 9, on déclare le nom du tarball (xz-ed tarball recommandé) et l'emplacement du tarball sur le Web. Buildroot téléchargera automatiquement l'archive tar depuis cet emplacement.
• À la ligne 10, on déclare les dépendances, afin qu'elles soient construites avant le démarrage du processus de construction de notre paquet.
• A la ligne 12, on invoque la macro rebar-package qui génère toutes les règles Makefile qui permettent réellement de construire le package.

La macro principale de l'infrastructure du package rebar est rebar-package. Elle est similaire à la macro de package générique. La possibilité d'avoir des packages hôtes est également disponible, avec la macro host-rebar-package.

Tout comme l'infrastructure générique, l'infrastructure rebar fonctionne en définissant un certain nombre de variables avant d'appeler la macro rebar-package.

Tout d'abord, toutes les variables d'informations sur les métadonnées du package qui existent dans l'infrastructure générique _ ENSEMBLE existent également dans l'infrastructure de rebar :

Quelques variables supplémentaires, spécifiques à l'infrastructure d'armatures, peuvent également être définies. Beaucoup d'entre eux ne sont utiles que dans des cas très spécifiques, les packages typiques n'en utiliseront donc que quelques-uns.

Avec l'infrastructure de erlang, toutes les étapes requises pour créer et installer les packages sont déjà définies, et elles fonctionnent généralement bien pour la plupart des packages basés sur les erlang. Cependant, si nécessaire, il est toujours possible de personnaliser ce qui est fait à une étape particulière :

• En ajoutant un hook post-opération (après extraction, patch, configuration, compilation ou installation). Voir Section « hooks disponibles dans les différentes étapes de construction » pour plus de détails.
• En remplaçant l'une des étapes. Par exemple, même si l'infrastructure de erlang est utilisée, si le fichier .mk du package définit sa propre variable ERLANG_FOOBAR_BUILD_CMDS, elle sera utilisée à la place de la barre d'armature par défaut.une. Cependant, l'utilisation de cette méthode doit être limitée à des cas très spécifiques. Ne pas l'utiliser dans le cas général.

Voyons d'abord comment écrire un fichier .mk pour un package basé sur Waf, avec un exemple :

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_CONF_OPTS = --enable-bar --disable-baz
11: LIBFOO_DEPENDENCIES = bar
12:
13: $(eval $(waf-package))

• A la ligne 7, on déclare la version du package.
• Aux lignes 8 et 9, on déclare le nom du tarball (xz-ed tarball recommandé) et l'emplacement du tarball sur le Web. Buildroot téléchargera automatiquement l'archive tar depuis cet emplacement.
• À la ligne 10, on indique à Buildroot quelles options activer pour libfoo.
• À la ligne 11, on indique à Buildroot les dépendances de libfoo.
• A la ligne ligne 13, on invoque la macro waf-package qui génère toutes les règles Makefile qui permettent réellement de construire le package.

La macro principale de l'infrastructure de paquets Waf est waf-package. Elle est similaire à la macro de package générique.

Tout comme l'infrastructure générique, l'infrastructure Waf fonctionne en définissant un certain nombre de variables avant d'appeler la macro waf-package.

Tout d'abord, toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure générique existent également dans l'infrastructure Waf : LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

Une variable supplémentaire, spécifique à l'infrastructure Waf, peut également être définie.

Meson est un système de construction open source censé être à la fois extrêmement rapide et, plus important encore, aussi convivial que possible. Il utilise Ninja comme outil compagnon pour effectuer les opérations de construction réelles.

Voyons comment écrire un fichier .mk pour un package basé sur Meson, avec un exemple :

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.0
08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
09: FOO_SITE = http://www.foosoftware.org/download
10: FOO_LICENSE = GPL-3.0+
11: FOO_LICENSE_FILES = COPYING
12: FOO_INSTALL_STAGING = YES
13:
14: FOO_DEPENDENCIES = host-pkgconf bar
15:
16: ifeq ($(BR2_PACKAGE_BAZ),y)
17: FOO_CONF_OPTS += -Dbaz=true
18: FOO_DEPENDENCIES += baz
19: else
20: FOO_CONF_OPTS += -Dbaz=false
21: endif
22:
23: $(eval $(meson-package))

Le Makefile commence par la définition des variables standard pour la déclaration des packages (lignes 7 à 11).

• À la ligne ligne 23, on invoque la macro meson-package qui génère toutes les règles Makefile qui permettent réellement de construire le paquet.

Dans l'exemple, host-pkgconf et bar sont déclarés comme dépendances dans FOO_DEPENDENCIES * à la ligne 14 car le fichier de construction Meson de foo utilise pkg-config pour déterminer les drapeaux de compilation et les bibliothèques du paquet bar.

Si le package “baz” est sélectionné, la prise en charge de la fonctionnalité “baz” dans “foo” est activée en ajoutant -Dbaz=true à FOO_CONF_OPTS * à la ligne 17, comme spécifié dans le mefichier son_options.txt dans l'arborescence des sources “foo”. Le package “baz” est également ajouté à FOO_DEPENDENCIES. La prise en charge de base est explicitement désactivée * à la ligne 20, si le package n'est pas sélectionné.

Pour résumer, pour ajouter un nouveau package basé sur meson, l'exemple Makefile peut être copié textuellement puis édité pour remplacer toutes les occurrences de FOO par le nom en majuscule du nouveau package et mettre à jour les valeurs des variables standard.

La macro principale de l'infrastructure de paquets Meson est meson-package. Elle est similaire à la macro de package générique. La possibilité d'avoir des packages cible et hôte est également disponible, avec la macro host-meson-package.

Tout comme l'infrastructure générique, l'infrastructure Meson fonctionne en définissant un certain nombre de variables avant d'appeler la macro meson-package.

Tout d'abord, toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure générique existent également dans l'infrastructure Meson : FOO_VERSION, FOO_SOURCE, FOO_PATCH, FOO_SITE, FOO_SUBDIR, FOO_DEPENDENCIES, FOO_INSTALL_STAGING, FOO_INSTALL_TARGET.

Quelques variables supplémentaires, spécifiques à l'infrastructure Meson, peuvent également être définies. Beaucoup d'entre eux ne sont utiles que dans des cas très spécifiques, les packages typiques n'en utiliseront donc que quelques-uns.

Cargo est le gestionnaire de paquets pour le langage de programmation Rust. Il permet à l'utilisateur de construire des programmes ou des bibliothèques écrits en Rust, mais il télécharge et gère également leurs dépendances, pour assurer des constructions reproductibles. Les colis de fret sont appelés “caisses”.

Le fichier Config.in du package foo basé sur Cargo doit contenir :

01: config BR2_PACKAGE_FOO
02:     bool "foo"
03:     depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS
04:     select BR2_PACKAGE_HOST_RUSTC
05:     help
06:       This is a comment that explains what foo is.
07:
08:       http://foosoftware.org/foo/

Buildroot ne fournit pas (encore) d'infrastructure de packages dédiée aux packages basés sur Cargo. On va donc expliquer comment écrire un fichier .mk pour un tel package. Commençons par un exemple :

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.0
08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
09: FOO_SITE = http://www.foosoftware.org/download
10: FOO_LICENSE = GPL-3.0+
11: FOO_LICENSE_FILES = COPYING
12:
13: FOO_DEPENDENCIES = host-rustc
14:
15: FOO_CARGO_ENV = CARGO_HOME=$(HOST_DIR)/share/cargo
16:
17: FOO_BIN_DIR = target/$(RUSTC_TARGET_NAME)/$(FOO_CARGO_MODE)
18:
19: FOO_CARGO_OPTS = \
20:     $(if $(BR2_ENABLE_DEBUG),,--release) \
21:     --target=$(RUSTC_TARGET_NAME) \
22:     --manifest-path=$(@D)/Cargo.toml
23:
24: define FOO_BUILD_CMDS
25:     $(TARGET_MAKE_ENV) $(FOO_CARGO_ENV) \
26:             cargo build $(FOO_CARGO_OPTS)
27: endef
28:
29: define FOO_INSTALL_TARGET_CMDS
30:     $(INSTALL) -D -m 0755 $(@D)/$(FOO_BIN_DIR)/foo \
31:             $(TARGET_DIR)/usr/bin/foo
32: endef
33:
34: $(eval $(generic-package))

Le Makefile commence par la définition des variables standard pour la déclaration des packages (lignes 7 à 11).

Comme on le voit * à la ligne 34, il est basé sur l'infrastructure des packages génériques. Ainsi, il définit les variables requises par cette infrastructure particulière, où Cargo est invoqué :

• FOO_BUILD_CMDS : Cargo est appelé pour effectuer la construction. Les options nécessaires pour configurer la compilation croisée du package sont passées via FOO_CONF_OPTS.
• FOO_INSTALL_TARGET_CMDS : L'exécutable binaire généré est installé sur la cible.

Afin que Cargo soit disponible pour la construction, FOO_DEPENDENCIES doit contenir host-cargo.

Pour résumer, pour ajouter un nouveau package basé sur Cargo, l'exemple Makefile peut être copié textuellement puis édité pour remplacer toutes les occurrences de FOO par le nom en majuscule du nouveau package et mettre à jour les valeurs des variables standard.

Une caisse peut dépendre d'autres bibliothèques des dépôts crates.io ou git, listées dans son fichier Cargo.toml. Avant de commencer une construction, Cargo les télécharge généralement automatiquement. Cette étape peut également être effectuée indépendamment, via la commande cargo fetch.

Cargo maintient un cache local de l'index de registre et des git checkouts des caisses, dont l'emplacement est donné par $CARGO_HOME. Comme indiqué dans l'exemple Makefile du package * à la ligne 15, cette variable d'environnement est définie sur $(HOST_DIR)/share/cargo.

Ce mécanisme de téléchargement de dépendances n'est pas pratique lors de l'exécution d'une construction hors ligne, car Cargo ne parviendra pas à récupérer les dépendances. Dans ce cas, il est conseillé de générer une archive tar des dépendances à l'aide du fournisseur de fret et de l'ajouter à FOO_EXTRA_DOWNLOADS.

Cette infrastructure s'applique aux packages Go qui utilisent le système de construction standard et utilisent des dépendances groupées.

Voyons d'abord comment écrire un fichier .mk pour un package go, avec un exemple :

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.0
08: FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))
09: FOO_LICENSE = BSD-3-Clause
10: FOO_LICENSE_FILES = LICENSE
11:
12: $(eval $(golang-package))

• A la ligne 7, on déclare la version du package.
• À la ligne 8, on déclare l'emplacement en amont du paquet, ici récupéré sur Github, car un grand nombre de paquets Go sont hébergés sur Github.
• Aux lignes 9 et 10, on donne des détails sur la licence du package.
• A la ligne 12, on invoque la macro golang-package qui génère toutes les règles Makefile qui permettent réellement de construire le package.

Dans leur fichier Config.in, les packages utilisant l'infrastructure golang-package doivent dépendre de BR2_PACKAGE_HOST_GO_TARGET_ARCH_SUPPORTS car Buildroot ajoutera automatiquement une dépendance sur host-go à ces packages. Si on a besoin de la prise en charge de CGO dans le package, ajouter une dépendance sur BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS.

La macro principale de l'infrastructure du package Go est golang-package. Elle est similaire à la macro de package générique. La possibilité de créer des packages hôtes est également disponible, avec la macro host-golang-package. Les packages hôtes créés par la macro host-golang-package doivent dépendre de BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.

Tout comme l'infrastructure générique, l'infrastructure Go fonctionne en définissant un certain nombre de variables avant d'appeler le package golang.

Toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure de package générique existent également dans l'infrastructure Go : FOO_VERSION, FOO_SOURCE, FOO_PATCH, FOO_SITE, FOO_SUBDIR, FOO_DEPENDENCIES, FOO_LICENSE, FOO_LICENSE_FILES, FOO_INSTALL_STAGING, etc.

Quelques variables supplémentaires, spécifiques à l'infrastructure Go, peuvent éventuellement être définies, en fonction des besoins du package. Beaucoup d'entre eux ne sont utiles que dans des cas très spécifiques, les packages typiques n'en utiliseront donc que quelques-uns, voire aucun.

Avec l'infrastructure Go, toutes les étapes nécessaires à la création et à l'installation des packages sont déjà définies et fonctionnent généralement bien pour la plupart des packages basés sur Go. Cependant, si nécessaire, il est toujours possible de personnaliser ce qui est fait à une étape particulière :

• En ajoutant un hook post-opération (après extraction, patch, configuration, compilation ou installation). Voir Section « hooks disponibles dans les différentes étapes de construction » pour plus de détails.
• En remplaçant l'une des étapes. Par exemple, même si l'infrastructure Go est utilisée, si le fichier .mk du package définit sa propre variable FOO_BUILD_CMDS, elle sera utilisée à la place de celle par défaut de Go. Cependant, l'utilisation de cette méthode doit être limitée à des cas très spécifiques. Ne pas l'utiliser dans le cas général.

Voyons d'abord comment écrire un fichier .mk pour un package basé sur QMake, avec un exemple :

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_CONF_OPTS = QT_CONFIG+=bar QT_CONFIG-=baz
11: LIBFOO_DEPENDENCIES = bar
12:
13: $(eval $(qmake-package))

• A la ligne 7, on déclare la version du package.
• Aux lignes 8 et 9, on déclare le nom du tarball (xz-ed tarball recommandé) et l'emplacement du tarball sur le Web. Buildroot téléchargera automatiquement l'archive tar depuis cet emplacement.
• À la ligne 10, on indique à Buildroot quelles options activer pour libfoo.
• À la ligne 11, on indique à Buildroot les dépendances de libfoo.
• A la ligne ligne 13, on invoque la macro qmake-package qui génère toutes les règles Makefile qui permettent réellement de construire le paquet.

La macro principale de l'infrastructure de packages QMake est qmake-package. Elle est similaire à la macro de package générique.

Tout comme l'infrastructure générique, l'infrastructure QMake fonctionne en définissant un certain nombre de variables avant d'appeler la macro qmake-package.

Tout d'abord, toutes les variables d'informations de métadonnées de package qui existent dans l'infrastructure générique existent également dans l'infrastructure QMake : LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

Une variable supplémentaire, spécifique à l'infrastructure QMake, peut également être définie.

Buildroot offre une infrastructure d'assistance pour faciliter l'écriture de packages qui construisent et installent des modules du noyau Linux. Certains packages ne contiennent qu'un module noyau, d'autres packages contiennent des programmes et des bibliothèques en plus des modules noyau. L'infrastructure d'assistance de Buildroot prend en charge les deux cas.

Commençons par un exemple sur la façon de préparer un package simple qui ne construit qu'un module de noyau, et aucun autre composant :

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.2.3
08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
09: FOO_SITE = http://www.foosoftware.org/download
10: FOO_LICENSE = GPL-2.0
11: FOO_LICENSE_FILES = COPYING
12:
13: $(eval $(kernel-module))
14: $(eval $(generic-package))

• Les lignes 7 à 11 définissent les métadonnées habituelles pour spécifier la version, le nom de l'archive, l'URI distant où trouver la source du paquet, les informations de licence.
• À la ligne 13, on invoque l'infrastructure d'assistance du module du noyau, qui génère toutes les règles et variables Makefile appropriées pour construire ce module du noyau.
• A la ligne 14, on invoque l'infrastructure de paquets génériques.

La dépendance à linux est automatiquement ajoutée, il n'est donc pas nécessaire de la spécifier dans FOO_DEPENDENCIES.

Contrairement à d'autres infrastructures de packages, on invoque explicitement une seconde infrastructure. Cela permet à un paquet de construire un module noyau, mais aussi, si nécessaire, d'utiliser n'importe laquelle des autres infrastructures de paquets pour construire des composants utilisateur normaux (bibliothèques, exécutables…). L'utilisation de l'infrastructure noyau-module seule n'est pas suffisante ; une autre infrastructure de package doit être utilisée.

Prenons un exemple plus complexe :

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.2.3
08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
09: FOO_SITE = http://www.foosoftware.org/download
10: FOO_LICENSE = GPL-2.0
11: FOO_LICENSE_FILES = COPYING
12:
13: FOO_MODULE_SUBDIRS = driver/base
14: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED)
15:
16: ifeq ($(BR2_PACKAGE_LIBBAR),y)
17: FOO_DEPENDENCIES = libbar
18: FOO_CONF_OPTS = --enable-bar
19: FOO_MODULE_SUBDIRS += driver/bar
20: else
21: FOO_CONF_OPTS = --disable-bar
22: endif
23:
24: $(eval $(kernel-module))
26: $(eval $(autotools-package))

Ici, on voit que buildroot a un paquet basé sur autotools, qui construit également le module noyau situé dans le sous-répertoire driver/base et, si libbar est activé, le module noyau situé dans le sous-répertoire driver/bar, et définit la variable KVERSION à transmettre au système de construction Linux lors de la construction du ou des modules.

La macro principale pour l'infrastructure du module du noyau est kernel-module. Contrairement à d'autres infrastructures de packages, il n'est pas autonome et nécessite que l'une des autres macros *-package soit appelée après lui.

La macro kernel-module définit les hooks post-build et post-target-install pour construire les modules du noyau. Si le .mk du paquet a besoin d'accéder aux modules du noyau construits, il doit le faire dans un hook post-build, enregistré après l'appel à kernel-module. De même, si le .mk du paquet a besoin d'accéder au module du noyau après son installation, il doit le faire dans un hook post-install, enregistré après l'appel à kernel-module. Voici un exemple :

$(eval $(kernel-module))

define FOO_DO_STUFF_WITH_KERNEL_MODULE
    # Do something with it...
endef
FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE

$(eval $(generic-package))

Enfin, contrairement aux autres infrastructures de paquets, il n'y a pas de variante host-kernel-module pour construire un module noyau hôte.

Les variables supplémentaires suivantes peuvent éventuellement être définies pour configurer davantage la construction du module du noyau :

on peut également référencer (mais on ne peut pas définir !) ces variables :

• LINUX_DIR contient le chemin d'accès à l'endroit où le noyau Linux a été extrait et construit.
• LINUX_VERSION contient la chaîne de version telle que configurée par l'utilisateur.
• LINUX_VERSION_PROBED contient la chaîne de version réelle du noyau, récupérée avec l'exécution de make -C $(LINUX\_DIR) kernelrelease
• KERNEL_ARCH contient le nom de l'architecture actuelle, comme arm, mips…

Bien que Buildroot ne contienne qu'un seul document écrit en AsciiDoc, il existe, comme pour les packages, une infrastructure de rendu des documents utilisant la syntaxe AsciiDoc.

Toujours comme pour les packages, l'infrastructure AsciiDoc est disponible depuis une arborescence externe br2. Cela permet à la documentation d'une arborescence externe br2 de correspondre à la documentation Buildroot, car elle sera rendue dans les mêmes formats et utilisera la même mise en page et le même thème.

Tandis queles infrastructures de package sont suffixées par -package, les infrastructures de document sont suffixées par -document. Ainsi, l'infrastructure AsciiDoc est nommée asciidoc-document.

Voici un exemple pour rendre un document AsciiDoc simple.

01: ################################################################################
02: #
03: # foo-document
04: #
05: ################################################################################
06:
07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
08: $(eval $(call asciidoc-document))

• A la ligne 7, le Makefile déclare quelles sont les sources du document. Actuellement, on s'attend à ce que les sources du document soient uniquement locales ; Buildroot n'essaiera pas de télécharger quoi que ce soit pour rendre un document. Ainsi, indiquer où se trouvent les sources. Habituellement, la chaîne ci-dessus est suffisante pour un document sans structure de sous-répertoires.
• A la ligne 8, on appelle la fonction asciidoc-document, qui génère tout le code Makefile nécessaire pour rendre le document.

La liste des variables qui peuvent être définies dans un fichier .mk pour donner des informations de métadonnées est (en supposant que le nom du document est foo) :

Il existe également des hooks supplémentaires (voir Section « hooks disponibles dans les différentes étapes de construction » pour des informations générales sur les hooks), qu'un document peut définir pour définir des actions supplémentaires à effectuer à différentes étapes :

Voici un exemple complet qui utilise toutes les variables et tous les hooks :

01: ################################################################################
02: #
03: # foo-document
04: #
05: ################################################################################
06:
07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
09:
10: define FOO_GEN_EXTRA_DOC
11:     /path/to/generate-script --outdir=$(@D)
12: endef
13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
14:
15: define FOO_CHECK_MY_PROG
16:     if ! which my-prog >/dev/null 2>&1; then \
17:         echo "You need my-prog to generate the foo document"; \
18:         exit 1; \
19:     fi
20: endef
21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
22:
23: define FOO_CHECK_MY_OTHER_PROG
24:     if ! which my-other-prog >/dev/null 2>&1; then \
25:         echo "You need my-other-prog to generate the foo document as PDF"; \
26:         exit 1; \
27:     fi
28: endef
29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
30:
31: $(eval $(call asciidoc-document))

Le package du noyau Linux peut utiliser certaines infrastructures spécifiques basées sur des hooks de package pour créer des outils du noyau Linux ou/et créer des extensions du noyau Linux.

Buildroot offre une infrastructure d'assistance pour créer des outils d'espace utilisateur pour la cible disponible dans les sources du noyau Linux. Comme leur code source fait partie du code source du noyau, un package spécial, linux-tools, existe et réutilise les sources du noyau Linux qui s'exécute sur la cible.

Regardons un exemple d'outil Linux. Pour un nouvel outil Linux nommé foo, créer une nouvelle entrée de menu dans le package/linux-tools/Config.in existant. Ce fichier contiendra les descriptions d'options liées à chaque outil du noyau qui sera utilisé et affiché dans l'outil de configuration. Cela ressemblerait essentiellement à:

01: config BR2_PACKAGE_LINUX_TOOLS_FOO
02:     bool "foo"
03:     select BR2_PACKAGE_LINUX_TOOLS
04:     help
05:       This is a comment that explains what foo kernel tool is.
06:
07:       http://foosoftware.org/foo/

Le nom de l'option commence par le préfixe BR2_PACKAGE_LINUX_TOOLS_, suivi du nom de l'outil en majuscule (comme c'est le cas pour les packages).

Ensuite, pour chaque outil Linux, ajouter un nouveau fichier .mk.in nommé package/linux-tools/linux-tool-foo.mk.in. Cela ressemblerait essentiellement à:

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: LINUX_TOOLS += foo
08:
09: FOO_DEPENDENCIES = libbbb
10:
11: define FOO_BUILD_CMDS
12:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools foo
13: endef
14:
15: define FOO_INSTALL_STAGING_CMDS
16:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
17:             DESTDIR=$(STAGING_DIR) \
18:             foo_install
19: endef
20:
21: define FOO_INSTALL_TARGET_CMDS
22:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
23:             DESTDIR=$(TARGET_DIR) \
24:             foo_install
25: endef

• À la ligne 7, on enregistre l'outil Linux foo dans la liste des outils Linux disponibles.
• À la ligne 9, on spécifie la liste des dépendances sur lesquelles repose cet outil. Ces dépendances sont ajoutées à la liste des dépendances du package Linux uniquement lorsque l'outil foo est sélectionné.
• Le reste du Makefile, lignes 11-25 définit ce qui doit être fait aux différentes étapes du processus de construction de l'outil Linux comme pour un paquet générique. Ils ne seront en fait utilisés que lorsque l'outil foo est sélectionné. Les seules commandes prises en charge sont _BUILD_CMDS, _INSTALL_STAGING_CMDS et _INSTALL_TARGET_CMDS.

Certains packages fournissent de nouvelles fonctionnalités qui nécessitent la modification de l'arborescence du noyau Linux. Cela peut être sous la forme de correctifs à appliquer sur l'arborescence du noyau, ou sous la forme de nouveaux fichiers à ajouter à l'arborescence. L'infrastructure d'extensions du noyau Linux de Buildroot fournit une solution simple pour le faire automatiquement, juste après l'extraction des sources du noyau et avant l'application des correctifs du noyau. Des exemples d'extensions empaquetées à l'aide de ce mécanisme sont les extensions temps réel Xenomai et RTAI, ainsi que l'ensemble de pilotes d'écrans LCD hors arbre fbtft.

Regardons un exemple sur la façon d'ajouter une nouvelle extension Linux foo.

Tout d'abord, créer le package foo qui fournit l'extension : ce package est un package standard ; voir les chapitres précédents sur la façon de créer un tel package. Ce paquet est en charge du téléchargement de l'archive des sources, de la vérification du hash, de la définition des informations de licence et de la construction des outils de l'espace utilisateur s'il y en a.

Créer ensuite l'extension Linux proprement dite : créer une nouvelle entrée de menu dans le fichier linux/Config.ext.in existant. Ce fichier contient les descriptions d'options liées à chaque extension de noyau qui sera utilisée et affichée dans l'outil de configuration. Cela ressemblerait essentiellement à:

01: config BR2_LINUX_KERNEL_EXT_FOO
02:     bool "foo"
03:     help
04:       This is a comment that explains what foo kernel extension is.
05:
06:       http://foosoftware.org/foo/

Ensuite, pour chaque extension Linux, ajouter un nouveau fichier .mk nommé linux/linux-ext-foo.mk. Il doit essentiellement contenir :

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: LINUX_EXTENSIONS += foo
08:
09: define FOO_PREPARE_KERNEL
10:     $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D)
11: endef

• À la ligne 7, on ajoute l'extension Linux foo à la liste des extensions Linux disponibles.
• Aux lignes 9-11, on définit ce que doit faire l'extension pour modifier l'arborescence du noyau Linux ; celle-ci est spécifique à l'extension linux et peut utiliser les variables définies par le package foo, comme : $(FOO_DIR) ou $(FOO_VERSION)… ainsi que toutes les variables Linux, comme : $(LINUX_VERSION) ou $(LINUX_VERSION_PROBED), $(KERNEL_ARCH)… Voir la définition de ces variables du noyau.

L'infrastructure générique (et par conséquent également les autotools dérivés et les infrastructures cmake) permet aux packages de spécifier des hooks. Ceux-ci définissent d'autres actions à effectuer après les étapes existantes. La plupart des hooks ne sont pas vraiment utiles pour les packages génériques, car le fichier .mk a déjà un contrôle total sur les actions effectuées à chaque étape de la construction du package.

Les points d'accroche suivants sont disponibles :

• LIBFOO_PRE_DOWNLOAD_HOOKS
• LIBFOO_POST_DOWNLOAD_HOOKS
• LIBFOO_PRE_EXTRACT_HOOKS
• LIBFOO_POST_EXTRACT_HOOKS
• LIBFOO_PRE_RSYNC_HOOKS
• LIBFOO_POST_RSYNC_HOOKS
• LIBFOO_PRE_PATCH_HOOKS
• LIBFOO_POST_PATCH_HOOKS
• LIBFOO_PRE_CONFIGURE_HOOKS
• LIBFOO_POST_CONFIGURE_HOOKS
• LIBFOO_PRE_BUILD_HOOKS
• LIBFOO_POST_BUILD_HOOKS
• LIBFOO_PRE_INSTALL_HOOKS (pour les packages hôtes uniquement)
• LIBFOO_POST_INSTALL_HOOKS (pour les packages hôtes uniquement)
• LIBFOO_PRE_INSTALL_STAGING_HOOKS (pour les packages cibles uniquement)
• LIBFOO_POST_INSTALL_STAGING_HOOKS (pour les packages cibles uniquement)
• LIBFOO_PRE_INSTALL_TARGET_HOOKS (pour les packages cibles uniquement)
• LIBFOO_POST_INSTALL_TARGET_HOOKS (pour les packages cibles uniquement)
• LIBFOO_PRE_INSTALL_IMAGES_HOOKS
• LIBFOO_POST_INSTALL_IMAGES_HOOKS
• LIBFOO_PRE_LEGAL_INFO_HOOKS
• LIBFOO_POST_LEGAL_INFO_HOOKS

Ces variables sont des listes de noms de variables contenant des actions à effectuer à ce point de hook. Cela permet d'enregistrer plusieurs hameçons à un point d'hameçon donné. Voici un exemple:

define LIBFOO_POST_PATCH_FIXUP
        action1
        action2
endef

LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP

Le hook POST\\_RSYNC est exécuté uniquement pour les packages qui utilisent une source locale, via la méthode du site local ou le mécanisme OVERRIDE_SRCDIR. Dans ce cas, les sources de package sont copiées à l'aide de rsync depuis l'emplacement local dans le répertoire de construction buildroot. La commande rsync ne copie cependant pas tous les fichiers du répertoire source. Les fichiers appartenant à un système de contrôle de version, comme les répertoires .git, .hg, etc. ne sont pas copiés. Pour la plupart des packages, cela suffit, mais un package donné peut effectuer des actions supplémentaires à l'aide du hook POST_RSYNC.

En principe, le hook peut contenir n'importe quelle commande qu'on veut. Un cas d'utilisation spécifique, cependant, est la copie intentionnelle du répertoire de contrôle de version à l'aide de rsync. La commande rsync qu'onutilise dans le hook peut, entre autres, utiliser les variables suivantes :

• $(SRCDIR): le chemin vers le répertoire source remplacé
• $(@D): le chemin d'accès au répertoire de construction

Les packages peuvent également enregistrer des hooks dans LIBFOO_TARGET_FINALIZE_HOOKS. Ces hooks sont exécutés après la construction de tous les packages, mais avant la génération des images du système de fichiers. Ils sont rarement utilisés et le paquet n'en a probablement pas besoin.

De nombreux packages prenant en charge l'internationalisation utilisent la bibliothèque gettext. Les dépendances de cette bibliothèque sont assez compliquées et méritent donc quelques explications.

La bibliothèque glibc C intègre une implémentation complète de gettext, prenant en charge la traduction. La prise en charge des langues natives est donc intégrée à la glibc.

D'autre part, les bibliothèques uClibc et musl C ne fournissent qu'une implémentation stub de la fonctionnalité gettext, qui permet de compiler des bibliothèques et des programmes à l'aide de fonctions gettext, mais sans fournir les capacités de traduction d'une implémentation complète de gettext. Avec de telles bibliothèques C, si un véritable support de langage natif est nécessaire, il peut être fourni par la bibliothèque libintl du paquet gettext.

Pour cette raison, et afin de s'assurer que la prise en charge de la langue native est correctement gérée, les packages dans Buildroot qui peuvent utiliser la prise en charge NLS doivent :

• S'assurer que la prise en charge NLS est activée lorsque BR2_SYSTEM_ENABLE_NLS=y. Cette opération est effectuée automatiquement pour les packages autotools et ne doit donc être effectuée que pour les packages utilisant d'autres infrastructures de packages.
• Ajouter $(TARGET_NLS_DEPENDENCIES) à la variable <pkg>_DEPENDENCIES du package. Cet ajout doit être fait de manière inconditionnelle : la valeur de cette variable est automatiquement ajustée par l'infrastructure centrale pour contenir la liste des packages concernés. Si la prise en charge NLS est désactivée, cette variable est vide. Si la prise en charge NLS est activée, cette variable contient host-gettext afin que les outils nécessaires à la compilation des fichiers de traduction soient disponibles sur l'hôte. De plus, si uClibc ou musl sont utilisés, cette variable contient également gettext afin d'obtenir l'implémentation complète de gettext.
• Si nécessaire, ajouter $(TARGET_NLS_LIBS) aux drapeaux de l'éditeur de liens, afin que le package soit lié à libintl. Ce n'est généralement pas nécessaire avec les packages autotools car ils détectent généralement automatiquement qu'ils doivent être liés à libintl. Cependant, les packages utilisant d'autres systèmes de construction ou des packages problématiques basés sur des outils automatiques peuvent en avoir besoin. $(TARGET_NLS_LIBS) doit être ajouté sans condition aux drapeaux de l'éditeur de liens, car le noyau le rend automatiquement vide ou défini sur -lintl en fonction de la configuration.

Aucune modification ne doit être apportée au fichier Config.in pour prendre en charge NLS.

Enfin, certains packages nécessitent certains utilitaires gettext sur la cible, comme le programme gettext lui-même, qui permet de récupérer les chaînes traduites, à partir de la ligne de commande. Dans un tel cas, le colis doit :

• utiliser select BR2_PACKAGE_GETTEXT dans leur fichier Config.in, indiquant dans un commentaire ci-dessus qu'il s'agit uniquement d'une dépendance d'exécution.
• ne pas ajouter de dépendance gettext dans la variable DEPENDENCIES de leur fichier .mk.

Dans Buildroot, il existe une relation entre :

• le nom du package, qui est le nom du répertoire du package (et le nom du fichier *.mk) ;
• le nom de l'entrée de configuration déclarée dans le fichier Config.in ;
• le préfixe de la variable makefile.

Il est obligatoire de maintenir une cohérence entre ces éléments, en utilisant les règles suivantes :

• le répertoire du package et le nom *.mk sont le nom du package lui-même (par exemple : package/foo-bar_boo/foo-bar_boo.mk) ;
• le nom de la cible de création est le nom du paquet lui-même (par exemple : foo-bar_boo) ;
• l'entrée de configuration est le nom du package en majuscules avec . et -caractères remplacés par _, préfixés par BR2_PACKAGE_ (ex. : BR2_PACKAGE_FOO_BAR_BOO) ;
• le préfixe de la variable de fichier *.mk est le nom du package en majuscules avec . et - caractères remplacés par _ (ex : FOO_BAR_BOO_VERSION).

Buildroot fournit un script dans utils/check-package qui vérifie les fichiers nouveaux ou modifiés pour le style de codage. Ce n'est pas un validateur de langage complet, mais il détecte de nombreuses erreurs courantes. Il est destiné à s'exécuter dans les fichiers réels qu'on crée ou modifie, avant de créer le correctif à soumettre.

Ce script peut être utilisé pour les packages, les makefiles du système de fichiers, les fichiers Config.in, etc. Il ne vérifie pas les fichiers définissant les infrastructures des packages et certains autres fichiers contenant du code commun similaire.

Pour l'utiliser, exécuter le script check-package, en indiquant quels fichiers sont créés ou modifiés :

$ ./utils/check-package package/new-package/*

Si on a le répertoire utils dans le chemin, on peut également exécuter :

$ cd package/new-package/
$ check-package *

L'outil peut également être utilisé pour les packages dans un br2-external :

$ check-package -b /path/to/br2-ext-tree/package/my-package/*

Une fois qu'on a ajouté un nouveau package, il est important de le tester dans différentes conditions : est-ce qu'il est compatible avec toutes les architectures ? Est-ce qu'il se construit avec les différentes bibliothèques C ? A-t-il besoin de fils, NPTL ? Etc…

Buildroot exécute des constructeurs automatiques qui testent en permanence des configurations aléatoires. Cependant, ceux-ci ne construisent que la branche principale de l'arborescence git, et le nouveau package sophistiqué n'est pas encore là.

Buildroot fournit un script dans utils/test-pkg qui utilise les mêmes configurations de base que celles utilisées par les autobuilders afin qu'on puisse tester le package dans les mêmes conditions.

Tout d'abord, créer un extrait de configuration contenant toutes les options nécessaires pour activer le package, mais sans aucune option d'architecture ou de chaîne d'outils. Par exemple, créons un extrait de configuration qui active simplement libcurl, sans aucun backend TLS :

$ cat libcurl.config
BR2_PACKAGE_LIBCURL=y

Si le package a besoin de plus d'options de configuration, on peut les ajouter à l'extrait de configuration. Par exemple, voici comment tester libcurl avec openssl en tant que backend TLS et le programme curl :

$ cat libcurl.config
BR2_PACKAGE_LIBCURL=y
BR2_PACKAGE_LIBCURL_CURL=y
BR2_PACKAGE_OPENSSL=y

Exécuter ensuite le script test-pkg, en lui indiquant quel extrait de configuration utiliser et quel package tester :

$ ./utils/test-pkg -c libcurl.config -p libcurl

Par défaut, test-pkg construira le package par rapport à un sous-ensemble des chaînes d'outils utilisées par les autobuilders, qui a été sélectionné par les développeurs Buildroot comme étant le sous-ensemble le plus utile et le plus représentatif. Si on veut tester toutes les chaînes d'outils, passer l'option -a (dans tous les cas, les chaînes d'outils internes sont exclues car elles prennent trop de temps à construire).

La sortie répertorie toutes les chaînes d'outils testées et le résultat correspondant (extrait, les résultats sont faux) :

$ ./utils/test-pkg -c libcurl.config -p libcurl
                armv5-ctng-linux-gnueabi [ 1/11]: OK
              armv7-ctng-linux-gnueabihf [ 2/11]: OK
                        br-aarch64-glibc [ 3/11]: SKIPPED
                           br-arcle-hs38 [ 4/11]: SKIPPED
                            br-arm-basic [ 5/11]: FAILED
                  br-arm-cortex-a9-glibc [ 6/11]: OK
                   br-arm-cortex-a9-musl [ 7/11]: FAILED
                   br-arm-cortex-m4-full [ 8/11]: OK
                             br-arm-full [ 9/11]: OK
                    br-arm-full-nothread [10/11]: FAILED
                      br-arm-full-static [11/11]: OK
11 builds, 2 skipped, 2 build failed, 1 legal-info failed

Les résultats signifient :

• OK : la compilation a réussi.
• SKIPPED : une ou plusieurs options de configuration répertoriées dans l'extrait de configuration n'étaient pas présentes dans la configuration finale. Cela est dû à des options ayant des dépendances non satisfaites par la chaîne d'outils, comme par exemple un package qui dépend de BR2_USE_MMU avec une chaîne d'outils noMMU. Les options manquantes sont signalées dans missing.config dans le répertoire de construction de sortie (~/br-test-pkg/TOOLCHAIN_NAME/ par défaut).
• FAILED: la construction a échoué. Inspecter le fichier journal dans le répertoire de génération de sortie pour voir ce qui n'a pas fonctionné :
  • la construction réelle a échoué,
  • les informations légales ont échoué,
  • l'une des étapes préliminaires (téléchargement du fichier de configuration, application de la configuration, exécution de dirclean pour le package) a échoué.

En cas d'échec, on peut simplement réexécuter le script avec les mêmes options (après avoir corrigé le package) ; le script tentera de reconstruire le package spécifié avec -p pour toutes les chaînes d'outils, sans avoir besoin de reconstruire toutes les dépendances de ce package.

Le script test-pkg accepte quelques options, pour lesquelles on peut obtenir de l'aide en exécutant :

$ ./utils/test-pkg -h

Les packages sur GitHub n'ont souvent pas de zone de téléchargement avec des archives de publication. Cependant, il est possible de télécharger des tarballs directement depuis le dépôt sur GitHub. Comme GitHub est connu pour avoir modifié les mécanismes de téléchargement dans le passé, la fonction d'assistance github doit être utilisée comme indiqué ci-dessous.

# Utilise une balise ou un ID de validation complet
FOO_VERSION = 1.0
FOO_SITE = $(appel github,<utilisateur>,<paquet>,v$(FOO_VERSION))

Si le paquet qu'on souhaite ajouter a une section de publication sur GitHub, le responsable peut avoir téléchargé une archive tar de version, ou la version peut simplement pointer vers l'archive tar générée automatiquement à partir de la balise git. S'il y a une archive de version téléchargée par le responsable, buildroot préférons l'utiliser car elle peut être légèrement différente (par exemple, elle contient un script de configuration, buildroot n'a donc pas besoin de faire AUTORECONF).

on peut voir sur la page de publication s'il s'agit d'une archive tar téléchargée ou d'une balise git :

• elle a été téléchargée par le responsable et on doit utiliser ce lien (dans cet exemple : mongrel2-v1.9.2.tar.bz2) pour spécifier FOO_SITE, et ne pas utiliser l'assistant github.
• D'un autre côté, s'il n'y a que le lien “Code source”, il s'agit d'une archive tar générée automatiquement et on doit utiliser la fonction d'assistance github.

De la même manière que la macro github décrite dans la Section « Comment ajouter un paquet depuis GitHub », Buildroot fournit également la macro gitlab à télécharger depuis les référentiels Gitlab. Il peut être utilisé pour télécharger des archives tar générées automatiquement et produites par Gitlab, que ce soit pour des balises ou des commits spécifiques :

# Utilise une balise ou un ID de validation complet
FOO_VERSION = 1.0
FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION))

Par défaut, il utilisera une archive .tar.gz, mais Gitlab fournit également des archives .tar.bz2, donc en ajoutant une variable <pkg>_SOURCE, cette archive .tar.bz2 peut être utilisée :

# Utilise une balise ou un ID de validation complet
FOO_VERSION = 1.0
FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION))
FOO_SOURCE = foo-$(FOO_VERSION).tar.bz2

S'il existe une archive tar spécifique téléchargée par les développeurs en amont dans https://gitlab.com/<project>/releases/, ne pas utiliser pas cette macro, mais utiliser plutôt directement le lien vers l'archive tar.

Comme on peut le constater, l'ajout d'un package logiciel à Buildroot consiste simplement à écrire un Makefile à l'aide d'un exemple existant et à le modifier en fonction du processus de compilation requis par le package.

Lorsqu'on empaquete un logiciel qui pourrait être utile à d'autres personnes, ne pas oublier pas d'envoyer un correctif à la liste de diffusion Buildroot (voir Section 22.5, « Soumettre des correctifs ») !