0
# Node-gyp
1

2
Node-gyp is a cross-platform command-line tool for compiling native addon modules for Node.js. It contains a vendored copy of gyp-next and enables developers to build C/C++ native addons that interface with Node.js applications, automatically downloading necessary development files and headers for different Node.js versions.
3

4
## Package Information
5

6
- **Package Name**: node-gyp
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g node-gyp`
10

11
## Core Imports
12

13
```javascript
14
const gyp = require('node-gyp');
15
```
16

17
For creating a new gyp instance:
18

19
```javascript
20
const gypInstance = gyp();
21
```
22

23
For accessing the Gyp class directly:
24

25
```javascript
26
const { Gyp } = require('node-gyp');
27
```
28

29
## Basic Usage
30

31
```javascript
32
const gyp = require('node-gyp');
33

34
// Create a new gyp instance
35
const gypInstance = gyp();
36

37
// Parse command-line arguments (modifies gypInstance state)
38
gypInstance.parseArgv(['node-gyp', 'configure', '--debug']);
39

40
// Access parsed options
41
console.log(gypInstance.opts.debug); // true
42
console.log(gypInstance.todo); // [{ name: 'configure', args: [] }]
43

44
// Execute commands programmatically (returns promises)
45
try {
46
  await gypInstance.commands.configure([]);
47
  await gypInstance.commands.build([]);
48
} catch (error) {
49
  console.error('Build failed:', error);
50
}
51
```
52

53
## Architecture
54

55
Node-gyp is built around several key components:
56

57
- **Gyp Class**: Main orchestrator that handles command parsing, execution, and configuration
58
- **Command System**: Modular command handlers for build operations (build, clean, configure, etc.)
59
- **Platform Detection**: Cross-platform toolchain discovery for Visual Studio, Python, and build tools
60
- **Development File Management**: Downloads and manages Node.js headers and libraries for different versions
61
- **Logging System**: Configurable multi-level logging with color support and prefixes
62

63
## Capabilities
64

65
### Core Build System
66

67
Primary build operations for compiling native Node.js addons with cross-platform support.
68

69
```javascript { .api }
70
// Main factory function
71
function gyp(): Gyp;
72

73
// Gyp class with command execution
74
class Gyp extends EventEmitter {
75
  parseArgv(argv: string[]): void;
76
  spawn(command: string, args: string[], opts?: object): ChildProcess;
77
  usage(): string;
78
}
79
```
80

81
[Core Build System](./core-build-system.md)
82

83
### Build Commands
84

85
Individual build operations that can be executed independently or as part of workflows.
86

87
```javascript { .api }
88
// Build command functions
89
async function build(gyp: Gyp, argv: string[]): Promise<void>;
90
async function clean(gyp: Gyp, argv: string[]): Promise<void>;
91
async function configure(gyp: Gyp, argv: string[]): Promise<void>;
92
async function rebuild(gyp: Gyp, argv: string[]): Promise<void>;
93
```
94

95
[Build Commands](./build-commands.md)
96

97
### Development File Management
98

99
Node.js development file installation and management for different Node.js versions.
100

101
```javascript { .api }
102
// Development file management
103
async function install(gyp: Gyp, argv: string[]): Promise<void>;
104
async function list(gyp: Gyp, argv: string[]): Promise<string[]>;
105
async function remove(gyp: Gyp, argv: string[]): Promise<void>;
106
```
107

108
[Development File Management](./dev-file-management.md)
109

110
### Platform-Specific Toolchain Discovery
111

112
Automated discovery and validation of build toolchains across different platforms.
113

114
```javascript { .api }
115
// Platform detection classes
116
class PythonFinder {
117
  static findPython(...args: any[]): Promise<string>;
118
}
119

120
class VisualStudioFinder {
121
  static findVisualStudio(...args: any[]): Promise<object>;
122
}
123

124
function findNodeDirectory(scriptLocation?: string, processObj?: object): string;
125
```
126

127
[Platform Toolchain Discovery](./platform-toolchain.md)
128

129
### Utility Functions
130

131
Core utilities for file operations, registry access, and system integration.
132

133
```javascript { .api }
134
// Utility functions
135
async function download(gyp: Gyp, url: string): Promise<Response>;
136
async function execFile(...args: any[]): Promise<[Error?, string?, string?]>;
137
function findAccessibleSync(logprefix: string, dir: string, candidates: string[]): string | undefined;
138
function withPrefix(prefix: string): object;
139
function processRelease(argv: string[], gyp: Gyp, defaultVersion: string, defaultRelease: object): object;
140
```
141

142
[Utility Functions](./utilities.md)
143

144
## Types
145

146
```javascript { .api }
147
interface GypOptions {
148
  help?: boolean;
149
  arch?: string;
150
  cafile?: string;
151
  debug?: boolean;
152
  directory?: string;
153
  make?: string;
154
  'msvs-version'?: string;
155
  ensure?: boolean;
156
  solution?: string;
157
  proxy?: string;
158
  noproxy?: string;
159
  devdir?: string;
160
  nodedir?: string;
161
  loglevel?: string;
162
  python?: string;
163
  'dist-url'?: string;
164
  tarball?: string;
165
  jobs?: string;
166
  thin?: string;
167
  'force-process-config'?: boolean;
168
}
169

170
interface GypShorthands {
171
  release: '--no-debug';
172
  C: '--directory';
173
  debug: '--debug';
174
  j: '--jobs';
175
  silly: '--loglevel=silly';
176
  verbose: '--loglevel=verbose';
177
  silent: '--loglevel=silent';
178
}
179

180
interface CommandObject {
181
  name: string;
182
  args: string[];
183
}
184

185
class Gyp extends EventEmitter {
186
  package: object;
187
  version: string;
188
  devDir: string;
189
  commands: { [key: string]: (argv: string[]) => Promise<any> };
190
  configDefs: object;
191
  shorthands: GypShorthands;
192
  aliases: { ls: 'list'; rm: 'remove' };
193
  opts: GypOptions;
194
  argv: string[];
195
  todo: CommandObject[];
196
}
197
```