0
# Development File Management
1

2
Development file management handles the installation, listing, and removal of Node.js development files (headers and libraries) required for compiling native addons against different Node.js versions.
3

4
## Capabilities
5

6
### Install Command
7

8
Downloads and installs Node.js development files for a specified Node.js version, including headers, libraries, and platform-specific build artifacts.
9

10
```javascript { .api }
11
/**
12
 * Install node development files for the specified node version
13
 * @param {Gyp} gyp - The gyp instance
14
 * @param {string[]} argv - Command arguments, first element can be Node.js version
15
 * @returns {Promise<void>}
16
 */
17
async function install(gyp: Gyp, argv: string[]): Promise<void>;
18
```
19

20
**Usage Examples:**
21

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

26
// Install development files for current Node.js version
27
await gypInstance.commands.install([]);
28

29
// Install for specific version
30
await gypInstance.commands.install(['16.14.0']);
31

32
// Install for latest LTS
33
await gypInstance.commands.install(['lts']);
34

35
// Install with options
36
gypInstance.opts.target = '18.0.0';
37
gypInstance.opts['dist-url'] = 'https://nodejs.org/dist';
38
await gypInstance.commands.install([]);
39
```
40

41
**Installation Process:**
42
1. **Version Resolution**: Determines target Node.js version from arguments or options
43
2. **Download Location**: Uses configured distribution URL (default: nodejs.org)
44
3. **Header Download**: Downloads and extracts Node.js header files
45
4. **Library Download**: Downloads platform-specific libraries (Windows: .lib files)
46
5. **Checksum Verification**: Validates downloaded files using SHA checksums
47
6. **Cache Management**: Stores files in development directory for reuse
48

49
### List Command
50

51
Lists all currently installed Node.js development file versions in the development directory.
52

53
```javascript { .api }
54
/**
55
 * Prints a listing of the currently installed node development files
56
 * @param {Gyp} gyp - The gyp instance
57
 * @param {string[]} argv - Command arguments (unused)
58
 * @returns {Promise<string[]>} Array of installed version strings
59
 */
60
async function list(gyp: Gyp, argv: string[]): Promise<string[]>;
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
const gyp = require('node-gyp');
67
const gypInstance = gyp();
68

69
// List all installed versions
70
const versions = await gypInstance.commands.list([]);
71
console.log('Installed versions:', versions);
72
// Output: ['16.14.0', '18.0.0', '18.12.1']
73

74
// Check if specific version is installed
75
const installedVersions = await gypInstance.commands.list([]);
76
const hasVersion = installedVersions.includes('16.14.0');
77
console.log('Has 16.14.0:', hasVersion);
78
```
79

80
**Output Format:**
81
- Returns array of version strings for installed development files
82
- Versions are sorted and deduplicated
83
- Empty array if no development files are installed
84

85
### Remove Command
86

87
Removes installed Node.js development files for a specified version from the development directory.
88

89
```javascript { .api }
90
/**
91
 * Removes the node development files for the specified version
92
 * @param {Gyp} gyp - The gyp instance
93
 * @param {string[]} argv - Command arguments, first element should be Node.js version
94
 * @returns {Promise<void>}
95
 */
96
async function remove(gyp: Gyp, argv: string[]): Promise<void>;
97
```
98

99
**Usage Examples:**
100

101
```javascript
102
const gyp = require('node-gyp');
103
const gypInstance = gyp();
104

105
// Remove specific version
106
await gypInstance.commands.remove(['16.14.0']);
107

108
// Remove multiple versions
109
await gypInstance.commands.remove(['16.14.0']);
110
await gypInstance.commands.remove(['18.0.0']);
111

112
// Check what's installed first
113
const versions = await gypInstance.commands.list([]);
114
console.log('Before removal:', versions);
115

116
await gypInstance.commands.remove(['16.14.0']);
117

118
const versionsAfter = await gypInstance.commands.list([]);
119
console.log('After removal:', versionsAfter);
120
```
121

122
**Removal Process:**
123
1. **Version Validation**: Confirms the specified version exists in development directory
124
2. **Directory Cleanup**: Removes all files and directories for that version
125
3. **Cache Invalidation**: Cleans up any cached metadata for the version
126

127
## Development Directory Structure
128

129
Node-gyp stores development files in a structured directory layout:
130

131
```
132
~/.cache/node-gyp/  (or configured devdir)
133
├── 16.14.0/
134
│   ├── include/
135
│   │   └── node/
136
│   │       ├── node.h
137
│   │       ├── v8.h
138
│   │       └── ...
139
│   ├── src/
140
│   ├── deps/
141
│   └── node.lib        (Windows only)
142
├── 18.0.0/
143
│   └── ...
144
└── 18.12.1/
145
    └── ...
146
```
147

148
## Configuration Options
149

150
### Development Directory
151

152
```javascript
153
const gyp = require('node-gyp');
154
const gypInstance = gyp();
155

156
// Set custom development directory
157
gypInstance.opts.devdir = '/custom/path/to/dev/files';
158
await gypInstance.commands.install(['16.14.0']);
159
```
160

161
### Distribution URL
162

163
```javascript
164
// Use custom distribution mirror
165
gypInstance.opts['dist-url'] = 'https://mirror.example.com/nodejs/dist';
166
await gypInstance.commands.install(['16.14.0']);
167

168
// Use local tarball
169
gypInstance.opts.tarball = '/path/to/node-v16.14.0.tar.gz';
170
await gypInstance.commands.install([]);
171
```
172

173
### Proxy Configuration
174

175
```javascript
176
// Configure HTTP proxy
177
gypInstance.opts.proxy = 'http://proxy.company.com:8080';
178
gypInstance.opts.noproxy = 'localhost,127.0.0.1,.company.com';
179
await gypInstance.commands.install(['16.14.0']);
180
```
181

182
### CA Certificate
183

184
```javascript
185
// Use custom CA certificate file
186
gypInstance.opts.cafile = '/path/to/ca-certificates.crt';
187
await gypInstance.commands.install(['16.14.0']);
188
```
189

190
## Advanced Usage Patterns
191

192
### Version Management Workflow
193

194
```javascript
195
const gyp = require('node-gyp');
196
const gypInstance = gyp();
197

198
// Development workflow: manage multiple Node.js versions
199
async function setupDevEnvironment() {
200
  // Install multiple versions
201
  await gypInstance.commands.install(['16.14.0']);
202
  await gypInstance.commands.install(['18.12.1']);
203
  await gypInstance.commands.install(['20.0.0']);
204
  
205
  // List what's available
206
  const versions = await gypInstance.commands.list([]);  
207
  console.log('Available versions:', versions);
208
  
209
  // Build against specific version
210
  gypInstance.opts.target = '18.12.1';
211
  await gypInstance.commands.configure([]);
212
  await gypInstance.commands.build([]);
213
}
214
```
215

216
### Cleanup and Maintenance
217

218
```javascript
219
const gyp = require('node-gyp');
220
const gypInstance = gyp();
221

222
// Clean up old versions
223
async function cleanupOldVersions() {
224
  const versions = await gypInstance.commands.list([]);
225
  
226
  // Remove versions older than 16.x
227
  for (const version of versions) {
228
    const major = parseInt(version.split('.')[0]);
229
    if (major < 16) {
230
      console.log(`Removing old version: ${version}`);
231
      await gypInstance.commands.remove([version]);
232
    }
233
  }
234
}
235
```
236

237
### Conditional Installation
238

239
```javascript
240
const gyp = require('node-gyp');
241
const gypInstance = gyp();
242

243
// Only install if not already present
244
async function ensureVersionInstalled(targetVersion) {
245
  const installedVersions = await gypInstance.commands.list([]);
246
  
247
  if (!installedVersions.includes(targetVersion)) {
248
    console.log(`Installing Node.js ${targetVersion} development files...`);
249
    await gypInstance.commands.install([targetVersion]);
250
  } else {
251
    console.log(`Node.js ${targetVersion} already installed`);
252
  }
253
}
254

255
// Usage
256
await ensureVersionInstalled('18.12.1');
257
```
258

259
## ShaSum Class
260

261
The install module also exports a SHA checksum verification utility:
262

263
```javascript { .api }
264
/**
265
 * Transform stream for SHA checksum verification during downloads
266
 * @extends Transform
267
 */
268
class ShaSum extends Transform {
269
  constructor(algorithm: string, expected: string);
270
  
271
  /**
272
   * Validates the computed hash against expected value
273
   * @throws {Error} If checksum doesn't match
274
   */
275
  validate(): void;
276
}
277
```
278

279
**Usage Example:**
280

281
```javascript
282
const { ShaSum } = require('node-gyp/lib/install');
283
const fs = require('fs');
284

285
// Verify file checksum during streaming
286
const fileStream = fs.createReadStream('node-headers.tar.gz');
287
const shasum = new ShaSum('sha256', 'expected-hash-here');
288

289
fileStream
290
  .pipe(shasum)
291
  .on('end', () => {
292
    try {
293
      shasum.validate();
294
      console.log('Checksum verified successfully');
295
    } catch (error) {
296
      console.error('Checksum verification failed:', error.message);
297
    }
298
  });
299
```
300

301
## Error Handling
302

303
Common error scenarios and handling:
304

305
```javascript
306
const gyp = require('node-gyp');
307
const gypInstance = gyp();
308

309
try {
310
  await gypInstance.commands.install(['16.14.0']);
311
} catch (error) {
312
  if (error.message.includes('ENOTFOUND')) {
313
    console.error('Network error: Unable to reach download server');
314
  } else if (error.message.includes('EACCES')) {
315
    console.error('Permission error: Cannot write to development directory');
316
  } else if (error.message.includes('checksum')) {
317
    console.error('Download corrupted: Checksum verification failed');
318
  } else {
319
    console.error('Installation failed:', error.message);
320
  }
321
}
322

323
try {
324
  await gypInstance.commands.remove(['99.99.99']);
325
} catch (error) {
326
  if (error.message.includes('ENOENT')) {
327
    console.error('Version not found: 99.99.99 is not installed');
328
  }
329
}
330
```