Узел для авторов формул

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

Выполнение npm install

Homebrew предоставляет два вспомогательных метода в модуле Language::Node: std_npm_install_args и local_npm_install_args. Оба они устанавливают правильную среду для npm и возвращают аргументы для npm install для своих конкретных случаев использования. Ваша формула должна использовать их вместо вызова npm install явно. Синтаксис для стандартной установки модуля Node:

system "npm", "install", *Language::Node.std_npm_install_args(libexec)

где libexec — это префикс назначения (обычно переменная libexec).

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 (например, node@12).

Специальные требования для нативных дополнений

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

depends_on "python" => :build

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

Установка

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

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

• формулы для стандартных модулей Node, совместимые с глобальным форматом модулей npm, которые должны использовать std_npm_install_args (например, azure-cli или webpack)
• формулы, где вызов npm install не является единственным необходимым шагом по установке (например, необходимо также скомпилировать исходные файлы, не являющиеся JavaScript), которые должны использовать local_npm_install_args (например, elixirscript или grunt-cli)

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

Чтобы использовать их, необходимо потребовать модуль языка Node в начале файла вашей формулы с:

require "language/node"

Установка глобальных модулей с std_npm_install_args в libexec

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

system "npm", "install", *Language::Node.std_npm_install_args(libexec)

Это установит ваш модуль Node в стиле глобальных модулей npm с настраиваемым префиксом в libexec. Все исполняемые файлы ваших модулей будут автоматически разрешены npm в libexec/bin за вас, которые не символически связаны с префиксом Homebrew. Нам нужно убедиться, что они установлены. Для этого нам нужно символически связать все исполняемые файлы с bin с помощью:

bin.install_symlink Dir["#{libexec}/bin/*"]

Установка локальных зависимостей модулей с помощью local_npm_install_args

В методе install вашей формулы выполните все шаги установки, которые нужно выполнить до шага npm install, и затем cd до верхнего уровня включённого модуля Node. Затем используйте system с Language::Node.local_npm_install_args для вызова npm install так:

system "npm", "install", *Language::Node.local_npm_install_args

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

Пример

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

require "language/node"

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

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

  def install
    system "npm", "install", *Language::Node.std_npm_install_args(libexec)
    bin.install_symlink Dir["#{libexec}/bin/*"]
  end

  test do
    # add a meaningful test here
  end
end

Инструменты

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