Xproject

A modern Swift command line tool for Xcode project build automation.

Installation & Usage

No external dependencies required! Xproject runs with just Xcode's built-in Swift tooling.

Requirements

Swift 6.2+ (included with Xcode 16.4+)
macOS 15+ (specified in Package.swift platforms)

Quick Start

Install from GitHub Releases (recommended):

curl -L https://github.com/diogot/Xproject/releases/latest/download/xp-macos-universal.tar.gz | tar xz
sudo mv xp /usr/local/bin/
xp --version

Or build from source:

git clone https://github.com/diogot/Xproject.git
cd Xproject
swift build -c release
sudo cp .build/release/xp /usr/local/bin/

Create Xproject.yml in your project root:

This is the only required configuration file. Create it with:

# Minimal configuration (required)
app_name: MyApp
project_path:
  ios: MyApp.xcodeproj

# Test configuration (for xp test)
xcode:
  tests:
    schemes:
      - scheme: MyApp
        build_destination: "generic/platform=iOS Simulator"
        test_destinations:
          - platform=iOS Simulator,name=iPhone 16 Pro

Required fields:

app_name - Your app's name
project_path - Map of target names to .xcodeproj paths

Optional features (add as needed):

# Homebrew dependencies
setup:
  brew:
    formulas:
      - swiftlint

# Release builds
xcode:
  release:
    production-ios:
      scheme: MyApp
      configuration: Release
      destination: iOS

See also:

Configuration Reference - Complete list of all options
Environment Setup - xcconfig and Swift code generation
Secrets Management - EJSON encryption
Provision Management - Provisioning profiles for CI/CD

Run commands:

# Show help
xp --help

# Setup project
xp setup

# Build project for testing
xp build --scheme MyApp --clean

# Run tests
xp test --scheme MyApp --clean

# Create release
xp release production-ios

Available Commands

xp setup - Setup project dependencies and environment
xp build - Build the Xcode project for testing
xp test - Run unit tests with multi-destination support
xp release - Create release builds with archive, IPA generation, and App Store upload
xp clean - Remove build artifacts and test reports directories
xp config - Manage and validate project configuration
xp env - Manage environment configurations (dev, staging, production)
xp secrets - Manage encrypted secrets with EJSON and XOR obfuscation
xp version - Manage semantic versioning and build numbers
xp provision - Manage encrypted provisioning profiles for CI/CD
xp pr-report - Post build/test results to GitHub PRs via Checks API

Global Options

All commands support the following global options:

-C, --working-directory <path> - Working directory for the command (default: current directory)
-c, --config <path> - Specify custom configuration file (default: auto-discover Xproject.yml, rake-config.yml)
-v, --verbose - Show detailed output and commands being executed
--dry-run - Show what would be done without executing (available on most commands)

Command Examples

# Run from any directory with -C flag
xp -C /path/to/project config show
xp --working-directory MyProject build

# Use custom configuration file
xp test --config my-project.yml --dry-run

# Run tests with specific options
xp test --scheme MyApp --clean --destination "platform=iOS Simulator,OS=18.5,name=iPhone 16 Pro"

# Setup with dry-run preview
xp setup --dry-run

# Clean build artifacts
xp clean --dry-run

# Validate configuration
xp config validate

# Show current configuration with verbose output
xp config show --verbose

# Create release builds
xp release production-ios
xp release dev-ios --archive-only
xp release staging-ios --skip-upload --dry-run

# Environment management
xp env list
xp env load dev --dry-run
xp env load production
xp env show dev

# Secret management
xp secrets generate-keys dev
xp secrets generate dev
xp secrets encrypt
xp secrets show dev
xp secrets decrypt dev  # Dev only

# Version management
xp version show
xp version bump patch
xp version commit
xp version tag --environment production
xp version push

# PR reporting (GitHub Actions)
xp pr-report                          # Auto-discover xcresult bundles
xp pr-report --check-name "iOS Tests" # Custom check name
xp pr-report --dry-run                # Preview without posting

Environment Management

Xproject includes a powerful environment management system for handling multiple deployment environments (dev, staging, production, etc.) with automatic .xcconfig file generation.

Quick Setup

Create environment configuration (env/config.yml):

targets:
  - name: MyApp
    xcconfig_path: MyApp/Config
    shared_variables:
      PRODUCT_BUNDLE_IDENTIFIER: apps.bundle_identifier
      BUNDLE_DISPLAY_NAME: apps.display_name
      API_URL: api_url
    configurations:
      debug: {}
      release:
        variables:
          PROVISIONING_PROFILE_SPECIFIER: apps.ios.provision_profile

Create environment files:

# env/dev/env.yml
environment_name: development
api_url: https://dev-api.example.com

apps:
  bundle_identifier: com.example.myapp.dev
  display_name: MyApp Dev
  ios:
    app_icon_name: AppIcon
    provision_profile: Development

Create output directory and activate:
```
mkdir -p MyApp/Config
xp env load dev
```

Features

Configuration-driven: Define targets and variable mappings in YAML, no hardcoded paths
Nested YAML structure: Access values with dot notation (apps.ios.bundle_identifier)
Bundle ID suffixes: Automatic suffix appending for app extensions (.widget, .notification-content)
Per-configuration overrides: Different variables for debug vs release builds
Multiple targets: Support for main app + extensions (widgets, notification extensions, etc.)
Swift code generation: Type-safe Swift files with namespace filtering, camelCase conversion, and automatic type inference
Validation: Comprehensive validation of configuration and environment files
Dry-run mode: Preview xcconfig and Swift generation without writing files

Available Commands

xp env list                    # List available environments
xp env show [name]             # Display environment variables
xp env current                 # Show currently activated environment
xp env load <name>         # Activate environment and generate xcconfigs
xp env validate                # Validate environment configuration

Generated Files

When you activate an environment, Xproject generates .xcconfig files for each target and configuration:

MyApp/Config/
├── MyApp.debug.xcconfig       # Debug configuration
└── MyApp.release.xcconfig     # Release configuration

These files contain your environment-specific variables:

// Generated by xp env load dev
// Target: MyApp
// Configuration: release
API_URL = https://dev-api.example.com
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon
BUNDLE_DISPLAY_NAME = MyApp Dev
PRODUCT_BUNDLE_IDENTIFIER = com.example.myapp.dev
PROVISIONING_PROFILE_SPECIFIER = Development

Xcode Integration

In Xcode, select your project → target → Info tab
Under Configurations, set:
- Debug → MyApp.debug.xcconfig
- Release → MyApp.release.xcconfig

Build settings from xcconfig files will override project settings.

Swift Code Generation (Optional)

Automatically generate type-safe Swift files from environment variables:

# Add to env/config.yml
swift_generation:
  outputs:
    # Base class - automatically includes ALL root-level variables
    - path: MyApp/Generated/EnvironmentService.swift
      prefixes: []
      type: base
    # Extension - specify namespaces to include
    - path: MyApp/Generated/EnvironmentService+App.swift
      prefixes: [apps, features]
      type: extension

Generated Swift code:

public final class EnvironmentService {
    public init() {}
    public let apiURL = url("https://dev-api.example.com")
    public let environmentName = "development"
}

extension EnvironmentService {
    public var bundleIdentifier: String { "com.example.myapp.dev" }
    public var debugMenu: Bool { true }
}

.gitignore Recommendations

Add these to your .gitignore:

# Environment management
env/.current
**/Config/*.xcconfig
**/Generated/EnvironmentService*.swift  # If using Swift generation

Documentation: See docs/environment-setup.md for detailed setup guide and advanced features.

Secret Management

Xproject includes a dual-layer security system for managing API keys and secrets:

Layer 1: EJSON encryption (at-rest) - Secrets encrypted in repository using asymmetric cryptography
Layer 2: XOR obfuscation (in-binary) - Prevents extraction from compiled app with strings command

Quick Start

Configure in your Xproject.yml:

secrets:
  swift_generation:
    outputs:
      - path: MyApp/Generated/AppKeys.swift
        prefixes: [all, ios]

Create encrypted secrets file (env/dev/keys.ejson):

{
  "_public_key": "a1b2c3d4...",
  "shopify_api_key": "EJ[1:...]",
  "mux_key": "EJ[1:...]"
}

Generate obfuscated Swift code:

xp env load dev  # Automatically generates AppKeys.swift
# or manually:
xp secrets generate dev

Features

Dual-layer protection: EJSON (repo) + XOR

Xproject

Install / Use

README

Xproject

Installation & Usage

Requirements

Quick Start

Available Commands

Global Options

Command Examples

Environment Management

Quick Setup

Features

Available Commands

Generated Files

Xcode Integration

Swift Code Generation (Optional)

.gitignore Recommendations

Secret Management

Quick Start

Features