0
# Platform Toolchain Discovery
1

2
Platform toolchain discovery provides automated detection and validation of build tools across different operating systems, including Python interpreters, Visual Studio installations, and Node.js directories.
3

4
## Capabilities
5

6
### Python Discovery
7

8
Finds and validates Python installations across platforms with version compatibility checking.
9

10
```javascript { .api }
11
/**
12
 * Python detection and validation class
13
 */
14
class PythonFinder {
15
  /**
16
   * Static factory method to find Python executable
17
   * @param {...any} args - Configuration arguments
18
   * @returns {Promise<string>} Path to valid Python executable
19
   */
20
  static findPython(...args: any[]): Promise<string>;
21
  
22
  /**
23
   * Logging instance with 'find Python' prefix
24
   * @type {object}
25
   */
26
  log: object;
27
  
28
  /**
29
   * Supported Python version range
30
   * @type {string}
31
   */
32
  semverRange: string;
33
}
34
```
35

36
**Usage Examples:**
37

38
```javascript
39
const { PythonFinder } = require('node-gyp/lib/find-python');
40

41
// Find system Python
42
try {
43
  const pythonPath = await PythonFinder.findPython();
44
  console.log('Found Python at:', pythonPath);
45
} catch (error) {
46
  console.error('Python not found:', error.message);
47
}
48

49
// Find Python with custom configuration
50
const pythonPath = await PythonFinder.findPython({
51
  execPath: '/usr/bin/python3.8',
52
  configPython: process.env.npm_config_python
53
});
54
```
55

56
**Python Detection Process:**
57
1. **Command Line Option**: Checks `--python` flag
58
2. **Environment Variables**: Checks `npm_config_python`, `PYTHON`, `NODE_GYP_FORCE_PYTHON`
59
3. **System PATH**: Searches common Python executable names
60
4. **Platform Defaults**: Uses platform-specific default locations
61
5. **Version Validation**: Ensures Python version meets requirements (>=3.6.0)
62

63
### Visual Studio Discovery (Windows)
64

65
Locates and validates Visual Studio installations on Windows systems for native compilation.
66

67
```javascript { .api }
68
/**
69
 * Visual Studio detection and validation class (Windows only)
70
 */
71
class VisualStudioFinder {
72
  /**
73
   * Static factory method to find Visual Studio installation
74
   * @param {...any} args - Configuration arguments (nodeSemver, configMsvsVersion)
75
   * @returns {Promise<object>} Visual Studio installation details
76
   */
77
  static findVisualStudio(...args: any[]): Promise<object>;
78
  
79
  /**
80
   * Node.js semver for compatibility checking
81
   * @type {string}
82
   */
83
  nodeSemver: string;
84
  
85
  /**
86
   * Configured Visual Studio version preference
87
   * @type {string}
88
   */
89
  configMsvsVersion: string;
90
  
91
  /**
92
   * Accumulated error messages for diagnostics
93
   * @type {string[]}
94
   */
95
  errorLog: string[];
96
  
97
  /**
98
   * Found valid Visual Studio installations
99
   * @type {object[]}
100
   */
101
  validVersions: object[];
102
}
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
const { VisualStudioFinder } = require('node-gyp/lib/find-visualstudio');
109

110
// Find any compatible Visual Studio
111
try {
112
  const vsInfo = await VisualStudioFinder.findVisualStudio('16.0.0');
113
  console.log('Visual Studio found:', vsInfo);
114
} catch (error) {
115
  console.error('Visual Studio not found:', error.message);
116
}
117

118
// Find specific Visual Studio version
119
try {
120
  const vsInfo = await VisualStudioFinder.findVisualStudio('16.0.0', '2019');
121
  console.log('VS 2019 found at:', vsInfo.path);
122
} catch (error) {
123
  console.error('VS 2019 not available');
124
}
125
```
126

127
**Visual Studio Detection Process:**
128
1. **Version Preference**: Checks `--msvs-version` or configured preference
129
2. **Environment Detection**: Checks `VCINSTALLDIR` environment variable
130
3. **Registry Search**: Searches Windows registry for VS installations
131
4. **VSWhere Tool**: Uses vswhere.exe if available for newer versions
132
5. **Compatibility Check**: Validates version compatibility with Node.js version
133
6. **Tool Validation**: Confirms required build tools are present
134

135
### Node.js Directory Discovery
136

137
Locates Node.js installation directory from various contexts and installation methods.
138

139
```javascript { .api }
140
/**
141
 * Finds Node.js installation directory
142
 * @param {string} [scriptLocation] - Script location for context detection
143
 * @param {object} [processObj] - Process object for platform detection
144
 * @returns {string} Path to Node.js root directory or empty string if not found
145
 */
146
function findNodeDirectory(scriptLocation?: string, processObj?: object): string;
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
const findNodeDirectory = require('node-gyp/lib/find-node-directory');
153

154
// Find Node.js directory from current context
155
const nodeDir = findNodeDirectory();
156
console.log('Node.js directory:', nodeDir);
157

158
// Find with custom script location
159
const nodeDir = findNodeDirectory('/path/to/script', process);
160
console.log('Node.js directory:', nodeDir);
161

162
// Use in build configuration
163
const gyp = require('node-gyp');
164
const gypInstance = gyp();
165

166
const nodeDir = findNodeDirectory();
167
if (nodeDir) {
168
  gypInstance.opts.nodedir = nodeDir;
169
}
170
```
171

172
**Detection Strategy:**
173
1. **Build Directory**: Detects if running from Node.js build directory
174
2. **Install Directory**: Detects standard Node.js installation layout
175
3. **Binary Location**: Uses Node.js executable path as fallback
176
4. **Platform Specific**: Handles Windows vs Unix directory structures
177

178
## Platform-Specific Considerations
179

180
### Windows Platform
181

182
```javascript
183
// Windows-specific Python locations
184
const winDefaultLocations = [
185
  '%LOCALAPPDATA%\\Programs\\Python\\Python39\\python.exe',
186
  '%ProgramFiles%\\Python39\\python.exe',
187
  '%ProgramFiles(x86)%\\Python39\\python.exe'
188
];
189

190
// Visual Studio detection priority
191
const vsVersions = ['2022', '2019', '2017', '2015'];
192
```
193

194
### Unix/Linux Platform
195

196
```javascript
197
// Common Python executable names on Unix
198
const pythonExecutables = [
199
  'python3',
200
  'python3.9',
201
  'python3.8', 
202
  'python3.7',
203
  'python3.6',
204
  'python'
205
];
206

207
// Standard paths searched
208
const searchPaths = [
209
  '/usr/bin',
210
  '/usr/local/bin',
211
  '/opt/python/bin'
212
];
213
```
214

215
### macOS Platform
216

217
```javascript
218
// macOS-specific considerations
219
const macPythonPaths = [
220
  '/usr/bin/python3',
221
  '/usr/local/bin/python3',
222
  '/opt/homebrew/bin/python3',  // Apple Silicon Homebrew
223
  '/usr/local/opt/python/bin/python3'  // Intel Homebrew
224
];
225
```
226

227
## Integration with Build Process
228

229
### Configure Integration
230

231
The toolchain discovery integrates with the configure command:
232

233
```javascript
234
const gyp = require('node-gyp');
235
const gypInstance = gyp();
236

237
// Configure automatically discovers toolchain
238
await gypInstance.commands.configure([]);
239

240
// Manual toolchain specification
241
gypInstance.opts.python = '/usr/bin/python3.8';
242
gypInstance.opts['msvs-version'] = '2019';
243
gypInstance.opts.nodedir = '/usr/local/node';
244
await gypInstance.commands.configure([]);
245
```
246

247
### Environment Variable Integration
248

249
```javascript
250
// Set environment variables for toolchain discovery
251
process.env.PYTHON = '/usr/bin/python3.8';
252
process.env.npm_config_msvs_version = '2019';
253
process.env.VCINSTALLDIR = 'C:\\Program Files\\Microsoft Visual Studio\\2019\\Community\\VC';
254

255
const gyp = require('node-gyp');
256
const gypInstance = gyp();
257
gypInstance.parseArgv(['configure']); // Picks up environment variables
258
```
259

260
## Error Handling and Diagnostics
261

262
### Python Detection Errors
263

264
```javascript
265
const { PythonFinder } = require('node-gyp/lib/find-python');
266

267
try {
268
  const pythonPath = await PythonFinder.findPython();
269
} catch (error) {
270
  // Common error scenarios
271
  if (error.message.includes('not found')) {
272
    console.error('Python not installed or not in PATH');
273
    console.error('Install Python 3.6+ from https://python.org');
274
  } else if (error.message.includes('version')) {
275
    console.error('Python version too old, need Python 3.6+');
276
  } else if (error.message.includes('permission')) {
277
    console.error('Permission denied accessing Python executable');
278
  }
279
}
280
```
281

282
### Visual Studio Detection Errors
283

284
```javascript
285
const { VisualStudioFinder } = require('node-gyp/lib/find-visualstudio');
286

287
try {
288
  const vsInfo = await VisualStudioFinder.findVisualStudio('16.0.0');
289
} catch (error) {
290
  console.error('Visual Studio detection failed');
291
  
292
  // Error log contains detailed diagnostic information
293
  if (error.finder && error.finder.errorLog) {
294
    console.error('Diagnostic information:');
295
    error.finder.errorLog.forEach(msg => console.error('  -', msg));
296
  }
297
  
298
  console.error('Install Visual Studio with C++ build tools');
299
  console.error('Or install Build Tools for Visual Studio');
300
}
301
```
302

303
### Node.js Directory Detection
304

305
```javascript
306
const findNodeDirectory = require('node-gyp/lib/find-node-directory');
307

308
const nodeDir = findNodeDirectory();
309
if (!nodeDir) {
310
  console.warn('Could not determine Node.js installation directory');
311
  console.warn('You may need to specify --nodedir manually');
312
} else {
313
  console.log('Using Node.js from:', nodeDir);
314
}
315
```
316

317
## Advanced Configuration
318

319
### Custom Toolchain Paths
320

321
```javascript
322
const gyp = require('node-gyp');
323
const gypInstance = gyp();
324

325
// Specify exact toolchain paths
326
gypInstance.opts.python = '/opt/python3.9/bin/python3';
327
gypInstance.opts['msvs-version'] = 'C:\\VS2019\\';  // Custom VS path
328
gypInstance.opts.nodedir = '/opt/node-v16.14.0';
329

330
await gypInstance.commands.configure([]);
331
```
332

333
### Toolchain Validation
334

335
```javascript
336
const { PythonFinder } = require('node-gyp/lib/find-python');
337
const { VisualStudioFinder } = require('node-gyp/lib/find-visualstudio');
338

339
// Validate toolchain before building
340
async function validateToolchain() {
341
  try {
342
    // Check Python
343
    const pythonPath = await PythonFinder.findPython();
344
    console.log('✓ Python found:', pythonPath);
345
    
346
    // Check Visual Studio (Windows only)
347
    if (process.platform === 'win32') {
348
      const vsInfo = await VisualStudioFinder.findVisualStudio(process.version);
349
      console.log('✓ Visual Studio found:', vsInfo.version);
350
    }
351
    
352
    return true;
353
  } catch (error) {
354
    console.error('✗ Toolchain validation failed:', error.message);
355
    return false;
356
  }
357
}
358

359
// Use in build workflow
360
if (await validateToolchain()) {
361
  await gypInstance.commands.build([]);
362
} else {
363
  console.error('Please install required build tools');
364
}
365
```