0
# Core Build System
1

2
The core build system provides the main entry points and orchestration for node-gyp operations, handling command parsing, execution, and cross-platform build coordination.
3

4
## Capabilities
5

6
### Main Factory Function
7

8
Creates a new Gyp instance for build operations.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Gyp instance
13
 * @returns {Gyp} New Gyp instance
14
 */
15
function gyp(): Gyp;
16
```
17

18
### Gyp Class
19

20
Main orchestrator class that extends EventEmitter for build operations and command coordination.
21

22
```javascript { .api }
23
/**
24
 * Main node-gyp class that handles command parsing and execution
25
 * @extends EventEmitter
26
 */
27
class Gyp extends EventEmitter {
28
  /**
29
   * Package.json contents
30
   * @type {object}
31
   */
32
  package: object;
33
  
34
  /**
35
   * Version from package.json
36
   * @type {string}
37
   */
38
  version: string;
39
  
40
  /**
41
   * Development files directory path
42
   * @type {string}
43
   */
44
  devDir: string;
45
  
46
  /**
47
   * Map of command names to handler functions
48
   * @type {object}
49
   */
50
  commands: { [key: string]: (argv: string[]) => Promise<any> };
51
  
52
  /**
53
   * Configuration definitions for nopt
54
   * @type {object}
55
   */
56
  configDefs: object;
57
  
58
  /**
59
   * Shorthand mappings for command-line options
60
   * @type {object}
61
   */
62
  shorthands: object;
63
  
64
  /**
65
   * Command aliases (ls -> list, rm -> remove)
66
   * @type {object}
67
   */
68
  aliases: object;
69
  
70
  /**
71
   * Parsed command-line options
72
   * @type {GypOptions}
73
   */
74
  opts: GypOptions;
75
  
76
  /**
77
   * Remaining command-line arguments
78
   * @type {string[]}
79
   */
80
  argv: string[];
81
  
82
  /**
83
   * Queue of commands to execute
84
   * @type {CommandObject[]}
85
   */
86
  todo: CommandObject[];
87
}
88
```
89

90
### Command Line Parsing
91

92
Parses command-line arguments and configures the gyp instance.
93

94
```javascript { .api }
95
/**
96
 * Parses command-line arguments and sets opts, argv, and todo properties
97
 * @param {string[]} argv - Command-line arguments to parse
98
 */
99
parseArgv(argv: string[]): void;
100
```
101

102
**Usage Example:**
103

104
```javascript
105
const gyp = require('node-gyp');
106
const gypInstance = gyp();
107

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

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

116
### Process Spawning
117

118
Spawns child processes for build operations with proper logging and event emission.
119

120
```javascript { .api }
121
/**
122
 * Spawns a child process and emits a 'spawn' event
123
 * @param {string} command - Command to execute
124
 * @param {string[]} args - Arguments for the command
125
 * @param {object} [opts] - Options for child_process.spawn
126
 * @returns {ChildProcess} The spawned child process
127
 */
128
spawn(command: string, args: string[], opts?: object): ChildProcess;
129
```
130

131
**Usage Example:**
132

133
```javascript
134
const gyp = require('node-gyp');
135
const gypInstance = gyp();
136

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

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

148
### Usage Information
149

150
Returns formatted usage instructions for the command-line interface.
151

152
```javascript { .api }
153
/**
154
 * Returns usage instructions for node-gyp
155
 * @returns {string} Formatted usage instructions
156
 */
157
usage(): string;
158
```
159

160
**Usage Example:**
161

162
```javascript
163
const gyp = require('node-gyp');
164
const gypInstance = gyp();
165

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

176
## Configuration System
177

178
### Configuration Definitions
179

180
Node-gyp supports extensive configuration through command-line options and environment variables.
181

182
```javascript { .api }
183
interface GypOptions {
184
  help?: boolean;              // Show help information
185
  arch?: string;               // Target architecture (x86, x64, arm64)
186
  cafile?: string;             // CA certificate file path
187
  debug?: boolean;             // Build in debug mode
188
  directory?: string;          // Working directory
189
  make?: string;               // Make command to use
190
  'msvs-version'?: string;     // Visual Studio version (Windows)
191
  ensure?: boolean;            // Only install if not already present
192
  solution?: string;           // Solution file to build (Windows)
193
  proxy?: string;              // HTTP proxy settings
194
  noproxy?: string;            // Proxy bypass settings
195
  devdir?: string;             // Development files directory
196
  nodedir?: string;            // Node.js directory path
197
  loglevel?: string;           // Logging level (silly, verbose, info, warn, error)
198
  python?: string;             // Python executable path
199
  'dist-url'?: string;         // Distribution URL for downloads
200
  tarball?: string;            // Local tarball path
201
  jobs?: string;               // Build job parallelization
202
  thin?: string;               // Thin archive support
203
  'force-process-config'?: boolean; // Force process configuration
204
}
205
```
206

207
### Environment Variable Support
208

209
Node-gyp automatically reads configuration from environment variables:
210

211
- `npm_config_*` - Standard npm configuration variables
212
- `npm_package_config_node_gyp_*` - Package-specific node-gyp configuration
213
- `PYTHON` - Python executable path
214
- `VCINSTALLDIR` - Visual Studio install directory (Windows)
215
- `NODE_GYP_FORCE_PYTHON` - Force specific Python version
216

217
**Usage Example:**
218

219
```bash
220
# Set options via environment variables
221
export npm_config_python=/usr/bin/python3.8
222
export npm_config_msvs_version=2019
223
export npm_config_debug=true
224

225
# These will be automatically picked up by parseArgv
226
```
227

228
## Command Structure
229

230
### Command Object Interface
231

232
```javascript { .api }
233
interface CommandObject {
234
  name: string;    // Command name (build, clean, configure, etc.)
235
  args: string[];  // Arguments specific to this command
236
}
237
```
238

239
### Available Commands
240

241
Node-gyp provides these core commands:
242

243
- `build` - Compile the native module
244
- `clean` - Remove build artifacts
245
- `configure` - Generate build files
246
- `rebuild` - Clean, configure, and build in sequence
247
- `install` - Install Node.js development files
248
- `list` - List installed development files
249
- `remove` - Remove development files
250

251
### Command Aliases
252

253
- `ls` → `list`
254
- `rm` → `remove`
255

256
## Event System
257

258
The Gyp class extends EventEmitter and emits events during operation:
259

260
```javascript
261
const gyp = require('node-gyp');
262
const gypInstance = gyp();
263

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

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