- Homebrew es un gestor de paquetes que permite instalar y administrar fácilmente herramientas CLI en macOS, y ayuda a los desarrolladores a configurar de forma eficiente su entorno del sistema con herramientas de uso frecuente
- Esta guía explica el proceso de distribuir scripts CLI personales con Homebrew y muestra cómo simplificar el mantenimiento mediante la integración con GitHub y flujos de trabajo automatizados
- El proceso de distribución sigue esta secuencia: crear la CLI → publicar un release en GitHub → crear un Tap → escribir y actualizar la Formula, y al final se puede instalar solo con los comandos
brew tap y brew install
- Entender la terminología y las mejores prácticas de Homebrew permite una distribución estable con mayor reproducibilidad y seguridad de la cadena de suministro
- También puede automatizarse con flujos de trabajo de GitHub Actions, y una vez configurado, la gran ventaja es que luego distribuir otras CLI se vuelve muy sencillo
Contexto y motivación
- Homebrew es el gestor de paquetes preferido para instalar herramientas CLI en macOS y es usado por muchos desarrolladores
- Sin embargo, muchas veces las CLI creadas por uno mismo se distribuyen como npm o RubyGem, y la forma de distribución con Homebrew puede sentirse poco familiar
- El repositorio core oficial de Homebrew tiene la política de no aceptar el registro de herramientas caseras, por lo que los desarrolladores comunes distribuyen con un tap y una formula por separado
- Esta guía se basa en una experiencia sencilla de distribución de una CLI hecha en Ruby
Explicación de términos
- Homebrew usa una terminología propia inspirada en la elaboración de cerveza, así que entenderla facilita captar la estructura del sistema
- Formula es un archivo de definición de paquete que incluye instrucciones para instalar código fuente o binarios
- Tap es un repositorio Git de formulas, usado para administrar paquetes personalizados por usuario u organización
- Cask es un manifiesto de instalación para apps GUI o binarios grandes; es similar a Formula, pero maneja archivos precompilados
- Bottle es un paquete binario precompilado que se copia en lugar de compilar desde el código fuente, lo que acelera la instalación
- Cellar es el directorio donde se ubican las formulas instaladas; por ejemplo, puede estar en
/opt/homebrew/Cellar
- Keg es el directorio de instancia instalada de una Formula específica, organizado por versión dentro del Cellar
Resumen general
- Como el repositorio core de Homebrew no acepta contenido de nicho o enviado de forma personal, los usuarios deben crear un repositorio tap separado para distribuir su CLI
- 1. Crear la CLI, subirla a GitHub y hacer un release con tag
- 2. Crear el Tap con
brew tap-new y hacer push a GitHub
- 3. Crear la Formula con
brew create (incluyendo la URL del tarball y el SHA256)
- 4. Actualizar la Formula en cada nueva versión para que los usuarios puedan instalarla fácilmente con
brew install
- Una vez terminada la distribución, los usuarios pueden instalar la CLI con dos comandos:
brew tap your_github_handle/tap y brew install your_cool_cli
- Esta guía omite el desarrollo de la CLI y se enfoca en la creación del tap, la generación de la Formula y su actualización
- Como ejemplo, usa la CLI
imsg, que crea un archivo web interactivo a partir de una base de datos de iMessage
Crear el tap
- Se sigue la guía de creación de tap de Homebrew, reemplazando el nombre de usuario u organización de GitHub según corresponda
- Como se recomienda reunir todas las futuras herramientas CLI en un solo tap, se sugiere el nombre
homebrew-tap; el prefijo homebrew recibe un tratamiento especial en la CLI y el sufijo tap es una convención
- Ejecutar el comando para crear el tap:
brew tap-new searlsco/homebrew-tap
- Esto genera el scaffold en
/opt/homebrew/Library/Taps/searlsco/homebrew-tap
- Luego se crea el repositorio correspondiente en GitHub y se hace push del contenido generado:
cd /opt/homebrew/Library/Taps/searlsco/homebrew-tap, git remote add origin git@github.com:searlsco/homebrew-tap.git, git push -u origin main
- Una vez que se posee el tap, otros usuarios pueden clonar el repositorio en
/opt/homebrew/Library/Taps con el comando brew tap searlsco/tap
- Al principio no habrá nada útil dentro, pero sí se puede confirmar el funcionamiento básico
Crear la Formula
- Aunque Homebrew puede referenciar directamente un repositorio de GitHub, recomienda usar un tarball versionado y su checksum para reforzar la reproducibilidad y la seguridad de la cadena de suministro de software libre
- Comando para crear 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
- La bandera
--tap especifica el tap personalizado y coloca la Formula en /opt/homebrew/Library/Taps/searlsco/homebrew-tap/Formula
--set-name imsg establece explícitamente el nombre de la Formula; conviene elegir uno único para evitar duplicados (por ejemplo, tener cuidado con colisiones con CLIs existentes como TLDR o standard)--ruby es un preset de plantilla para CLI en Ruby, una de varias opciones que simplifican la personalización
- La Formula generada puede no funcionar al principio, así que se sugiere corregirla con ayuda de un LLM: ejecutar
brew install --verbose imsg, pasar el error a ChatGPT y repetir la actualización de la Formula
- El archivo final Formula/imsg.rb puede copiarse como punto de partida para distribuir una CLI en Ruby
- Distribuir con Homebrew en vez de un gestor de paquetes específico del lenguaje permite que las actualizaciones para los usuarios sigan siendo fluidas incluso si cambia el lenguaje de implementación
Puntos destacados de la Formula
- Todas las Formulas están escritas en Ruby, porque muchas herramientas de desarrollo populares antes de JavaScript o la IA estaban basadas en Ruby
- El método
head permite especificar un repositorio Git, aunque no está claro qué tan útil resulta en la práctica
- Agregar
livecheck vale la pena porque facilita actualizar la versión de la Formula
- La prueba de ejecución del binario puede implementarse de forma simple verificando la salida de ayuda; no hay que intimidarse por los comentarios generados
- Se pueden revisar errores de estilo con el comando
brew style searlsco/tap
- El
uses_from_macos "ruby" predeterminado de la plantilla --ruby usa la versión 2.6.10 (un release previo al COVID y con EOL hace 3 años), por lo que se recomienda depender de la Formula más reciente con depends_on "ruby@3"
- Cuando la Formula ya esté lista, basta con
git push para publicarla en vivo, y los usuarios podrán instalarla con brew tap searlsco/tap y brew install imsg
Actualizar la Formula en cada release de la CLI
- Actualizar manualmente la URL y el hash
sha256 en la parte superior de la Formula en cada release es tedioso, y se señala que incluso crear tags o releases en GitHub puede volverse cansado
- Es posible crear PRs con el comando
bump-formula-pr de Homebrew o con acciones de GitHub, pero el proceso de fork y PR resulta innecesariamente complejo
- Si se es dueño del tap, es preferible un método simple que haga commit directo a la rama main
- Para evitarlo, se recomienda agregar un workflow de GitHub al repositorio de la Formula para actualizar automáticamente el tap al publicar un release
- Se puede copiar este ejemplo de workflow
- Configuración necesaria: al crear un token de acceso personal (PAT), otorgar permiso
Content → Write al repositorio homebrew-tap, y guardarlo en los Secrets del repositorio de la Formula como HOMEBREW_TAP_TOKEN
- Definir el tap y la Formula mediante variables de entorno (por ejemplo, en las líneas 13-15)
- Se recomienda usar la cuenta bot de GitHub para la actualización:
GH_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com, GH_NAME: github-actions[bot]
- Después de crear el release y ejecutar
git push --tags, la actualización se hace automáticamente en unos segundos, y los usuarios pueden actualizar con brew update y brew upgrade imsg
Lo mejor de todo
- Aunque el proceso es complejo, una vez que se completa la configuración del tap y un ejemplo de Formula, publicar CLI adicionales se vuelve casi trivial
- Es muy práctico poder publicar una nueva Formula en solo unos minutos
- El proceso oficial de Homebrew es algo complicado, pero con automatización se vuelve cómodo
- Reduce la fricción entre el release y la distribución de cada herramienta, y puede ampliarse para dar soporte a CLI en distintos lenguajes
- No está claro si realmente se publicará otra Formula, pero resulta satisfactorio tener abierta esa posibilidad
Aún no hay comentarios.