0
# Build Commands
1

2
Build commands handle the core compilation and build management operations for native Node.js addons. Each command is designed to work independently or as part of automated workflows.
3

4
## Capabilities
5

6
### Build Command
7

8
Compiles the native module using the appropriate build system for the current platform.
9

10
```javascript { .api }
11
/**
12
 * Invokes `msbuild` (on Windows) or `make` (on other platforms) and builds the module
13
 * @param {Gyp} gyp - The gyp instance
14
 * @param {string[]} argv - Command arguments
15
 * @returns {Promise<void>}
16
 */
17
async function build(gyp: Gyp, argv: string[]): Promise<void>;
18
```
19

20
**Usage Example:**
21

22
```javascript
23
const gyp = require('node-gyp');
24
const gypInstance = gyp();
25

26
// Build in release mode
27
await gypInstance.commands.build([]);
28

29
// Build in debug mode
30
gypInstance.opts.debug = true;
31
await gypInstance.commands.build([]);
32

33
// Build with specific job count
34
gypInstance.opts.jobs = '4';
35
await gypInstance.commands.build([]);
36
```
37

38
**Platform-Specific Behavior:**
39
- **Windows**: Uses MSBuild with Visual Studio project files
40
- **Unix/Linux/macOS**: Uses Make with generated Makefiles
41
- **Supports**: Parallel builds, debug/release modes, architecture targeting
42

43
### Clean Command
44

45
Removes all generated build files and the output directory to ensure a clean build state.
46

47
```javascript { .api }
48
/**
49
 * Removes any generated build files and the "out" dir
50
 * @param {Gyp} gyp - The gyp instance
51
 * @param {string[]} argv - Command arguments
52
 * @returns {Promise<void>}
53
 */
54
async function clean(gyp: Gyp, argv: string[]): Promise<void>;
55
```
56

57
**Usage Example:**
58

59
```javascript
60
const gyp = require('node-gyp');
61
const gypInstance = gyp();
62

63
// Clean all build artifacts
64
await gypInstance.commands.clean([]);
65

66
// Clean is typically used before rebuild
67
await gypInstance.commands.clean([]);
68
await gypInstance.commands.configure([]);
69
await gypInstance.commands.build([]);
70
```
71

72
**What Gets Cleaned:**
73
- `build/` directory and all contents
74
- Generated Makefiles or Visual Studio project files
75
- Compiled object files and intermediate build artifacts
76
- Output binaries and libraries
77

78
### Configure Command
79

80
Generates the necessary build files (Makefiles or Visual Studio project files) for the current platform and configuration.
81

82
```javascript { .api }
83
/**
84
 * Generates MSVC project files (on Windows) or a Makefile (on other platforms) for the current module
85
 * @param {Gyp} gyp - The gyp instance
86
 * @param {string[]} argv - Command arguments
87
 * @returns {Promise<void>}
88
 */
89
async function configure(gyp: Gyp, argv: string[]): Promise<void>;
90
```
91

92
**Usage Example:**
93

94
```javascript
95
const gyp = require('node-gyp');
96
const gypInstance = gyp();
97

98
// Basic configuration
99
await gypInstance.commands.configure([]);
100

101
// Configure for specific Node.js version
102
gypInstance.opts.target = '16.14.0';
103
await gypInstance.commands.configure([]);
104

105
// Configure for specific architecture
106
gypInstance.opts.arch = 'x64';
107
await gypInstance.commands.configure([]);
108

109
// Configure with custom Python
110
gypInstance.opts.python = '/usr/bin/python3.8';
111
await gypInstance.commands.configure([]);
112
```
113

114
**Configuration Process:**
115
1. **Node.js Headers**: Downloads or locates Node.js development headers
116
2. **Python Detection**: Finds and validates Python installation
117
3. **Toolchain Discovery**: Locates build tools (Visual Studio on Windows, GCC/Clang on Unix)
118
4. **Build File Generation**: Creates platform-specific build files from binding.gyp
119
5. **Environment Setup**: Configures include paths, library paths, and compiler flags
120

121
### Rebuild Command
122

123
Convenience command that performs a complete rebuild by running clean, configure, and build in sequence.
124

125
```javascript { .api }
126
/**
127
 * Runs "clean", "configure" and "build" all at once
128
 * @param {Gyp} gyp - The gyp instance
129
 * @param {string[]} argv - Command arguments
130
 * @returns {Promise<void>}
131
 */
132
async function rebuild(gyp: Gyp, argv: string[]): Promise<void>;
133
```
134

135
**Usage Example:**
136

137
```javascript
138
const gyp = require('node-gyp');
139
const gypInstance = gyp();
140

141
// Complete rebuild - equivalent to clean + configure + build
142
await gypInstance.commands.rebuild([]);
143

144
// Rebuild with options
145
gypInstance.opts.debug = true;
146
gypInstance.opts.arch = 'x64';
147
await gypInstance.commands.rebuild([]);
148
```
149

150
**Rebuild Sequence:**
151
1. **Clean**: Removes all existing build artifacts
152
2. **Configure**: Regenerates build files with current settings
153
3. **Build**: Compiles the native module
154

155
## Build Configuration Options
156

157
### Debug vs Release Builds
158

159
```javascript
160
// Debug build - includes debug symbols, no optimization
161
gypInstance.opts.debug = true;
162
await gypInstance.commands.build([]);
163

164
// Release build - optimized, no debug symbols (default)
165
gypInstance.opts.debug = false;
166
await gypInstance.commands.build([]);
167
```
168

169
### Architecture Targeting
170

171
```javascript
172
// Target specific architectures
173
gypInstance.opts.arch = 'x64';     // 64-bit Intel/AMD
174
gypInstance.opts.arch = 'x86';     // 32-bit Intel/AMD
175
gypInstance.opts.arch = 'arm64';   // 64-bit ARM (Apple Silicon, etc.)
176
await gypInstance.commands.configure([]);
177
```
178

179
### Parallel Building
180

181
```javascript
182
// Control build parallelization
183
gypInstance.opts.jobs = '4';       // Use 4 parallel jobs
184
gypInstance.opts.jobs = '$(nproc)'; // Use all available cores (Unix)
185
await gypInstance.commands.build([]);
186
```
187

188
### Custom Build Tools
189

190
```javascript
191
// Specify custom make command
192
gypInstance.opts.make = 'gmake';   // Use GNU make specifically
193
gypInstance.opts.make = 'ninja';   // Use Ninja build system
194

195
// Windows: Specify Visual Studio version
196
gypInstance.opts['msvs-version'] = '2019';
197
gypInstance.opts['msvs-version'] = '2022';
198
```
199

200
## Error Handling
201

202
All build commands are async functions that may throw errors. Common error scenarios:
203

204
```javascript
205
const gyp = require('node-gyp');
206
const gypInstance = gyp();
207

208
try {
209
  await gypInstance.commands.build([]);
210
} catch (error) {
211
  if (error.message.includes('Python')) {
212
    console.error('Python not found or incompatible version');
213
  } else if (error.message.includes('Visual Studio')) {
214
    console.error('Visual Studio build tools not found');
215
  } else if (error.message.includes('make')) {
216
    console.error('Make build failed');
217
  }
218
  
219
  // Error details
220
  console.error('Build failed:', error.message);
221
  console.error('Stack:', error.stack);
222
}
223
```
224

225
## Command Integration Patterns
226

227
### Sequential Execution
228

229
```javascript
230
const gyp = require('node-gyp');
231
const gypInstance = gyp();
232

233
// Manual sequential execution
234
await gypInstance.commands.clean([]);
235
await gypInstance.commands.configure([]);
236
await gypInstance.commands.build([]);
237

238
// Or use rebuild for the same effect
239
await gypInstance.commands.rebuild([]);
240
```
241

242
### Conditional Building
243

244
```javascript
245
const gyp = require('node-gyp');
246
const fs = require('fs');
247

248
const gypInstance = gyp();
249

250
// Only configure if build files don't exist
251
if (!fs.existsSync('build/Makefile') && !fs.existsSync('build/binding.sln')) {
252
  await gypInstance.commands.configure([]);
253
}
254

255
await gypInstance.commands.build([]);
256
```
257

258
### Development Workflow
259

260
```javascript
261
// Typical development workflow
262
const gyp = require('node-gyp');
263
const gypInstance = gyp();
264

265
// Development build with debug symbols
266
gypInstance.opts.debug = true;
267

268
// Clean build
269
await gypInstance.commands.clean([]);
270
await gypInstance.commands.configure([]);
271
await gypInstance.commands.build([]);
272

273
// Later: quick rebuild without clean
274
await gypInstance.commands.build([]);
275
```