tessl/npm-xcode

Parser utility for xcodeproj/project.pbxproj files that allows editing and writing back Xcode project files

Overview

Eval results

Files

Build Configuration

Name: tessl/npm-xcode
Author: tessl

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

Capabilities

Build Property Management

Add, update, and remove build properties across configurations.

/**
 * Add build property to configurations
 * Adds property to all configurations or specific build type
 * @param {string} prop - Property name (e.g., 'SWIFT_VERSION', 'CODE_SIGN_IDENTITY')
 * @param {string|array} value - Property value
 * @param {string} buildName - Build configuration name (Debug/Release), optional
 */
addBuildProperty(prop, value, buildName);

/**
 * Update build property for specific target and configuration
 * @param {string} prop - Property name
 * @param {string|array} value - Property value
 * @param {string} build - Build configuration name (Debug/Release)
 * @param {string} targetName - Target name for target-specific settings
 */
updateBuildProperty(prop, value, build, targetName);

/**
 * Remove build property from configurations
 * @param {string} prop - Property name to remove
 * @param {string} buildName - Build configuration name, optional
 */
removeBuildProperty(prop, buildName);

/**
 * Get build property value
 * @param {string} prop - Property name
 * @param {string} build - Build configuration name, optional
 * @param {string} targetName - Target name for target-specific lookup
 * @returns {any} Property value or undefined if not found
 */
getBuildProperty(prop, build, targetName);

Usage Examples:

// Add Swift version to all configurations
proj.addBuildProperty('SWIFT_VERSION', '5.0');

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

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

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

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

// Remove property
proj.removeBuildProperty('DEPRECATED_SETTING');

Configuration Management

Access and manage build configurations directly.

/**
 * Get build configuration by name
 * @param {string} name - Configuration name (Debug/Release)
 * @returns {object} Configuration objects keyed by UUID
 */
getBuildConfigByName(name);

/**
 * Add new build configuration list
 * @param {object[]} configArray - Array of configuration objects
 * @param {string} defaultConfig - Default configuration name
 * @param {string} comment - Configuration list comment
 * @returns {object} Configuration list object with UUID
 */
addXCConfigurationList(configArray, defaultConfig, comment);

Usage Examples:

// Get Debug configurations
const debugConfigs = proj.getBuildConfigByName('Debug');
Object.keys(debugConfigs).forEach(uuid => {
    const config = debugConfigs[uuid];
    console.log('Debug config:', config.name, config.buildSettings);
});

// Create custom configuration
const customConfigs = [
    {
        name: 'Staging',
        isa: 'XCBuildConfiguration',
        buildSettings: {
            'SWIFT_OPTIMIZATION_LEVEL': '-Onone',
            'SWIFT_ACTIVE_COMPILATION_CONDITIONS': 'STAGING',
            'OTHER_SWIFT_FLAGS': ['-DSTAGING']
        }
    }
];

const configList = proj.addXCConfigurationList(
    customConfigs, 
    'Staging', 
    'Build configuration list for staging'
);

Product Name Management

Manage product names and bundle identifiers.

/**
 * Update product name in build settings
 * @param {string} name - New product name
 */
updateProductName(name);

/**
 * Get product name from build settings
 * @returns {string} Current product name
 */
get productName();

Usage Examples:

// Update product name
proj.updateProductName('MyAwesomeApp');

// Get current product name
console.log('Current product name:', proj.productName);

General Build Settings

Add and remove arbitrary build settings.

/**
 * Add build setting to all configurations
 * @param {string} buildSetting - Setting name
 * @param {any} value - Setting value
 */
addToBuildSettings(buildSetting, value);

/**
 * Remove build setting from all configurations
 * @param {string} buildSetting - Setting name to remove
 */
removeFromBuildSettings(buildSetting);

Usage Examples:

// Add custom build settings
proj.addToBuildSettings('CUSTOM_FLAG', 'MY_VALUE');
proj.addToBuildSettings('ENABLE_BITCODE', 'NO');
proj.addToBuildSettings('SWIFT_TREAT_WARNINGS_AS_ERRORS', 'YES');

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

// Remove deprecated settings
proj.removeFromBuildSettings('ARCHS');
proj.removeFromBuildSettings('VALID_ARCHS');

Common Build Settings

/**
 * Common build setting properties and their typical values
 */
const COMMON_BUILD_SETTINGS = {
  // Language and compilation
  'SWIFT_VERSION': '5.0',
  'CLANG_ENABLE_OBJC_ARC': 'YES',
  'CLANG_ENABLE_MODULES': 'YES',
  
  // Deployment
  'IPHONEOS_DEPLOYMENT_TARGET': '13.0',
  'MACOSX_DEPLOYMENT_TARGET': '10.15',
  'WATCHOS_DEPLOYMENT_TARGET': '6.0',
  'TVOS_DEPLOYMENT_TARGET': '13.0',
  
  // Code signing
  'CODE_SIGN_IDENTITY': 'iPhone Developer',
  'CODE_SIGN_STYLE': 'Automatic',
  'DEVELOPMENT_TEAM': 'TEAM_ID_HERE',
  
  // Bundle and product
  'PRODUCT_NAME': '$(TARGET_NAME)',
  'PRODUCT_BUNDLE_IDENTIFIER': 'com.company.app',
  
  // Optimization
  'GCC_OPTIMIZATION_LEVEL': {
    'Debug': '0',
    'Release': 's'
  },
  'SWIFT_OPTIMIZATION_LEVEL': {
    'Debug': '-Onone',
    'Release': '-O'
  },
  
  // Debugging
  'DEBUG_INFORMATION_FORMAT': {
    'Debug': 'dwarf',
    'Release': 'dwarf-with-dsym'
  },
  
  // Preprocessor definitions
  'GCC_PREPROCESSOR_DEFINITIONS': {
    'Debug': ['DEBUG=1', '$(inherited)'],
    'Release': ['$(inherited)']
  },
  
  // Swift compilation conditions
  'SWIFT_ACTIVE_COMPILATION_CONDITIONS': {
    'Debug': 'DEBUG',
    'Release': ''
  }
};

Build Configuration Examples

iOS App Configuration:

// Basic iOS app setup
proj.addBuildProperty('IPHONEOS_DEPLOYMENT_TARGET', '13.0');
proj.addBuildProperty('TARGETED_DEVICE_FAMILY', '1,2'); // iPhone and iPad
proj.addBuildProperty('SWIFT_VERSION', '5.0');
proj.addBuildProperty('CODE_SIGN_STYLE', 'Automatic');

// Debug-specific settings
proj.addBuildProperty('SWIFT_ACTIVE_COMPILATION_CONDITIONS', 'DEBUG', 'Debug');
proj.addBuildProperty('SWIFT_OPTIMIZATION_LEVEL', '-Onone', 'Debug');
proj.addBuildProperty('ONLY_ACTIVE_ARCH', 'YES', 'Debug');

// Release-specific settings
proj.addBuildProperty('SWIFT_OPTIMIZATION_LEVEL', '-O', 'Release');
proj.addBuildProperty('VALIDATE_PRODUCT', 'YES', 'Release');

Framework Configuration:

// Framework-specific settings
proj.addBuildProperty('DEFINES_MODULE', 'YES');
proj.addBuildProperty('DYLIB_COMPATIBILITY_VERSION', '1');
proj.addBuildProperty('DYLIB_CURRENT_VERSION', '1');
proj.addBuildProperty('DYLIB_INSTALL_NAME_BASE', '@rpath');
proj.addBuildProperty('INSTALL_PATH', '$(LOCAL_LIBRARY_DIR)/Frameworks');
proj.addBuildProperty('LD_RUNPATH_SEARCH_PATHS', [
    '$(inherited)',
    '@executable_path/Frameworks',
    '@loader_path/Frameworks'
]);
proj.addBuildProperty('SKIP_INSTALL', 'YES');
proj.addBuildProperty('VERSIONING_SYSTEM', 'apple-generic');
proj.addBuildProperty('VERSION_INFO_PREFIX', '');

App Extension Configuration:

// App extension settings
proj.addBuildProperty('APPLICATION_EXTENSION_API_ONLY', 'YES');
proj.addBuildProperty('SKIP_INSTALL', 'YES');
proj.addBuildProperty('LD_RUNPATH_SEARCH_PATHS', [
    '$(inherited)',
    '@executable_path/Frameworks',
    '@executable_path/../../Frameworks'
]);

// Extension-specific bundle identifier
proj.updateBuildProperty(
    'PRODUCT_BUNDLE_IDENTIFIER', 
    'com.company.myapp.extension', 
    null, 
    'MyExtension'
);

Swift Package Manager Integration:

// Swift Package Manager settings
proj.addBuildProperty('SWIFT_PACKAGE_MANAGER_ENABLED', 'YES');
proj.addBuildProperty('SWIFT_PACKAGE_MANAGER_TARGET_NAME', '$(TARGET_NAME)');
proj.addBuildProperty('PACKAGE_RESOURCE_BUNDLE_NAME', '$(PRODUCT_NAME)');

Testing Configuration:

// Test bundle settings
proj.updateBuildProperty('BUNDLE_LOADER', '$(TEST_HOST)', null, 'MyAppTests');
proj.updateBuildProperty('TEST_HOST', '$(BUILT_PRODUCTS_DIR)/MyApp.app/MyApp', null, 'MyAppTests');
proj.updateBuildProperty('LD_RUNPATH_SEARCH_PATHS', [
    '$(inherited)',
    '@executable_path/Frameworks',
    '@loader_path/Frameworks'
], null, 'MyAppTests');

Multi-Configuration Setup:

// Configuration-specific compiler flags
const debugFlags = ['-DDEBUG', '-DTESTING', '-enable-testing'];
const releaseFlags = ['-DRELEASE', '-DNDEBUG'];

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

// Environment-specific settings
proj.addBuildProperty('API_BASE_URL', '"https://api-dev.company.com"', 'Debug');
proj.addBuildProperty('API_BASE_URL', '"https://api.company.com"', 'Release');

Configuration Structure Types

/**
 * Build configuration structure
 */
interface XCBuildConfiguration {
  /** Configuration type */
  isa: 'XCBuildConfiguration';
  
  /** Configuration name (Debug/Release) */
  name: string;
  
  /** Build settings dictionary */
  buildSettings: BuildSettings;
}

interface BuildSettings {
  [key: string]: string | string[] | number | boolean;
}

interface XCConfigurationList {
  /** Configuration list type */
  isa: 'XCConfigurationList';
  
  /** Array of configuration references */
  buildConfigurations: ConfigurationReference[];
  
  /** Default configuration visibility */
  defaultConfigurationIsVisible: number;
  
  /** Default configuration name */
  defaultConfigurationName: string;
}

interface ConfigurationReference {
  /** Configuration UUID */
  value: string;
  
  /** Configuration name comment */
  comment: string;
}

Install with Tessl CLI