0
# Prebuild
1

2
Prebuild is a command line tool and JavaScript library for easily making prebuilt binaries for multiple versions of Node.js, Node-API, Electron, and NW.js on a specific platform. It automates the complex process of cross-compilation by downloading appropriate headers, managing build environments, and uploading prebuilt binaries to GitHub releases for distribution.
3

4
## Package Information
5

6
- **Package Name**: prebuild
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g prebuild` (CLI) or `npm install prebuild` (programmatic)
10

11
## Core Imports
12

13
```javascript
14
const { build } = require('prebuild');
15
```
16

17
For individual modules:
18

19
```javascript
20
const build = require('prebuild/build');
21
const upload = require('prebuild/upload'); 
22
const util = require('prebuild/util');
23
const prebuild = require('prebuild/prebuild');
24
```
25

26
## Basic Usage
27

28
### CLI Usage
29

30
```bash
31
# Build for all supported ABI versions
32
prebuild --all
33

34
# Build for specific targets
35
prebuild -t 16.14.0 -t 18.0.0
36

37
# Build for Node-API
38
prebuild -t 3 -r napi
39

40
# Build for Electron
41
prebuild -t 22.0.0 -r electron
42

43
# Build and upload to GitHub
44
prebuild --all --upload <github-token>
45

46
# Strip debug symbols
47
prebuild --all --strip
48
```
49

50
### Programmatic Usage
51

52
```javascript
53
const { build } = require('prebuild');
54

55
// Build for current Node.js version
56
build({
57
  pkg: require('./package.json'),
58
  log: console
59
}, '16.14.0', (err) => {
60
  if (err) throw err;
61
  console.log('Build completed');
62
});
63
```
64

65
## Architecture
66

67
Prebuild is built around several key components:
68

69
- **CLI Interface**: Command-line tool (`bin.js`) that orchestrates the build process
70
- **Build System**: Core build logic (`build.js`, `prebuild.js`) that manages compilation
71
- **Backend Abstraction**: Support for multiple build systems (`node-gyp`, `cmake-js`, `nw-gyp`, `node-ninja`)
72
- **Cross-Platform Support**: Handles Node.js, Node-API, Electron, and NW.js runtimes
73
- **Artifact Management**: Packaging (`pack.js`), stripping (`strip.js`), and upload (`upload.js`) functionality
74
- **Configuration System**: Runtime configuration (`rc.js`) with command-line and config file support
75

76
## Capabilities
77

78
### Build System
79

80
Core build functionality for compiling native modules against different Node.js runtimes and versions.
81

82
```javascript { .api }
83
/**
84
 * Build native module for specified target and runtime
85
 * @param opts - Build options including pkg, log, backend, debug flags
86
 * @param version - Target version to build for
87
 * @param cb - Callback function (err) => void
88
 */
89
function build(opts, version, cb);
90

91
interface BuildOptions {
92
  pkg: PackageJson;
93
  log?: Logger;
94
  preinstall?: string;
95
  gyp?: object;
96
  backend?: 'node-gyp' | 'node-ninja' | 'nw-gyp' | 'cmake-js';
97
  args?: string[];
98
  debug?: boolean;
99
}
100
```
101

102
[Build System](./build-system.md)
103

104
### Configuration Management
105

106
Runtime configuration system supporting command-line arguments, config files, and environment variables.
107

108
```javascript { .api }
109
/**
110
 * Parsed configuration object with defaults and CLI arguments
111
 */
112
interface ConfigurationOptions {
113
  target: string | string[];
114
  runtime: 'node' | 'napi' | 'electron' | 'node-webkit';
115
  arch: string;
116
  platform: string;
117
  backend: string;
118
  debug: boolean;
119
  strip: boolean;
120
  upload?: string;
121
  all: boolean;
122
  force: boolean;
123
  verbose: boolean;
124
  'include-regex': RegExp;
125
  'tag-prefix': string;
126
  prerelease: boolean;
127
}
128
```
129

130
[Configuration](./configuration.md)
131

132
### Upload System
133

134
GitHub releases integration for uploading prebuilt binaries with automatic release creation.
135

136
```javascript { .api }
137
/**
138
 * Upload prebuilt binaries to GitHub releases
139
 * @param opts - Upload options including files, token, and release settings
140
 * @param cb - Callback function (err, result) => void
141
 */
142
function upload(opts, cb);
143

144
interface UploadOptions {
145
  pkg: PackageJson;
146
  files: string[];
147
  upload: string; // GitHub token
148
  'tag-prefix'?: string;
149
  prerelease?: boolean;
150
  gh?: object;
151
}
152

153
interface UploadResult {
154
  new: string[];
155
  old: string[];
156
}
157
```
158

159
[Upload System](./upload-system.md)
160

161
### Utilities
162

163
Common utility functions for file operations, process spawning, and path generation.
164

165
```javascript { .api }
166
/**
167
 * Generate tar file path for prebuilt binary
168
 * @param opts - Options containing package info and build settings
169
 * @param abi - ABI version string
170
 * @returns Generated tar file path
171
 */
172
function getTarPath(opts, abi): string;
173

174
/**
175
 * Spawn child process with error handling
176
 * @param cmd - Command to execute
177
 * @param args - Command arguments
178
 * @param cb - Callback function (err) => void
179
 */
180
function spawn(cmd, args, cb): void;
181

182
/**
183
 * Execute shell command or JavaScript file
184
 * @param item - Shell command or .js file path
185
 * @param cb - Callback function (err) => void
186
 */
187
function run(item, cb): void;
188
```
189

190
[Utilities](./utilities.md)
191

192
## Types
193

194
```javascript { .api }
195
interface PackageJson {
196
  name: string;
197
  version: string;
198
  binary?: {
199
    module_name?: string; 
200
    module_path?: string;
201
    napi_versions?: number[];
202
  };
203
}
204

205
interface Logger {
206
  info: (...args: any[]) => void;
207
  verbose: (...args: any[]) => void;
208
  error: (...args: any[]) => void;
209
}
210

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