Evita que el PATH del Mac decideixi per tu
En un Mac de desenvolupament, el problema rarament és que falti una eina. El problema apareix quan n’hi ha massa. Una versió antiga de node, un openssl instal·lat per un altre projecte o un postgresql que el teu shell localitza abans que el que esperaves poden convertir una compilació aparentment repetible en una conversa amb el passat.
Homebrew permet declarar l’entorn d’un projecte en un Brewfile i executar-hi ordres amb brew bundle exec. Aquesta ordre prepara les rutes i les variables necessàries perquè el procés trobi les dependències declarades, incloses les fórmules keg-only, sense haver de reescriure el PATH a mà. (docs.brew.sh)
El cas és realista: un equip manté una aplicació que compila una extensió nativa amb Node, pkg-config i openssl@3. Al Mac d’una persona funciona perquè té eines antigues acumulades; en un altre Mac, el mateix projecte falla o enllaça contra una biblioteca diferent. El remei és fer visible la dependència i convertir-la en una condició verificable.
Abans de començar, cal tenir Homebrew operatiu amb el compte que compila el projecte. En Apple Silicon, la instal·lació acostuma a residir a /opt/homebrew; en equips Intel, a /usr/local. Comprova quin prefix utilitza realment el Mac amb brew --prefix, en lloc d’assumir-lo. (docs.brew.sh)
Crea un Brewfile a l’arrel del repositori:
brew "node"
brew "pkg-config"
brew "openssl@3"
Cada línia declara una fórmula requerida. Evita incloure eines personals, com editors o utilitats de terminal: aquest fitxer descriu el contracte tècnic del projecte, no la fotografia completa del teu ordinador.
Ara executa:
brew bundle check
L’ordre no modifica res. Revisa si totes les dependències del Brewfile ja són presents i retorna un codi d’error si en falta alguna. En automatitzacions, aquest resultat permet aturar una compilació abans que produeixi errors ambigus. Si vols saber què falta, afegeix --verbose. (docs.brew.sh)
Per instal·lar o actualitzar les eines declarades, fes servir:
brew bundle install
Aquesta ordre modifica l’estat del Mac: instal·la dependències absents i, per defecte, pot actualitzar les existents. En un projecte que exigeix canvis controlats, executa-la durant l’actualització planificada de l’entorn o afegeix --no-upgrade quan només necessitis completar absències. Aquesta opció evita l’actualització, però no fixa versions ni crea cap fitxer de bloqueig. (docs.brew.sh)
El pas decisiu és compilar dins l’entorn declarat:
brew bundle exec --check npm ci
brew bundle exec --check npm run build
--check exigeix que el Brewfile ja estigui satisfet; així, la compilació no instal·la res silenciosament. brew bundle exec prepara l’entorn del procés fill i fa que node, pkg-config i les biblioteques necessàries es resolguin des de Homebrew segons la declaració del projecte. Pots verificar-ho així:
brew bundle exec --check which node
brew bundle exec --check pkg-config --modversion openssl
La primera ordre ha d’assenyalar el binari dins el prefix de Homebrew. La segona confirma que pkg-config localitza openssl en aquest context.
En entorns corporatius, evita executar aquesta preparació com a root. Si un MDM gestiona Homebrew, la documentació recomana que l’agent seleccioni explícitament el propietari del prefix amb brew as-brew-user; també recomana conservar la sortida i el codi de retorn de cada feina de gestió. (docs.brew.sh)
Hi ha una limitació important: un Brewfile descriu paquets, no una imatge immutable del Mac. Les actualitzacions poden variar amb el temps. Per això convé revisar les actualitzacions en integració contínua i reservar brew bundle cleanup --force per a revisions conscients: pot desinstal·lar programari que no consti al fitxer.
Repte final: afegeix un objectiu bootstrap al teu projecte que executi brew bundle check || brew bundle install, i fes que la compilació sempre passi per brew bundle exec --check. Quan algú incorpori una dependència nova, el repositori deixarà de confiar en la memòria del seu Mac.