0
# Build Configuration
1

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

4
## Capabilities
5

6
### Build Property Management
7

8
Add, update, and remove build properties across configurations.
9

10
```javascript { .api }
11
/**
12
 * Add build property to configurations
13
 * Adds property to all configurations or specific build type
14
 * @param {string} prop - Property name (e.g., 'SWIFT_VERSION', 'CODE_SIGN_IDENTITY')
15
 * @param {string|array} value - Property value
16
 * @param {string} buildName - Build configuration name (Debug/Release), optional
17
 */
18
addBuildProperty(prop, value, buildName);
19

20
/**
21
 * Update build property for specific target and configuration
22
 * @param {string} prop - Property name
23
 * @param {string|array} value - Property value
24
 * @param {string} build - Build configuration name (Debug/Release)
25
 * @param {string} targetName - Target name for target-specific settings
26
 */
27
updateBuildProperty(prop, value, build, targetName);
28

29
/**
30
 * Remove build property from configurations
31
 * @param {string} prop - Property name to remove
32
 * @param {string} buildName - Build configuration name, optional
33
 */
34
removeBuildProperty(prop, buildName);
35

36
/**
37
 * Get build property value
38
 * @param {string} prop - Property name
39
 * @param {string} build - Build configuration name, optional
40
 * @param {string} targetName - Target name for target-specific lookup
41
 * @returns {any} Property value or undefined if not found
42
 */
43
getBuildProperty(prop, build, targetName);
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
// Add Swift version to all configurations
50
proj.addBuildProperty('SWIFT_VERSION', '5.0');
51

52
// Add property to specific configuration
53
proj.addBuildProperty('GCC_OPTIMIZATION_LEVEL', '0', 'Debug');
54
proj.addBuildProperty('GCC_OPTIMIZATION_LEVEL', 's', 'Release');
55

56
// Update target-specific property
57
proj.updateBuildProperty('PRODUCT_BUNDLE_IDENTIFIER', 'com.company.myapp', 'Debug', 'MyApp');
58
proj.updateBuildProperty('PRODUCT_BUNDLE_IDENTIFIER', 'com.company.myapp', 'Release', 'MyApp');
59

60
// Add array-based property
61
proj.addBuildProperty('OTHER_SWIFT_FLAGS', ['-DDEBUG', '-enable-testing'], 'Debug');
62

63
// Get property value
64
const swiftVersion = proj.getBuildProperty('SWIFT_VERSION');
65
console.log('Swift version:', swiftVersion);
66

67
// Remove property
68
proj.removeBuildProperty('DEPRECATED_SETTING');
69
```
70

71
### Configuration Management
72

73
Access and manage build configurations directly.
74

75
```javascript { .api }
76
/**
77
 * Get build configuration by name
78
 * @param {string} name - Configuration name (Debug/Release)
79
 * @returns {object} Configuration objects keyed by UUID
80
 */
81
getBuildConfigByName(name);
82

83
/**
84
 * Add new build configuration list
85
 * @param {object[]} configArray - Array of configuration objects
86
 * @param {string} defaultConfig - Default configuration name
87
 * @param {string} comment - Configuration list comment
88
 * @returns {object} Configuration list object with UUID
89
 */
90
addXCConfigurationList(configArray, defaultConfig, comment);
91
```
92

93
**Usage Examples:**
94

95
```javascript
96
// Get Debug configurations
97
const debugConfigs = proj.getBuildConfigByName('Debug');
98
Object.keys(debugConfigs).forEach(uuid => {
99
    const config = debugConfigs[uuid];
100
    console.log('Debug config:', config.name, config.buildSettings);
101
});
102

103
// Create custom configuration
104
const customConfigs = [
105
    {
106
        name: 'Staging',
107
        isa: 'XCBuildConfiguration',
108
        buildSettings: {
109
            'SWIFT_OPTIMIZATION_LEVEL': '-Onone',
110
            'SWIFT_ACTIVE_COMPILATION_CONDITIONS': 'STAGING',
111
            'OTHER_SWIFT_FLAGS': ['-DSTAGING']
112
        }
113
    }
114
];
115

116
const configList = proj.addXCConfigurationList(
117
    customConfigs, 
118
    'Staging', 
119
    'Build configuration list for staging'
120
);
121
```
122

123
### Product Name Management
124

125
Manage product names and bundle identifiers.
126

127
```javascript { .api }
128
/**
129
 * Update product name in build settings
130
 * @param {string} name - New product name
131
 */
132
updateProductName(name);
133

134
/**
135
 * Get product name from build settings
136
 * @returns {string} Current product name
137
 */
138
get productName();
139
```
140

141
**Usage Examples:**
142

143
```javascript
144
// Update product name
145
proj.updateProductName('MyAwesomeApp');
146

147
// Get current product name
148
console.log('Current product name:', proj.productName);
149
```
150

151
### General Build Settings
152

153
Add and remove arbitrary build settings.
154

155
```javascript { .api }
156
/**
157
 * Add build setting to all configurations
158
 * @param {string} buildSetting - Setting name
159
 * @param {any} value - Setting value
160
 */
161
addToBuildSettings(buildSetting, value);
162

163
/**
164
 * Remove build setting from all configurations
165
 * @param {string} buildSetting - Setting name to remove
166
 */
167
removeFromBuildSettings(buildSetting);
168
```
169

170
**Usage Examples:**
171

172
```javascript
173
// Add custom build settings
174
proj.addToBuildSettings('CUSTOM_FLAG', 'MY_VALUE');
175
proj.addToBuildSettings('ENABLE_BITCODE', 'NO');
176
proj.addToBuildSettings('SWIFT_TREAT_WARNINGS_AS_ERRORS', 'YES');
177

178
// Add deployment target
179
proj.addToBuildSettings('IPHONEOS_DEPLOYMENT_TARGET', '13.0');
180

181
// Remove deprecated settings
182
proj.removeFromBuildSettings('ARCHS');
183
proj.removeFromBuildSettings('VALID_ARCHS');
184
```
185

186
### Common Build Settings
187

188
```javascript { .api }
189
/**
190
 * Common build setting properties and their typical values
191
 */
192
const COMMON_BUILD_SETTINGS = {
193
  // Language and compilation
194
  'SWIFT_VERSION': '5.0',
195
  'CLANG_ENABLE_OBJC_ARC': 'YES',
196
  'CLANG_ENABLE_MODULES': 'YES',
197
  
198
  // Deployment
199
  'IPHONEOS_DEPLOYMENT_TARGET': '13.0',
200
  'MACOSX_DEPLOYMENT_TARGET': '10.15',
201
  'WATCHOS_DEPLOYMENT_TARGET': '6.0',
202
  'TVOS_DEPLOYMENT_TARGET': '13.0',
203
  
204
  // Code signing
205
  'CODE_SIGN_IDENTITY': 'iPhone Developer',
206
  'CODE_SIGN_STYLE': 'Automatic',
207
  'DEVELOPMENT_TEAM': 'TEAM_ID_HERE',
208
  
209
  // Bundle and product
210
  'PRODUCT_NAME': '$(TARGET_NAME)',
211
  'PRODUCT_BUNDLE_IDENTIFIER': 'com.company.app',
212
  
213
  // Optimization
214
  'GCC_OPTIMIZATION_LEVEL': {
215
    'Debug': '0',
216
    'Release': 's'
217
  },
218
  'SWIFT_OPTIMIZATION_LEVEL': {
219
    'Debug': '-Onone',
220
    'Release': '-O'
221
  },
222
  
223
  // Debugging
224
  'DEBUG_INFORMATION_FORMAT': {
225
    'Debug': 'dwarf',
226
    'Release': 'dwarf-with-dsym'
227
  },
228
  
229
  // Preprocessor definitions
230
  'GCC_PREPROCESSOR_DEFINITIONS': {
231
    'Debug': ['DEBUG=1', '$(inherited)'],
232
    'Release': ['$(inherited)']
233
  },
234
  
235
  // Swift compilation conditions
236
  'SWIFT_ACTIVE_COMPILATION_CONDITIONS': {
237
    'Debug': 'DEBUG',
238
    'Release': ''
239
  }
240
};
241
```
242

243
### Build Configuration Examples
244

245
**iOS App Configuration:**
246
```javascript
247
// Basic iOS app setup
248
proj.addBuildProperty('IPHONEOS_DEPLOYMENT_TARGET', '13.0');
249
proj.addBuildProperty('TARGETED_DEVICE_FAMILY', '1,2'); // iPhone and iPad
250
proj.addBuildProperty('SWIFT_VERSION', '5.0');
251
proj.addBuildProperty('CODE_SIGN_STYLE', 'Automatic');
252

253
// Debug-specific settings
254
proj.addBuildProperty('SWIFT_ACTIVE_COMPILATION_CONDITIONS', 'DEBUG', 'Debug');
255
proj.addBuildProperty('SWIFT_OPTIMIZATION_LEVEL', '-Onone', 'Debug');
256
proj.addBuildProperty('ONLY_ACTIVE_ARCH', 'YES', 'Debug');
257

258
// Release-specific settings
259
proj.addBuildProperty('SWIFT_OPTIMIZATION_LEVEL', '-O', 'Release');
260
proj.addBuildProperty('VALIDATE_PRODUCT', 'YES', 'Release');
261
```
262

263
**Framework Configuration:**
264
```javascript
265
// Framework-specific settings
266
proj.addBuildProperty('DEFINES_MODULE', 'YES');
267
proj.addBuildProperty('DYLIB_COMPATIBILITY_VERSION', '1');
268
proj.addBuildProperty('DYLIB_CURRENT_VERSION', '1');
269
proj.addBuildProperty('DYLIB_INSTALL_NAME_BASE', '@rpath');
270
proj.addBuildProperty('INSTALL_PATH', '$(LOCAL_LIBRARY_DIR)/Frameworks');
271
proj.addBuildProperty('LD_RUNPATH_SEARCH_PATHS', [
272
    '$(inherited)',
273
    '@executable_path/Frameworks',
274
    '@loader_path/Frameworks'
275
]);
276
proj.addBuildProperty('SKIP_INSTALL', 'YES');
277
proj.addBuildProperty('VERSIONING_SYSTEM', 'apple-generic');
278
proj.addBuildProperty('VERSION_INFO_PREFIX', '');
279
```
280

281
**App Extension Configuration:**
282
```javascript
283
// App extension settings
284
proj.addBuildProperty('APPLICATION_EXTENSION_API_ONLY', 'YES');
285
proj.addBuildProperty('SKIP_INSTALL', 'YES');
286
proj.addBuildProperty('LD_RUNPATH_SEARCH_PATHS', [
287
    '$(inherited)',
288
    '@executable_path/Frameworks',
289
    '@executable_path/../../Frameworks'
290
]);
291

292
// Extension-specific bundle identifier
293
proj.updateBuildProperty(
294
    'PRODUCT_BUNDLE_IDENTIFIER', 
295
    'com.company.myapp.extension', 
296
    null, 
297
    'MyExtension'
298
);
299
```
300

301
**Swift Package Manager Integration:**
302
```javascript
303
// Swift Package Manager settings
304
proj.addBuildProperty('SWIFT_PACKAGE_MANAGER_ENABLED', 'YES');
305
proj.addBuildProperty('SWIFT_PACKAGE_MANAGER_TARGET_NAME', '$(TARGET_NAME)');
306
proj.addBuildProperty('PACKAGE_RESOURCE_BUNDLE_NAME', '$(PRODUCT_NAME)');
307
```
308

309
**Testing Configuration:**
310
```javascript
311
// Test bundle settings
312
proj.updateBuildProperty('BUNDLE_LOADER', '$(TEST_HOST)', null, 'MyAppTests');
313
proj.updateBuildProperty('TEST_HOST', '$(BUILT_PRODUCTS_DIR)/MyApp.app/MyApp', null, 'MyAppTests');
314
proj.updateBuildProperty('LD_RUNPATH_SEARCH_PATHS', [
315
    '$(inherited)',
316
    '@executable_path/Frameworks',
317
    '@loader_path/Frameworks'
318
], null, 'MyAppTests');
319
```
320

321
**Multi-Configuration Setup:**
322
```javascript
323
// Configuration-specific compiler flags
324
const debugFlags = ['-DDEBUG', '-DTESTING', '-enable-testing'];
325
const releaseFlags = ['-DRELEASE', '-DNDEBUG'];
326

327
proj.addBuildProperty('OTHER_SWIFT_FLAGS', debugFlags, 'Debug');
328
proj.addBuildProperty('OTHER_SWIFT_FLAGS', releaseFlags, 'Release');
329

330
// Environment-specific settings
331
proj.addBuildProperty('API_BASE_URL', '"https://api-dev.company.com"', 'Debug');
332
proj.addBuildProperty('API_BASE_URL', '"https://api.company.com"', 'Release');
333
```
334

335
### Configuration Structure Types
336

337
```javascript { .api }
338
/**
339
 * Build configuration structure
340
 */
341
interface XCBuildConfiguration {
342
  /** Configuration type */
343
  isa: 'XCBuildConfiguration';
344
  
345
  /** Configuration name (Debug/Release) */
346
  name: string;
347
  
348
  /** Build settings dictionary */
349
  buildSettings: BuildSettings;
350
}
351

352
interface BuildSettings {
353
  [key: string]: string | string[] | number | boolean;
354
}
355

356
interface XCConfigurationList {
357
  /** Configuration list type */
358
  isa: 'XCConfigurationList';
359
  
360
  /** Array of configuration references */
361
  buildConfigurations: ConfigurationReference[];
362
  
363
  /** Default configuration visibility */
364
  defaultConfigurationIsVisible: number;
365
  
366
  /** Default configuration name */
367
  defaultConfigurationName: string;
368
}
369

370
interface ConfigurationReference {
371
  /** Configuration UUID */
372
  value: string;
373
  
374
  /** Configuration name comment */
375
  comment: string;
376
}
377
```