- Homebrew est un gestionnaire de paquets qui permet d’installer et de gérer facilement des outils CLI sur macOS, et aide les développeurs à configurer efficacement leur environnement système avec les outils qu’ils utilisent le plus souvent
- Ce guide explique comment distribuer des scripts CLI personnels avec Homebrew, et montre comment simplifier la maintenance grâce à l’intégration GitHub et à des workflows automatisés
- Le processus de distribution suit les étapes création du CLI → release GitHub → création d’un Tap → rédaction et mise à jour de la Formula, pour aboutir à une installation possible uniquement avec les commandes
brew tap et brew install
- Bien comprendre la terminologie et les bonnes pratiques de Homebrew permet de mettre en place une distribution fiable, avec une meilleure reproductibilité et une sécurité renforcée de la chaîne d’approvisionnement
- Le tout peut être automatisé via des workflows GitHub Actions, et une fois configuré, la distribution d’autres CLI devient extrêmement simple
Contexte et motivation
- Homebrew est le gestionnaire de paquets privilégié pour installer des outils CLI sur macOS, et il est largement utilisé par les développeurs
- Pourtant, quand on distribue un CLI que l’on a créé, on passe souvent par npm ou RubyGems, et la méthode de distribution via Homebrew peut sembler moins familière
- Le dépôt core officiel de Homebrew applique une politique selon laquelle l’équipe Homebrew hésite à accepter des outils artisanaux, si bien que les développeurs publient généralement via un tap et une formula séparés
- Ce guide s’appuie sur une expérience concrète de distribution d’un CLI simple en Ruby
Explication des termes
- Homebrew utilise une terminologie particulière inspirée de l’univers du brassage, et la comprendre aide à mieux saisir l’architecture du système
- Une Formula est un fichier de définition de paquet, qui contient les instructions pour installer un code source ou un binaire
- Un Tap est un dépôt Git de Formulas, utilisé pour gérer des paquets personnalisés au niveau d’un utilisateur ou d’une organisation
- Un Cask est un manifeste d’installation pour des applications GUI ou de gros binaires, proche d’une Formula mais destiné à des fichiers précompilés
- Une Bottle est un paquet binaire précompilé copié tel quel au lieu d’être compilé depuis les sources, ce qui accélère l’installation
- Le Cellar est le répertoire où se trouvent les Formulas installées, par exemple
/opt/homebrew/Cellar
- Un Keg est le répertoire d’installation d’une Formula donnée, placé dans le Cellar et organisé par version
Vue d’ensemble
- Le dépôt core de Homebrew n’accepte pas les contenus de niche ou soumis à titre personnel, donc les utilisateurs doivent créer un dépôt Tap séparé pour distribuer leur CLI
- 1. Créer le CLI, le publier sur GitHub et faire une release taguée
- 2. Créer le Tap avec
brew tap-new, puis le pousser sur GitHub
- 3. Générer la Formula avec
brew create (incluant l’URL du tarball et le SHA256)
- 4. À chaque nouvelle version, mettre à jour la Formula afin que les utilisateurs puissent installer facilement avec
brew install
- Une fois la distribution prête, les utilisateurs peuvent installer le CLI avec deux commandes :
brew tap your_github_handle/tap et brew install your_cool_cli
- Ce guide laisse de côté le développement du CLI lui-même et se concentre sur la création du tap, la génération de la Formula et son cycle de mise à jour
- L’exemple utilisé est le CLI
imsg, qui crée une archive web interactive à partir de la base de données iMessage
Création du tap
- Il faut suivre le guide de création de tap de Homebrew en remplaçant le nom d’utilisateur ou d’organisation GitHub selon son cas
- Pour regrouper tous ses futurs outils CLI dans un seul tap, le nom
homebrew-tap est recommandé ; le préfixe homebrew fait l’objet d’un traitement spécial dans le CLI, et tap est un suffixe courant par convention
- Exécuter la commande de création du tap :
brew tap-new searlsco/homebrew-tap
- Cela génère un squelette dans
/opt/homebrew/Library/Taps/searlsco/homebrew-tap
- Créer ensuite le dépôt correspondant sur GitHub et y pousser le contenu généré :
cd /opt/homebrew/Library/Taps/searlsco/homebrew-tap, git remote add origin git@github.com:searlsco/homebrew-tap.git, git push -u origin main
- Une fois propriétaire du tap, d’autres utilisateurs peuvent cloner le dépôt dans
/opt/homebrew/Library/Taps avec la commande brew tap searlsco/tap
- Au départ, le dépôt n’a rien d’utile, mais cela permet déjà de vérifier que le mécanisme de base fonctionne
Création de la Formula
- Homebrew peut référencer directement un dépôt GitHub, mais recommande d’utiliser un tarball versionné et sa somme de contrôle afin de renforcer la reproductibilité et la sécurité de la chaîne d’approvisionnement open source
- Commande de création de la Formula :
brew create https://github.com/searlsco/imsg/archive/refs/tags/v0.0.5.tar.gz --tap searlsco/homebrew-tap --set-name imsg --ruby
- Le drapeau
--tap désigne le tap personnalisé et place la Formula dans /opt/homebrew/Library/Taps/searlsco/homebrew-tap/Formula
--set-name imsg définit explicitement le nom de la Formula, à choisir de façon unique pour éviter les doublons (attention par exemple aux conflits avec des CLI existants comme TLDR ou standard)--ruby est un préréglage de template pour les CLI Ruby, l’une des nombreuses options qui simplifient la personnalisation
- La Formula générée peut ne pas fonctionner immédiatement ; l’auteur recommande alors de la corriger avec l’aide d’un LLM : exécuter
brew install --verbose imsg, copier l’erreur dans ChatGPT, puis itérer sur la Formula
- Le fichier final Formula/imsg.rb peut servir de point de départ réutilisable pour distribuer d’autres CLI Ruby
- Distribuer via Homebrew plutôt que via un gestionnaire de paquets spécifique au langage facilite aussi les évolutions de l’implémentation sans perturber les mises à jour côté utilisateur
Points clés de la Formula
- Toutes les Formulas sont écrites en Ruby, car de nombreux outils de développement populaires avant l’ère de JavaScript ou de l’IA reposaient sur Ruby
- La méthode
head permet de désigner un dépôt Git, même si son intérêt concret reste incertain
- Ajouter
livecheck a de la valeur, car cela facilite la mise à jour des versions de la Formula
- Le test d’exécution du binaire peut être implémenté simplement en vérifiant l’affichage de l’aide ; il ne faut pas se laisser intimider par les commentaires générés
- La commande
brew style searlsco/tap permet de repérer les erreurs de style
- Le
uses_from_macos "ruby" par défaut du template --ruby utilise la version 2.6.10 (une release antérieure au COVID et arrivée en fin de vie depuis 3 ans), donc il est recommandé de déclarer depends_on "ruby@3" pour dépendre d’une Formula Ruby plus récente
- Une fois la Formula satisfaisante, un
git push suffit pour la publier en production, et les utilisateurs pourront l’installer avec brew tap searlsco/tap puis brew install imsg
Mise à jour de la Formula à chaque release du CLI
- Mettre à jour manuellement l’
url et le hash sha256 en tête de la Formula à chaque release est fastidieux, et même la création d’un tag ou d’une release GitHub finit par devenir pesante
- On peut utiliser la commande
bump-formula-pr de Homebrew ou une GitHub Action pour générer une PR, mais le processus fork + PR paraît inutilement complexe
- Si l’on possède le tap, une méthode plus simple consiste à committer directement sur la branche main
- Pour éviter cela, il est recommandé d’ajouter un workflow GitHub au dépôt de la Formula afin de mettre à jour automatiquement le tap lors d’une release
- Le workflow d’exemple peut être repris tel quel
- Configuration nécessaire : créer un Personal Access Token GitHub avec le droit
Content → Write sur le dépôt homebrew-tap, puis l’enregistrer dans les Secrets du dépôt de la Formula sous le nom HOMEBREW_TAP_TOKEN
- Définir le tap et la Formula via des variables d’environnement (par exemple lignes 13 à 15)
- Il est recommandé d’utiliser le compte bot GitHub pour les mises à jour :
GH_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com, GH_NAME: github-actions[bot]
- Une fois la release créée, un
git push --tags déclenche la mise à jour automatique en quelques secondes, et les utilisateurs peuvent ensuite faire la mise à niveau avec brew update puis brew upgrade imsg
Le plus intéressant
- Le processus est complexe, mais une fois le tap configuré et un premier exemple de Formula en place, publier des CLI supplémentaires devient presque trivial
- Il devient pratique de publier une nouvelle Formula en quelques minutes
- Le processus officiel de Homebrew est un peu lourd, mais l’automatisation le rend beaucoup plus confortable
- Cela réduit les frictions entre la release d’un outil et sa distribution, tout en restant extensible à des CLI écrits dans différents langages
- Rien ne dit qu’un autre Formula sera réellement publiée, mais il est satisfaisant de savoir que cette possibilité existe
Aucun commentaire pour le moment.