Build System

/**
 * Build native module for specified target and runtime
 * @param opts - Build options including package info, logging, and build configuration
 * @param version - Target version to build for (Node.js version or Node-API version)
 * @param cb - Callback function (err) => void
 */
function build(opts, version, cb);

interface BuildOptions {
  /** Package.json object containing project metadata */
  pkg: PackageJson;
  /** Logger instance for build output (defaults to noop-logger) */
  log?: Logger;
  /** Script to run before building (shell command or .js file) */
  preinstall?: string;
  /** Custom node-gyp instance to use */
  gyp?: object;
  /** Build backend to use */
  backend?: 'node-gyp' | 'node-ninja' | 'nw-gyp' | 'cmake-js';
  /** Additional command line arguments to pass to build backend */
  args?: string[];
  /** Build in debug mode */
  debug?: boolean;
  /** Script to run before packing (useful for code signing) */
  prepack?: string;
}

const build = require('prebuild/build');

// Basic build
build({
  pkg: require('./package.json'),
  log: console
}, '16.14.0', (err) => {
  if (err) throw err;
  console.log('Build completed');
});

// Build with preinstall script
build({
  pkg: require('./package.json'),
  log: console,
  preinstall: './setup.sh',
  debug: true
}, '18.0.0', (err) => {
  if (err) throw err;
  console.log('Debug build completed');
});

// Build with cmake-js backend
build({
  pkg: require('./package.json'),
  backend: 'cmake-js',
  args: ['--prefer-clang']
}, '16.14.0', (err) => {
  if (err) throw err;
  console.log('CMake build completed');
});

/**
 * Complete prebuild process: build, optionally strip, and package
 * @param opts - Prebuild options including build settings and output configuration
 * @param target - Target version or ABI to build for
 * @param runtime - Runtime to build for ('node', 'napi', 'electron', 'node-webkit')
 * @param callback - Callback function (err, tarPath) => void
 */
function prebuild(opts, target, runtime, callback);

interface PrebuildOptions extends BuildOptions {
  /** Platform to build for (defaults to process.platform) */
  platform?: string;
  /** Architecture to build for (defaults to process.arch) */
  arch?: string;
  /** LIBC variant (for Linux builds) */
  libc?: string;
  /** Force rebuild even if tarball exists */
  force?: boolean;
  /** Strip debug symbols from binaries */
  strip?: boolean;
  /** Function for build progress logging */
  buildLog?: (...args: any[]) => void;
  /** Regex pattern for including files in package */
  'include-regex'?: RegExp;
}

const prebuild = require('prebuild/prebuild');

// Build for Node.js 16.14.0
prebuild({
  pkg: require('./package.json'),
  platform: 'linux',
  arch: 'x64'
}, '16.14.0', 'node', (err, tarPath) => {
  if (err) throw err;
  console.log('Prebuild saved to:', tarPath);
});

// Build for Electron with debug symbols stripped
prebuild({
  pkg: require('./package.json'),
  strip: true,
  buildLog: console.log
}, '22.0.0', 'electron', (err, tarPath) => {
  if (err) throw err;
  console.log('Electron prebuild ready:', tarPath);
});

/**
 * Build using node-gyp backend
 * @param opts - Build options with gyp-specific configuration
 * @param target - Target Node.js version or Node-API version
 * @param cb - Callback function (err) => void
 */
function runGyp(opts, target, cb);

interface GypBuildOptions extends BuildOptions {
  /** Target runtime ('node', 'electron', 'node-webkit', 'napi') */
  runtime?: Runtime;
  /** Custom node-gyp format parameters */
  format?: string;
}

/**
 * Build using cmake-js backend
 * @param opts - Build options with cmake-specific configuration
 * @param target - Target version to build for
 * @param cb - Callback function (err) => void
 */
function runCmake(opts, target, cb);

interface CmakeBuildOptions extends BuildOptions {
  /** Command line arguments passed to cmake-js */
  argv?: string[];
}

/**
 * Collect build artifacts from release folder
 * @param release - Path to build output directory
 * @param opts - Options including file inclusion regex
 * @param cb - Callback function (err, filenames) => void where filenames is string[]
 */
function collectArtifacts(release, opts, cb);

interface ArtifactOptions {
  /** Regex pattern for files to include (defaults to /\.node$/i) */
  'include-regex': RegExp;
}

const collectArtifacts = require('prebuild/collect-artifacts');

// Collect .node files from build directory
collectArtifacts('build/Release', {
  'include-regex': /\.node$/i
}, (err, files) => {
  if (err) throw err;
  console.log('Found artifacts:', files);
});

// Collect multiple file types
collectArtifacts('build/Release', {
  'include-regex': /\.(node|so|dylib|dll)$/i
}, (err, files) => {
  if (err) throw err;
  console.log('Found native libraries:', files);
});

/**
 * Execute gyp build with specified backend
 * @param opts - Gyp execution options including backend and command filtering
 * @param cb - Callback function (err) => void
 */
function runGyp(opts, cb);

interface GypOptions {
  /** Build backend instance or name */
  backend?: string;
  /** Custom gyp instance to use */
  gyp?: object;
  /** Logger for build output */
  log: Logger;
  /** Command line arguments array */
  args: string[];
  /** Optional command filter function */
  filter?: (command: GypCommand) => boolean;
  /** Runtime for determining dev directory */
  runtime?: Runtime;
}

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

interface PackageJson {
  name: string;
  version: string;
  binary?: {
    /** Custom module name for gyp builds */
    module_name?: string;
    /** Custom module output path */
    module_path?: string;
    /** Supported Node-API versions for napi builds */
    napi_versions?: number[];
  };
}

interface Logger {
  info: (...args: any[]) => void;
  verbose: (...args: any[]) => void;
  error: (...args: any[]) => void;
}

type Runtime = 'node' | 'napi' | 'electron' | 'node-webkit';
type Backend = 'node-gyp' | 'node-ninja' | 'nw-gyp' | 'cmake-js';