Core Build System

/**
 * Creates a new Gyp instance
 * @returns {Gyp} New Gyp instance
 */
function gyp(): Gyp;

/**
 * Main node-gyp class that handles command parsing and execution
 * @extends EventEmitter
 */
class Gyp extends EventEmitter {
  /**
   * Package.json contents
   * @type {object}
   */
  package: object;
  
  /**
   * Version from package.json
   * @type {string}
   */
  version: string;
  
  /**
   * Development files directory path
   * @type {string}
   */
  devDir: string;
  
  /**
   * Map of command names to handler functions
   * @type {object}
   */
  commands: { [key: string]: (argv: string[]) => Promise<any> };
  
  /**
   * Configuration definitions for nopt
   * @type {object}
   */
  configDefs: object;
  
  /**
   * Shorthand mappings for command-line options
   * @type {object}
   */
  shorthands: object;
  
  /**
   * Command aliases (ls -> list, rm -> remove)
   * @type {object}
   */
  aliases: object;
  
  /**
   * Parsed command-line options
   * @type {GypOptions}
   */
  opts: GypOptions;
  
  /**
   * Remaining command-line arguments
   * @type {string[]}
   */
  argv: string[];
  
  /**
   * Queue of commands to execute
   * @type {CommandObject[]}
   */
  todo: CommandObject[];
}

/**
 * Parses command-line arguments and sets opts, argv, and todo properties
 * @param {string[]} argv - Command-line arguments to parse
 */
parseArgv(argv: string[]): void;

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

// Parse arguments for debug build
gypInstance.parseArgv(['build', '--debug', '--arch=x64']);

console.log(gypInstance.opts.debug); // true
console.log(gypInstance.opts.arch); // 'x64'
console.log(gypInstance.todo); // [{ name: 'build', args: [] }]

/**
 * Spawns a child process and emits a 'spawn' event
 * @param {string} command - Command to execute
 * @param {string[]} args - Arguments for the command
 * @param {object} [opts] - Options for child_process.spawn
 * @returns {ChildProcess} The spawned child process
 */
spawn(command: string, args: string[], opts?: object): ChildProcess;

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

// Spawn make command
const makeProcess = gypInstance.spawn('make', ['-j4'], {
  cwd: './build',
  stdio: 'inherit'
});

makeProcess.on('exit', (code) => {
  console.log(`Make process exited with code ${code}`);
});

/**
 * Returns usage instructions for node-gyp
 * @returns {string} Formatted usage instructions
 */
usage(): string;

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

console.log(gypInstance.usage());
// Outputs:
//   Usage: node-gyp <command> [options]
//   
//   where <command> is one of:
//     - build - Invokes `msbuild` (on Windows) or `make` (on other platforms) and builds the module
//     - clean - Removes any generated build files and the "out" dir
//     ...

interface GypOptions {
  help?: boolean;              // Show help information
  arch?: string;               // Target architecture (x86, x64, arm64)
  cafile?: string;             // CA certificate file path
  debug?: boolean;             // Build in debug mode
  directory?: string;          // Working directory
  make?: string;               // Make command to use
  'msvs-version'?: string;     // Visual Studio version (Windows)
  ensure?: boolean;            // Only install if not already present
  solution?: string;           // Solution file to build (Windows)
  proxy?: string;              // HTTP proxy settings
  noproxy?: string;            // Proxy bypass settings
  devdir?: string;             // Development files directory
  nodedir?: string;            // Node.js directory path
  loglevel?: string;           // Logging level (silly, verbose, info, warn, error)
  python?: string;             // Python executable path
  'dist-url'?: string;         // Distribution URL for downloads
  tarball?: string;            // Local tarball path
  jobs?: string;               // Build job parallelization
  thin?: string;               // Thin archive support
  'force-process-config'?: boolean; // Force process configuration
}

# Set options via environment variables
export npm_config_python=/usr/bin/python3.8
export npm_config_msvs_version=2019
export npm_config_debug=true

# These will be automatically picked up by parseArgv

interface CommandObject {
  name: string;    // Command name (build, clean, configure, etc.)
  args: string[];  // Arguments specific to this command
}

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

// Listen for spawn events
gypInstance.on('spawn', (command, args) => {
  console.log(`Spawning: ${command} ${args.join(' ')}`);
});

// Execute commands
gypInstance.parseArgv(['build', '--debug']);