0
# Configuration
1

2
Runtime configuration system supporting command-line arguments, config files, and environment variables with automatic target selection and prebuild configuration.
3

4
## Capabilities
5

6
### Configuration Object
7

8
Main configuration object combining defaults, RC files, and command-line arguments.
9

10
```javascript { .api }
11
/**
12
 * Runtime configuration object parsed from command line, config files, and defaults
13
 */
14
interface ConfigurationOptions {
15
  /** Target version(s) to build for - can be single version or array */
16
  target: string | string[];
17
  /** Runtime to build for */
18
  runtime: 'node' | 'napi' | 'electron' | 'node-webkit';
19
  /** Target CPU architecture */
20
  arch: string;
21
  /** Target platform */
22
  platform: string;
23
  /** LIBC variant for Linux builds */
24
  libc: string;
25
  /** Build backend to use */
26
  backend: 'node-gyp' | 'node-ninja' | 'nw-gyp' | 'cmake-js';
27
  /** Additional format parameters for node-gyp */
28
  format: string | false;
29
  /** Build all supported ABI versions */
30
  all: boolean;
31
  /** Force rebuild even if output exists */
32
  force: boolean;
33
  /** Build in debug mode */
34
  debug: boolean;
35
  /** Enable verbose logging */
36
  verbose: boolean;
37
  /** Working directory for build */
38
  path: string;
39
  /** Strip debug symbols from output */
40
  strip: boolean;
41
  /** GitHub token for uploading releases */
42
  upload?: string;
43
  /** Upload all files from prebuilds directory */
44
  'upload-all'?: string;
45
  /** Tag prefix for GitHub releases */
46
  'tag-prefix': string;
47
  /** Mark release as prerelease */
48
  prerelease: boolean;
49
  /** Regex pattern for files to include in package */
50
  'include-regex': RegExp;
51
  /** Script to run before building */
52
  preinstall?: string;
53
  /** Script to run before packing */
54
  prepack?: string;
55
  /** Processed prebuild targets array */
56
  prebuild?: PrebuildTarget[];
57
  /** Command line arguments */
58
  argv?: string[];
59
}
60

61
interface PrebuildTarget {
62
  runtime: Runtime;
63
  target: string;
64
}
65

66
type Runtime = 'node' | 'napi' | 'electron' | 'node-webkit';
67
```
68

69
**Usage Examples:**
70

71
```javascript
72
const rc = require('prebuild/rc');
73

74
// Access configuration
75
console.log('Building for:', rc.runtime, rc.target);
76
console.log('Architecture:', rc.arch);
77
console.log('Backend:', rc.backend);
78

79
// Check if uploading
80
if (rc.upload) {
81
  console.log('Will upload to GitHub with token');
82
}
83

84
// Access prebuild targets
85
rc.prebuild.forEach(target => {
86
  console.log(`Target: ${target.runtime} ${target.target}`);
87
});
88
```
89

90
### Default Configuration
91

92
Default values applied before parsing command-line arguments and config files.
93

94
```javascript { .api }
95
/**
96
 * Default configuration values
97
 */
98
interface DefaultConfiguration {
99
  target: string; // process.versions.node
100
  runtime: 'node';
101
  arch: string; // process.arch  
102
  libc: string; // auto-detected or empty
103
  platform: string; // process.platform
104
  all: false;
105
  force: false;
106
  debug: false;
107
  verbose: false;
108
  path: '.';
109
  backend: 'node-gyp';
110
  format: false;
111
  'include-regex': '\\.node$';
112
  'tag-prefix': 'v';
113
  prerelease: false;
114
}
115
```
116

117
### Command Line Aliases
118

119
Supported command-line argument aliases for common options.
120

121
```javascript { .api }
122
/**
123
 * Command line argument aliases
124
 */
125
interface CommandAliases {
126
  target: 't';
127
  runtime: 'r';
128
  help: 'h';
129
  arch: 'a';
130
  path: 'p';
131
  force: 'f';
132
  version: 'v';
133
  upload: 'u';
134
  preinstall: 'i';
135
  prepack: 'c';
136
}
137
```
138

139
**Usage Examples:**
140

141
```bash
142
# Long form arguments
143
prebuild --target 16.14.0 --runtime node --arch x64
144

145
# Short form aliases  
146
prebuild -t 16.14.0 -r node -a x64
147

148
# Upload with token
149
prebuild --all --upload ghp_token123
150

151
# Using aliases
152
prebuild --all -u ghp_token123
153
```
154

155
### Node-API Configuration
156

157
Automatic Node-API version handling and validation.
158

159
```javascript { .api }
160
/**
161
 * Node-API specific configuration handling
162
 */
163
interface NapiConfiguration {
164
  /** Available Node-API build versions */
165
  napiBuildVersions: number[];
166
  /** Best Node-API version for current Node.js */
167
  bestNapiBuildVersion: number;
168
  /** Supported Node-API versions from package.json */
169
  supportedVersions: number[];
170
}
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
// Building for Node-API (configured automatically)
177
// Command: prebuild -r napi --all
178
// Results in prebuild targets for all supported Node-API versions
179

180
// Single Node-API version
181
// Command: prebuild -r napi -t 3
182
// Results in prebuild target for Node-API version 3
183
```
184

185
### RC File Configuration
186

187
Configuration file support using the 'rc' module with `~/.prebuildrc` files.
188

189
```javascript { .api }
190
/**
191
 * RC file configuration options
192
 */
193
interface RcFileOptions {
194
  /** GitHub upload token */
195
  upload?: string;
196
  /** Default target versions */
197
  target?: string | string[];
198
  /** Default runtime */
199
  runtime?: Runtime;
200
  /** Default architecture */
201
  arch?: string;
202
  /** Default build backend */
203
  backend?: Backend;
204
  /** Enable verbose logging by default */
205
  verbose?: boolean;
206
  /** Default tag prefix for releases */
207
  'tag-prefix'?: string;
208
}
209
```
210

211
**RC File Example (`~/.prebuildrc`):**
212

213
```json
214
{
215
  "upload": "ghp_your_github_token_here",
216
  "verbose": true,
217
  "tag-prefix": "v",
218
  "backend": "node-gyp"
219
}
220
```
221

222
### Environment Variables
223

224
Environment variables that affect configuration.
225

226
```javascript { .api }
227
/**
228
 * Recognized environment variables
229
 */
230
interface EnvironmentVariables {
231
  /** LIBC family detection override */
232
  LIBC?: string;
233
  /** Strip command override (defaults to 'strip') */
234
  STRIP?: string;
235
  /** NVM mirror URLs (automatically deleted) */
236
  NVM_IOJS_ORG_MIRROR?: string;
237
  NVM_NODEJS_ORG_MIRROR?: string;
238
}
239
```
240

241
### Target Selection Logic
242

243
Automatic target selection based on runtime and flags.
244

245
```javascript { .api }
246
/**
247
 * Target selection for different scenarios
248
 */
249
interface TargetSelection {
250
  /** When --all is used with Node.js runtime */
251
  allNodeTargets: PrebuildTarget[]; // All supported Node.js ABI versions
252
  /** When --all is used with Node-API runtime */
253
  allNapiTargets: PrebuildTarget[]; // All supported Node-API versions
254
  /** When specific targets provided */
255
  specificTargets: PrebuildTarget[];
256
  /** Default when no targets specified */
257
  defaultTarget: PrebuildTarget;
258
}
259
```
260

261
## Configuration Flow
262

263
1. **Defaults Applied**: Base configuration with platform-specific defaults
264
2. **RC Files Parsed**: `~/.prebuildrc` and project-level `.prebuildrc` files
265
3. **Command Line Parsed**: Arguments and aliases processed with minimist
266
4. **Environment Variables**: `LIBC` and other env vars applied
267
5. **Target Processing**: Node-API version resolution and target array generation
268
6. **Validation**: Backend compatibility and option validation
269
7. **Regex Compilation**: Include patterns compiled to RegExp objects
270

271
## Types
272

273
```javascript { .api }
274
type Runtime = 'node' | 'napi' | 'electron' | 'node-webkit';
275
type Backend = 'node-gyp' | 'node-ninja' | 'nw-gyp' | 'cmake-js';
276

277
interface PrebuildTarget {
278
  runtime: Runtime;
279
  target: string;
280
}
281
```