nodejs/doc/contributing/gn-build.md

GN Build

Similar to GYP, GN is a build system designed for building Chromium. The official builds of Node.js are built with GYP, but GN build files are also provided as an unofficial alternative build system.

The GN build files only support a subset of the Node.js build configurations. It's not required for all pull requests to Node.js to support GN builds, and the CI of Node.js does not currently test GN builds, though Node.js welcomes pull requests that improve GN support or fix breakages introduced by other pull requests.

Currently the GN build is used by:

1. Electron for building Node.js together with Chromium.
2. V8 for testing the integration of Node.js in CI.

Files for GN support

Node.js contains following GN build files:

• node.gni - Public GN arguments for configuring the build.
• */BUILD.gn - This is the file where GN looks for build rules, in Node.js it just includes the unofficial.gni file to avoid accidental modifications.
• */unofficial.gni - The actual build rules for each component.

Build with GN

Unlike GYP, the GN tool does not include any built-in rules for compiling a project, which means projects building with GN must provide their own build configurations for things like how to invoke a C++ compiler. Chromium related projects like V8 and skia choose to reuse Chromium's build configurations, and V8's Node.js integration testing repository (node-ci) can be reused for building Node.js.

1. Install depot_tools

The depot_tools is a set of tools used by Chromium related projects for checking out code and managing dependencies, and since this guide is reusing the infra of V8, it needs to be installed and added to PATH:

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
export PATH=/path/to/depot_tools:$PATH

You can also follow the official tutorial of depot_tools.

2. Check out code of Node.js

To check out the latest main branch of Node.js for building, use the fetch tool from depot_tools:

mkdir node_gn
cd node_gn
fetch node

You can choose to save some time by omitting git history:

fetch --no-history node

After syncing is done, you will get a directory structure like this:

node_gn/
├── .gclient
├── .gclient_entries
├── ...
└── node
    ├── DEPS
    ├── ...
    ├── build/
    ├── node/
    └── tools/

The node_gn is a workspace directory, which only contains configurations and caches of the gclient tool from depot_tools, and the repository is checked out at node_gn/node.

The node_gn/node directory is not a checkout of Node.js, it is actually node-ci, the repository used by V8 for testing integration with Node.js. The source code of Node.js is checked out at node_gn/node/node.

3. Build

GN only supports ninja for building, so to build Node.js with GN, ninja build files should be generated first, and then ninja can be invoked to do the building.

The node-ci repository provides a script for calling GN:

cd node  # Enter `node_gn/node` which contains a node-ci checkout
./tools/gn-gen.py out/Release

which writes ninja build files into the out/Release directory under node_gn/node.

And then you can execute ninja:

ninja -C out/Release node

After the build is completed, the compiled Node.js executable can be found in out/Release/node.

Status of the GN build

Currently the GN build of Node.js is not fully functioning. It builds for macOS and Linux, while the Windows build is still a work in progress. And some tests are still failing with the GN build.

There are also efforts on making GN build work without using depot_tools, which is tracked in the issue #51689.