Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


An API for manipulating Xcode project files.


Adding Source Files to a Project

XCProject* project = [[XCProject alloc] initWithFilePath:@"MyProject.xcodeproj"];
XCGroup* group = [project groupWithPathFromRoot:@"Main"];
XCClassDefinition* classDefinition = [[XCClassDefinition alloc] initWithName:@"MyNewClass"];
[classDefinition setHeader:@"<some-header-text>"];
[classDefinition setSource:@"<some-impl-text>"];

[group addClass:classDefinition];
[project save];

Duplicating Targets

It will be added to project as well.

XCTarget* target = [project targetWithName:@"SomeTarget"];
XCTarget* duplicated = [target duplicateWithTargetName:@"DuplicatedTarget" productName:@"NewProduct"];

Specifying Source File Belongs to Target

XCSourceFile* sourceFile = [project fileWithName:@"MyNewClass.m"];
XCTarget* examples = [project targetWithName:@"Examples"];
[examples addMember:sourceFile];
[project save];

Adding a Xib File

This time, we'll use a convenience method on XCGroup to specify the targets at the same time:

XCXibDefinition* xibDefinition = [[XCXibDefinition alloc] initWithName:@"MyXibFile" content:@"<xibXml>"];
[group addXib:xibDefinition toTargets:[project targets]];
[project save];

Adding a Framework

XCFrameworkDefinition* frameworkDefinition =
    [[XCFrameworkDefinition alloc] initWithFilePath:@"<framework path>" copyToDestination:NO];
[group addFramework:frameworkDefinition toTargets:[project targets]];
[project save];

Setting copyToDestination to YES, will cause the framework to be first copied to the group's directory within the project, and subsequently linked from there.

Adding an Image Resource

XCSourceFileDefinition* sourceFileDefinition = [[XCSourceFileDefinition alloc]
    initWithName:@"MyImageFile.png" data:[NSData dataWithContentsOfFile:<your image file name>]

[group addSourceFile:sourceFileDefinition];
[project save];

Adding Asset Catalog (ImageSet)

XCSourceFileDefinition* sourceFileDefinition = [XCSourceFileDefinition sourceDefinitionWithAssetCatalogName:<path to asset catalog>];

[group addSourceFile:sourceFileDefinition];
[project save];

Adding a Header

XCSourceFileDefinition* header = [[XCSourceFileDefinition alloc]
    initWithName:@"SomeHeader.h" text:<your header text> type:SourceCodeHeader];

[group addSourceFile:header];
[project save];

Adding a sub-project

subProjectDefinition = [XCSubProjectDefinition withName:@"mySubproject" projPath=@"/Path/To/Subproject" type:XcodeProject];
[group addSubProject:subProjectDefinition toTargets:[project targets]];

Removing a sub-project

[group removeSubProject:subProjectDefinition];  //TODO: project should be able to remove itself from parent.

Configuring targets

We can add/update linker flags, header search paths, C-flags, etc to a target. Here we'll add header search paths:

XCTarget* target = [_project targetWithName:_projectName];
for (NSString* configName in [target configurations])
    XCBuildConfiguration* configuration = [target configurationWithName:configName];
    NSMutableArray* headerPaths = [[NSMutableArray alloc] init];
    [headerPaths addObject:@"$(inherited)"];
    [headerPaths addObject:@"$(SRCROOT)/include"];        
    [configuration addOrReplaceSetting:headerPaths forKey:@"HEADER_SEARCH_PATHS"];

. . . these settings are added by key, as they would appear in a make file. (Xcode provides more human friendly descriptions). To find the key for a given build setting, consult the compiler docs. Common settings are:


###Adding a Library

XCSourceFile * libSourceFile = [project fileWithName:@"libAmazing.a"];

XCTarget* target = [project targetWithName:self.mProject.projectName];
[target addMember:libSourceFile];

for (NSString* configName in [target configurations]) {
    XCProjectBuildConfig* configuration = [target configurationWithName:configName];
    NSMutableArray* headerPaths = [[NSMutableArray alloc] init];
    [headerPaths addObject:@"$(inherited)"];
    [headerPaths addObject:@"$(PROJECT_DIR)/Amazing"];
    [configuration addOrReplaceSetting:headerPaths forKey:@"LIBRARY_SEARCH_PATHS"];

File write behavior

//Creates the reference in the project and writes the contents to disk. If a file already exists at the 
//specified location, its contents will be updated.
[definition setFileOperationStyle:FileOperationStyleOverwrite]; 
//Creates the reference in the project. If a file already exists at the specified location, the contents will 
//not be updated.
[definition setFileOperationStyle:FileOperationStyleAcceptExisting]; 
//Creates the reference in the project, but does not write to disk. The filesystem is expected to be updated 
//through some other means.
[definition setFileOperationStyle:FileOperationStyleReferenceOnly]; 


Open the project in XCode and choose Product/Build. Alternatively install with CocoaPods.

Feature Requests and Contributions

. . . are very welcome.

If you're using the API shoot me an email and tell me what you're doing with it.


  • Xcode-editor has been tested on Xcode 4+. It should also work on earlier versions of Xcode.
  • The AppCode IDE from JetBrains is now supported too!
  • Supports both ARC and MRR modes of memory management.

Who's using it?

  • Apportable : Develop Android applications using Xcode, Objective-C and Cocoa APIs
  • Xamarin: The Calabash automated functional testing for mobile applications.
  • Peckham : A great plugin for managing Xcode imports
  • Level Helper: A RAD framework for developing 2D games on iOS & Android.
  • Text Mate: The missing Text Editor for OSX.


With contributions from:

  • Connor Duggan - lots of bug fixes, maintenance and enhancements.
  • Alexander Smirnov - Cleaned up, generalized and contributed back the changes from the Calabash fork.
  • Zach Drayer - lots of fixes and features to support TextMate.
  • Janine Ohmer - support adding and removing sub-projects (
  • Bogdan Vladu - support adding and removing groups (
  • Chris Ross of Hidden Memory (
  • Paul Taykalo
  • Vladislav Alekseev
  • Felix Schneider - bug fixes.
  • Isak Sky - mutable XCSourceFiles.
  • Derk-Jan Hartman : Adding folder references, by-file compiler flags.
  • StoneSpb : Speed improvements
  • Ce Zheng : Fixes relating to Xcode 7, xcconfig support and others.



Apache License, Version 2.0, January 2004,

  • © 2011 - 2012 Jasper Blues and contributors.