- Homebrew ist ein Paketmanager für macOS, mit dem sich CLI-Tools einfach installieren und verwalten lassen, sodass Entwickler ihre Systemumgebung mit häufig genutzten Werkzeugen effizient einrichten können
- Dieser Leitfaden erklärt, wie man mit Homebrew persönliche CLI-Skripte verteilt, und zeigt, wie sich die Wartung durch GitHub-Integration und automatisierte Workflows vereinfachen lässt
- Der Distributionsprozess verläuft über CLI erstellen → GitHub-Release → Tap anlegen → Formula schreiben und aktualisieren und ermöglicht am Ende die Installation allein mit den Befehlen
brew tap und brew install
- Wer das Begriffssystem und die Best Practices von Homebrew versteht, kann eine stabile Distribution mit besserer Reproduzierbarkeit und Supply-Chain-Sicherheit aufsetzen
- Der Prozess lässt sich mit GitHub Actions automatisieren; ist er einmal eingerichtet, wird auch die spätere Distribution anderer CLIs sehr viel einfacher
Hintergrund und Motivation
- Homebrew ist der bevorzugte Paketmanager für die Installation von CLI-Tools und wird von vielen Entwicklern genutzt
- Eigene CLIs werden jedoch oft über npm oder RubyGems verteilt, weshalb sich der Distributionsweg über Homebrew zunächst ungewohnt anfühlen kann
- Da das offizielle Core-Repository von Homebrew selbst entwickelte Tools nur ungern aufnimmt, verteilen normale Entwickler sie über einen separaten Tap und eine eigene Formula
- Dieser Leitfaden basiert auf Erfahrungen mit der Distribution einer einfachen Ruby-basierten CLI
Begriffserklärung
- Homebrew verwendet eigene Begriffe im Stil des Bierbrauens; wer sie versteht, kann die Systemstruktur leichter erfassen
- Eine Formula ist eine Paketdefinitionsdatei, die Anweisungen zur Installation von Quellcode oder Binärdateien enthält
- Ein Tap ist ein Git-Repository für Formulas, mit dem benutzer- oder organisationsspezifische Pakete verwaltet werden
- Ein Cask ist ein Installationsmanifest für GUI-Apps oder große Binärdateien; ähnlich wie eine Formula, aber für vorgebaute Dateien
- Eine Bottle ist ein vorgebautes Binärpaket, das statt eines Builds aus dem Quellcode einfach kopiert wird und so die Installation beschleunigt
- Der Cellar ist das Verzeichnis, in dem installierte Formulas liegen, zum Beispiel unter
/opt/homebrew/Cellar
- Ein Keg ist das Installationsinstanz-Verzeichnis einer bestimmten Formula und liegt versionsweise innerhalb des Cellar
Überblick
- Das Homebrew-Core-Repository nimmt nischige oder persönliche Einreichungen nicht an, daher müssen Nutzer ein separates Tap-Repository anlegen, um ihre CLI zu verteilen
- 1. CLI erstellen, auf GitHub hochladen und ein Tag-Release veröffentlichen
- 2. Mit
brew tap-new ein Tap anlegen und zu GitHub pushen
- 3. Mit
brew create eine Formula erstellen (einschließlich Tarball-URL und SHA256)
- 4. Bei jeder neuen Version die Formula aktualisieren, damit Nutzer die CLI einfach mit
brew install installieren können
- Nach Abschluss der Distribution können Nutzer die CLI mit zwei Befehlen installieren:
brew tap your_github_handle/tap und brew install your_cool_cli
- Dieser Leitfaden überspringt die CLI-Entwicklung und konzentriert sich auf das Anlegen des Tap, das Erstellen der Formula und deren Aktualisierung
- Als Beispiel dient die CLI
imsg, die aus einer iMessage-Datenbank ein interaktives Web-Archiv erstellt
Tap anlegen
- Dazu folgt man dem Leitfaden zum Erstellen eines Tap von Homebrew und ersetzt dabei GitHub-Benutzernamen oder Organisationsnamen entsprechend
- Um künftig alle CLI-Tools in einem Tap zu bündeln, wird der Name
homebrew-tap empfohlen; das Präfix homebrew wird von der CLI speziell behandelt und das Präfix tap ist gängige Konvention
- Befehl zum Anlegen des Tap:
brew tap-new searlsco/homebrew-tap
- Dadurch wird ein Scaffold unter
/opt/homebrew/Library/Taps/searlsco/homebrew-tap erzeugt
- Anschließend erstellt man das entsprechende Repository auf GitHub und pusht den generierten Inhalt:
cd /opt/homebrew/Library/Taps/searlsco/homebrew-tap, git remote add origin git@github.com:searlsco/homebrew-tap.git, git push -u origin main
- Sobald man Eigentümer des Tap ist, können andere Nutzer das Repository mit
brew tap searlsco/tap klonen und unter /opt/homebrew/Library/Taps ablegen
- Anfangs ist dort noch nichts Nützliches enthalten, aber das Grundverhalten lässt sich bereits überprüfen
Formula erstellen
- Homebrew kann GitHub-Repositories direkt referenzieren, empfiehlt aber die Verwendung von versionierten Tarballs und Checksummen, um Reproduzierbarkeit und Open-Source-Supply-Chain-Sicherheit zu stärken
- Befehl zum Erstellen der Formula:
brew create https://github.com/searlsco/imsg/archive/refs/tags/v0.0.5.tar.gz --tap searlsco/homebrew-tap --set-name imsg --ruby
- Das Flag
--tap gibt das benutzerdefinierte Tap an und legt die Formula unter /opt/homebrew/Library/Taps/searlsco/homebrew-tap/Formula ab
--set-name imsg setzt den Namen der Formula explizit; dieser sollte eindeutig gewählt werden, um Namenskonflikte zu vermeiden (zum Beispiel mit vorhandenem TLDR oder der Standard-CLI)--ruby ist ein Template-Preset für Ruby-CLIs und eines von mehreren Optionen, die die Anpassung vereinfachen
- Die erzeugte Formula funktioniert anfangs möglicherweise noch nicht, daher kann man sie mit Hilfe eines LLM überarbeiten:
brew install --verbose imsg ausführen, den Fehler in ChatGPT eingeben und die Formula wiederholt anpassen
- Die finale Datei Formula/imsg.rb kann als Ausgangspunkt für die Distribution einer Ruby-CLI kopiert werden
- Wer statt eines sprachspezifischen Paketmanagers über Homebrew verteilt, ermöglicht Nutzern reibungslose Upgrades auch dann, wenn sich die Implementierungssprache ändert
Wichtige Highlights der Formula
- Alle Formulas werden in Ruby geschrieben, da viele beliebte Entwicklerwerkzeuge vor JavaScript oder AI auf Ruby basierten
- Mit der Methode
head lässt sich ein Git-Repository angeben, auch wenn der tatsächliche Effekt unklar ist
- Das Hinzufügen von
livecheck lohnt sich, weil es Versionsupdates der Formula erleichtert
- Ein Test für die Ausführung der Binärdatei lässt sich einfach über die Prüfung der Hilfsausgabe implementieren; man sollte sich von den generierten Kommentaren nicht einschüchtern lassen
- Mit
brew style searlsco/tap lassen sich Stilfehler prüfen
- Das Standard-
uses_from_macos "ruby" des --ruby-Templates verwendet Version 2.6.10 (ein Release von vor COVID, seit 3 Jahren EOL), daher wird stattdessen depends_on "ruby@3" als Abhängigkeit von der aktuellen Ruby-Formula empfohlen
- Wenn die Formula zufriedenstellend ist, wird sie mit
git push live verteilt; Nutzer können sie dann mit brew tap searlsco/tap und brew install imsg installieren
Formula bei jedem CLI-Release aktualisieren
- Die
url und der sha256-Hash am Anfang der Formula müssen bei jedem Release manuell aktualisiert werden, was mühsam ist; selbst das Pushen eines Tags oder das Erstellen eines GitHub-Releases kann auf Dauer lästig werden
- Mit dem Homebrew-Befehl
bump-formula-pr oder per GitHub Action lässt sich zwar ein PR erzeugen, aber der Prozess mit Fork und PR ist unnötig komplex
- Wenn man Eigentümer des Tap ist, ist ein einfacher Weg mit direkten Commits auf den Main-Branch wünschenswerter
- Um das zu vermeiden, wird empfohlen, dem Formula-Repository einen GitHub-Workflow hinzuzufügen, der das Tap beim Release automatisch aktualisiert
- Das Workflow-Beispiel kann direkt kopiert und verwendet werden
- Erforderliche Einrichtung: Beim Erstellen eines GitHub Personal Access Token (PAT) dem Repository
homebrew-tap die Berechtigung Content → Write geben und das Token in den Secrets des Formula-Repositories unter HOMEBREW_TAP_TOKEN speichern
- Tap und Formula werden über Umgebungsvariablen festgelegt (zum Beispiel in Zeile 13–15)
- Für Updates wird das GitHub-Bot-Konto empfohlen:
GH_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com, GH_NAME: github-actions[bot]
- Nach dem Erstellen eines Releases genügt
git push --tags, und innerhalb weniger Sekunden erfolgt die automatische Aktualisierung; Nutzer können dann mit brew update und brew upgrade imsg upgraden
Das Beste daran
- Der Prozess ist zwar komplex, aber sobald das Tap eingerichtet und ein Formula-Beispiel fertig ist, wird die Verteilung zusätzlicher CLIs fast trivial
- Neue Formulas lassen sich bequem in wenigen Minuten veröffentlichen
- Der offizielle Homebrew-Prozess ist etwas kompliziert, wird durch Automatisierung aber deutlich angenehmer
- So lässt sich der Aufwand zwischen Tool-Release und Distribution verringern und auch auf CLIs in verschiedenen Sprachen ausweiten
- Ob tatsächlich noch eine weitere Formula veröffentlicht wird, ist offen, aber allein die Möglichkeit fühlt sich lohnend an
Noch keine Kommentare.