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

Не нашли нужную программу в Homebrew? Тогда именно вы можете решить эту проблему.

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

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

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

Если всё в порядке, можно приступать к созданию новой формулы!

Формулы

Написание формулы

1. Полезно найти в Homebrew существующие формулы для программ, похожих на ту, которую вы хотите добавить. Это поможет понять, как обычно работают с конкретными языками, методами сборки и т. д. Для начала подключите homebrew/core: сначала задайте HOMEBREW_NO_INSTALL_FROM_API=1 в окружении оболочки, затем выполните brew tap --force homebrew/core, чтобы клонировать tap homebrew/core в путь, возвращённый командой brew --repository homebrew/core.

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

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

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

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

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

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

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

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

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

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

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

Cask

Примечание: прежде чем тратить время на создание нового Cask:

• убедитесь, что его можно принять, ознакомившись с разделом Часто задаваемые вопросы об отклонённых Cask, и
• проверьте, не был ли этот Cask уже отклонён.

Создание Cask

Создать новый Cask просто. Для начала следуйте инструкциям в разделе Как создать пул-реквест в Homebrew.

Примеры

Вот пример Cask для dixa. Обратите внимание на параметр verified после url: он необходим, если домены URL и главной страницы различаются.

cask "dixa" do
  version "4.0.12"
  sha256 "a4e1a30d074e724ba24e9e2674a72bc4050f00161fb7dc23295a2c189ecda5bb"

  url "https://github.com/dixahq/dixa-desktop-app-release/releases/download/v#{version}/dixa-#{version}.dmg",
      verified: "github.com/dixahq/dixa-desktop-app-release/"
  name "Dixa"
  desc "Customer service platform"
  homepage "https://dixa.com/"

  livecheck do
    url :url
    strategy :github_latest
  end

  app "Dixa.app"

  zap trash: [
    "~/Library/Application Support/Dixa",
    "~/Library/Logs/Dixa",
    "~/Library/Preferences/dixa.plist",
    "~/Library/Saved Application State/dixa.savedState",
  ]
end

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

cask "pomello" do
  version "0.10.17"
  sha256 :no_check

  url "https://pomelloapp.com/download/mac/latest"
  name "Pomello"
  desc "Turns your Trello cards into Pomodoro tasks"
  homepage "https://pomelloapp.com/"

  livecheck do
    url :url
    strategy :header_match
  end

  app "Pomello.app"

  zap trash: [
    "~/Library/Application Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.ApplicationRecentDocuments/com.tinynudge.pomello.*",
    "~/Library/Application Support/Pomello",
    "~/Library/Caches/com.tinynudge.pomello",
    "~/Library/Caches/com.tinynudge.pomello.ShipIt",
    "~/Library/HTTPStorages/com.tinynudge.pomello",
    "~/Library/Preferences/com.tinynudge.pomello.plist",
    "~/Library/Saved Application State/com.tinynudge.pomello.savedState",
  ]
end

Последний пример — для fabfilter-one. В нём используется установщик pkg для установки приложения, а не отдельный пакет приложения (.app). Обратите внимание на секцию uninstall pkgutil:, необходимую для удаления всех файлов, установленных с помощью установщика.

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

cask "fabfilter-one" do
  version "3.37"
  sha256 "4059594580e365237ded16a213d8d549cbb01c4b8bad80895c61f44bcff7eb68"

  url "https://download.fabfilter.com/ffone#{version.no_dots}.dmg"
  name "FabFilter One"
  desc "Synthesizer plug-in"
  homepage "https://www.fabfilter.com/products/volcano-2-powerful-filter-plug-in"

  livecheck do
    url "https://www.fabfilter.com/download"
    strategy :page_match do |page|
      match = page.match(/ffone(\d)(\d+)\.dmg/i)
      next if match.blank?

      "#{match[1]}.#{match[2]}"
    end
  end

  depends_on macos: :sonoma

  pkg "FabFilter One #{version} Installer.pkg"

  uninstall pkgutil: "com.fabfilter.One.#{version.major}"

  # No zap stanza required
end

Создание токена для Cask

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

Проще всего создать токен для Cask, выполнив generate_cask_token:

$(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.

Секции Cask

Заполните в Cask следующие секции:

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

В особых случаях могут понадобиться дополнительные секции артефактов. Ещё больше секций для особых случаев перечислено в разделе Необязательные секции.

Подробнее о токенах Cask

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

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

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

Архивы с вложенными папками

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

Пример:

1. Simple Floating Clock загружается в файл sfc.zip.
2. sfc.zip распаковывает архив в папку с именем Simple Floating Clock.
3. В папке Simple Floating Clock находится приложение SimpleFloatingClock.app.
4. Поэтому в секции app следует указать относительный путь к вложенной папке:

app "Simple Floating Clock/SimpleFloatingClock.app"

Тестирование и аудит Cask

Попробуйте выполнить:

export HOMEBREW_NO_AUTO_UPDATE=1
export HOMEBREW_NO_INSTALL_FROM_API=1
brew install my-new-cask

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

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

brew uninstall my-new-cask

Если всё в порядке, убедитесь, что Cask проходит аудит:

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

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

brew style --fix my-new-cask

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

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

Отправка Cask

Куда добавить Cask

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

Перейдите в свой tap и убедитесь, что новый Cask находится там:

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

Пока всё хорошо. Теперь создайте ветку для новой функциональности my-new-cask-branch, которую будете использовать в пул-реквесте:

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

Добавьте Cask в индекс:

git add Casks/m/my-new-cask.rb

Посмотреть изменения, которые будут зафиксированы, можно командой:

git diff --cached

Зафиксируйте изменения:

git commit -v

Сообщения коммитов

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

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

Подробнее см. Заметка о сообщениях коммитов Git.

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

В коммитах для проекта Homebrew Cask в первой строке мы рекомендуем указывать название приложения, номер версии и цель коммита.

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

• transmission 1.0 (new cask)
• transmission 2.82
• transmission: fix checksum
• codebox latest (new cask)

Примеры неудачных и неясных кратких описаний коммитов:

• Upgrade to v2.82
• Checksum was bad

Отправка изменений

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

git push $YOUR_GITHUB_USERNAME my-new-cask-branch

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

Создание пул-реквеста на GitHub

а) воспользуйтесь предложением команды git push

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

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

б) воспользуйтесь подсказкой на сайте GitHub

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

в) создайте пул-реквест на GitHub вручную

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

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

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

Завершение работы

После отправки пул-реквеста переключитесь обратно на main, чтобы brew update корректно загружал новые Cask:

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

Если ранее вы задали переменную HOMEBREW_NO_AUTO_UPDATE и HOMEBREW_NO_INSTALL_FROM_API, удалите их:

unset HOMEBREW_NO_AUTO_UPDATE
unset HOMEBREW_NO_INSTALL_FROM_API