Linux Embedded

Le blog des technologies libres et embarquées

Votre première contribution à Buildroot

Introduction

Nous avons vu dans un précédent article comment facilement ajouter un paquetage à buildroot. Ce n'est pas bien compliqué mais, maintenant que vous avez créé ce nouveau paquetage, il est souhaitable de contribuer à la communauté Buildroot et de participer à l'effort commun.

Buildroot étant un projet animé par des volontaires, participer à l'effort commun en partageant vos modifications fait partie du savoir vivre normal dans le monde du logiciel libre. Ce n'est pourtant pas la seule raison de le faire.

  • Maintenir des modifications locales est un processus compliqué, long et source d'erreurs. C'est également une tâche de fond qu'il faut recommencer régulièrement pour suivre les évolutions de Buildroot. Plus on attend, plus c'est difficile. Toute modification logicielle doit être maintenue et tout ce que vous ne contribuez pas doit donc être maintenu par vos soins.
  • Les contributions à Buildroot sont relues et critiquées par les auteurs de Buildroot, donc par les meilleurs experts du domaine. Leurs critiques sont sans doute la meilleure façon d'apprendre et c'est un gage de qualité pour vos modifications.
  • En participant activement à la communauté vous serez considéré comme une personne utile en non pas juste un utilisateur. Le jour où vos aurez des problèmes plus compliqués avec Buildroot ou que vous souhaiterez intégrer des modifications plus complexes, la communauté sera plus réceptive à vos problèmes.

Prendre contact avec la communauté.

Avant toute chose il est recommandé de prendre contact avec la communauté Buildroot. Le développement de Buildroot a principalement lieu sur la mailing-list ( ici ). Il va donc falloir s'y abonner. Cette mailing-list est très active ( une cinquantaine de mails par jour ) et très sympathique. Le niveau d'anglais y est raisonnable car la plupart des contributeurs de Buildroot ne viennent pas de pays anglophones. Si vous avez fait de l'anglais au lycée vous devriez être à votre aise et quelques jours à lire les mails devraient vous donner une idée de l'ambiance amicale de cette communauté.

Il est également intéressant de se connecter sur le canal IRC de buildroot ( #buildroot sur freenode ). Si vous avez des questions précises il peut être plus rapide de passer par IRC que par la mailing list.

Vérifier vos modifications.

Avant toute chose nous allons revoir les modifications que vous avez apportées à Buildroot pour ajouter votre paquetage. Il s'agit ici d'éviter d'avoir trop de problèmes à corriger lorsque votre patch sera revu sur la mailing-list Buildroot. Un peu de temps passé à se relire vous fera gagner beaucoup de temps, ainsi qu'à vos relecteurs.

  • Vérifiez l'indentation dans votre fichier Config.in. L'indentation doit être d'une tabulation pour les lignes normales, et d'un tabulation et deux espaces pour la section d'aide.
  • La section d'aide doit décrire le programme, suivi d'une ligne blanche puis de l'URL du projet que vous intégrez.
  • votre fichier .mk positionne différentes variables. Vérifiez que vous ne positionnez pas de variables à leur valeur par défaut. C'est inutile et cela complique la lisibilité.
  • vérifiez que vous avez positionné correctement la variable <paquetage>_LICENSE La liste des valeurs standards se trouve ici.
  • de même, remplissez le champs <paquetage>_LICENSE_FILE, il s'agit généralement d'un lien vers le fichier COPYING de votre paquetage
  • Vérifiez vos dépendances. En particulier l'utilisation des mots clés depends et select dans votre Config.in. La différence entre ces deux mots clé est expliquée ici. Si vous utilisez select pour sélectionner un paquetage, vérifiez également que vous avez bien un depends pour chaque depends du paquet en question.
  • Si vous avez des depends, pensez à ajouter un commentaire à afficher quand la dépendance n'est pas satisfaite, comme dans l'exemple ici
  • Vérifiez que votre paquet est correctement placé dans la liste des paquets de package/Config.in. Êtes vous dans la bonne section ? Avez vous respecté l'ordre alphabétique ?
  • Si votre paquetage utilise l'appel système fork pensez à mettre un depends sur BR2_USE_MMU.
  • Vérifiez qu'il y a bien une ligne blanche entre les entêtes et les variables de votre fichier .mk
  • Si votre paquetage peut être téléchargé dans différents formats, privilégiez le plus compressé  ( .xz pusi .bz puis .gz)
  • Vérifiez que vous n'avez pas d'espaces en fin de lignes dans vos différents fichiers
  • Harmonisez le nom de votre paquetage. Faites attention de le capitaliser de la même façon partout (et de préférence tout en minuscules)
  • Enfin, vérifiez que toutes vos dépendances sont également positionnées dans le fichier .mk. Buildroot utilise cette information pour décider dans quel ordre compiler les paquetages.
  • Vérifiez que votre projet fonctionne également avec uClibc, vérifiez si il a besoin de MMU et de threading. Si c'est le cas, mettez les dépendances correspondantes dans le Config.in

Commiter votre contribution localement.

Je ne reviendrai pas en détail sur l'ajout du paquetage lui même qui a été détaillé dans un autre article. Ici nous allons plutôt étudier comment préparer votre paquetage pour pouvoir l'envoyer à la communauté Buildroot.

Normalement toutes vos modifications ont étés sauvegardées proprement dans git et dans une branche portant le nom de votre paquetage... non ? pas de panique il est toujours temps de rattraper le coup..

D'abord, nous allons créer une branche git nommée d'après votre paquetage

git checkout -b <nom du paquetage>

Ensuite, nous allons ajouter vos modifications à git

git add -u # mise à jour des fichiers déjà gérés par git
git add <liste des nouveaux fichiers> # ajout des fichiers de votre paquetage
git status # pour vérifier que tout est bien en place

La dernière ligne nous permet de vérifier que tout se passe bien. Sa sortie ressemble à l'exemple ci-dessous

# On branch uncompressed_linux
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
#	modified:   Config.in
#
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   package/Config.in

Nous pouvons vérifier :

  • Que nous sommes sur la bonne branche
  • Que tous les fichiers à envoyer sont bien dans la section "changes to be commited"
  • Que les fichiers dans la section "changes not staged for commit" ne sont pas à envoyer

Une fois ces petites vérifications faites, il est temps de commiter nos modifications

git commit -s

Cette commande ouvrira un éditeur de texte qui vous permettra de saisir votre message de commit. Vous pourrez également vérifier la liste des fichiers qui seront commités.

Votre message de commit devrait ressembler à l'exemple ci-dessous :

<mon paquetage>: new package

 Signed-off-by: Jérémy Rosen <jeremy.rosen@openwide.fr>
---
v0: initial commit
 <mon paquetage> is an awesome package that does everything you need

Ici, il y a quelques conventions particulières à respecter

  • La première ligne du commit suit un format précis.
  • une ligne blanche
  • la ligne de signature (qui est rempli automatiquement par git grâce à l'option -s, mais que vous pouvez corriger)
  • une ligne avec trois tirets
  • Tout ce qui suit le tiret ne sera pas pris en compte lorsque les mainteneurs buildroot intégrerons vos modifications. Vous pouvez donc y saisir des informations secondaires comme une petite description du paquetage ou un message pour la mailing list

Et voila, nos modifications ont étés commitées localement. L'étape suivante consiste à récupérer la dernière version de buildroot et à mettre à jour nos modifications.

Tout d'abord il faut récupérer les dernières modifications venant du projet

git fetch origin

ensuite nous devons actualiser nos modifications pour être à jour par rapport à la dernière version de buildroot

git branch
#vérifiez que vous êtes bien dans la branche de votre paquetage
git rebase origin/master

Si tout se passe bien, votre commit est prêt à être envoyé.

Si git rebase vous signale des conflits à corriger, la liste des fichiers en conflit peut être obtenue par la commande git status

Éditez les fichiers en conflit en cherchant les marqueurs (<<< puis === puis >>> suivant les conventions de la plupart des outils de gestion de configuration) et corrigez les différents problèmes. Testez à nouveau votre paquetage jusqu'à ce que tout fonctione puis, une fois les conflits résolu, utilisez la commande suivant pour signaler à git que les fichiers ne sont plus en conflit

git add <fichier en conflit>

une fois tous les conflits résolus, utilisez la commande suivante pour poursuivre le merge

git rebase --continue

Si vous êtes perdu et que vous voulez recommencer à zéro il suffit d'utiliser la commande suivante pour annuler toute l'opération

git rebase --abort

après ces petites manipulations, votre contribution est prête à être envoyée.

Envoyer votre contribution.

Tout d'abord nous allons créer le patch à envoyer à la mailing list. Rien de plus simple, la commande suivante fait tout pour vous

git format-patch -M -n -s -o outgoing origin/master

Cette commande crée un répertoire outgoing avec un fichier par commit à envoyer. Vous pouvez tout relire une dernière fois avant d'envoyer...

Pour envoyer, il faut utiliser un client mail qui enverra ces fichiers en ligne (et non pas en pièce jointe), un fichier par mail et qui ne tronquera pas les lignes trop longues, n'ajoutera pas de signatures ni de mise en forme html.

Bref le plus simple est d'utiliser la commande git send-email plutôt que votre client mail pour l'envoi. La commande de base est la suivante

git send-email [options] --to buildroot@busybox.net outgoing/*

Il y a un certain nombre d'options à ajouter pour configurer git send-email pour utiliser votre serveur de mail. La documentation de git send-email vous expliquera tout ça...

Je vous conseille d'utiliser votre propre adresse dans le champs --to une première fois pour vérifier que tout se passe bien avant d'envoyer votre série de patch sur la mailing list.

Relectures, critiques et nouvelles versions.

Voila, votre patch a été envoyé, que va-t-il se passer ?

La mailing-list buildroot est assez active et les mainteneurs ont souvent un peu de retard par rapport aux différents patches. Ne soyez pas surpris si il n'y a pas de réponse avant une semaine. Souvent la seule réponse sera le message indiquant que votre paquetage a été intégré. Félicitations.

Néanmoins la plupart des premières contributions ne sont pas parfaites et vous aurez certainement des réponses des différents mainteneurs vous demandant d'ajuster votre patch pour répondre aux critères de qualité du projet. En général il vous suffit de faire les corrections demandées et de soumettre une nouvelle version de votre patch.

Pour cela, commencez par effectuer les modifications localement dans votre clone git puis modifiez le dernier commit au lieu d'en ajouter un nouveau :

git add -u # mise à jour des fichiers à commiter
git commit --amend # modification du dernier commit

Cela vous ouvrira un éditeur de texte avec le message de commit que vous aviez utilisé dans la version précédente du patch. Profitez en pour le modifier en ajoutant une description de vos modification et un nouveau numéro de version pour votre patch :

v1: added suggestions by <personne ayant soumis les critiques>

au dessus de la ligne avec la v0.

si une personne a répondu à votre patch en mettant dans sa réponse une ligne du type :

Tested-by: <quelqu'un d'important>

ou bien :

Acked-by: <quelqu'un d'important>

Ajoutez cette ligne telle-quelle au dessous de la ligne avec votre signature et au dessus de la ligne avec les trois tirets. Cela signifie que la personne en question a relu votre patch et ne s'oppose pas à son intégration. Cette information sera intégrée au commit final.

Une fois ces modifications effectuées, vous devez refaire les manipulations pour actualiser (git fetch et git rebase) puis envoyer (git format-patch et git send-email) vos modifications.

Après quelques cycles de critiques et corrections votre patch devrait être intégré dans buildroot.

Conclusion

Voila, vous êtes désormais un contributeur du projet buildroot, félicitations. Il serait dommage de s'arrêter en si bon chemin.

Il y a plein de façons simples de contribuer à buildroot, la plupart ne prennent que peu de temps quand on sait comment contribuer au projet :

  • Si vous trouvez un bug quelconque, une dépendance manquante ou que vous avez un problème avec buildroot qui n'est pas spécifique à votre projet, une contribution évitera à d'autres de refaire le travail que vous avez déjà fait.
  • Chaque paquetage buildroot utilise une version précise du projet amont qui est codé en dur dans son fichier .mk. Le projet buildroot ne peut pas suivre toutes les évolutions de tous les paquetages distribués, aussi, si vous utilisez un paquetage et que la dernière version n'est pas celle mise à disposition par buildroot, un petit patch d'une ligne ne prends qu'une minute et est toujours bienvenu.
  • Si vous utilisez une carte de développement qui n'est pas supportée en natif par buildroot pensez à partager les fichiers de configuration avec la communauté. Il y a beaucoup de cartes et le travail que vous avez effectué est loin d'être négligeable. Les autres utilisateurs vous remercieront.
  • Le projet buildroot utilise un mécanisme d'autobuild pour tester aléatoirement des configurations. Les résultats de ces tests sont disponibles ici. La plupart des problèmes sont des dépendances manquantes et sont donc faciles à corriger. N'hésitez pas à le faire. Ajoutez à votre message de commit l'URL du test que vous corrigez et les développeurs vous remercieront.

liens

Update : Mise à jour de la checklist, merci à Nicolas Menegale pour ses remarques

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée.