SwiftBrowser docs
View as MarkdownEdit on GitHub

@swiftbrowser/xcodeproj#

Reads Xcode projects without Xcode: a pure-TypeScript parser for project.pbxproj (Node built-ins only) that answers the questions a CLI has about an iOS app: which targets exist, which Swift files and asset catalogs they compile, and what their build settings are.

import { findXcodeProjects, readXcodeProject } from '@swiftbrowser/xcodeproj';

const [xcodeproj] = findXcodeProjects(process.cwd()); // ./*.xcodeproj, else one level down
const project = readXcodeProject(xcodeproj);
const [app] = project.appTargets(); // targets whose product is an application

app.name; // 'GuessTheFlag'
app.productName; // PRODUCT_NAME with $(TARGET_NAME) resolved
app.bundleIdentifier; // PRODUCT_BUNDLE_IDENTIFIER
app.displayName; // INFOPLIST_KEY_CFBundleDisplayName, else CFBundleDisplayName from INFOPLIST_FILE
app.appIconName; // ASSETCATALOG_COMPILER_APPICON_NAME
app.swiftVersion; // SWIFT_VERSION
app.deploymentTarget; // IPHONEOS_DEPLOYMENT_TARGET
app.sources; // absolute paths of the .swift files, in navigator order
app.models; // the Core ML models (.mlmodel, .mlpackage) it compiles
app.resources; // absolute paths of the Resources build phase entries
app.assetCatalogs; // the *.xcassets among them (and in synchronized folders)
app.dependencies; // names of target dependencies
app.packageProducts; // Swift package products the target links
app.packageDependencies; // the same, each with its package (URL and version rule, or local path)
project.packages; // the project's Swift package references
app.settings('Release'); // merged build settings for a configuration

API#

  • readXcodeProject(xcodeprojPath) parses <xcodeprojPath>/project.pbxproj and returns an XcodeProject: path, root (the directory containing the bundle, what $(SRCROOT) means), objectVersion, targets (every PBXNativeTarget), packages (its XCRemoteSwiftPackageReferences, with the dependency rule, and XCLocalSwiftPackageReferences, with the absolute path; each with SwiftPM's identity, see packageIdentity) and appTargets().
  • parsePbxproj(text) returns the raw object graph: { objectVersion, rootObject, objects }, where each object has an isa plus arbitrary fields (strings, arrays, nested dictionaries). parseOldStylePlist(text) parses any old-style property list fragment.
  • xcodeProjectFromDocument(doc, xcodeprojPath) interprets an already parsed document as the project at that path.
  • findXcodeProjects(dir) lists the *.xcodeproj bundles directly in dir, else one level down (sorted), skipping Pods/, Carthage/, DerivedData/, .build/, node_modules/ and dot-directories.
  • parseXmlPlist(text) is the minimal XML plist reader used for Info.plist.

How paths are resolved#

A file's absolute path is the project root plus the chain of group paths leading to it, following each object's sourceTree: <group> is relative to the parent group, SOURCE_ROOT to the root, <absolute> is absolute; others (BUILT_PRODUCTS_DIR, SDKROOT, ...) fall back to the root. Groups without a path contribute nothing. Build phase files are listed in the order of the group tree (what the Xcode navigator shows), not the arbitrary order of the build phase. Paths are resolved exactly as written; a project whose group path differs from the folder on disk only in letter case works on macOS but not on a case-sensitive filesystem.

Xcode 16 "synchronized folders" (PBXFileSystemSynchronizedRootGroup referenced from a target's fileSystemSynchronizedGroups) are read from disk: every *.swift under the folder (recursive, sorted) is a source of the target and every *.xcassets an asset catalog, minus the paths listed in the target's PBXFileSystemSynchronizedBuildFileExceptionSet.membershipExceptions. A folder missing on disk contributes nothing.

Build settings#

target.settings(configuration?) merges the project-level buildSettings of the named XCBuildConfiguration with the target-level ones on top. The default configuration is Debug when the target has one, else the configuration list's defaultConfigurationName. Array-valued settings are space-joined. $(TARGET_NAME), $(PRODUCT_NAME), $(SRCROOT) and $(PROJECT_DIR) (also in ${...} form) are expanded; every other $(...) reference, including $(inherited) and modifiers such as $(X:rfc1034identifier), is left as is.

Not handled#

  • .xcconfig files referenced by baseConfigurationReference are not read, so settings defined only there are absent.
  • Binary Info.plist files are skipped (only XML plists are read).
  • PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet (Xcode 16 per-build-phase exceptions) and PBXBuildRules are ignored.
  • Workspaces (.xcworkspace), referenced projects (PBXReferenceProxy) and PBXAggregateTarget/PBXLegacyTarget are not modelled; only PBXNativeTargets appear in targets.