Updating Available Definitions

How node-build works

node-build inherits its architecture from ruby-build, which has a more complicated process for compiling ruby. As such, node-build relies on the use of definition files to instruct node-build how to build/compile/install a version of node. While this does have its drawbacks, it also enables node-build (and nodenv) to more easily add support for alternative node runtimes (like iojs, lowjs, quickjs, graalvm, chakracore, etc). Thus, in order to install a particular version of node, a definition file for that particular version must exist somewhere for node-build to find.

Where node-build finds definitions

node-build itself looks in two locations:

1. all the colon-separated paths listed in NODE_BUILD_DEFINITIONS

2. node-build's own installation under share/node-build/

   (When installed via Homebrew, this is $(brew --prefix node-build)/share/node-build/.)

The nodenv-install plugin for nodenv adds additional locations:

1. all paths found in $(nodenv root)/plugins/*/share/node-build

The process for releasing official definitions

1. A new version of node is released.

   • At this point, anyone may manually download the node version directly from nodejs.org and either compile or unpack it under $(nodenv root)/versions/.
   • Alternatively, users of the node-build-update-defs plugin may run the command to scrape the new node definition themselves.
   • Also of note: the node-build-update-defs plugin above works by creating the definition file and writing it to $(nodenv root)/plugins/node-build-update-defs/share/node-build/. This means any plugin can leverage the definition path feature documented above; by generating (scraped?) definition files, or a team could have their own nodenv plugin (git repo) containing definitions shared amongst themselves.

2. The nodenv scraper (via GitHub Actions) generates a definition file for the new version and opens a PR to node-build. (within 4hrs)

   • At this point, users with node-build installed via git-clone may optionally switch their clone to this PR's branch in order to get the new definition file. (this is uncommon)

3. The PR is reviewed and merged to master. (typically ~1 day)

   • At this point, users who have node-build installed via git-clone will have access to the new definition in master by doing a git-pull (or using the nodenv-update plugin).

4. node-build itself is tagged for a new release, including all new definitions added since last release. (typically ~1 week)

   • At this point, users who have node-build installed via npm may update to the latest release and get the new definitions. (this is uncommon)

5. A PR is opened to Homebrew to bump the version of node-build in homebrew-core. (automatic as part of the node-build release)

   • At this point, users who have node-build installed via Homebrew may checkout the node-build formula PR to upgrade to the latest node-build and get the new definitions. (this is very uncommon)

6. The Homebrew team merges the PR to update the node-build formula. (typically ~1-2 days)

   • At this point, users who have node-build installed via Homebrew may run brew upgrade node-build to get the new definitions.

As is clear from the process above, there are numerous steps in the process but also numerous alternatives to hasten the availability of new node releases. All in all, the two most common methods of node-build installation – git-clone and homebrew – have a typical lead time of about 1 day or 1-2 weeks, respectively.