Monter une bibliothèque !

Une clé de dix et un marteau ? Non ! Un explorateur de fichiers et un décompresseur zip....

. Par : Thierry. URL : https://www.locoduino.org/spip.php?article146

Vous avez créé avec votre Arduino une jolie petite chose qui à coup sûr bouleversera l’équilibre mondial et la programmation sur Arduino... C’est très bien, mais si vous ne diffusez pas ce génial fruit de votre intelligence, ça ne sert à rien !

Dans le petit monde de l’Arduino, le savoir et l’expertise passent soit par des sites comme Locoduino ou Arduino.cc, soit par des bibliothèques destinées à simplifier la vie de l’utilisateur lambda.
Si vous êtes là, c’est que le premier mode de transmission d’information vous est connu. Concentrons nous sur le second...
Une bibliothèque (certains disent une librairie parce que la traduction en Anglais est ’library’...) est un fichier compressé au format zip pouvant contenir trois parties :

Informations sur la bibliothèque :

Les fichiers présents à la racine du répertoire de la bibliothèque (pfff, ’librairie’ c’est quand même plus court à écrire...) sont des fichiers textes éditables avec n’importe quel éditeur, bloc-note compris. Prenons en exemple la bibliothèque Servo livrée avec la version 1.6.4 :

PNG - 4.3 kio
  • README.adoc
    Ce fichier au format AsciiDoc décrit le rôle et le fonctionnement de la bibliothèque. Celui de Servo est là :
= Servo Library for Arduino =

This library allows an Arduino board to control RC (hobby) servo motors.

For more information about this library please visit us at
http://arduino.cc/en/Reference/Servo

== License ==

Copyright (c) 2013 Arduino LLC. All right reserved.
Copyright (c) 2009 Michael Margolis.  All right reserved.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Les signes ’=’ et ’==’ désignent des têtes de chapitre plus ou moins importants, le reste est du texte littéral. Dans la première partie on trouve la description de la bibliothèque, alors que dans la seconde on a les copyright et la licence utilisée pour la diffusion de son code source.

  • library.properties
    C’est un autre fichier texte décrivant la bibliothèque via une syntaxe particulière :
name=Servo
version=1.0.2
author=Michael Margolis, Arduino
maintainer=Arduino <info@arduino.cc>
sentence=Allows Arduino boards to control a variety of servo motors. For all Arduino boards.
paragraph=This library can control a great number of servos.<br />It makes careful use of timers: the library can control 12 servos using only 1 timer.<br />On the Arduino Due you can control up to 60 servos.<br />
category=Device Control
url=http://arduino.cc/en/Reference/Servo
architectures=avr,sam

Ce fichier possible depuis la 1.5 permet au ’Library Manager’ de trouver et proposer la bibliothèque à l’installation. Il permet aussi à l’IDE de ne pas proposer une bibliothèque qui ne serait pas compatible avec certains modèles de cartes.

  • keywords.txt

Ce fichier permet à la coloration syntaxique de l’IDE Arduino de fonctionner. Ce n’est pas vital, mais c’est plutôt sympa de constater que l’on a pas fait d’erreur de frappe parce le nom de la constante ou de la fonction s’affiche en couleur !

#######################################
# Syntax Coloring Map Servo
#######################################

#######################################
# Datatypes (KEYWORD1)
#######################################

Servo	KEYWORD1	Servo

#######################################
# Methods and Functions (KEYWORD2)
#######################################
attach	KEYWORD2
detach	KEYWORD2
write	KEYWORD2
read	KEYWORD2
attached	KEYWORD2
writeMicroseconds	KEYWORD2
readMicroseconds	KEYWORD2

#######################################
# Constants (LITERAL1)
#######################################

KEYWORD1, KEYWORD2 et LITERAL1 sont trois types de coloration à disposition. Il suffit de dire celui que l’on veut utiliser pour tel ou tel mot. KEYWORD1 est destiné au nom de classe et de structure, ou de types de données. KEYWORD2 est pour le nom des fonctions de votre bibliothèque. Enfin LITERAL1 correspond aux constantes et defines de votre code.

Entre le mot clé et son type (KEYWORD1, LITERAL1...) doit se trouver une et une seule tabulation. Avec des espaces, ça ne marche pas !
PNG - 29.7 kio

On voit bien que la classe Servo et ses méthodes attach et write sont colorées...

  • WhatsNew.txt
    A ces fichiers dictés par l’IDE et les conventions, j’ajoute quelquefois un fichier personnel qui permet de suivre les évolutions de la bibliothèque : corrections de bug, ajouts de fonctionnalités... Le corollaire de ce fichier est la présence dans le fichier .h principal d’un numéro de version qui lui aussi évolue. Par exemple, ma bibliothèque EEPROMextent a un numéro de version visible au lancement en mode debug sur la console série, et un fichier WhatsNew.txt :
This is a library for Arduino to read/write complex data to EEPROM.


Whats New ?

15/07/2018 V1.2.1
	- Correction du format de Keywords.txt
	- Ajout du fichier LICENSE

	- Fix Keywords.txt format.
	- Add of LICENSE file

24/11/2017 V1.2.0
	- Mise en forme du numéro de version en 'semver' (Semantic Versioning 2.0.0).

	- Version number converted to 'semver' format (Semantic Versioning 2.0.0).


.....

Chaque début de version donne la date de création de cette version, et son numéro. Dans le développement logiciel on parle de version majeure (ré-écriture ou au moins grosses modifications) pour le premier chiffre (1 ici) et version mineure pour des corrections et des ajustements (le nombre après la virgule...). Je corrige les bugs signalés par les utilisateurs et je change la version mineure à chaque correction poussée. Il peut y avoir plusieurs corrections sur une même version mineure.
Après le numéro de version, viennent les corrections effectuées avec une tabulation devant pour rendre le fichier plus lisible. Les commentaires placés ici doivent être lus par les utilisateurs, il s’agit donc d’être clair et concis, et de se placer de son point de vue. Il n’a que faire du re-formatage du source ou du changement de nom d’une classe interne. Par contre, savoir que telle fonctionnalité marche maintenant est beaucoup plus intéressant !
Le parti pris de mes bibliothèques est la documentation en Français et en Anglais. WhatsNew suit ce principe en séparant les lignes Françaises (placées en premier, quand même !) des lignes Anglaises par une ligne vide, mais c’est mon choix.

Dans mes bibliothèques plus récentes, le whatsnew n’existe plus et est remplacé par des commentaires au début du fichier .h associé. C’est une autre façon de faire.

Sources

Jusqu’à la version 1.5 de l’IDE, tous les fichiers étaient présents dans le répertoire de la bibliothèque, sources et annexes. Ce n’est plus le cas depuis, un répertoire ’src’ peut être créé et ne contenir que les sources à compiler. Le principal fichier d’include doit forcément porter le même nom que le répertoire de la bibliothèque avec l’extension ’.h’ ! A noter qu’il est bien sûr possible d’inclure plusieurs fichiers sources, h ou hpp, c ou cpp . library.properties permet aussi de spécifier le nom du ou des fichiers include à ajouter au .ino pour que la bibliothèque fonctionne.
Si votre bibliothèque n’est prévue que pour certains types d’Arduino, il faut créer des sous-répertoires par architecture. Dans notre exemple ’Servo’, il y a une version pour les Arduino équipés de micro-contrôleur AVR, et une autre pour le DUE (architecture sam). Essentiellement à cause de la gestion des Timers très différente.

PNG - 1.8 kio

Exemples

Il est toujours bon de fournir des exemples d’utilisation de votre bibliothèque. C’est une référence facile pour l’utilisateur à laquelle il peut se référer rapidement. C’est aussi une démonstration de ses capacités ! Le plus souvent l’utilisateur va prendre votre exemple, le renommer et le garnir de son code... N’hésitez surtout pas à illustrer de pointus usages avec un exemple précis. Personne ne vous le reprochera... A moins bien sûr qu’il ne marche pas ! Rien n’est pire qu’une source d’information qui n’est pas fiable. Et c’est encore plus vrai si la source, c’est l’auteur de la bibliothèque ! A chaque nouvelle version, prenez la peine de relancer tous vos exemples pour vous assurer qu’ils marchent encore.
Ces exemples doivent figurer dans un répertoire ’examples’. Chaque exemple est dans un répertoire individuel, avec le nom du fichier .ino qui porte le même nom que le répertoire de l’exemple.

PNG - 3.1 kio

extras

Il peut être utile de fournir de la documentation extérieure à la bibliothèque, comme des datasheets de composants, des textes de norme ou des fichiers pour fabriquer son circuit imprimé. L’IDE Arduino ne se préoccupe pas de ce qui se trouve là, vous pouvez donc y mettre ce que vous voulez. Attention malgré tout à la taille. Une bibliothèque est généralement un fichier zip très réduit de quelques kilo-octets seulement. N’y ajoutez pas un pdf de 20 Mégas ou des images directement sorties de votre superbe appareil photo !

Mon truc, c’est une bibliothèque ou pas ?

Il n’y a qu’une seule règle pour que votre programme ait la possibilité de devenir une bibliothèque, c’est que l’utilisateur n’ai pas à le modifier pour faire son propre programme ! Votre code doit rester une ’boite noire’ pour lui. Prenez encore ’Servo’, nul besoin de changer quelque chose dedans si vous voulez l’utiliser... Tout passe par les arguments du constructeur de classe, et les fonctions appelées, comme le numéro de pin ou les valeurs mini/maxi.
Pour devenir une bibliothèque, votre programme doit devenir configurable de l’extérieur ! On peut même ajouter une fonction ’setup’ ou ’begin’ qui va gérer des initialisations générales, et peut être aussi une fonction ’loop’ pour faire ce qui doit être fait tout en restant invisible de l’utilisateur... Ce n’est pas le cas de ’Servo’ qui se sert d’une interruption pour faire cela.
En clair, cela signifie que l’on ne peut pas impunément prendre un .ino quelconque et l’ériger en bibliothèque. Il y a un travail de préparation pour rendre son usage simple et efficace, pour définir l’API (Application Programming Interface ou interface de programmation) la plus simple et concise, tout en restant souple et puissante... Un métier quoi !
Le meilleur moyen que j’ai trouvé, c’est de faire un .ino en considérant que la bibliothèque existe. De quoi est-ce que j’aurais besoin ? De quelles fonctions, de quelles données ? Une fois l’exemple simple mais couvrant l’essentiel des besoins tapé, on peut réfléchir à comment fournir les fonctionnalités demandées, dans la bibliothèque cette fois... Un métier je vous dis...

Une fausse contrainte : la complexité.

Le but d’une bibliothèque est précisément de proposer un moyen simple de faire quelque chose de forcément plus compliqué... Toutes les bibliothèques pourraient disparaître, on continuerai de faire marcher nos Arduino. C’est juste que ça deviendrait très pénible de devoir à chaque fois refaire ce que d’autres ont déjà fait pour eux.
La complexité gagnée peut être très minime comme la bibliothèque TFT livrée avec l’IDE 1.6.4 pour gérer un écran TFT Adafruit. Une seule classe, deux méthodes dont le constructeur. Moins de vingt lignes utiles en tout...
A l’autre bout, on a Robot_Control ou Commanders qui tentent de fournir une version complète et packagée d’une utilisation particulière de l’Arduino. Le but étant ici de décharger l’utilisateur de la tripaille, des fonctions de base de gestion de bouton, de potentiomètre, de décodage DCC, et de lui fournir une API pour construire un appareil évolué, Robot ou décodeur de fonction DCC, en quelques lignes... Et pour ce type de bibliothèque, la taille n’est limitée que par celle de l’Arduino cible !

Une fausse obligation : l’Anglais

Clairement l’usage de l’Anglais est un atout supplémentaire pour élargir l’audience de votre travail. Par exemple Commanders aujourd’hui c’est 25% de téléchargements depuis la France, tout le reste vient du monde entier ! El le deuxième pays n’est pas francophone puisque c’est l’Allemagne !
Mais ce n’est pas un but en soi. On peut très bien créer une bibliothèque franco-française. Elle restera juste cantonnée aux pays francophones.
Une fois la décision prise, il faut s’y tenir. Les noms, le code, les documentations, tout doit être dans la langue voulue. La règle c’est l’homogénéité.

Le code

Le code d’une bibliothèque doit être irréprochable et homogène.
Par définition, vous livrez du code chez un client. Alors certes il n’a pas payé, mais il a malgré tout le droit d’avoir quelque chose de formaté, de lisible...

  • Du code propre :
    Ce qui importe ici, ce n’est pas votre manière de coder, c’est surtout que vous soyez constant. Oui mais non, le chaos n’est pas une manière de coder ! Faut pas pousser mémère dans les orties...
    Que vous mettez l’accolade ouvrante après le nom de fonction ou sur la ligne du dessous, faites le partout !
    Si vous mettez toujours des accolades dans un if ou un for, même s’il n’y a qu’une seule ligne, mettez les partout !
    Si vous mettez une ou deux lignes vides entre deux fonctions, faites le entre toutes les fonctions !
    Les tabulations de début de ligne doivent être respectées et bien alignées pour mieux comprendre les tests et les boucles. Je sais que l’IDE Arduino n’aime pas les tabulations et préfère insérer trois espaces, mais même des espaces sont préférables à rien du tout !
    La plupart du temps, une seule instruction par ligne. Une ligne vide ou presque ne coûte rien à tous points de vue.
    Les fichiers sources de plus de 100 ou 200 lignes sont à proscrire. Fixez vous même la limite, mais il faut s’y tenir. Une maxime essentielle du développement, c’est ’diviser pour régner’ !
  • Des commentaires à jour :
    Documenter est essentiel, à la fois pour vous lorsque vous vous relirez, et pour les ’clients’ qui voudront comprendre votre travail. Mais une documentation obsolète est pire qu’aucune doc ! Si vous documentez, et vous devez le faire, maintenez cette doc au fur et à mesure des évolutions de votre source.
  • Des noms clairs :
    La fonction ’f’ ou la variable ’i’ n’ont pas droit de cité dans une bibliothèque. Même une boucle simple sur un objet très connu doit utiliser une variable avec un nom expressif : à un for(int i...) préférez un for(int pinIndex...). C’est plus long à écrire, mais ça ne change pas la taille du code produit, c’est bien plus clair à lire, et cela peut même éviter des erreurs de base comme l’utilisation d’une variable pour une autre... Les bonnes résolutions de nommage s’appliquent évidemment aussi aux noms de fichier !
  • Préférez ’private’ à ’public’ ! :
    Si vous codez en C++, vous avez peut être pris le parti de tout mettre en public pour vous simplifier la vie. Ce ne doit pas être la règle pour une bibliothèque. Toute fonction ou donnée publique sera forcément utilisée par quelqu’un, et ce quelqu’un verra son programme cesser de fonctionner si vous touchez à cette fonction ou cette donnée à l’occasion d’une nouvelle version, alors que vous pensiez que ça ne servirait jamais à qui que ce soit... La règle est donc que tout doit être privé par défaut, et on ouvre à ’protected’ si besoin pour les classes dérivées. En dernier recours, on met public si on est obligé...

Et pour la diffuser, je fais un site juste pour elle ?

C’est évidemment une possibilité, tout comme créer un magazine ou une chaîne de télévision dédiée. Mais il y a peut être des moyens plus simples... Décomposons le problème.

Hébergement

Votre bibliothèque est un fichier zip de quelques Ko, ça ne devrait pas être difficile de trouver de la place... Et pourtant.

A la maison ?

Si vous avez déjà un site internet, stocker votre bibliothèque sur un répertoire privé de votre espace est une bonne idée. Mais admettons que vous n’ayez pas de site...

Payer ?

La version luxe, s’est s’offrir un espace disque chez un hébergeur payant. C’est assez peu cher, quelques euros par an, et c’est une petite garantie de pérennité du service.

Gratuit ?

Les hébergeurs gratuits existent. Comme par exemple votre fournisseur d’accès qui offre généralement un espace sur ses serveurs pour votre site internet maison. Il suffit de lui demander son ouverture... Vous avez aussi des espaces communautaires offerts par des bénévoles. Au delà de la générosité dont ils font preuve, il faut être conscient des limites du modèle. Pour survivre, certains n’hésitent pas à afficher de la publicité, à limiter la bande passante ou le nombre mensuel d’accès. Ce n’est pas forcément très grave, il suffit de le savoir et d’en tenir compte. Le problème majeur vient de la durée de vie de ces stockages. Vous changerez sans doute un jour de FAI, que deviendront vos fichiers ? Les hébergeurs gratuits peuvent disparaître du jour au lendemain, sans préavis. Ce jour là tous les liens qui se sont répandus sur la toile vers votre bibliothèque seront périmés ! Même si vous la relogez ailleurs, les anciens liens resteront invalides...

Et le Cloud ?

Le Cloud, qui n’est rien d’autre qu’un espace de stockage déporté sur des serveurs distants, est un espace privé. Vous pouvez ouvrir une partie de cet espace, le partager, mais je ne suis pas sûr que l’on puisse l’ouvrir au monde entier ! On retrouve les mêmes avantages et inconvénients que les hébergeurs classiques payants ou gratuits...

Les forges

La forge a été inventée par Internet. C’est un espace de stockage gratuit le plus souvent, mais il est destiné à des développeurs (ce que vous êtes devenus en créant un programme, voire une bibliothèque !) à destination d’autres développeurs, mais aussi pour les utilisateurs finaux.
Le rôle de la forge est d’offrir un espace pour les sources, avec une gestion très poussée des versions de chaque fichier, de branches parallèles de développement, de travail collaboratif. Le tout géré par des outils en ligne ou pas, des outils souvent assez abscons pour les néophytes. Parmi ces forges, on trouve celui choisi par Locoduino : le site GitHub, racheté par Microsoft il y a peu de temps, [https://github.com/Locoduino] qui repose sur Git, un outil de travail collaboratif Open Source.

Faire connaître votre travail

Ceux qui ont déjà un site internet perso ont déjà la plateforme pour diffuser de l’information à grande échelle, selon la fréquentation de votre site. Pour info, les recettes de cuisine sont une bonne manière de faire venir du monde (environ 100 visites par jour dans mon cas) !
Les forums spécialisés sont une source de diffusion d’info ciblée très pratique.
Si vous avez l’occasion, ou si vous avez le talent d’un Scorsese ou d’un Besson, créez votre vidéo pour démontrer le fonctionnement de votre bibliothèque et mettez là en ligne sur une ou plusieurs plateformes communautaires
.
Enfin il reste Locoduino ! C’est l’option la plus évidente puisque vous êtes là :) . Devenir rédacteur, écrire une bafouille où vous expliquez la genèse et le fonctionnement de votre oeuvre, avec un joli lien à la fin de l’article sur le fichier zip. Il suffit de s’inscrire, pas de droits d’inscription. Locoduino vous offre de la place pour votre prose, une visibilité de votre travail et même un petit peu de stockage (quelques Ko, hein, c’est pas le cloud non plus !).

Monter une bibliothèque répond à un canevas assez simple tout en impliquant un travail préparatoire de documentation, formatage de code. Une fois que c’est fait, ne reste plus que la publicité (ou Locoduino) pour la faire connaître !