tuist/XcodeProj

XcodeProj is a Swift library that reads, writes, and manipulates Xcode project and workspace files. It provides programmatic access to project structures, including targets, build phases, schemes, and build settings, while supporting both legacy property list formats and newer JSON-based project formats. The system also handles local Swift package references, workspace settings, and user-specific configurations to facilitate automated Xcode project management.

17 changes.

The project established modern development tooling, including Tuist and Swift 6.0 support, while significantly expanding the test fixture suite. This period focused on adding comprehensive iOS, workspace, and scheme fixtures to validate parsing logic and ensure coverage for advanced Xcode features.

28 changes.

The project underwent a comprehensive refactoring of its internal object models to support Xcode 16 and 26 features, including file system synchronization, JSON project formats, and strongly typed build settings. This architectural overhaul was accompanied by the introduction of centralized error handling, deterministic serialization, and extensive new test coverage to ensure stability and correctness across the updated API surface.

15 changes.

The project expanded its fixture suite to cover complex iOS configurations, including app extensions, shared headers, custom build rules, and local Swift packages. Significant development focused on supporting Xcode 16 features such as synchronized root groups and updated project reference ordering. The library also introduced experimental support for reading and writing Xcode's new JSON-based project format (project.xcproj).

Added new fixture files in Fixtures/XCProj to represent the Xcode 27.2 JSON project format (project.xcproj). These fixtures include ConfigurationOverrides, Everything, LocalizedResources, and XcodeGenerated projects, demonstrating support for JSON-based project structures with features such as localized resource paths, build setting configuration overrides, and various build phases.

Fixtures/XCProj · high confidence

This change adds support for XCLocalSwiftPackageReference, enabling the integration of local Swift packages within Xcode projects. The implementation includes a new fixture demonstrating a local Swift package structure with source files, tests, and configuration, ensuring compatibility with local package references in iOS development workflows.

Fixtures/iOS/MyOtherLocalPackage · high confidence

Added a new fixture project (Xcode16BuildConfigurations) that demonstrates the Xcode 16 XCBuildConfiguration format, including a project.pbxproj with objectVersion 77, file-system synchronized groups, and xcconfig files for Debug, Release, and Target configurations.

Fixtures/Xcode16BuildConfigurations · high confidence

A new iOS application fixture has been added to the project, providing a standard Xcode project structure for testing purposes. This includes the core application files such as the AppDelegate and ViewController, along with necessary assets like the app icon set, launch screen and main storyboards, the Info.plist configuration, and an empty Core Data model.

Fixtures/iOS/iOS · high confidence

Added the standard Xcode workspace files (contents.xcworkspacedata and IDEWorkspaceChecks.plist) for the iOS project fixture, establishing the basic workspace structure required for the test environment.

Fixtures/iOS/Project.xcodeproj/project.xcworkspace · high confidence

A new Xcode project fixture has been added to demonstrate and test the behavior of sharing header files (specifically SharedHeader.h) across multiple build targets within a single framework. This includes the project configuration, a public header, and a corresponding test target to verify the setup.

Fixtures/FileSharedAcrossTargets · high confidence

Added a new fixture project demonstrating Xcode 16's file-system synchronized groups, including the \PBXFileSystemSynchronizedRootGroup\ and its associated exception sets (\PBXFileSystemSynchronizedBuildFileExceptionSet\ and \PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet\).

Fixtures/SynchronizedRootGroups · high confidence

A new Xcode project fixture has been added to demonstrate static library targets with custom build rules. The project includes a target configured with three distinct build rules: a generic script-based rule, a rule with dependency file generation, and a rule targeting a custom file type (\.skybox\). This fixture serves as a test case for parsing and handling custom build rule configurations in Xcode projects.

Fixtures/TargetWithCustomBuildRules · high confidence

The Fixtures/iOS/AppWithExtensions directory now contains a complete Xcode project demonstrating an iOS app integrated with several extensions: a Today View widget, a Messages app extension, and a Watch App with its extension. The project includes the necessary source files, storyboards, asset catalogs, and Xcode scheme configurations to build and run these components, providing a reference implementation for multi-target iOS applications.

Fixtures/iOS/AppWithExtensions · high confidence

A new fixture has been added at Fixtures/iOS/MyLocalPackage containing a sample Swift package structure. This includes the package source code, a basic test suite with functional tests, and configuration files such as .gitignore and README.md to support local Swift package development on iOS.

Fixtures/iOS/MyLocalPackage · high confidence

New mise task scripts have been added to streamline local development workflows. Users can now run \build\ and \test\ on the host machine, or execute \build-linux\ and \test-linux\ to run Swift 6.1.2 inside a Docker or Podman container. Additionally, \lint\ and \lint-fix\ tasks have been introduced to run SwiftFormat and SwiftLint for code style enforcement and automatic fixes.

.mise · high confidence

A new Python script, \Scripts/dump-known-file-extensions.py\, has been added to the repository. This utility scans an Xcode installation's plug-ins for \.xcspec\ and \.pbfilespec\ files, extracts the file extensions defined within them, and outputs the results as a sorted JSON object to standard output. It allows users to programmatically retrieve the list of file types recognized by a specific Xcode version.

Scripts · high confidence

The library now provides dedicated model classes for aggregate, legacy, and native build targets, each supporting serialization and deserialization of their specific attributes (such as build tool paths for legacy targets or install paths for native targets). A new \addDependency()\ helper method is available on both aggregate and native targets to simplify creating local target dependencies. The \PBXProductType\ enum has been extended to cover additional Xcode product types, including xcframeworks, extension kit extensions, host build tools, on-demand install capable applications, and metal libraries. Furthermore, \PBXTargetDependency\ now supports the \platformFilter\ and \platformFilters\ attributes introduced in Xcode 11, allowing for more precise dependency configuration.

Sources/XcodeProj/Objects/Targets · high confidence

This change introduces a new \Errors.swift\ file that defines a comprehensive set of error enums for the XcodeProj library, including \XCodeProjError\, \XCSharedDataError\, \XCUserDataError\, \XCWorkspaceError\, \XcodeprojEditingError\, \XcodeprojWritingError\, \PBXObjectError\, \PBXProjEncoderError\, and \PBXProjError\. These types provide specific, descriptive error cases for common failure scenarios such as missing files, invalid project structures, and encoding issues, improving error handling clarity for users of the library.

Sources/XcodeProj/Errors · high confidence

A new \Writable\ protocol has been introduced in \Sources/XcodeProj/Protocols\, allowing entities to be written to disk via \write(path:override:)\ and \write(pathString:override:)\, and to provide a data representation via \dataRepresentation()\. The protocol includes default implementations that delegate the string-based write to the path-based version and return \nil\ for data representation, providing a consistent interface for saving and serializing project objects.

Sources/XcodeProj/Protocols · high confidence

The iOS fixture project now includes support for test plans (iOS.xctestplan) and custom build rules. The project structure demonstrates integration with local Swift packages (MyLocalPackage) and system frameworks (CoreData), includes header visibility settings (Public, Protected, Private), and features a copy frameworks build phase. A new test plan file configures test targets, environment variables, and command-line arguments for the iOS target.

Fixtures/iOS/Project.xcodeproj · high confidence

This change introduces several new utility components in the Sources/XcodeProj/Utils directory. BuildSettingsProvider now supplies default build settings for various platforms (including visionOS), product types, and build variants, ensuring generated projects match Xcode's defaults. PBXBatchUpdater allows for the efficient addition of large numbers of files to a project by batching group and reference lookups. ReferenceGenerator ensures that object references in the project are deterministic and permanent before saving, which improves stability and consistency. Additionally, CommentedString and PlistValue utilities provide optimized string escaping and plist value handling, while XCConfig supports parsing and writing .xcconfig files with include resolution.

Sources/XcodeProj/Utils · high confidence

The repository has been reorganized and initialized with standard tooling configurations. This includes adding an \.editorconfig\ for consistent code formatting, \.swiftformat\ and \.swiftlint.yml\ for code style enforcement, and a \.mise.toml\ to manage development tools (SwiftFormat, Tuist, SwiftLint, git-cliff). A \Tuist.swift\ manifest is introduced to define the project for Tuist generation. The project now uses \git-cliff\ (configured in \cliff.toml\) for automated changelog generation and \renovate.json\ for dependency updates. The \.gitignore\ has been expanded to cover macOS, Swift, and Xcode artifacts, and the \CHANGELOG.md\ has been populated with historical release notes up to version 9.17.5. The \.all-contributorsrc\ file tracks community contributors.

(repo-wide) · high confidence

The library now models Xcode 16's file system synchronization features by introducing \PBXFileSystemSynchronizedRootGroup\ and related exception sets (\PBXFileSystemSynchronizedBuildFileExceptionSet\, \PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet\), allowing users to read and write projects that use this modern grouping strategy. Additionally, \PBXFileReference\ now supports the \expectedSignature\ property for signed XCFrameworks, and \PBXGroup\ provides new helper methods (\group(with:)\, \synchronizedRootGroup(named:)\, \file(named:)\) to locate children by path or name, improving the usability of the file and group object model.

Sources/XcodeProj/Objects/Files · high confidence

The library now supports reading and writing Xcode's new JSON5-based project format (project.xcproj) alongside the legacy project.pbxproj. This adds new mapping logic to convert between the two formats, handling build file attributes, build settings with configuration conditions, file paths, and object identifiers. Users can now convert projects to and from the new format, with options to preserve existing UUIDs or use minimal identifiers.

Sources/XcodeProj/XCProj · high confidence

XcodeProj can now read and write projects using Xcode 27.2's new JSON-based \project.xcproj\ format alongside the traditional \project.pbxproj\ property list, automatically detecting the on-disk format. The library also introduces support for workspace settings (including custom Derived Data paths and build system selection) and user/shared data breakpoints, allowing these configurations to be read from and written to \.xcshareddata\ and \.xcuserdata\ directories.

Sources/XcodeProj/Project · high confidence

XcodeProj now supports local Swift package references via the new XCLocalSwiftPackageReference class, allowing projects to reference packages stored on the local filesystem. Additionally, both local and remote package references (XCRemoteSwiftPackageReference) now support the 'traits' property, enabling users to specify enabled package traits (requires Xcode 26.4+). The library also introduces XCSwiftPackageProductDependency to handle product dependencies, including support for build tool plugins identified by a 'plugin:' prefix in the product name.

Sources/XcodeProj/Objects/SwiftPackage · high confidence

The iOS fixture project now includes user-specific configuration files under \xcuserdata\, allowing individual developers to maintain their own breakpoints and scheme settings without affecting shared project state. This change adds breakpoint definitions for \AppDelegate.swift\ and \ViewController.swift\ for \username1\, along with multiple Xcode schemes (\iOS-debug\, \iOS-release\, \iOS-other\, \iOSTests\, \custom-scheme\) and a scheme management list that controls the visibility and order of these schemes in the Xcode IDE.

Fixtures/iOS/Project.xcodeproj/xcuserdata · high confidence

The Templates/Equality.stencil file was added to generate isEqual methods for models conforming to AutoEquatable. This template now includes specific logic to handle dictionary-typed stored variables by comparing them using NSDictionary, ensuring correct equality checks for properties containing dictionaries, while also supporting optional dictionaries and computed variables annotated for forced equality.

Templates · high confidence

The \BuildSettings\ dictionary now uses a strongly typed \BuildSetting\ enum (supporting string, array, and boolean values) instead of raw strings, and \XCBuildConfiguration\ has been updated to support the Xcode 16+ \XCBuildConfiguration\ format, including new initializers and serialization logic for referencing base xcconfig files via \PBXFileSystemSynchronizedRootGroup\ anchors and relative paths. This change improves type safety for build settings and ensures compatibility with newer Xcode project structures.

Sources/XcodeProj/Objects/Configuration · high confidence

The iOS project fixture has been updated to include a \project.pbxproj\ file that demonstrates the use of \XCRemoteSwiftPackageReference\ and \XCLocalSwiftPackageReference\ with the new \traits\ property, allowing users to verify how package traits are handled in generated Xcode projects.

Fixtures/iOS/ProjectWithSwiftPackageTraits.xcodeproj · medium confidence

The library now includes auto-generated \isEqual(to:)\ methods for Xcode project object models (such as \PBXBuildFile\, \PBXBuildPhase\, \PBXProject\, etc.) via Sourcery. This ensures that equality checks for these objects correctly compare all relevant properties, improving reliability when comparing or caching project structures.

Sources/XcodeProj/Objects/Sourcery · high confidence

The \Sources/XcodeProj/Workspace\ files introduce a new \XCWorkspace\ model that tracks the file path of the workspace and prevents overwriting the \.xcworkspacedata\ file if its content has not changed, which avoids unnecessary Xcode project reloads. The implementation also adds support for parsing \FileSystemSynchronizedGroup\ elements within the workspace structure.

Sources/XcodeProj/Workspace · high confidence

The build phase objects in Sources/XcodeProj/Objects/BuildPhase have been restructured to support newer Xcode formats and add granular control. PBXCopyFilesBuildPhase now supports the new Xcode 26 dstSubfolder attribute alongside the legacy dstSubfolderSpec. PBXShellScriptBuildPhase handles the Xcode 16 shellScript array format and exposes the alwaysOutOfDate and dependencyFile attributes. PBXBuildFile now supports platformFilter and platformFilters attributes, and PBXBuildRule includes runOncePerArchitecture and dependencyFile. The legacy PBXBuildPhase.type() function is deprecated in favor of the buildPhase property.

Sources/XcodeProj/Objects/BuildPhase · high confidence

The internal architecture for representing and parsing Xcode project files has been restructured to improve type safety and maintainability. A new base \PBXObject\ class and dedicated \PBXObjectReference\ mechanism now manage object identity and UUIDs, replacing the previous ad-hoc approach. Decoding is centralized through \PBXObjectDictionaryEntry\, which routes plist entries to specific model classes, while \PBXObjects\ serves as a strongly-typed, thread-safe container for all project elements. This refactoring also introduces \PBXOutputSettings\ to control file sorting and reference formatting during serialization, and updates \PBXProject\ to support Xcode 16 features such as optional compatibility versions and file system synchronization models.

Sources/XcodeProj/Objects/Project · high confidence

This change introduces a suite of extension files in the XcodeProj library to improve how project files are read and written. The new AEXML+XcodeFormat extension enforces a consistent, Xcode-native attribute ordering when serializing scheme and build actions to XML, ensuring generated files match the style expected by Xcode. It also adds specific decoding helpers (such as decodeIntIfPresent) to robustly handle legacy or inconsistent integer/boolean values in project files, and includes utility extensions for path handling, string manipulation, and MD5 hashing to support these operations.

Sources/XcodeProj/Extensions · high confidence

The iOS build settings fixture now sets SWIFT\_OPTIMIZATION\_LEVEL to "-O" instead of "-Owholemodule". This change affects how Swift code is compiled within this specific test fixture, switching from whole-module optimization to a standard optimization level.

Fixtures/iOS/BuildSettings.xcodeproj · high confidence

The iOS project fixture now includes a new Breakpoints\_v2.xcbkptlist file that defines a full set of Xcode debugger breakpoints. This configuration adds support for Swift error, exception, symbolic, OpenGL error, constraint error, test failure, and runtime issue breakpoints, each pre-configured with specific actions such as playing sounds, logging messages, executing shell commands, or running AppleScripts. This ensures the project fixture accurately reflects modern Xcode debugging capabilities and breakpoint behaviors.

Fixtures/iOS/Project.xcodeproj/xcshareddata/xcdebugger · high confidence

The XcodeProj scheme model has been refactored to introduce dedicated types for scheme actions (AnalyzeAction, ArchiveAction, BuildAction, ProfileAction, TestAction) and runnable targets (Runnable, PathRunnable, RemoteRunnable, BuildableProductRunnable). This change adds support for modern Xcode scheme attributes, including build architectures, custom working directories, GPU frame capture modes, sanitizers, test plans, and StoreKit configuration references, while maintaining backward compatibility through deprecated convenience initializers.

Sources/XcodeProj/Scheme · high confidence

The iOS Xcode scheme fixture has been updated to include a full set of execution actions and configuration attributes. The BuildAction now defines pre- and post-actions, with the post-action explicitly specifying the shell to invoke. The TestAction has been expanded to support test plans, screen capture format selection, code coverage filtering for specified targets, command-line arguments, and environment variables. The LaunchAction now includes a custom launch command, pre- and post-actions with environment buildable references, command-line arguments, and environment variables.

Fixtures/iOS/Project.xcodeproj/xcshareddata/xcschemes · high confidence

Added a new fixture in Fixtures/Xcode16 that includes a sample Xcode project (project.pbxproj) and source files structured to reflect changes introduced in Xcode 16, such as the use of PBXFileSystemSynchronizedRootGroup and updated object versions. This fixture is designed to allow tests to validate correct parsing of these specific Xcode 16 project structures.

Fixtures/Xcode16 · high confidence

A .gitkeep file was added to the Fixtures/dummy.framework directory to ensure the folder is tracked by version control, resolving an error that occurred when adding a framework reference.

Fixtures/dummy.framework · medium confidence

The Xcode 16 project reference order fixture has been corrected to match Xcode 16's expected sorting and structure. The new \Test.xcodeproj\ now uses \objectVersion = 90\ and correctly orders project references (Framework1 before Framework2) and build phases, while the \Wrong.xcodeproj\ retains the older \objectVersion = 56\ and incorrect ordering to serve as a comparison baseline. This ensures the fixture accurately reflects the target Xcode 16 format for validation purposes.

Fixtures/Xcode16ProjectReferenceOrder · high confidence

Add WithoutWorkspace fixture for testing single-project scenarios; Add iOS test fixture project; Add test infrastructure for Xcode project serialization; Added XCConfig fixture files for testing parsing logic; Added iOS fixture for projects without a products group; Added iOS fixture projects with XCLocalSwiftPackageReference support; Added sample Xcode workspace fixture for parsing tests; Added test coverage for WorkspaceSettings, breakpoints, xcuserdata, and Xcode 16 project parsing; Added test coverage for XCScheme, XCSchemeManagement, and BuildableReference; Added test coverage for Xcode project file objects and fixtures; Added test coverage for Xcode project target objects; Added test coverage for XcodeProj build phase objects; Added test coverage for XcodeProj utility components; Added test coverage for project configuration, encoding, and file ordering; Added test coverage for the new JSON project format (project.xcproj); Added test suite for XcodeProj XML formatting and path utilities; Added tests for Swift package reference objects and plugin support; Added tests for XCWorkspace, XCWorkspaceData, and XCWorkspaceDataElement; Added workspace settings fixtures for build system and derived data configuration; Expanded Xcode scheme fixture coverage for advanced build and launch configurations; Removal of LinuxMain.swift test runner.

The XcodeProj package has been upgraded to Swift tools version 6.0, requiring macOS 14 and iOS 17 as minimum deployment targets. The package manifest now explicitly declares dependencies on AEXML (4.7.0), PathKit (1.0.1), and xcode-project-format (0.1.0), and enables the StrictConcurrency experimental feature for the main target. Corresponding fixture packages and resolved dependency files have been updated to reflect these new version constraints and platform requirements.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 56 → 51 (-5.3)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 96 → 94 (-1.3)
• Architecture 99 → 94 (-4.8)
• Maturity 53 → 53 (+0.2)
• Readiness 65 → 47 (-17.8)
• Security 42 → 42 (+0.0)
• Domain Modelling 100 → 100 (+0.0)
• Performance 63 (new)

• Documentation: no usage examples (Documentation/README.md)
• Off-boarding risk: anonymized user #1
• Orphaned files with no living knowledge

• AEXMLElement._xmlXcodeFormat (cognitive 17) (Sources/XcodeProj/Extensions/AEXML+XcodeFormat.swift)
• Coverage not measured — broken report
• Duplicated block (10 lines × 2) (Sources/XcodeProj/XCProj/XCProjEncoder.swift)
• Duplicated block (14 lines × 2) (Sources/XcodeProj/XCProj/XCProjDecoder.swift)
• Duplicated block (8 lines × 2) (Sources/XcodeProj/Errors/Errors.swift)
• FileTooLong: XCProj/XCProjDecoder.swift (Sources/XcodeProj/XCProj/XCProjDecoder.swift)
• FileTooLong: XCProj/XCProjEncoder.swift (Sources/XcodeProj/XCProj/XCProjEncoder.swift)
• Flaky test: .::XcodeProjTests.XCSchemeIntegrationTests.test_write_runnableWithoutBuildableReferenceScheme
• Flaky test: .::XcodeProjTests.XcodeProjIntegrationTests.test_read_iosXcodeProj
• Flaky test: .::XcodeProjTests.XcodeProjIntegrationTests.test_write_includes_workspace_settings
• Flaky test: .::XcodeProjTests.XcodeProjIntegrationTests.test_write_iosXcodeProj
• Inconsistent method overloading strategy. While overloading is common, the third overload introduces XCProjOutputSettings which is specific to the .xcproj file, whereas the second overload only handles PBXOutputSettings (for .pbxproj). This creates a confusing hierarchy where write behaves differently depending on the number of arguments, mixing concerns of the main project file vs. the xcproj wrapper file in the same method name without clear separation.
• Low cohesion: PBXProj (LCOM4 4) (Sources/XcodeProj/Objects/Project/PBXProj.swift)
• No assertions: convertIOSProject (Tests/XcodeProjTests/XCProj/XCProjEncoderTests.swift)
• No assertions: decodeResolvesLocalizedResourcePaths (Tests/XcodeProjTests/XCProj/XCProjLocalizedResourceTests.swift)
• Off-boarding risk: anonymized user #1
• Projects may be oversized for their cohesion
• Redundant constructors for path input. Similar to XcodeProj, XCScheme exposes both init(path: Path) and init(pathString: String), duplicating the intent of loading a scheme from a file path.
• Redundant constructors for path input. The library provides two distinct initializers for loading a project from a path: one accepting a Path type and another accepting a String. This forces users to choose based on their input type rather than intent, and creates unnecessary API surface duplication.
• Redundant constructors for path input. XCWorkspace also exposes both init(path: Path) and init(pathString: String), creating inconsistency with the rest of the API if Path is the preferred type.
• …and 6 more

• 20 commits — 13 feature/other, 7 fixes

• (root) — 10 commits
• Sources/XcodeProj — 6 commits
• .github/workflows — 2 commits
• Fixtures/XCProj — 1 commit
• Tests/XcodeProjTests — 1 commit

• fix: fix: identify nameless copy files and script phases in project.xcproj (#1181)
• fix: fix: preserve JSON build setting configuration overrides (#1178)
• fix: fix: reference file elements by the name project.xcproj writes (#1182)
• fix: fix: resolve base-localized resource paths in JSON projects (#1179)
• fix: fix: resolve the references project.xcproj left undefined (#1184)
• fix: fix: settle object identifiers when encoding project.xcproj (#1180)
• fix: fix: support the Swift Static Linux SDK (musl) (#1168)
• change: [Release] XcodeProj 9.16.1
• change: [Release] XcodeProj 9.17.0
• change: [Release] XcodeProj 9.17.1
• change: [Release] XcodeProj 9.17.2
• change: [Release] XcodeProj 9.17.3
• change: [Release] XcodeProj 9.17.4
• change: [Release] XcodeProj 9.17.5
• change: chore(deps): update dependency git-cliff to v2.14.2 (#1185)
• change: chore(deps): update dependency tuist to v4.209.0 (#1186)
• change: chore(deps): update dependency tuist to v4.210.0 (#1187)
• change: chore(deps): update jdx/mise-action action to v4 (#1081)
• change: chore(deps): update softprops/action-gh-release action to v3 (#1109)
• change: feat: [Experimental] support Xcode 27.2's JSON project format (project.xcproj) (#1177)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

tuist/XcodeProj was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.