tessl/npm-node-gyp

Node.js native addon build tool

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Build Commands

Name: tessl/npm-node-gyp
Author: tessl

Build commands handle the core compilation and build management operations for native Node.js addons. Each command is designed to work independently or as part of automated workflows.

Capabilities

Build Command

Compiles the native module using the appropriate build system for the current platform.

/**
 * Invokes `msbuild` (on Windows) or `make` (on other platforms) and builds the module
 * @param {Gyp} gyp - The gyp instance
 * @param {string[]} argv - Command arguments
 * @returns {Promise<void>}
 */
async function build(gyp: Gyp, argv: string[]): Promise<void>;

Usage Example:

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

// Build in release mode
await gypInstance.commands.build([]);

// Build in debug mode
gypInstance.opts.debug = true;
await gypInstance.commands.build([]);

// Build with specific job count
gypInstance.opts.jobs = '4';
await gypInstance.commands.build([]);

Platform-Specific Behavior:

Windows: Uses MSBuild with Visual Studio project files
Unix/Linux/macOS: Uses Make with generated Makefiles
Supports: Parallel builds, debug/release modes, architecture targeting

Clean Command

Removes all generated build files and the output directory to ensure a clean build state.

/**
 * Removes any generated build files and the "out" dir
 * @param {Gyp} gyp - The gyp instance
 * @param {string[]} argv - Command arguments
 * @returns {Promise<void>}
 */
async function clean(gyp: Gyp, argv: string[]): Promise<void>;

Usage Example:

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

// Clean all build artifacts
await gypInstance.commands.clean([]);

// Clean is typically used before rebuild
await gypInstance.commands.clean([]);
await gypInstance.commands.configure([]);
await gypInstance.commands.build([]);

What Gets Cleaned:

build/ directory and all contents
Generated Makefiles or Visual Studio project files
Compiled object files and intermediate build artifacts
Output binaries and libraries

Configure Command

Generates the necessary build files (Makefiles or Visual Studio project files) for the current platform and configuration.

/**
 * Generates MSVC project files (on Windows) or a Makefile (on other platforms) for the current module
 * @param {Gyp} gyp - The gyp instance
 * @param {string[]} argv - Command arguments
 * @returns {Promise<void>}
 */
async function configure(gyp: Gyp, argv: string[]): Promise<void>;

Usage Example:

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

// Basic configuration
await gypInstance.commands.configure([]);

// Configure for specific Node.js version
gypInstance.opts.target = '16.14.0';
await gypInstance.commands.configure([]);

// Configure for specific architecture
gypInstance.opts.arch = 'x64';
await gypInstance.commands.configure([]);

// Configure with custom Python
gypInstance.opts.python = '/usr/bin/python3.8';
await gypInstance.commands.configure([]);

Configuration Process:

Node.js Headers: Downloads or locates Node.js development headers
Python Detection: Finds and validates Python installation
Toolchain Discovery: Locates build tools (Visual Studio on Windows, GCC/Clang on Unix)
Build File Generation: Creates platform-specific build files from binding.gyp
Environment Setup: Configures include paths, library paths, and compiler flags

Rebuild Command

Convenience command that performs a complete rebuild by running clean, configure, and build in sequence.

/**
 * Runs "clean", "configure" and "build" all at once
 * @param {Gyp} gyp - The gyp instance
 * @param {string[]} argv - Command arguments
 * @returns {Promise<void>}
 */
async function rebuild(gyp: Gyp, argv: string[]): Promise<void>;

Usage Example:

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

// Complete rebuild - equivalent to clean + configure + build
await gypInstance.commands.rebuild([]);

// Rebuild with options
gypInstance.opts.debug = true;
gypInstance.opts.arch = 'x64';
await gypInstance.commands.rebuild([]);

Rebuild Sequence:

Clean: Removes all existing build artifacts
Configure: Regenerates build files with current settings
Build: Compiles the native module

Build Configuration Options

Debug vs Release Builds

// Debug build - includes debug symbols, no optimization
gypInstance.opts.debug = true;
await gypInstance.commands.build([]);

// Release build - optimized, no debug symbols (default)
gypInstance.opts.debug = false;
await gypInstance.commands.build([]);

Architecture Targeting

// Target specific architectures
gypInstance.opts.arch = 'x64';     // 64-bit Intel/AMD
gypInstance.opts.arch = 'x86';     // 32-bit Intel/AMD
gypInstance.opts.arch = 'arm64';   // 64-bit ARM (Apple Silicon, etc.)
await gypInstance.commands.configure([]);

Parallel Building

// Control build parallelization
gypInstance.opts.jobs = '4';       // Use 4 parallel jobs
gypInstance.opts.jobs = '$(nproc)'; // Use all available cores (Unix)
await gypInstance.commands.build([]);

Custom Build Tools

// Specify custom make command
gypInstance.opts.make = 'gmake';   // Use GNU make specifically
gypInstance.opts.make = 'ninja';   // Use Ninja build system

// Windows: Specify Visual Studio version
gypInstance.opts['msvs-version'] = '2019';
gypInstance.opts['msvs-version'] = '2022';

Error Handling

All build commands are async functions that may throw errors. Common error scenarios:

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

try {
  await gypInstance.commands.build([]);
} catch (error) {
  if (error.message.includes('Python')) {
    console.error('Python not found or incompatible version');
  } else if (error.message.includes('Visual Studio')) {
    console.error('Visual Studio build tools not found');
  } else if (error.message.includes('make')) {
    console.error('Make build failed');
  }
  
  // Error details
  console.error('Build failed:', error.message);
  console.error('Stack:', error.stack);
}

Command Integration Patterns

Sequential Execution

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

// Manual sequential execution
await gypInstance.commands.clean([]);
await gypInstance.commands.configure([]);
await gypInstance.commands.build([]);

// Or use rebuild for the same effect
await gypInstance.commands.rebuild([]);

Conditional Building

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

const gypInstance = gyp();

// Only configure if build files don't exist
if (!fs.existsSync('build/Makefile') && !fs.existsSync('build/binding.sln')) {
  await gypInstance.commands.configure([]);
}

await gypInstance.commands.build([]);

Development Workflow

// Typical development workflow
const gyp = require('node-gyp');
const gypInstance = gyp();

// Development build with debug symbols
gypInstance.opts.debug = true;

// Clean build
await gypInstance.commands.clean([]);
await gypInstance.commands.configure([]);
await gypInstance.commands.build([]);

// Later: quick rebuild without clean
await gypInstance.commands.build([]);