Добавление программ в Homebrew

Не хватает вашей любимой программы в Homebrew? Тогда вы — идеальный человек для решения этой проблемы.

Если вы хотите добавить программу с закрытым исходным кодом или программу только с графическим интерфейсом, следуйте руководству для Casks. В противном случае следуйте руководству для Formulae. Также см.: Терминология Homebrew

Прежде чем начать, проверьте открытые запросы на добавление для Homebrew/homebrew-core или Homebrew/homebrew-cask, чтобы убедиться, что никто не опередил вас.

Далее, вы должны ознакомиться с документацией Допустимых Formulae или Допустимых Casks, чтобы определить, подходит ли данная программа для добавления в Homebrew. Если вы создаёте формулу для альтернативной версии программы, уже присутствующей в Homebrew (например, для версии, которая существенно отличается от существующей версии по основным/дополнительным версиям), обязательно прочитайте документацию Версий, чтобы понять требования к формулам с версиями.

Если всё проверено, вы готовы начать работу с новой формулой!

Formulae

Создание формулы

1. Полезно найти существующие формулы в Homebrew, похожие на программу, которую вы хотите добавить. Это поможет понять, как обычно обрабатываются конкретные языки, методы сборки и т. д.

2. Если вы начинаете с нуля, вы можете использовать команду brew create для создания базовой версии вашей формулы. Эта команда принимает ряд опций, и вы можете сэкономить время, используя соответствующую шаблонную опцию, например --python.

3. Теперь вам нужно развить шаблонный код из brew create в полноценную формулу. Основными ссылками будут Поваренная книга формул, аналогичные формулы в Homebrew и документация по выбранному вами программному обеспечению. Не забудьте также ознакомиться с документацией Homebrew по написанию формул для Python и Node, если это применимо.

4. Убедитесь, что вы написали хороший тест в рамках своей формулы. Обратитесь к разделу Добавление теста в формулу в Поваренной книге для получения помощи.

5. Попробуйте установить свою формулу, используя brew install --build-from-source <formula>, где <formula> — имя вашей формулы. Если возникнут ошибки, исправьте формулу и попробуйте установить её снова. Установка формулы должна завершиться без ошибок к концу этого шага.

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

Тестирование и аудит формулы

1. Запустите brew audit --strict --new-formula --online <formula> со своей формулой. Если возникнут ошибки, исправьте формулу и запустите аудит снова. Аудит должен завершиться без ошибок к концу этого шага.

2. Запустите тест формулы, используя brew test <formula>. Тест должен завершиться без ошибок.

Отправка формулы

Наконец, вы готовы отправить свою формулу в репозиторий homebrew-core. Если вы делаете это впервые, вы можете обратиться к документации Как создать запрос на добавление для получения помощи. Разработчики проверят запрос на добавление и дадут обратную связь по любым вопросам, которые необходимо решить, прежде чем формула может быть добавлена в Homebrew.

Если вы дошли до этого момента, поздравляем! Вы успешно создали формулу Homebrew! Мы ценим ваши усилия, и вы можете быть уверены, что ваша работа принесёт пользу другим пользователям Homebrew.

Casks

Примечание: Перед тем, как потратить время на создание нового cask:

• убедитесь, что его можно принять, проверив ЧаВО по отклоненным Casks, и
• убедитесь, что cask не был уже отклонен.

Написание cask

Создание нового cask просто. Следуйте инструкциям в Руководстве по участию.

Примеры

Вот cask для shuttle в качестве примера. Обратите внимание на параметр verified ниже url, который необходим, когда адреса URL и домашние страницы имеют разные домены.

cask "shuttle" do
  version "1.2.9"
  sha256 "0b80bf62922291da391098f979683e69cc7b65c4bdb986a431e3f1d9175fba20"

  url "https://github.com/fitztrev/shuttle/releases/download/v#{version}/Shuttle.zip",
      verified: "github.com/fitztrev/shuttle/"
  name "Shuttle"
  desc "Simple shortcut menu"
  homepage "https://fitztrev.github.io/shuttle/"

  app "Shuttle.app"

  zap trash: "~/.shuttle.json"
end

А вот один для noisy. Обратите внимание, что он имеет загрузку без версии (загрузка url не содержит номер версии, в отличие от примера выше). Он также подавляет контрольную сумму с sha256 :no_check, что необходимо, потому что так как загрузка url не содержит номер версии, её контрольная сумма изменится при появлении новой версии.

cask "noisy" do
  version "1.3"
  sha256 :no_check

  url "https://github.com/downloads/jonshea/Noisy/Noisy.zip"
  name "Noisy"
  desc "White noise generator"
  homepage "https://github.com/jonshea/Noisy"

  app "Noisy.app"
end

Вот последний пример для airdisplay, который использует установщик pkg для установки приложения вместо автономного пакета приложения (.app). Обратите внимание на uninstall pkgutil раздел, который необходим для удаления всех файлов, установленных с помощью установщика.

Вы также увидите, как адаптировать version к загрузке url. Используйте наши пользовательские version методы, обращаясь к стандартным методам Ruby String, когда они не подходят.

cask "airdisplay" do
  version "3.4.2,26581"
  sha256 "272d14f33b3a4a16e5e0e1ebb2d519db4e0e3da17f95f77c91455b354bee7ee7"

  url "https://www.avatron.com/updates/software/airdisplay/ad#{version.before_comma.no_dots}.zip"
  name "Air Display"
  desc "Utility for using a tablet as a second monitor"
  homepage "https://avatron.com/applications/air-display/"

  livecheck do
    url "https://www.avatron.com/updates/software/airdisplay/appcast.xml"
    strategy :sparkle
  end

  depends_on macos: ">= :mojave"

  pkg "Air Display Installer.pkg"

  uninstall pkgutil: [
    "com.avatron.pkg.AirDisplay",
    "com.avatron.pkg.AirDisplayHost2",
  ]
end

Генерация маркера для cask

Маркер cask — это мнемоническая строка, которую люди будут использовать для взаимодействия с cask через brew install, и т. д. Имя файла cask — это просто маркер с расширением .rb.

Самый простой способ сгенерировать маркер для cask — это выполнить эту команду:

$(brew --repository homebrew/cask)/developer/bin/generate_cask_token "/full/path/to/new/software.app"

Если программное обеспечение, для которого вы хотите создать cask, не установлено или не имеет связанного пакета App, просто укажите полное правильное имя программного обеспечения вместо пути к файлу:

$(brew --repository homebrew/cask)/developer/bin/generate_cask_token "Google Chrome"

Если скрипт generate_cask_token не работает для вас, см. Подробности о маркерах cask.

Создание файла cask

После того, как вы узнали маркер, создайте свой cask с помощью удобной команды brew create --cask.

brew create --cask download-url --set-name my-new-cask

Это откроет $EDITOR с шаблоном для вашего нового cask, который будет сохранён в файле my-new-cask.rb. Выполнение команды create выше даст вам шаблон, который выглядит так:

cask "my-new-cask" do
  version ""
  sha256 ""

  url "download-url"
  name ""
  desc ""
  homepage ""

  app ""
end

Разделы cask

Заполните следующие разделы для вашего cask:

Другие часто используемые разделы:

Дополнительные artifact разделы могут потребоваться для специальных случаев. Ещё более специализированные разделы приведены в Дополнительные разделы.

Подробности о маркерах cask

Если маркер конфликтует с уже существующим cask, авторы должны вручную сделать новый маркер уникальным, добавив имя производителя в префикс. Пример: unison.rb и panic-unison.rb.

Если возможно, избегайте создания маркеров, отличающихся только положением дефисов.

Чтобы вручную сгенерировать маркер или узнать об исключениях для необычных случаев, см. Справочник по маркерам.

Архивы с подпапками

Когда загруженный архив распаковывается в подпапку, имя подпапки должно быть включено в значение app.

Пример:

1. Texmaker скачивается в файл TexmakerMacosxLion.zip.
2. TexmakerMacosxLion.zip распаковывается в папку TexmakerMacosxLion.
3. Папка TexmakerMacosxLion содержит приложение texmaker.app.
4. Таким образом, фрагмент app должен включать подпапку в качестве относительного пути:

app "TexmakerMacosxLion/texmaker.app"

Тестирование и аудит бочки

Попробуйте:

export HOMEBREW_NO_AUTO_UPDATE=1
brew install my-new-cask

Установка прошла успешно? Если возникла ошибка, отредактируйте свою бочку с помощью brew edit my-new-cask, чтобы исправить её.

Также протестируйте, работает ли удаление:

brew uninstall my-new-cask

Если всё в порядке, убедитесь, что ваша бочка пройдёт аудит с помощью:

brew audit --new-cask my-new-cask

Также проверьте стилистические детали с помощью brew style:

brew style --fix my-new-cask

Помните, что все эти проверки будут выполнены при отправке вашего запроса на включение, поэтому, выполнив их заранее, вы экономите всем время и усилия.

Если ваше приложение и Homebrew Cask не работают вместе должным образом, не стесняйтесь отправить сообщение о проблеме после ознакомления с открытыми проблемами.

Отправка бочки

Нахождение места для вашей бочки

См. документацию по допустимым бочкам.

Перейдите в свой Tap и убедитесь, что ваша новая бочка там:

$ cd "$(brew --repository)"/Library/Taps/homebrew/homebrew-cask
$ git status
# On branch master
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#       Casks/my-new-cask.rb

Всё хорошо. Теперь создайте ветвь my-new-cask-branch, которую вы будете использовать в своём запросе на включение:

$ git checkout -b my-new-cask-branch
Switched to a new branch 'my-new-cask-branch'

Подготовьте вашу бочку с помощью:

git add Casks/my-new-cask.rb

Вы можете просмотреть изменения, которые будут добавлены с помощью:

git diff --cached

Зафиксируйте изменения с помощью:

git commit -v

Сообщения об изменениях

Для любого проекта Git хорошими правилами для сообщений об изменениях являются:

• Первая строка — это сводка изменений, не более 50 символов,
• За ней следует пустая строка,
• За ней следует объяснение изменений, разбитые на строки по 72 символа.

См. Заметку о сообщениях об изменениях в Git для получения дополнительной информации.

Первая строка сообщения об изменениях становится заголовком запроса на включение в GitHub, подобно предметной строке письма. Включение ключевой информации в первую строку поможет нам быстрее реагировать на ваш запрос на включение.

Для коммитов бочек в проекте Homebrew Cask мы хотели бы включить название приложения, номер версии и назначение коммита в первую строку.

Примеры хороших, понятных сводок изменений:

• Add Transmission.app v1.0
• Upgrade Transmission.app to v2.82
• Fix checksum in Transmission.app cask
• Add CodeBox Latest

Примеры сложных, непонятных сводок изменений:

• Upgrade to v2.82
• Checksum was bad

Отправка

Отправьте свои изменения на ветвь my-new-cask-branch на ваш GitHub аккаунт:

git push  my-new-cask-branch

Если вы используете двухфакторную аутентификацию GitHub и установили удалённый репозиторий как HTTPS, вам необходимо создать токен доступа и использовать его вместо пароля.

Создание запроса на включение в GitHub

a) использовать предложение из git push

Команда git push выводит предложение о том, как создать запрос на включение:

remote: Create a pull request for 'new-cask-cask' on GitHub by visiting:
remote:      https://github.com//homebrew-cask/pull/new/my-new-cask-branch

b) использовать предложение с сайта GitHub

Теперь перейдите на homebrew-cask репозиторий GitHub. GitHub часто будет показывать вашу ветвь my-new-cask-branch с удобной кнопкой для Compare & pull request.

c) создать запрос на включение в GitHub вручную

В противном случае, нажмите кнопку Contribute > Open pull request и выберите compare across forks. Базовая ветвь должна быть Homebrew/homebrew-cask @ master, а головная ветвь — my-github-username/homebrew-cask @ my-new-cask-branch. Вы также можете добавить дополнительные комментарии к своему запросу на этом этапе.

Поздравляем!

Всё готово, и ваша бочка должна быть включена или замечена в ближайшее время. Если поддерживающий предлагает некоторые изменения, просто внесите их в ветвь my-new-cask-branch локально и отправьте.

Очистка

После отправки запроса на включение вернитесь на ветвь master, чтобы brew update правильно скачал новые бочки:

cd "$(brew --repository)"/Library/Taps/homebrew/homebrew-cask
git checkout master

Если вы ранее установили переменную HOMEBREW_NO_AUTO_UPDATE, очистите её с помощью:

unset HOMEBREW_NO_AUTO_UPDATE