0
# Framework and Library Management
1

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

4
## Capabilities
5

6
### Framework Management
7

8
Add and remove frameworks with comprehensive linking and embedding options.
9

10
```javascript { .api }
11
/**
12
 * Add framework to project with linking and embedding options
13
 * Handles system frameworks, custom frameworks, and embedded frameworks
14
 * @param {string} path - Framework path (e.g., 'UIKit.framework', 'Custom.framework')
15
 * @param {object} opt - Options including customFramework, link, embed, target, weak
16
 * @returns {object|boolean} File object or false if framework already exists
17
 */
18
addFramework(path, opt);
19

20
/**
21
 * Remove framework from project and clean up all references
22
 * @param {string} path - Framework path to remove
23
 * @param {object} opt - Options including embed flag for cleanup
24
 * @returns {object} Removed framework file object
25
 */
26
removeFramework(path, opt);
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
// Add system framework
33
const uikit = proj.addFramework('UIKit.framework');
34

35
// Add framework with weak linking
36
const optional = proj.addFramework('SomeFramework.framework', {
37
    weak: true
38
});
39

40
// Add custom framework
41
const custom = proj.addFramework('MyCustom.framework', {
42
    customFramework: true
43
});
44

45
// Add embedded custom framework
46
const embedded = proj.addFramework('ThirdParty.framework', {
47
    customFramework: true,
48
    embed: true,
49
    sign: true  // Code sign on copy
50
});
51

52
// Add framework to specific target
53
const targetFramework = proj.addFramework('CoreData.framework', {
54
    target: 'TARGET_UUID_HERE'
55
});
56

57
// Add framework without linking (reference only)
58
const reference = proj.addFramework('Reference.framework', {
59
    link: false
60
});
61

62
// Remove framework
63
proj.removeFramework('OldFramework.framework');
64

65
// Remove embedded framework
66
proj.removeFramework('EmbeddedFramework.framework', {
67
    embed: true
68
});
69
```
70

71
### Static Library Management
72

73
Add and remove static libraries with automatic linking and search path configuration.
74

75
```javascript { .api }
76
/**
77
 * Add static library with automatic linking setup
78
 * Automatically configures library search paths and linking
79
 * @param {string} path - Library path (e.g., 'libsqlite3.a', 'libMyLib.a')
80
 * @param {object} opt - Options including plugin flag, target specification
81
 * @returns {object|boolean} File object or false if library already exists
82
 */
83
addStaticLibrary(path, opt);
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
// Add system static library
90
const sqlite = proj.addStaticLibrary('libsqlite3.a');
91

92
// Add custom static library
93
const customLib = proj.addStaticLibrary('libMyCustomLib.a');
94

95
// Add plugin static library
96
const pluginLib = proj.addStaticLibrary('libPlugin.a', {
97
    plugin: true
98
});
99

100
// Add library to specific target
101
const targetLib = proj.addStaticLibrary('libTargetSpecific.a', {
102
    target: 'TARGET_UUID_HERE'
103
});
104
```
105

106
### Search Path Management
107

108
Manage framework, library, and header search paths for custom frameworks and libraries.
109

110
```javascript { .api }
111
/**
112
 * Add framework search path for custom frameworks
113
 * @param {object} file - File object representing the framework
114
 */
115
addToFrameworkSearchPaths(file);
116

117
/**
118
 * Remove framework search path
119
 * @param {object} file - File object representing the framework
120
 */
121
removeFromFrameworkSearchPaths(file);
122

123
/**
124
 * Add library search path for static libraries
125
 * @param {object|string} file - File object or path string
126
 */
127
addToLibrarySearchPaths(file);
128

129
/**
130
 * Remove library search path
131
 * @param {object} file - File object representing the library
132
 */
133
removeFromLibrarySearchPaths(file);
134

135
/**
136
 * Add header search path for header files
137
 * @param {object|string} file - File object or path string
138
 */
139
addToHeaderSearchPaths(file);
140

141
/**
142
 * Remove header search path
143
 * @param {object} file - File object representing the header location
144
 */
145
removeFromHeaderSearchPaths(file);
146
```
147

148
**Usage Examples:**
149

150
```javascript
151
// Framework search paths are automatically managed when adding custom frameworks
152
const customFramework = proj.addFramework('Custom.framework', {
153
    customFramework: true
154
});
155
// Search path automatically added
156

157
// Manually add library search path
158
proj.addToLibrarySearchPaths('/usr/local/lib');
159

160
// Add header search path for custom headers
161
proj.addToHeaderSearchPaths('$(SRCROOT)/ThirdParty/include');
162

163
// Remove search paths
164
proj.removeFromFrameworkSearchPaths(customFramework);
165
proj.removeFromLibrarySearchPaths('/usr/local/lib');
166
```
167

168
### Linker Flags Management
169

170
Manage additional linker flags for frameworks and libraries.
171

172
```javascript { .api }
173
/**
174
 * Add other linker flag
175
 * Used for additional linking options like -ObjC, -all_load, etc.
176
 * @param {string} flag - Linker flag to add
177
 */
178
addToOtherLinkerFlags(flag);
179

180
/**
181
 * Remove other linker flag
182
 * @param {string} flag - Linker flag to remove
183
 */
184
removeFromOtherLinkerFlags(flag);
185
```
186

187
**Usage Examples:**
188

189
```javascript
190
// Add common linker flags
191
proj.addToOtherLinkerFlags('-ObjC');
192
proj.addToOtherLinkerFlags('-all_load');
193
proj.addToOtherLinkerFlags('-force_load $(BUILT_PRODUCTS_DIR)/libCustom.a');
194

195
// Add framework-specific flags
196
proj.addToOtherLinkerFlags('-framework CoreGraphics');
197
proj.addToOtherLinkerFlags('-weak_framework SomeOptionalFramework');
198

199
// Remove linker flags
200
proj.removeFromOtherLinkerFlags('-all_load');
201
```
202

203
### Framework Options Reference
204

205
```javascript { .api }
206
/**
207
 * Options for framework operations
208
 */
209
interface FrameworkOptions {
210
  /** Target UUID for multi-target projects */
211
  target?: string;
212
  
213
  /** Mark as custom framework (not system framework) */
214
  customFramework?: boolean;
215
  
216
  /** Enable framework linking (default: true) */
217
  link?: boolean;
218
  
219
  /** Embed framework in app bundle */
220
  embed?: boolean;
221
  
222
  /** Enable weak linking for optional frameworks */
223
  weak?: boolean;
224
  
225
  /** Code sign framework when copying */
226
  sign?: boolean;
227
}
228
```
229

230
### Framework Types and Handling
231

232
The package handles different types of frameworks automatically:
233

234
```javascript { .api }
235
/**
236
 * Framework type detection and handling
237
 */
238
interface FrameworkHandling {
239
  /** System frameworks (UIKit.framework, Foundation.framework) */
240
  system: {
241
    sourceTree: 'SDKROOT',
242
    path: 'System/Library/Frameworks/',
243
    searchPaths: false  // No custom search paths needed
244
  };
245
  
246
  /** Custom frameworks (MyFramework.framework) */
247
  custom: {
248
    sourceTree: '"<group>"',
249
    path: 'relative to project',
250
    searchPaths: true,  // Automatically adds search paths
251
    embedding: 'optional'  // Can be embedded in app bundle
252
  };
253
  
254
  /** Embedded frameworks (for app extensions, etc.) */
255
  embedded: {
256
    copyPhase: 'PBXCopyFilesBuildPhase',
257
    destination: 'frameworks',
258
    codeSign: 'optional'  // Can be code signed on copy
259
  };
260
}
261
```
262

263
### Common Framework Patterns
264

265
**System Frameworks:**
266
```javascript
267
// iOS system frameworks
268
proj.addFramework('UIKit.framework');
269
proj.addFramework('Foundation.framework');
270
proj.addFramework('CoreData.framework');
271

272
// Optional system frameworks
273
proj.addFramework('HealthKit.framework', { weak: true });
274
```
275

276
**Custom Frameworks:**
277
```javascript
278
// Local custom framework
279
proj.addFramework('MySDK.framework', {
280
    customFramework: true
281
});
282

283
// Embedded custom framework with code signing
284
proj.addFramework('ThirdPartySDK.framework', {
285
    customFramework: true,
286
    embed: true,
287
    sign: true
288
});
289
```
290

291
**Static Libraries:**
292
```javascript
293
// System libraries
294
proj.addStaticLibrary('libz.a');
295
proj.addStaticLibrary('libsqlite3.a');
296

297
// Custom libraries with search paths
298
proj.addStaticLibrary('libMyLib.a');
299
proj.addToLibrarySearchPaths('$(SRCROOT)/Libraries');
300
```
301

302
**Dynamic Libraries:**
303
```javascript
304
// System dynamic libraries (treated as frameworks)
305
proj.addFramework('libxml2.dylib');
306

307
// Custom dynamic libraries
308
proj.addFramework('libCustom.dylib', {
309
    customFramework: true
310
});
311
```
312

313
### Text-Based Dylib Definition (.tbd) Support
314

315
```javascript
316
// Add .tbd file (iOS 9+ text-based dylib definitions)
317
proj.addFramework('libSystem.tbd');
318

319
// Custom .tbd file
320
proj.addFramework('MyLib.tbd', {
321
    customFramework: true
322
});
323
```
324

325
### Framework Embedding for App Extensions
326

327
```javascript
328
// App extension with embedded framework
329
const framework = proj.addFramework('SharedFramework.framework', {
330
    customFramework: true,
331
    embed: true,
332
    target: 'APP_EXTENSION_TARGET_UUID'
333
});
334

335
// The framework is automatically:
336
// 1. Added to file references
337
// 2. Added to framework group
338
// 3. Added to frameworks build phase
339
// 4. Added to embed frameworks build phase
340
// 5. Configured for code signing if requested
341
```