Xcode Project File Format

2022 - 09 - 15

Posted by Monobjc

Introduction

The Xcode project file is an old-style plist (Next style) based on braces to delimit the hierarchy. The file begins with an explicit encoding information, usually the UTF-8 one. This means that the file must not bear a BOM (Byte Ordering Mark) at its start or the parsing will fail.

Note: The following document is based on observations of various *.pbxproj files and element properties have been inferred. There was not code reverse engineering involved what so ever.

Unique Identification

Each element in the file is uniquely identified by a 96 bits identifier using a 24 hexadecimal representation. This unique identifier is unique accross the document.

The algorithm used by Xcode to generate the unique identifier seems to be based both on date, sequence and pre-defined values, but as there is no evidence that these identifiers must follow a generation convention, one can think that arbitrary identifier can be used, as long as they are unique accross the document.

The following references were useful while writing this note:

A brief look at the Xcode project format [Cmake] Re: CMake Apple XCode support? PBTOMAKE – Xcode to Unix

Elements

Here is the list of elements contained in the file format:

  • Root Element
  • PBXBuildFile
  • PBXBuildPhase
    • PBXAppleScriptBuildPhase
    • PBXCopyFilesBuildPhase
    • PBXFrameworksBuildPhase
    • PBXHeadersBuildPhase
    • PBXResourcesBuildPhase
    • PBXShellScriptBuildPhase
    • PBXSourcesBuildPhase
  • PBXContainerItemProxy
  • PBXFileElement
    • PBXFileReference
    • PBXGroup
    • PBXVariantGroup
  • PBXTarget
    • PBXAggregateTarget
    • PBXLegacyTarget
    • PBXNativeTarget
  • PBXProject
  • PBXTargetDependency
  • XCBuildConfiguration
  • XCConfigurationList

Root Element

The root section contains the general informations.

Attribute Type Value Comment
archiveVersion Number 1 Default value.
classes List Empty  
objectVersion Number   See XcodeCompatibilityVersion enumeration.
objects Map A map of element The map is indexed by the elements identifier.
rootObject Reference An element reference The object is a reference to a PBXProject element.

Example:

// !$*UTF8*$!
{
    archiveVersion = 1;
    classes = {
    };
    objectVersion = 45;
    objects = {

    ...

    };
    rootObject = 0867D690FE84028FC02AAC07 /* Project object */;
}

PBXAggregateTarget

This is the element for a build target that aggregates several others.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXAggregateTarget Empty  
buildConfigurationList Reference An element reference The object is a reference to a XCConfigurationList element.
buildPhases List A list of element reference The objects are a reference to a PBXBuildPhase element.
dependencies List A list of element reference The objects are a reference to a PBXTargetDependency element.
name String The name of the target.  
productName String The product name.  

Example:

4DA521A6115A00AF007C19C3 /* documentation */ = {
    isa = PBXAggregateTarget;
    buildConfigurationList = 4DA521AE115A00ED007C19C3 /* Build configuration list for PBXAggregateTarget "documentation" */;
    buildPhases = (
        4DA521A5115A00AF007C19C3 /* ShellScript */,
    );
    dependencies = (
        4DA521AA115A00BC007C19C3 /* PBXTargetDependency */,
    );
    name = documentation;
    productName = documentation;
};

PBXBuildFile

This element indicate a file reference that is used in a PBXBuildPhase (either as an include or resource).

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXBuildFile Empty  
fileRef Reference An element reference The object is a reference to a PBXFileReference element.
settings Map   A map of key/value pairs for additionnal settings.

Example:

4D05CA6B1193055000125045 /* xxx.c in Sources */ = {
    isa = PBXBuildFile;
    fileRef = 4D05CA411193055000125045 /* xxx.c */;
};

PBXBuildPhase

This element is an abstract parent for specialized build phases.

PBXContainerItemProxy

This is the element for to decorate a target item.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXContainerItemProxy Empty  
containerPortal Reference An element reference The object is a reference to a PBXProject element.
proxyType Number 1  
remoteGlobalIDString Reference An element reference A unique reference ID.
remoteInfo String    

Example:

4D22DC0C1167C992007AF714 /* PBXContainerItemProxy */ = {
    isa = PBXContainerItemProxy;
    containerPortal = 08FB7793FE84155DC02AAC07 /* Project object */;
    proxyType = 1;
    remoteGlobalIDString = 87293EBF1153C114007AFD45;
    remoteInfo = xxx;
};

PBXCopyFilesBuildPhase

This is the element for the copy file build phase.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXCopyFilesBuildPhase Empty  
buildActionMask Number 2^32-1  
dstPath String The destination path  
dstSubfolderSpec Number    
files List A list of element reference The objects are a reference to a PBXBuildFile element.
runOnlyForDeploymentPostprocessing Number 0  

Example:

MISSING

PBXFileElement

This element is an abstract parent for file and group elements.

PBXFileReference

A PBXFileReference is used to track every external file referenced by the project: source files, resource files, libraries, generated application files, and so on.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXFileReference Empty  
fileEncoding Number   See the PBXFileEncoding enumeration.
explicitFileType String   See the PBXFileType enumeration.
lastKnownFileType String   See the PBXFileType enumeration.
name String The filename.  
path String The path to the filename.  
sourceTree String See the PBXSourceTree enumeration.  

Example:

87293F901153D870007AFD45 /* monobjc.mm */ = {
    isa = PBXFileReference; 
    fileEncoding = 4; 
    lastKnownFileType = sourcecode.cpp.objcpp; 
    name = monobjc.mm; 
    path = sources/monobjc.mm; 
    sourceTree = "";
};

PBXFrameworksBuildPhase

This is the element for the framewrok link build phase.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXFrameworksBuildPhase Empty  
buildActionMask Number 2^32-1  
files List A list of element reference The objects are a reference to a PBXBuildFile element.
runOnlyForDeploymentPostprocessing Number 0  

Example:

4D05CA2C119304BD00125045 /* Frameworks */ = {
    isa = PBXFrameworksBuildPhase;
    buildActionMask = 2147483647;
    files = (
    );
    runOnlyForDeploymentPostprocessing = 0;
};

PBXGroup

This is the element to group files or groups.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXGroup Empty  
children List A list of element reference The objects are a reference to a PBXFileElement element.
name String The filename.  
sourceTree String See the PBXSourceTree enumeration.  

Example:

4DA521A2115A003E007C19C3 /* scripts */ = {
    isa = PBXGroup;
    children = (
    4D22DBAF116742DE007AF714 /* fix_references.sh */,
    4DA521A1115A0032007C19C3 /* generate_descriptors.sh */,
    );
    name = scripts;
    sourceTree = "";
};

PBXHeadersBuildPhase

This is the element for the framewrok link build phase.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXHeadersBuildPhase Empty  
buildActionMask Number 2^32-1  
files List A list of element reference The objects are a reference to a PBXBuildFile element.
runOnlyForDeploymentPostprocessing Number 0  

Example:

87293EBC1153C114007AFD45 /* Headers */ = {
    isa = PBXHeadersBuildPhase;
    buildActionMask = 2147483647;
    files = (
    );
    runOnlyForDeploymentPostprocessing = 0;
};

PBXLegacyTarget

MISSING

PBXNativeTarget

This is the element for a build target that produces a binary content (application or library).

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXNativeTarget Empty  
buildConfigurationList Reference An element reference The object is a reference to a XCConfigurationList element.
buildPhases List A list of element reference The objects are a reference to a PBXBuildPhase element.
dependencies List A list of element reference The objects are a reference to a PBXTargetDependency element.
name String The name of the target.  
productInstallPath String The product install path.  
productName String The product name.  
productReference Reference An element reference The object is a reference to a PBXFileReference element.
productType String   See the PBXProductType enumeration.

Example:

8D1107260486CEB800E47090 /* XXX */ = {
    isa = PBXNativeTarget;
    buildConfigurationList = C01FCF4A08A954540054247B /* Build configuration list for PBXNativeTarget "XXX" */;
    buildPhases = (
        8D1107290486CEB800E47090 /* Resources */,
        8D11072C0486CEB800E47090 /* Sources */,
        8D11072E0486CEB800E47090 /* Frameworks */,
    );
    buildRules = (
    );
    dependencies = (
    );
    name = XXX;
    productInstallPath = "$(HOME)/Applications";
    productName = TrackIt;
    productReference = 8D1107320486CEB800E47090 /* XXX.app */;
    productType = "com.apple.product-type.application";
};

PBXProject

This is the element for a build target that produces a binary content (application or library).

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXProject Empty  
buildConfigurationList Reference An element reference The object is a reference to a XCConfigurationList element.
compatibilityVersion String A string representation of the XcodeCompatibilityVersion.  
developmentRegion String   The region of development.
hasScannedForEncodings Number 0 or 1 Whether file encodings have been scanned.
knownRegions List A list of string The known regions for localized files.
mainGroup Reference An element reference The object is a reference to a PBXGroup element.
productRefGroup Reference An element reference The object is a reference to a PBXGroup element.
projectDirPath String The relative path of the project.  
projectReferences Array of map Each map in the array contains two keys: ProductGroup and ProjectRef.  
projectRoot String The relative root path of the project.  
targets List A list of element reference The objects are a reference to a PBXTarget element.

Example:

29B97313FDCFA39411CA2CEA /* Project object */ = {
        isa = PBXProject;
        buildConfigurationList = C01FCF4E08A954540054247B /* Build configuration list for PBXProject "XXX" */;
        compatibilityVersion = "Xcode 2.4";
        developmentRegion = English;
        hasScannedForEncodings = 1;
        knownRegions = (
                English,
                Japanese,
                French,
                German,
                en,
        );
        mainGroup = 29B97314FDCFA39411CA2CEA /* XXX*/;
        projectDirPath = "";
        projectRoot = "";
        targets = (
             8D1107260486CEB800E47090 /* XXX*/,
        );
};

PBXResourcesBuildPhase

This is the element for the resources copy build phase.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXResourcesBuildPhase Empty  
buildActionMask Number 2^32-1  
files List A list of element reference The objects are a reference to a PBXBuildFile element.
runOnlyForDeploymentPostprocessing Number 0  

Example:

8D1107290486CEB800E47090 /* Resources */ = {
        isa = PBXResourcesBuildPhase;
        buildActionMask = 2147483647;
        files = (
                535C1E1B10AB6B6300F50231 /* ReadMe.txt in Resources */,
                533B968312721D05005E617D /* Credits.rtf in Resources */,
                533B968412721D05005E617D /* InfoPlist.strings in Resources */,
                533B968512721D05005E617D /* MainMenu.nib in Resources */,
                533B968612721D05005E617D /* TableEdit.nib in Resources */,
                533B968712721D05005E617D /* TestWindow.nib in Resources */,
        );
        runOnlyForDeploymentPostprocessing = 0;
};

PBXShellScriptBuildPhase

This is the element for the resources copy build phase.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXShellScriptBuildPhase Empty  
buildActionMask Number 2^32-1  
files List A list of element reference The objects are a reference to a PBXBuildFile element.
inputPaths List A list of string The input paths.
outputPaths List A list of string The output paths.
runOnlyForDeploymentPostprocessing Number 0  
shellPath String The path to the shell interpreter.  
shellScript String The content of the script shell.  

Example:

4D22DBAE11674009007AF714 /* ShellScript */ = {
        isa = PBXShellScriptBuildPhase;
        buildActionMask = 2147483647;
        files = (
        );
        inputPaths = (
        );
        outputPaths = (
        );
        runOnlyForDeploymentPostprocessing = 0;
        shellPath = /bin/sh;
        shellScript = "./fix_references.sh";
};

PBXSourcesBuildPhase

This is the element for the sources compilation build phase.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXSourcesBuildPhase Empty  
buildActionMask Number 2^32-1  
files List A list of element reference The objects are a reference to a PBXBuildFile element.
runOnlyForDeploymentPostprocessing Number 0  

Example:

4DF8B22D1171CFBF0081C1DD /* Sources */ = {
        isa = PBXSourcesBuildPhase;
        buildActionMask = 2147483647;
        files = (
                4DF8B23E1171D0310081C1DD /* test.mm in Sources */,
        );
        runOnlyForDeploymentPostprocessing = 0;
};

PBXTarget

This element is an abstract parent for specialized targets.

PBXTargetDependency

This is the element for referencing other target through content proxies.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXTargetDependency Empty  
target Reference An element reference The object is a reference to a PBXNativeTarget element.
targetProxy Reference An element reference The object is a reference to a PBXContainerItemProxy element.

Example:

4D22DC0D1167C992007AF714 /* PBXTargetDependency */ = {
        isa = PBXTargetDependency;
        target = 87293EBF1153C114007AFD45 /* libXXX */;
        targetProxy = 4D22DC0C1167C992007AF714 /* PBXContainerItemProxy */;
};

PBXVariantGroup

This is the element for referencing localized resources.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa PBXVariantGroup Empty  
children List A list of element reference The objects are a reference to a PBXFileElement element.
name String The filename.  
sourceTree String See the PBXSourceTree enumeration.  

Example:

870C88031338A77600A69309 /* MainMenu.xib */ = {
        isa = PBXVariantGroup;
        children = (
                870C88041338A77600A69309 /* en */,
        );
        name = MainMenu.xib;
        sourceTree = "";
};

XCBuildConfiguration

This is the element for defining build configuration.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa XCBuildConfiguration Empty  
baseConfigurationReference String The path to a xcconfig file  
buildSettings Map A map of build settings.  
name String The configuration name.  

Example:

870C88151338ABB600A69309 /* Debug */ = {
        isa = XCBuildConfiguration;
        buildSettings = {
                PRODUCT_NAME = "$(TARGET_NAME)";
        };
        name = Debug;
};
870C88161338ABB600A69309 /* Release */ = {
        isa = XCBuildConfiguration;
        buildSettings = {
                PRODUCT_NAME = "$(TARGET_NAME)";
        };
        name = Release;
};

XCConfigurationList

This is the element for listing build configurations.

Attribute Type Value Comment
reference UUID A 96 bits identifier  
isa XCConfigurationList Empty  
buildConfigurations List A list of element reference The objects are a reference to a XCBuildConfiguration element.
defaultConfigurationIsVisible Number 0  
defaultConfigurationName String The default configuration name.  

Example:

870C87E41338A77600A69309 /* Build configuration list for PBXProject "CocoaApp" */ = {
        isa = XCConfigurationList;
        buildConfigurations = (
                870C88061338A77600A69309 /* Debug */,
                870C88071338A77600A69309 /* Release */,
        );
        defaultConfigurationIsVisible = 0;
        defaultConfigurationName = Release;
};
Table of Contents