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

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

brew mycommand --option1 --option3 <formula>

не изменяя внутренний код Homebrew.

Типы команд

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

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

Для удобного распространения внешние команды можно добавлять в tap. Подробнее см. ниже.

Команды Ruby

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

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

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

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

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

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

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

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

Обратите внимание: эти команды в основном не тестировались. Как всегда, будьте осторожны, запуская на своём компьютере непроверенный код.

brew-gem

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

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

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

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

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

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

• Имя класса должно совпадать с именем команды в CamelCase (например, my-cmd следует назвать MyCmd).
• Добавьте блок cmd_args с описанием команды и её аргументов.
• Реализуйте метод run, который будет вызван при выполнении команды. В методе run разобранные аргументы доступны через args.

# frozen_string_literal: true

module Homebrew
  module Cmd
    class Foo < AbstractCommand
      cmd_args 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

      def run
        something if args.force?
        something_else if args.file == "file.txt"
      end
    end
  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. Дополнительные примеры использования см. во внутренних командах и командах для разработчиков.