or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-commands.mdcore-build-system.mddev-file-management.mdindex.mdplatform-toolchain.mdutilities.md
tile.json

tessl/npm-node-gyp

Node.js native addon build tool

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/node-gyp@11.4.x

To install, run

npx @tessl/cli install tessl/npm-node-gyp@11.4.0

index.mddocs/

Node-gyp

Node-gyp is a cross-platform command-line tool for compiling native addon modules for Node.js. It contains a vendored copy of gyp-next and enables developers to build C/C++ native addons that interface with Node.js applications, automatically downloading necessary development files and headers for different Node.js versions.

Package Information

  • Package Name: node-gyp
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install -g node-gyp

Core Imports

const gyp = require('node-gyp');

For creating a new gyp instance:

const gypInstance = gyp();

For accessing the Gyp class directly:

const { Gyp } = require('node-gyp');

Basic Usage

const gyp = require('node-gyp');

// Create a new gyp instance
const gypInstance = gyp();

// Parse command-line arguments (modifies gypInstance state)
gypInstance.parseArgv(['node-gyp', 'configure', '--debug']);

// Access parsed options
console.log(gypInstance.opts.debug); // true
console.log(gypInstance.todo); // [{ name: 'configure', args: [] }]

// Execute commands programmatically (returns promises)
try {
  await gypInstance.commands.configure([]);
  await gypInstance.commands.build([]);
} catch (error) {
  console.error('Build failed:', error);
}

Architecture

Node-gyp is built around several key components:

  • Gyp Class: Main orchestrator that handles command parsing, execution, and configuration
  • Command System: Modular command handlers for build operations (build, clean, configure, etc.)
  • Platform Detection: Cross-platform toolchain discovery for Visual Studio, Python, and build tools
  • Development File Management: Downloads and manages Node.js headers and libraries for different versions
  • Logging System: Configurable multi-level logging with color support and prefixes

Capabilities

Core Build System

Primary build operations for compiling native Node.js addons with cross-platform support.

// Main factory function
function gyp(): Gyp;

// Gyp class with command execution
class Gyp extends EventEmitter {
  parseArgv(argv: string[]): void;
  spawn(command: string, args: string[], opts?: object): ChildProcess;
  usage(): string;
}

Core Build System

Build Commands

Individual build operations that can be executed independently or as part of workflows.

// Build command functions
async function build(gyp: Gyp, argv: string[]): Promise<void>;
async function clean(gyp: Gyp, argv: string[]): Promise<void>;
async function configure(gyp: Gyp, argv: string[]): Promise<void>;
async function rebuild(gyp: Gyp, argv: string[]): Promise<void>;

Build Commands

Development File Management

Node.js development file installation and management for different Node.js versions.

// Development file management
async function install(gyp: Gyp, argv: string[]): Promise<void>;
async function list(gyp: Gyp, argv: string[]): Promise<string[]>;
async function remove(gyp: Gyp, argv: string[]): Promise<void>;

Development File Management

Platform-Specific Toolchain Discovery

Automated discovery and validation of build toolchains across different platforms.

// Platform detection classes
class PythonFinder {
  static findPython(...args: any[]): Promise<string>;
}

class VisualStudioFinder {
  static findVisualStudio(...args: any[]): Promise<object>;
}

function findNodeDirectory(scriptLocation?: string, processObj?: object): string;

Platform Toolchain Discovery

Utility Functions

Core utilities for file operations, registry access, and system integration.

// Utility functions
async function download(gyp: Gyp, url: string): Promise<Response>;
async function execFile(...args: any[]): Promise<[Error?, string?, string?]>;
function findAccessibleSync(logprefix: string, dir: string, candidates: string[]): string | undefined;
function withPrefix(prefix: string): object;
function processRelease(argv: string[], gyp: Gyp, defaultVersion: string, defaultRelease: object): object;

Utility Functions

Types

interface GypOptions {
  help?: boolean;
  arch?: string;
  cafile?: string;
  debug?: boolean;
  directory?: string;
  make?: string;
  'msvs-version'?: string;
  ensure?: boolean;
  solution?: string;
  proxy?: string;
  noproxy?: string;
  devdir?: string;
  nodedir?: string;
  loglevel?: string;
  python?: string;
  'dist-url'?: string;
  tarball?: string;
  jobs?: string;
  thin?: string;
  'force-process-config'?: boolean;
}

interface GypShorthands {
  release: '--no-debug';
  C: '--directory';
  debug: '--debug';
  j: '--jobs';
  silly: '--loglevel=silly';
  verbose: '--loglevel=verbose';
  silent: '--loglevel=silent';
}

interface CommandObject {
  name: string;
  args: string[];
}

class Gyp extends EventEmitter {
  package: object;
  version: string;
  devDir: string;
  commands: { [key: string]: (argv: string[]) => Promise<any> };
  configDefs: object;
  shorthands: GypShorthands;
  aliases: { ls: 'list'; rm: 'remove' };
  opts: GypOptions;
  argv: string[];
  todo: CommandObject[];
}