Leveraging Xcodegen for Hassle-free iOS Development

Why Use XcodeGen?

Managing Xcode project files manually can quickly become a cumbersome task, especially as projects grow in complexity. With multiple targets, configurations, and dependencies, it's easy for inconsistencies and errors to creep in. XcodeGen addresses these issues by automating the generation of Xcode project files from a configuration file, usually written in YAML or JSON.

Key Benefits:

Consistency Across Teams: XcodeGen ensures that every developer generates the same project structure, minimizing version control conflicts and reducing onboarding time for new team members.
Scalability and Maintainability: As projects evolve, XcodeGen simplifies managing multiple targets and build configurations, making it easier to scale and maintain the project over time.
Reducing Manual Work: By automating the project setup, XcodeGen eliminates the need for tedious manual configuration, reducing the risk of human error.

Current State

In many iOS development teams, managing the Xcode project file (.xcodeproj) manually is the norm. This approach has its drawbacks, particularly in larger teams or projects:

Merge Conflicts: The .xcodeproj file is notorious for generating merge conflicts in version control systems. These conflicts are often difficult to resolve and can lead to wasted time and frustration.
Inconsistent Configurations: When multiple developers manually manage project settings, inconsistencies can arise, leading to unexpected build issues or discrepancies between development environments.
Time-Consuming Processes: Setting up new targets, schemes, or configurations manually can be time-consuming, diverting focus from actual development work.

Our team experienced these issues firsthand. As the project grew, we found ourselves constantly dealing with frustrating conflicts in the .xcodeproj file. The merge conflicts were so frequent and disruptive that they started to slow down our progress significantly. This frustration led us to explore alternatives, and we finally decided to adopt XcodeGen mid-development. It was a game-changer, resolving our conflicts and making the project more manageable.

How Does It Improve Our Development Team?

XcodeGen significantly enhances team productivity and collaboration by addressing several common pain points in iOS development.

Improved Collaboration:

With a single source of truth for the project configuration, XcodeGen minimizes the chances of inconsistencies and conflicts. Team members can work more effectively, knowing that any changes to the project settings are controlled and predictable.

Easier Configuration Management:

Centralizing the project configuration in a project.yml file simplifies making global changes across the project. Whether adding a new target, modifying build settings, or managing dependencies, XcodeGen makes it easy to update and maintain the project.

How to Implement It?

First Configuration of XcodeGen

Getting started with XcodeGen is straightforward. Here’s a step-by-step guide to setting up your first configuration:

Installation:
- Install XcodeGen via Homebrew by running (Alternatively, download and install it from the official GitHub repository):
```
 brew install xcodegen
```
Adding .gitignore:
- Before configuring XcodeGen, ensure that you have a .gitignore file set up in your project. This is crucial to avoid committing the generated .xcodeproj file to your repository.
- Add the following to your .gitignore:
```
 # Ignore Xcode project files
 *.xcworkspace/
 *.xcodeproj/
```

Creating project.yml:

Create a new file named project.yml in the root of your project directory. This file will define the structure and settings of your Xcode project.
Here’s our implementation of project.yml file which defines four targets: App (an iOS application), PukPuk-Tests (a test suite and PukPukIntentsExtension and PukPukIntentsExtensionUI for Extensions (shortcut)

 name: PukPuk
 settings:
  MARKETING_VERSION: '1.0'
  CURRENT_PROJECT_VERSION: 1
 options:
  bundleIdPrefix: com.PukPuk

 targets:
  App:
   type: application
   platform: iOS
   sources: [PukPuk]
   resources: [Resources]
   settings:
    PRODUCT_BUNDLE_IDENTIFIER: com.PukPuk.App
    INFOPLIST_FILE: PukPuk/Info.plist
    GENERATE_INFOPLIST_FILE: true
    base:
     TARGETED_DEVICE_FAMILY: '1' # iPhone only
     SUPPORTED_INTERFACE_ORIENTATIONS: 'UIInterfaceOrientationPortrait' # Portrait only

  PukPuk-Tests:
   type: bundle.unit-test
   platform: iOS
   sources: [PukPuk-Tests]
   dependencies:
    - target: App
   settings:
    base:
     INFOPLIST_FILE: PukPuk/Info.plist
     GENERATE_INFOPLIST_FILE: true
     TEST_HOST: '$(BUILT_PRODUCTS_DIR)/App.app/App'
     BUNDLE_LOADER: '$(TEST_HOST)'

  PukPukIntentsExtension:
   type: app-extension
   platform: iOS
   sources: [PukPukIntentsExtension]
   settings:
    PRODUCT_BUNDLE_IDENTIFIER: com.PukPuk.AppIntentsExtension
    INFOPLIST_FILE: PukPukIntentsExtension/Info.plist
    GENERATE_INFOPLIST_FILE: true
   dependencies:
    - target: App

  PukPukIntentsExtensionUI:
   type: app-extension
   platform: iOS
   sources: [PukPukIntentsExtensionUI]
   settings:
    PRODUCT_BUNDLE_IDENTIFIER: com.PukPuk.AppIntentsExtensionUI
    INFOPLIST_FILE: PukPukIntentsExtensionUI/Info.plist
    GENERATE_INFOPLIST_FILE: true
   dependencies:
    - target: PukPukIntentsExtension

 schemes:
  PukPuk:
   build:
    targets:
     App: all
     PukPuk-Tests: all
     PukPukIntentsExtension: all
     PukPukIntentsExtensionUI: all
   test:
    targets:
     - name: PukPuk-Tests
       gatherCoverageData: true

Generating the Xcode Project:
- To generate the Xcode project based on the project.yml configuration., run:
```
 xcodegen generate
```
Adding ci_post_clone.sh:
- To ensure the project is correctly generated in your CI environment, create a ci_post_clone.sh script in a folder named ci_scripts:
```
 mkdir -p ci_scripts
 touch ci_scripts/ci_post_clone.sh
```

Add the following content to ci_post_clone.sh:

 #!/bin/bash

 # Exit immediately if a command exits with a non-zero status
 set -e

 # Print commands and their arguments as they are executed
 set -x

 # Install Homebrew if it's not already installed
 if ! command -v brew &>/dev/null; then
    echo "Homebrew not found. Installing Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 fi

 # Install xcodegen if it's not already installed
 if ! command -v xcodegen &>/dev/null; then
    echo "xcodegen not found. Installing xcodegen..."
    brew install xcodegen
 fi

 # Clean any previous builds or project files
 echo "Cleaning previous builds..."
 rm -rf ./build
 rm -rf ./DerivedData
 rm -rf ./YourProject.xcodeproj

 echo "Moving to the project directory..."
 cd ../
 # Generate the Xcode project using xcodegen
 echo "Generating Xcode project..."
 xcodegen generate

 # # Install CocoaPods dependencies if your project uses CocoaPods
 # if [ -f "Podfile" ]; then
 #  echo "Installing CocoaPods dependencies..."
 #  pod install
 # fi

 echo "Pre-build setup complete!"

Make sure to set the script as executable:
```
 chmod +x ci_scripts/ci_post_clone.sh
```
This script ensures that every time the CI pipeline runs, it installs XcodeGen and generates the project before building.

Conclusion

XcodeGen is a powerful tool for automating and streamlining iOS project management, offering significant benefits in terms of consistency, maintainability, and collaboration. By integrating XcodeGen into your development workflow, you can reduce manual work, minimize errors, and improve team productivity. Whether you're working on a small project or a large-scale app with multiple targets and configurations, XcodeGen is a must-have tool for modern iOS development.

Blog