0
# Build System
1

2
Core build functionality for compiling native Node.js modules against different runtimes and versions, with support for multiple build backends and cross-platform compilation.
3

4
## Capabilities
5

6
### Main Build Function
7

8
Entry point for the build system that orchestrates preinstall scripts, compilation, and prepack operations.
9

10
```javascript { .api }
11
/**
12
 * Build native module for specified target and runtime
13
 * @param opts - Build options including package info, logging, and build configuration
14
 * @param version - Target version to build for (Node.js version or Node-API version)
15
 * @param cb - Callback function (err) => void
16
 */
17
function build(opts, version, cb);
18

19
interface BuildOptions {
20
  /** Package.json object containing project metadata */
21
  pkg: PackageJson;
22
  /** Logger instance for build output (defaults to noop-logger) */
23
  log?: Logger;
24
  /** Script to run before building (shell command or .js file) */
25
  preinstall?: string;
26
  /** Custom node-gyp instance to use */
27
  gyp?: object;
28
  /** Build backend to use */
29
  backend?: 'node-gyp' | 'node-ninja' | 'nw-gyp' | 'cmake-js';
30
  /** Additional command line arguments to pass to build backend */
31
  args?: string[];
32
  /** Build in debug mode */
33
  debug?: boolean;
34
  /** Script to run before packing (useful for code signing) */
35
  prepack?: string;
36
}
37
```
38

39
**Usage Examples:**
40

41
```javascript
42
const build = require('prebuild/build');
43

44
// Basic build
45
build({
46
  pkg: require('./package.json'),
47
  log: console
48
}, '16.14.0', (err) => {
49
  if (err) throw err;
50
  console.log('Build completed');
51
});
52

53
// Build with preinstall script
54
build({
55
  pkg: require('./package.json'),
56
  log: console,
57
  preinstall: './setup.sh',
58
  debug: true
59
}, '18.0.0', (err) => {
60
  if (err) throw err;
61
  console.log('Debug build completed');
62
});
63

64
// Build with cmake-js backend
65
build({
66
  pkg: require('./package.json'),
67
  backend: 'cmake-js',
68
  args: ['--prefer-clang']
69
}, '16.14.0', (err) => {
70
  if (err) throw err;
71
  console.log('CMake build completed');
72
});
73
```
74

75
### Prebuild Orchestration
76

77
Main orchestration function that manages the complete prebuild process including building, stripping, and packaging.
78

79
```javascript { .api }
80
/**
81
 * Complete prebuild process: build, optionally strip, and package
82
 * @param opts - Prebuild options including build settings and output configuration
83
 * @param target - Target version or ABI to build for
84
 * @param runtime - Runtime to build for ('node', 'napi', 'electron', 'node-webkit')
85
 * @param callback - Callback function (err, tarPath) => void
86
 */
87
function prebuild(opts, target, runtime, callback);
88

89
interface PrebuildOptions extends BuildOptions {
90
  /** Platform to build for (defaults to process.platform) */
91
  platform?: string;
92
  /** Architecture to build for (defaults to process.arch) */
93
  arch?: string;
94
  /** LIBC variant (for Linux builds) */
95
  libc?: string;
96
  /** Force rebuild even if tarball exists */
97
  force?: boolean;
98
  /** Strip debug symbols from binaries */
99
  strip?: boolean;
100
  /** Function for build progress logging */
101
  buildLog?: (...args: any[]) => void;
102
  /** Regex pattern for including files in package */
103
  'include-regex'?: RegExp;
104
}
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
const prebuild = require('prebuild/prebuild');
111

112
// Build for Node.js 16.14.0
113
prebuild({
114
  pkg: require('./package.json'),
115
  platform: 'linux',
116
  arch: 'x64'
117
}, '16.14.0', 'node', (err, tarPath) => {
118
  if (err) throw err;
119
  console.log('Prebuild saved to:', tarPath);
120
});
121

122
// Build for Electron with debug symbols stripped
123
prebuild({
124
  pkg: require('./package.json'),
125
  strip: true,
126
  buildLog: console.log
127
}, '22.0.0', 'electron', (err, tarPath) => {
128
  if (err) throw err;
129
  console.log('Electron prebuild ready:', tarPath);
130
});
131
```
132

133
### Build Backends
134

135
#### Node-gyp Backend
136

137
Default backend using node-gyp for building Node.js native modules.
138

139
```javascript { .api }
140
/**
141
 * Build using node-gyp backend
142
 * @param opts - Build options with gyp-specific configuration
143
 * @param target - Target Node.js version or Node-API version
144
 * @param cb - Callback function (err) => void
145
 */
146
function runGyp(opts, target, cb);
147

148
interface GypBuildOptions extends BuildOptions {
149
  /** Target runtime ('node', 'electron', 'node-webkit', 'napi') */
150
  runtime?: Runtime;
151
  /** Custom node-gyp format parameters */
152
  format?: string;
153
}
154
```
155

156
#### CMake Backend
157

158
Alternative backend using cmake-js for projects with CMake build systems.
159

160
```javascript { .api }
161
/**
162
 * Build using cmake-js backend
163
 * @param opts - Build options with cmake-specific configuration
164
 * @param target - Target version to build for
165
 * @param cb - Callback function (err) => void
166
 */
167
function runCmake(opts, target, cb);
168

169
interface CmakeBuildOptions extends BuildOptions {
170
  /** Command line arguments passed to cmake-js */
171
  argv?: string[];
172
}
173
```
174

175
### Build Artifact Collection
176

177
Collects build artifacts matching specified patterns from the build output directory.
178

179
```javascript { .api }
180
/**
181
 * Collect build artifacts from release folder
182
 * @param release - Path to build output directory
183
 * @param opts - Options including file inclusion regex
184
 * @param cb - Callback function (err, filenames) => void where filenames is string[]
185
 */
186
function collectArtifacts(release, opts, cb);
187

188
interface ArtifactOptions {
189
  /** Regex pattern for files to include (defaults to /\.node$/i) */
190
  'include-regex': RegExp;
191
}
192
```
193

194
**Usage Examples:**
195

196
```javascript
197
const collectArtifacts = require('prebuild/collect-artifacts');
198

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

207
// Collect multiple file types
208
collectArtifacts('build/Release', {
209
  'include-regex': /\.(node|so|dylib|dll)$/i
210
}, (err, files) => {
211
  if (err) throw err;
212
  console.log('Found native libraries:', files);
213
});
214
```
215

216
### Core Gyp Execution
217

218
Low-level gyp execution with backend abstraction and custom command filtering.
219

220
```javascript { .api }
221
/**
222
 * Execute gyp build with specified backend
223
 * @param opts - Gyp execution options including backend and command filtering
224
 * @param cb - Callback function (err) => void
225
 */
226
function runGyp(opts, cb);
227

228
interface GypOptions {
229
  /** Build backend instance or name */
230
  backend?: string;
231
  /** Custom gyp instance to use */
232
  gyp?: object;
233
  /** Logger for build output */
234
  log: Logger;
235
  /** Command line arguments array */
236
  args: string[];
237
  /** Optional command filter function */
238
  filter?: (command: GypCommand) => boolean;
239
  /** Runtime for determining dev directory */
240
  runtime?: Runtime;
241
}
242

243
interface GypCommand {
244
  name: string;
245
  args: string[];
246
}
247
```
248

249
## Types
250

251
```javascript { .api }
252
interface PackageJson {
253
  name: string;
254
  version: string;
255
  binary?: {
256
    /** Custom module name for gyp builds */
257
    module_name?: string;
258
    /** Custom module output path */
259
    module_path?: string;
260
    /** Supported Node-API versions for napi builds */
261
    napi_versions?: number[];
262
  };
263
}
264

265
interface Logger {
266
  info: (...args: any[]) => void;
267
  verbose: (...args: any[]) => void;
268
  error: (...args: any[]) => void;
269
}
270

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