Build XCFrameworks from Xcode projects or Swift Packages across Apple platforms

Status: ✅ Production Ready for iOS | 🚧 Other platforms in development

XCFramework CLI is a Ruby gem that automates XCFramework creation from Xcode projects and Swift Packages. It handles the complexity of multi-platform builds, custom configurations, and resource management through simple configuration files and CLI commands.

Perfect for:

• Publishing framework libraries across Apple platforms
• Distributing SDKs with resource bundles (fonts, images, themes)
• Automating CI/CD pipelines for framework distribution
• Managing complex build settings per platform

• ✅ Xcode Projects - Build from .xcodeproj or .xcworkspace
• ✅ Swift Packages - Build from Package.swift
• ✅ iOS Support - iOS device (arm64) and Simulator (arm64, x86_64)
• ✅ Resource Bundles - Fonts, images, JSON themes with Bundle.module
• ✅ Configuration Files - YAML/JSON with validation
• ✅ Custom Build Settings - Override Xcode defaults per framework
• ✅ Beautiful Output - Colored build logs with xcbeautify/xcpretty
• ✅ Error Handling - Helpful suggestions for common issues
• 🚧 Platform Expansion - macOS, tvOS, watchOS, visionOS, Catalyst (Phase 2)

git clone https://github.com/phuongddx/xcframework-cli.git
cd xcframework-cli
bundle install

# Verify installation
./bin/xckit version

Requirements:

• Ruby 3.0+
• Xcode 12+ with command-line tools
• Bundler (gem install bundler)

Optional (better output):

brew install xcbeautify  # Xcode build formatter

Create .xcframework.yml in your project root:

project:
  name: MySDK
  xcode_project: MySDK.xcodeproj

frameworks:
  - name: MySDK
    scheme: MySDK
    platforms: [ios, ios-simulator]
    deployment_targets:
      ios: "14.0"

build:
  output_dir: build
  configuration: Release
  clean_before_build: true

./bin/xckit build --config .xcframework.yml

Output: build/MySDK.xcframework/ ready for distribution

./bin/xckit build \
  --project MySDK.xcodeproj \
  --scheme MySDK \
  --framework-name MySDK \
  --platforms ios ios-simulator

./bin/xckit spm build \
  --package-dir . \
  --platforms ios ios-simulator \
  --output-dir build

./bin/xckit build --config .xcframework.yml --verbose

./bin/xckit init
# Follow prompts to generate .xcframework.yml

project:
  name: MyFramework
  xcode_project: MyFramework.xcodeproj

frameworks:
  - name: MyFramework
    scheme: MyFramework
    platforms: [ios, ios-simulator]
    deployment_targets:
      ios: "14.0"
    architectures:
      ios: [arm64]
      ios-simulator: [arm64, x86_64]

build:
  output_dir: build
  configuration: Release
  clean_before_build: true
  verbose: false
  build_settings:
    OTHER_SWIFT_FLAGS: "-no-verify-emitted-module-interface"
    EXCLUDED_ARCHS: "x86_64"

spm:
  package_dir: "."
  targets: [MyLibrary]
  platforms: [ios, ios-simulator]
  library_evolution: true
  version: "14.0"

build:
  output_dir: "./build"
  configuration: Release

See config/examples/ for additional examples and use cases.

Online Documentation: xcframework-cli.vercel.app

The documentation site is built with Next.js + Nextra and automatically deployed to Vercel.

Prerequisites:

• Node.js 20.17.0 (specified in .nvmrc)
• Vercel CLI (optional): npm i -g vercel

Automatic Deployment (Recommended):

1. Connect repository to Vercel:

   • Visit vercel.com
   • Import project from GitHub: phuongddx/xcframework-cli
   • Vercel auto-detects Next.js framework

2. Configure project settings:

   • Root Directory: docs-site
   • Build Command: npm run build
   • Output Directory: .next
   • Node.js Version: 20.x

3. Deploy on push:

   • Every push to main triggers automatic deployment
   • Preview deployments for pull requests

Manual Deployment:

# Install Vercel CLI
npm i -g vercel

# Deploy from repository root
vercel

# Deploy to production
vercel --prod

GitHub Pages vs Vercel:

This project uses Vercel for documentation hosting. GitHub Pages configuration exists in .github/workflows/ but Vercel provides:

• Automatic preview deployments for PRs
• Faster builds and global CDN
• Built-in analytics and performance monitoring

To switch to GitHub Pages, disable Vercel integration and update the docs URL in README.md.

Phase 1 (Current): Foundation ✅

• iOS and iOS Simulator platforms fully implemented
• Xcode project and SPM builds working
• 280+ test cases with 80% coverage
• Configuration validation and error handling
• Resource bundle support (in progress)

Phase 2 (Planned): Platform Expansion

• macOS, tvOS, watchOS, visionOS, Catalyst support
• Template-based resource compilation
• Advanced caching and optimization

See Example/epost-ios-theme-ui/ for a production-ready UIKit framework using XCFramework CLI. Demonstrates:

• Complex resource management (fonts, images, themes)
• Custom build settings and workarounds
• Multi-platform configuration
• Integration with CI/CD

# Show all commands
./bin/xckit --help

# Show specific command help
./bin/xckit build --help

# Verbose output for debugging
./bin/xckit build --config .xcframework.yml -v

Module interface verification error:

build_settings:
  OTHER_SWIFT_FLAGS: "-no-verify-emitted-module-interface"

x86_64 simulator build failure (Apple Silicon):

build_settings:
  EXCLUDED_ARCHS: "x86_64"

Framework not found in archive: Check that scheme name matches framework name and scheme builds the target.

Copyright © 2025 AAVN. All rights reserved.

Repository: github.com/phuongddx/xcframework-cli