0
# xcode (cordova-node-xcode)
1

2
xcode is a comprehensive parser utility for xcodeproj/project.pbxproj files that enables programmatic manipulation of Xcode project configurations. It provides both asynchronous and synchronous parsing capabilities, extensive file management, build configuration control, and complete project structure modification for iOS, macOS, and other Apple platform development.
3

4
## Package Information
5

6
- **Package Name**: xcode
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install xcode`
10

11
## Core Imports
12

13
```javascript
14
const xcode = require('xcode');
15
```
16

17
For ES modules:
18

19
```javascript
20
import xcode from 'xcode';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const xcode = require('xcode');
27
const fs = require('fs');
28

29
// Create project instance
30
const projectPath = 'myproject.xcodeproj/project.pbxproj';
31
const myProj = xcode.project(projectPath);
32

33
// Parse asynchronously
34
myProj.parse(function (err) {
35
    if (err) throw err;
36
    
37
    // Add files
38
    myProj.addHeaderFile('src/MyHeader.h');
39
    myProj.addSourceFile('src/MySource.m');
40
    myProj.addFramework('MyFramework.framework');
41
    
42
    // Write back to file
43
    fs.writeFileSync(projectPath, myProj.writeSync());
44
    console.log('Project updated successfully');
45
});
46

47
// Or parse synchronously
48
myProj.parseSync();
49
myProj.addResourceFile('resources/icon.png');
50
fs.writeFileSync(projectPath, myProj.writeSync());
51
```
52

53
## Architecture
54

55
The xcode package is built around several key components:
56

57
- **Project Parser**: Core parsing engine using PEG.js grammar for pbxproj file format
58
- **pbxProject Class**: Main API class providing all project manipulation methods
59
- **pbxFile Helper**: File metadata management with automatic type detection and grouping
60
- **pbxWriter**: Serialization engine for writing project data back to pbxproj format
61
- **Build System Integration**: Direct manipulation of Xcode build phases, targets, and configurations
62
- **UUID Management**: Automatic generation and tracking of Xcode's 24-character UUID system
63

64
## Main Entry Point
65

66
### Project Constructor
67

68
Creates a new project instance for manipulating Xcode project files.
69

70
```javascript { .api }
71
/**
72
 * Create a new project instance
73
 * @param {string} filename - Path to the .pbxproj file
74
 * @returns {pbxProject} Project instance
75
 */
76
function project(filename);
77
```
78

79
## Capabilities
80

81
### Project Parsing and Writing
82

83
Core functionality for loading and saving Xcode project files with support for both asynchronous and synchronous operations.
84

85
```javascript { .api }
86
/**
87
 * Parse project file asynchronously using worker process
88
 * @param {function} callback - Callback function(err, project)
89
 */
90
parse(callback);
91

92
/**
93
 * Parse project file synchronously
94
 * @returns {pbxProject} Self for chaining
95
 */
96
parseSync();
97

98
/**
99
 * Write project data to string format
100
 * @param {object} options - Formatting options
101
 * @returns {string} Serialized project data
102
 */
103
writeSync(options);
104
```
105

106
[Project Parsing and Writing](./project-parsing.md)
107

108
### File Management
109

110
Comprehensive file management system supporting all Xcode file types including source files, headers, resources, plugin files, Core Data models, frameworks, and static libraries with automatic build phase integration.
111

112
```javascript { .api }
113
/**
114
 * Add source file to project with build phase integration
115
 * @param {string} path - File path
116
 * @param {object} opt - Options including target, weak linking, compiler flags
117
 * @param {string} group - Group key for organization
118
 * @returns {object|boolean} File object or false if exists
119
 */
120
addSourceFile(path, opt, group);
121

122
/**
123
 * Add header file to project
124
 * @param {string} path - File path
125
 * @param {object} opt - Options object
126
 * @param {string} group - Group key
127
 * @returns {object|null} File object or null if exists
128
 */
129
addHeaderFile(path, opt, group);
130

131
/**
132
 * Add resource file with automatic build phase integration
133
 * @param {string} path - File path
134
 * @param {object} opt - Options including plugin flag, target, variant group
135
 * @param {string} group - Group key
136
 * @returns {object|boolean} File object or false if exists
137
 */
138
addResourceFile(path, opt, group);
139

140
/**
141
 * Add plugin file with special Cordova/PhoneGap handling
142
 * @param {string} path - File path relative to project
143
 * @param {object} opt - Options object including target specification
144
 * @returns {object|null} File object or null if exists
145
 */
146
addPluginFile(path, opt);
147

148
/**
149
 * Add Core Data model document to project
150
 * @param {string} filePath - Path to .xcdatamodeld bundle
151
 * @param {string} group - Group key, defaults to 'Resources'
152
 * @param {object} opt - Options object
153
 * @returns {object|null} File object or null if exists
154
 */
155
addDataModelDocument(filePath, group, opt);
156
```
157

158
[File Management](./file-management.md)
159

160
### Framework and Library Management
161

162
Framework and static library management with support for system frameworks, custom frameworks, embedded frameworks, weak linking, and automatic search path configuration.
163

164
```javascript { .api }
165
/**
166
 * Add framework to project with linking and embedding options
167
 * @param {string} path - Framework path
168
 * @param {object} opt - Options including customFramework, link, embed, target
169
 * @returns {object|boolean} File object or false if exists
170
 */
171
addFramework(path, opt);
172

173
/**
174
 * Add static library with automatic linking setup
175
 * @param {string} path - Library path
176
 * @param {object} opt - Options including plugin flag, target
177
 * @returns {object|boolean} File object or false if exists
178
 */
179
addStaticLibrary(path, opt);
180
```
181

182
[Framework and Library Management](./frameworks-libraries.md)
183

184
### Group Management
185

186
Project organization system for managing file groups, variant groups, and hierarchical project structure with support for custom groups, localization, and low-level PBX object manipulation.
187

188
```javascript { .api }
189
/**
190
 * Create new PBXGroup with files
191
 * @param {string[]} filePathsArray - Array of file paths to include
192
 * @param {string} name - Group name
193
 * @param {string} path - Group path
194
 * @param {string} sourceTree - Source tree type
195
 * @returns {object} Group object with UUID
196
 */
197
addPbxGroup(filePathsArray, name, path, sourceTree);
198

199
/**
200
 * Find group by name
201
 * @param {string} name - Group name to search for
202
 * @returns {object|null} Group object or null if not found
203
 */
204
pbxGroupByName(name);
205

206
/**
207
 * Add file to any PBXGroup type with generic handling
208
 * @param {object|string} file - File object or group key
209
 * @param {string} groupKey - Target group UUID
210
 * @param {string} groupType - PBX group type
211
 */  
212
addToPbxGroupType(file, groupKey, groupType);
213

214
/**
215
 * Get any PBX object section for direct manipulation
216
 * @param {string} name - Section name (PBXGroup, PBXFileReference, etc.)
217
 * @returns {object} Section object containing all items of that type
218
 */
219
getPBXObject(name);
220
```
221

222
[Group Management](./group-management.md)
223

224
### Target Management
225

226
Build target management including creating new targets, managing target dependencies, and configuring target-specific build settings for iOS, macOS, watchOS, and extension targets.
227

228
```javascript { .api }
229
/**
230
 * Add new build target to project
231
 * @param {string} name - Target name
232
 * @param {string} type - Target type (application, app_extension, etc.)
233
 * @param {string} subfolder - Target subfolder
234
 * @param {string} bundleId - Bundle identifier
235
 * @returns {object} Target object with UUID
236
 */
237
addTarget(name, type, subfolder, bundleId);
238

239
/**
240
 * Add target dependency relationship
241
 * @param {string} target - Target UUID
242
 * @param {string[]} dependencyTargets - Array of dependency target UUIDs
243
 * @returns {object} Target object
244
 */
245
addTargetDependency(target, dependencyTargets);
246
```
247

248
[Target Management](./target-management.md)
249

250
### Build Configuration
251

252
Build settings and configuration management with support for Debug/Release configurations, custom build settings, search paths, linker flags, and target-specific configurations.
253

254
```javascript { .api }
255
/**
256
 * Add build property to configurations
257
 * @param {string} prop - Property name
258
 * @param {string|array} value - Property value
259
 * @param {string} buildName - Build configuration name (Debug/Release)
260
 */
261
addBuildProperty(prop, value, buildName);
262

263
/**
264
 * Update build property for specific target
265
 * @param {string} prop - Property name
266
 * @param {string|array} value - Property value
267
 * @param {string} build - Build configuration name
268
 * @param {string} targetName - Target name
269
 */
270
updateBuildProperty(prop, value, build, targetName);
271
```
272

273
[Build Configuration](./build-configuration.md)
274

275
### Build Phases
276

277
Build phase management for controlling compilation, resource copying, framework linking, and custom script execution with support for all Xcode build phase types.
278

279
```javascript { .api }
280
/**
281
 * Add custom build phase to target
282
 * @param {string[]} filePathsArray - Files to include in build phase
283
 * @param {string} buildPhaseType - Build phase type
284
 * @param {string} comment - Build phase name/comment
285
 * @param {string} target - Target UUID
286
 * @param {object|string} options - Build phase options or folder type
287
 * @param {string} subfolderPath - Subfolder path for copy phases
288
 * @returns {object} Build phase object with UUID
289
 */
290
addBuildPhase(filePathsArray, buildPhaseType, comment, target, options, subfolderPath);
291
```
292

293
[Build Phases](./build-phases.md)
294

295
### Utility Methods
296

297
Core utility functions for project management including UUID generation and project introspection.
298

299
```javascript { .api }
300
/**
301
 * Generate unique 24-character UUID for Xcode objects
302
 * Ensures uniqueness by checking against existing UUIDs in project
303
 * @returns {string} Unique 24-character uppercase hexadecimal UUID
304
 */
305
generateUuid();
306

307
/**
308
 * Get all UUIDs currently used in the project
309
 * Useful for debugging and ensuring UUID uniqueness
310
 * @returns {string[]} Array of all UUIDs in project sections
311
 */
312
allUuids();
313
```
314

315
## Types
316

317
### Core Types
318

319
```javascript { .api }
320
/**
321
 * Main project class representing an Xcode project
322
 */
323
class pbxProject {
324
  constructor(filename: string);
325
  
326
  /** Parsed project data structure */
327
  hash: object;
328
  
329
  /** Absolute path to project file */
330
  filepath: string;
331
  
332
  /** Product name from build settings */
333
  get productName(): string;
334
}
335

336
/**
337
 * File reference object with metadata
338
 */
339
class pbxFile {
340
  constructor(filepath: string, opt?: object);
341
  
342
  /** File basename */
343
  basename: string;
344
  
345
  /** Xcode file type */
346
  lastKnownFileType: string;
347
  
348
  /** Default group for file type */
349
  group: string;
350
  
351
  /** File path relative to project */
352
  path: string;
353
  
354
  /** Text encoding for text files */
355
  fileEncoding?: number;
356
  
357
  /** Source tree type */
358
  sourceTree: string;
359
  
360
  /** Include in index flag */
361
  includeInIndex: number;
362
  
363
  /** Build settings (weak linking, compiler flags, etc.) */
364
  settings?: object;
365
}
366
```
367

368
### File Options
369

370
```javascript { .api }
371
/**
372
 * Options for file operations
373
 */
374
interface FileOptions {
375
  /** Target UUID for multi-target projects */
376
  target?: string;
377
  
378
  /** Enable weak linking for frameworks */
379
  weak?: boolean;
380
  
381
  /** Custom compiler flags */
382
  compilerFlags?: string;
383
  
384
  /** Custom framework flag */
385
  customFramework?: boolean;
386
  
387
  /** Embed framework flag */
388
  embed?: boolean;
389
  
390
  /** Code sign on copy flag */
391
  sign?: boolean;
392
  
393
  /** Plugin file flag */
394
  plugin?: boolean;
395
  
396
  /** Explicit file type override */
397
  explicitFileType?: string;
398
  
399
  /** Last known file type override */
400
  lastKnownFileType?: string;
401
  
402
  /** Source tree override */
403
  sourceTree?: string;
404
  
405
  /** Default encoding override */
406
  defaultEncoding?: number;
407
}
408
```
409

410
### Target Types
411

412
```javascript { .api }
413
/**
414
 * Supported target types for addTarget
415
 */
416
type TargetType = 
417
  | 'application'
418
  | 'app_extension'
419
  | 'bundle'
420
  | 'command_line_tool'
421
  | 'dynamic_library'
422
  | 'framework'
423
  | 'static_library'
424
  | 'unit_test_bundle'
425
  | 'watch_app'
426
  | 'watch2_app'
427
  | 'watch_extension'
428
  | 'watch2_extension';
429
```
430

431
### Build Phase Types
432

433
```javascript { .api }
434
/**
435
 * Supported build phase types
436
 */
437
type BuildPhaseType =
438
  | 'PBXSourcesBuildPhase'
439
  | 'PBXResourcesBuildPhase'
440
  | 'PBXFrameworksBuildPhase'
441
  | 'PBXCopyFilesBuildPhase'
442
  | 'PBXShellScriptBuildPhase';
443
```