Как создать и поддерживать tap

Тапы — это внешние источники формул Homebrew, cask-приложений и/или внешних команд. Их может создавать кто угодно, чтобы предоставлять собственные формулы, cask-приложения и/или внешние команды любому пользователю Homebrew.

Создание tap

Обычно tap — это доступный в интернете репозиторий Git, но можно использовать что угодно, если это протокол, который понимает Git, или даже просто каталог с файлами. Если репозиторий размещён на GitHub, мы рекомендуем, чтобы его название начиналось с homebrew-, чтобы можно было использовать краткую команду brew tap. Подробнее о названиях репозиториев см. на странице руководства brew.

Команду brew tap-new можно использовать для создания нового tap с несколькими файлами-шаблонами:

$ brew tap-new $YOUR_GITHUB_USERNAME/homebrew-tap
Initialized empty Git repository in /opt/homebrew/Library/Taps/$YOUR_GITHUB_USERNAME/homebrew-tap/.git/
...
==> Created $YOUR_GITHUB_USERNAME/tap
/opt/homebrew/Library/Taps/$YOUR_GITHUB_USERNAME/homebrew-tap

Будет создан локальный tap с правильной структурой каталогов. Затем его можно отправить в новый репозиторий GitHub, выполнив команду (из любого каталога):

$ brew install gh
...
$ gh repo create $YOUR_GITHUB_USERNAME/homebrew-tap --push --public --source "$(brew --repository $YOUR_GITHUB_USERNAME/homebrew-tap)"
✓ Created repository $YOUR_GITHUB_USERNAME/homebrew-tap on github.com
  https://github.com/$YOUR_GITHUB_USERNAME/homebrew-tap
✓ Added remote https://github.com/$YOUR_GITHUB_USERNAME/homebrew-tap.git
...
✓ Pushed commits to https://github.com/$YOUR_GITHUB_USERNAME/homebrew-tap.git

Если оставить файлы .github/workflows по умолчанию, «бутылки» (бинарные пакеты) будут собираться с помощью GitHub Actions. После проверки pull request и подтверждения успешного прохождения проверок опубликуйте бутылки сразу с помощью brew pr-pull, передав SHA коммита, который прошёл проверку. Для повышения безопасности мы рекомендуем передавать --head-sha:

brew pr-pull --tap=$YOUR_GITHUB_USERNAME/tap --head-sha=0123456789abcdef0123456789abcdef01234567 123

Параметр --head-sha можно опустить: brew pr-pull выведет SHA головного коммита pull request, который будет использоваться. Это менее безопасно, если головной коммит pull request изменится после проверки, но до выполнения brew pr-pull, поскольку команда опубликует бутылки для более нового головного коммита, а не для проверенного вами коммита.

brew pr-pull --tap=$YOUR_GITHUB_USERNAME/tap 123

Можно также вручную запустить созданный рабочий процесс brew pr-pull, указав номер pull request и, при желании, SHA проверенного коммита. В репозитории tap на GitHub откройте вкладку Actions, выберите рабочий процесс brew pr-pull, нажмите Run workflow, введите номер pull request и при желании ожидаемый головной SHA, затем нажмите Run workflow. Если головной коммит pull request изменится до завершения публикации при использовании --head-sha или поля ввода SHA головного коммита в рабочем процессе, brew pr-pull завершится с ошибкой, а не опубликует бутылки для другого коммита.

Если вы запускаете brew tap-new --github-packages, вместо этого можно выполнять загрузку в GitHub Packages.

Формулы в tap имеют тот же формат, что и формулы в core, и могут размещаться либо в подкаталоге Formula, либо в подкаталоге HomebrewFormula, либо в корне репозитория. Используется первый доступный каталог, остальные расположения игнорируются. Мы рекомендуем использовать подкаталоги: так проще понять структуру репозитория, а файлы верхнего уровня не смешиваются с формулами.

Пример tap с подкаталогом Formula можно посмотреть в репозитории homebrew/core.

Создание формулы или cask-приложения

Выполните brew create, чтобы создать файл формулы или cask-приложения в tap и открыть его в текстовом редакторе:

$ brew create https://mirror.ibcp.fr/pub/gnu/wget/wget-1.25.0.tar.gz --tap $YOUR_GITHUB_USERNAME/homebrew-tap --set-name $YOUR_GITHUB_USERNAME-wget
==> Downloading from https://mirror.ibcp.fr/pub/gnu/wget/wget-1.25.0.tar.gz
...
Editing /opt/homebrew/Library/Taps/$YOUR_GITHUB_USERNAME/homebrew-tap/Formula/$YOUR_GITHUB_USERNAME-wget.rb

Затем следуйте руководству Добавление программного обеспечения в Homebrew, чтобы создать файл формулы или cask-приложения.

Наконец, добавьте git add, git commit и git push вашу формулу или cask-приложение в tap — и другие пользователи тоже смогут ими пользоваться.

Извлечение исторической версии формулы в ваш tap

Если вы хотите сохранить в tap старую версию формулы, brew extract может скопировать в него историческую версию из homebrew/core:

brew extract --version=1.2.3 foo $YOUR_GITHUB_USERNAME/homebrew-tap

Эта команда только создаёт файл формулы в tap. Вы сами отвечаете за его фиксацию в коммите, отправку в удалённый репозиторий и дальнейшее сопровождение, включая устранение проблем, связанных с устареванием, и установку обновлений безопасности. Если вам нужен более простой рабочий процесс, который одновременно извлекает и устанавливает формулу, используйте вместо этого brew version-install. О компромиссах и ограничениях поддержки этих подходов см. в разделе Закрепление установленных формул на конкретных версиях.

Как называть формулы, чтобы избежать конфликтов

Если формула в вашем tap имеет такое же название, как формула Homebrew/homebrew-core, установить их одновременно не получится. Если вы хотите создать другую версию формулы из Homebrew/homebrew-core (например, с optionами), подумайте о том, чтобы дать ей другое название; например, nginx-full для более функциональной формулы nginx. Это позволит одновременно установить и nginx, и nginx-full (при условии, что одна из них является только keg или связанные файлы не конфликтуют).

Установка

Пользователи могут устанавливать формулы из вашего tap двумя способами:

Прямая установка (рекомендуется)

Пользователи могут установить любую вашу формулу напрямую с помощью brew install user/repository/formula. Homebrew автоматически добавит ваш tap перед установкой формулы:

$ brew install alice/homebrew-tap/my-script
==> Tapping alice/homebrew-tap
Cloning into '/opt/homebrew/Library/Taps/alice/homebrew-tap'...
...
==> Installing my-script from alice/homebrew-tap

Это самый удобный для пользователей способ, поскольку для него нужна всего одна команда. Кроме того, он доверяет только устанавливаемой формуле. Подробнее см. в разделе Доверие к tap.

Установка tap вручную

Чтобы установить ваш tap, не устанавливая при этом никакую формулу, пользователи могут добавить его с помощью команды brew tap:

# For GitHub repositories
$ brew tap user/repository

# For repositories hosted elsewhere
$ brew tap user/repo <URL>

Здесь user — ваше имя пользователя GitHub, repository — название вашего репозитория, а <URL> — URL-адрес клонирования Git для репозиториев, размещённых не на GitHub.

После добавления tap пользователи могут установить ваши формулы одним из следующих способов:

brew install foo, если формулы с таким же названием в core нет
brew install user/repository/foo, чтобы избежать конфликтов с формулами core

Пользователям, устанавливающим формулы по краткому имени, сначала потребуется выполнить brew trust user/repository, если Homebrew потребует явно подтвердить доверие к неофициальным tap в Homebrew 6.0.0 или 5.2.0 — в зависимости от того, какая версия выйдет раньше.

Поддержка tap

Tap — это просто репозиторий Git, поэтому при внесении изменений не нужно выполнять никаких специальных действий, кроме фиксации изменений в коммите и отправки их в удалённый репозиторий.

Обновление

После установки tap Homebrew будет обновлять его каждый раз, когда пользователь выполняет brew update. Устаревшие формулы будут обновляться, когда пользователь выполнит brew upgrade, как и формулы core.

Устранение неполадок

Формула не найдена после установки: убедитесь, что файл формулы находится в правильном расположении (подкаталог Formula/) и имеет правильное расширение (.rb).
Установка завершается с ошибкой: проверьте правильность значений url и sha256 в формуле. Проверить SHA256 можно с помощью команды:
```
curl -L <URL> | shasum -a 256
```
Tap не обновляется: пользователям может потребоваться выполнить brew untap user/repository && brew tap user/repository, чтобы принудительно заново клонировать tap.
Конфликты с формулами core: если ваша формула конфликтует с формулой core, подумайте о том, чтобы переименовать её или сделать её только keg.

Cask-приложения

Cask-приложения тоже можно устанавливать из tap. Их можно включать в tap вместе с формулами или создать tap только для cask-приложений. Поместите все нужные файлы cask-приложений в каталог Casks в корне tap.

Пример tap с подкаталогом Casks можно посмотреть в репозитории homebrew/cask.

Именование

В отличие от формул, названия cask-приложений должны быть уникальными во всём мире, чтобы избежать конфликтов. Например, можно добавить к названию cask-приложения имя пользователя GitHub: username-formula-name.

Внешние команды

Вы можете предоставлять пользователям своего tap собственные команды brew, добавив их в подкаталог cmd. Подробнее о внешних командах.

Tap от upstream-проектов

Некоторые поставщики программного обеспечения, например upstream-проекты, предпочитают размещать свои программы в собственном tap Homebrew. Если их программы подходят для Homebrew/homebrew-core, мы предпочитаем сопровождать их там — это упрощает обновления, повышает находимость и позволяет использовать такие инструменты, как formulae.brew.sh.

Мы не будем удалять программы из Homebrew/homebrew-core в пользу tap от upstream-проекта. Мы также не будем рекомендовать пользователям наших формул вместо них использовать tap от upstream-проекта. Если upstream-проекты недовольны тем, как Homebrew упаковывает их программы, им следует сообщить о проблеме (а ещё лучше — предложить pull request), чтобы её устранить.

Если вы разработчик или представитель upstream-проекта и хотите узнать больше о том, почему Homebrew придерживается такого подхода, прочитайте также раздел Работа с Homebrew в качестве upstream-проекта.

Само по себе обращение upstream-проекта не является достаточной причиной для объявления программы устаревшей, отключения или удаления. Если по нашим аналитическим данным программу устанавливают, а в системе отслеживания ошибок нет сообщений пользователей о проблемах с упаковкой программы в Homebrew, мы, как правило, оставим её в Homebrew/homebrew-core до появления более веских технических, политических или общепроектных причин для другого решения.

В коммерческих проектах с открытым исходным кодом всё чаще стремятся «сохранять контроль», например точно определять, какие бинарные файлы поставляются пользователям. Отказ поддерживать сборку из исходного кода для пользователей (или даже дистрибутивов программного обеспечения) противоречит ценностям открытого исходного кода. Если вам кажется, что позиция Homebrew в этом вопросе раздражает, попробуйте узнать, как Debian реагирует на просьбы поставлять ваши бинарные файлы.

© 2009–present Homebrew contributors
Licensed under the BSD 2-Clause License.
https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap