Firefox for iOS - Comprehensive Deployment and Usage Guide

Prerequisites

Required Tools

• Xcode 26.2 or later (available on the App Store)
• Swift 6.2 or later
• iOS 15.0+ for deployment
• macOS (required for iOS development)

System Requirements

• Ensure xcode-select -p points to /Applications/Xcode.app/Contents/Developer
• Sufficient disk space (this is a large repository)

Installation

Automatic Installation (Recommended)

1. Install the fxios tool (Mozilla's repository management tool):

brew tap mozilla-mobile/fxios
brew install fxios

2. Set up the repository:

# For the main repository (HTTPS)
fxios setup --https

# For a fork (SSH)
fxios setup --ssh --with-fork <fork-url>

Manual Installation

1. Clone the repository:

git clone https://github.com/mozilla-mobile/firefox-ios.git
cd firefox-ios

2. Install dependencies (follow project-specific instructions):
   • Navigate to firefox-ios/firefox-ios for Firefox
   • Navigate to firefox-ios/focus-ios for Focus

Configuration

Environment Setup

• No specific environment variables are required for local development
• For SPM (Swift Package Manager) issues, reset package caches:
  • Xcode → File → Packages → Reset Package Caches

Project-Specific Configuration

Firefox iOS

1. Open Client.xcodeproj in the firefox-ios/firefox-ios folder
2. Select the Fennec scheme in Xcode

Focus iOS

1. Open Blockzilla.xcodeproj in the firefox-ios/focus-ios folder
2. Build the Focus scheme in Xcode

Build & Run

Development Build

Firefox iOS

# Open in Xcode
open firefox-ios/firefox-ios/Client.xcodeproj

# Select Fennec scheme
# Build and run using Cmd+R

Focus iOS

# Open in Xcode
open firefox-ios/focus-ios/Blockzilla.xcodeproj

# Select Focus scheme
# Build and run using Cmd+R

Production Build

• Use Xcode's Archive feature (Cmd+Shift+Option+K)
• Select appropriate provisioning profiles
• Export for distribution

Deployment

Distribution Platforms

• App Store: Primary distribution method
• TestFlight: For beta testing
• Enterprise Distribution: For internal testing

Deployment Requirements

• Apple Developer Account
• Valid provisioning profiles
• App Store Connect access

Deployment Steps

1. Archive the project in Xcode
2. Validate the archive
3. Upload to App Store Connect
4. Submit for review

Troubleshooting

Common Issues and Solutions

SPM Dependency Issues

Problem: Swift Package Manager dependencies fail to resolve Solution: Reset package caches

# In Xcode
File → Packages → Reset Package Caches

Build Failures

Problem: Compilation errors Solutions:

• Ensure Xcode version matches requirements (26.2+)
• Verify Swift version (6.2+)
• Clean build folder (Cmd+Shift+K)
• Reset simulator

Simulator Issues

Problem: App doesn't launch on simulator Solutions:

• Restart Xcode
• Reset simulator content and settings
• Try a different simulator device

Code Signing Issues

Problem: Code signing fails during build Solutions:

• Check provisioning profiles in Xcode
• Ensure Apple Developer account is active
• Verify team selection in project settings

Getting Help

• Chat: Join #fx-ios or #focus-ios on Element
• GitHub: Open issues or discussions on the repository
• Documentation: Refer to the Contributing guidelines

Performance Tips

• Use the latest Xcode version
• Keep Swift compiler up to date
• Monitor memory usage during development
• Use Instruments for performance analysis

Development Best Practices

• Follow the Mozilla Community Participation Guidelines
• Read the Contributing guidelines before contributing
• Use feature flags appropriately (see FeatureFlaggable protocol usage)
• Test on multiple iOS versions and devices