Node для авторов формул

В этом документе объясняется, как успешно использовать Node и npm в формуле Homebrew на основе модуля Node.

Запуск npm install

Homebrew предоставляет вспомогательный метод std_npm_args для настройки правильного окружения npm и возврата аргументов для npm install. Ваша формула должна использовать его при вызове npm install. Синтаксис стандартной установки модуля Node выглядит так:

system "npm", "install", *std_npm_args

URL для скачивания

Если модуль Node также доступен в реестре npm, мы предпочитаем архивы релизов, размещённые на npm, исходным архивам, размещённым на GitHub (или в другом месте). Преимущества таких архивов в том, что они не содержат файлы из .npmignore (например, тесты), что уменьшает размер загрузки, а также в том, что все возможные этапы транспиляции уже выполнены (например, не нужно компилировать файлы CoffeeScript в ходе сборки).

URL реестра npm обычно имеют следующий формат:

https://registry.npmjs.org/<name>/-/<name>-<version>.tgz

Также можно curl JSON по адресу https://registry.npmjs.org/<name> и найти значение versions[<version>].dist.tarball, соответствующее URL нужного архива.

Зависимости

Модули Node, совместимые с последней версией Node, должны объявлять зависимость от формулы node.

depends_on "node"

Если для выполнения формулы требуется более старая версия Node, следует использовать одну из формул для конкретных версий (например, node@20).

Особые требования к нативным дополнениям

Если ваш модуль Node является нативным дополнением или содержит нативное дополнение где-либо в дереве зависимостей, необходимо объявить дополнительную зависимость. Поскольку компиляция нативного дополнения приводит к вызову node-gyp, нам нужна дополнительная зависимость для сборки от "python" (так как GYP зависит от Python).

depends_on "python" => :build

Также обратите внимание, что такая формула будет совместима только с той же основной версией Node, с которой она была изначально скомпилирована. Это означает, что при каждом обновлении основной версии формулы node необходимо пересматривать все формулы с нативными дополнениями Node. Чтобы мы не забыли о вашей формуле при обновлении основной версии Node, напишите содержательный тест, который завершится ошибкой в таком случае (при запуске с версией Node, несовместимой по ABI).

Установка

Модули Node следует устанавливать в libexec. Это предотвращает попадание модулей Node в глобальный node_modules, что важно, чтобы npm не пытался управлять модулями Node, установленными Homebrew.

Далее мы различаем два типа модулей Node, устанавливаемых с помощью формул:

• формулы для стандартных модулей Node, совместимых с глобальным форматом модулей npm, которые должны использовать std_npm_args (например, angular-cli или webpack)
• формулы, для которых вызов npm install — не единственный необходимый шаг установки (например, требуется также компиляция исходников не на JavaScript); они должны использовать std_npm_args (например, emscripten или grunt-cli)

Оба метода настраивают правильное окружение для использования npm в Homebrew и возвращают аргументы для вызова npm install в соответствующих случаях. Это включает исправление важного пограничного случая с кэшем npm (вызванного перенаправлением Homebrew HOME во время сборки и тестирования) за счёт использования собственного npm_cache внутри HOMEBREW_CACHE. Без этого сборка занимала бы очень много времени и требовала бы значительного дискового пространства.

Установка модулей в глобальном стиле с помощью std_npm_args в libexec

В методе install вашей формулы при необходимости просто cd в корневой каталог модуля Node, а затем используйте system для вызова npm install с std_npm_args, например:

system "npm", "install", *std_npm_args

Модуль Node будет установлен в глобальном стиле модулей npm с пользовательским префиксом в libexec. npm автоматически разместит исполняемые файлы всех ваших модулей в libexec/bin; они не будут связаны символическими ссылками с префиксом Homebrew. Чтобы убедиться, что они установлены, нужно связать все исполняемые файлы символическими ссылками с bin:

bin.install_symlink libexec.glob("bin/*")

Локальная установка зависимостей модулей с помощью std_npm_args

В методе install вашей формулы выполните все шаги установки, которые необходимо сделать до этапа npm install, а затем cd в корневой каталог включённого модуля Node. Затем используйте system для вызова npm install с std_npm_args(prefix: false), например:

system "npm", "install", *std_npm_args(prefix: false)

Все зависимости модулей Node будут установлены в локальный каталог сборки. Теперь можно продолжить этапы сборки и самостоятельно выполнить установку в префикс Homebrew, следуя общим инструкциям по формулам Homebrew.

Пример

Установка формулы на основе стандартного модуля Node будет выглядеть так:

class Foo < Formula
  desc "An example formula"
  homepage "https://example.com"
  url "https://registry.npmjs.org/foo/-/foo-1.4.2.tgz"
  sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"

  depends_on "node"
  # uncomment if there is a native addon inside the dependency tree
  # depends_on "python" => :build

  def install
    system "npm", "install", *std_npm_args
    bin.install_symlink libexec.glob("bin/*")
  end

  test do
    # add a meaningful test here, version isn't usually meaningful
    assert_match version.to_s, shell_output("#{bin}/foo --version")
  end
end

Инструменты

Можно использовать homebrew-npm-noob, чтобы автоматически создать формулу для пакета npm, как в примере выше.