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

Homebrew, как и Git, поддерживает внешние команды. Это позволяет создавать новые команды, которые могут быть запущены так:

brew mycommand --option1 --option3 <formula>

без изменения внутренней части Homebrew.

Типы команд

Внешние команды бывают двух типов: команды Ruby и скрипты оболочки.

В обоих случаях файл команды должен быть исполняемым (chmod +x) и находиться где-то в вашей PATH.

Внешние команды могут быть добавлены в репозиторий (tap), чтобы обеспечить удобное распределение. Подробнее см. ниже.

Команды Ruby

Внешняя команда extcmd, реализованная как команда Ruby, должна иметь имя brew-extcmd.rb. Команда выполняется путем выполнения require по полному пути. Поскольку команда requireна, она имеет полный доступ к «среде» Homebrew, то есть ко всем глобальным переменным и модулям, к которым имеет доступ любая внутренняя команда. Будьте осторожны при использовании внутренних элементов Homebrew; они могут измениться в любое время без предупреждения.

Команда может Kernel.exit с кодом состояния, если это необходимо; если она не завершается явно, Homebrew вернёт 0.

Другие исполняемые скрипты

Исполняемый скрипт для команды с именем extcmd должен иметь имя brew-extcmd. Сам скрипт может использовать любую подходящую строку shebang (#!), поэтому внешний скрипт может быть написан на Bash, Ruby или даже Python. В отличие от команд Ruby, этот файл не должен заканчиваться языковым суффиксом (.sh, или .py). Этот файл будет запущен через exec с некоторыми переменными Homebrew, заданными как переменные среды, и переданы любые дополнительные аргументы командной строки.

Предоставление --help

Все внутренние и внешние команды Homebrew могут предоставлять стилизованный вывод --help с помощью парсера аргументов Homebrew, как показано в парсере аргументов, как показано в команде brew services; или путём включения строк, начинающихся с #: (комментарий, затем символ :) как в Bash, так и в Ruby, как показано в заголовке update.sh, который печатается с brew update --help

Неофициальные внешние команды

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

Обратите внимание, что они в значительной степени не протестированы, и, как всегда, будьте осторожны при запуске непроверенного кода на вашей машине.

brew-gem

Установите любой gem пакет в автономное расположение ячейки Homebrew: https://github.com/sportngin/brew-gem

Обратите внимание, что это также можно установить с помощью brew install brew-gem.

Внешние команды в репозиториях (taps)

Внешние команды могут размещаться в репозитории (tap), чтобы пользователи могли легко их устанавливать и использовать. Подробнее о создании и обслуживании репозитория (tap) см. Как создать и обслуживать репозиторий (tap).

Внешние команды должны добавляться в директорию cmd в репозитории (tap). Внешняя команда extcmd, реализованная как команда Ruby, должна находиться в cmd/extcmd.rb (не забудьте chmod +x).

Для удобного использования парсера аргументов Homebrew, скопируйте следующую шаблонную Ruby-команду для внешних команд (заменив все вхождения foo на имя команды):

# frozen_string_literal: true

module Homebrew
  module_function

  def foo_args
    Homebrew::CLI::Parser.new do
      description <<~EOS
        Do something. Place a description here.
      EOS
      switch "-f", "--force",
             description: "Force doing something in the command."
      flag   "--file=",
             description: "Specify a file to do something with in the command."
      comma_array "--names",
                  description: "Add a list of names to the command."

      named_args [:formula, :cask], min: 1
    end
  end

  def foo
    args = foo_args.parse

    something if args.force?
    something_else if args.file == "file.txt"
  end
end

Использование вышеприведенного кода сгенерирует соответствующий текст справки:

$ brew foo --help
Usage: brew foo [options] formula|cask [...]

Do something. Place a description here.

  -f, --force                      Force doing something in the command.
      --file                       Specify a file to do something with in the
                                   command.
      --names                      Add a list of names to the command.
  -d, --debug                      Display any debugging information.
  -q, --quiet                      Make some output more quiet.
  -v, --verbose                    Make some output more verbose.
  -h, --help                       Show this message.

Строка использования автоматически генерируется на основе указанного количества и типа именованных аргументов (подробнее о назначении именованных аргументов см. ниже). Сгенерированную строку использования можно переопределить, передав правильную строку использования методу usage_banner (расположенному непосредственно перед методом description) . Пример см. в команде brew tap.

Используйте метод named_args для указания типа и количества ожидаемых именованных аргументов. Передайте либо символ для указания ожидаемого типа аргумента, массив символов для указания ожидаемых нескольких типов, или массив строк для указания ожидаемых опций (пример см. в команде brew analytics).

Передайте целое число в параметр number, min, или max метода named_args для указания количества ожидаемых именованных аргументов. См. следующие примеры:

# Accept no named args
named_args :none

# Accept any number (including none) of formula arguments
named_args :formula

# Accept exactly one of the specified options as an argument
named_args %w[state off on], number: 1

# Accept at least one argument that is either a formula or a cask
named_args [:formula, :cask], min: 1

# Accept no more than one argument that is a tap
named_args :tap, max: 1

# Accept between one and two named args
named_args min: 1, max: 2

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