Is XcodeProj stable enough for use in CI/CD pipelines?

Yes, it's battle-tested by tools like Tuist and XcodeGen in production environments. The high code coverage and active maintenance suggest reliability for automating tasks like build setting updates or project generation.

How do I update build settings for all configurations using XcodeProj?

Iterate over the pbxproj.buildConfigurations array and modify the buildSettings dictionary. The README's scripting example shows updating the CURRENT_PROJECT_VERSION key for all configurations, which can be adapted for other settings.

XcodeProj vs CocoaPods Xcodeproj: which should I use?

XcodeProj is written in Swift and better integrated with Swift ecosystems, while CocoaPods Xcodeproj is in Ruby. Choose based on your project's primary language; for Swift-based tools or scripts, XcodeProj is more natural and performant.

Can XcodeProj handle .xcworkspace files?

The README focuses on .xcodeproj files without explicit mention of workspace support. It's primarily designed for project files, so for workspace manipulation, you may need to inspect the source code or use additional libraries.

What's the easiest way to get started with XcodeProj for scripting?

Use swift-sh to create Swift scripts, as demonstrated in the README. Import XcodeProj, load the project with XcodeProj(path:), make modifications via the API, and write back with write(path:).

Are there any known limitations or unsupported Xcode features?

While it covers most project structures, newer Xcode features or edge cases might not be fully supported. It's advisable to test with your specific project and check the GitHub issue tracker for known compatibility problems.

Open-Awesome

xcproj

MITSwift9.17.6

A Swift library for reading, updating, and writing Xcode project files programmatically.

GitHub

2.2k stars356 forks0 contributors

What is xcproj?

XcodeProj is a Swift library for parsing, modifying, and writing Xcode project files programmatically. It solves the problem of manually editing Xcode projects by providing a code-based interface to read and update project configurations, build settings, and targets. This enables automation of project-related tasks, such as syncing versions or generating projects dynamically.

Target Audience

iOS and macOS developers building tools for project generation, automation, or CI/CD pipelines, as well as teams needing to manage Xcode projects at scale without manual intervention.

Value Proposition

Developers choose XcodeProj because it offers a native Swift implementation for working with Xcode projects, is battle-tested by major tools like Tuist and XcodeGen, and provides a reliable way to automate project management tasks that are error-prone when done manually.

Overview

📝 Read, update and write your Xcode projects

Use Cases

Best For

Automating Xcode project version updates from git tags
Building custom project generation tools for iOS/macOS
Linting Xcode project files for consistency and correctness
Integrating project modifications into CI/CD pipelines
Creating Swift scripts to manage build settings dynamically
Developing plugins or extensions that interact with Xcode project structure

Not Ideal For

Projects managed entirely through Xcode's GUI without any automation needs
Teams using cross-platform build systems like Bazel or CMake that bypass Xcode project files
Developers writing quick, one-off scripts in non-Swift languages like Python or Ruby
Environments where integrating a Swift library adds unnecessary complexity for minor, infrequent edits

Pros & Cons

Pros

Wide Industry Adoption

Used by major tools like Tuist, XcodeGen, and Sourcery, indicating reliability and thorough testing in real-world automation scenarios.

Swift-Native Integration

Built entirely in Swift, it seamlessly works with Swift Package Manager and scripting tools like swift-sh, as shown in the installation examples.

Comprehensive Project Control

Provides full programmatic access to parse, modify, and write Xcode project files, enabling automation of complex tasks like version syncing from git tags.

Active Community Maintenance

With 47 contributors and regular updates indicated by badges, the project is actively maintained to keep pace with Xcode changes.

Cons

Swift Ecosystem Dependency

Requires the Swift toolchain and Package Manager, making it inaccessible for teams not using Swift or preferring polyglot automation setups.

Xcode Format Volatility

Relies on reverse-engineered Xcode project formats that can change with Apple updates, risking breakage in automation scripts without timely library updates.

Limited Documentation Depth

The README provides basic examples, but comprehensive API documentation is sparse, forcing developers to rely on source code or external references for advanced use.

Frequently Asked Questions

Related Projects

SwiftGen

The Swift code generator for your assets, storyboards, Localizable.strings, … — Get rid of all String-based APIs!

Stars9,541

Forks763

Last commit7 days ago

XcodeGen

A Swift command line tool for generating your Xcode project

Stars8,881

Forks919

Last commit10 days ago

Tuist

Your platform team, as a service

Better Codable through Property Wrappers

Stars1,803

Forks83

Last commit2 years ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub