Skip to main content
Get your development environment ready to contribute to Ora Browser. This guide covers everything from prerequisites to running the app locally.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • macOS 14.0 or later
  • Xcode 15 or later (with Swift 5.9+)
  • Homebrew - Install from brew.sh
The minimum deployment target is currently macOS 15.0 as specified in project.yml. Make sure your development machine meets this requirement.

​
Quick Start

1

Clone the Repository

Fork the repository on GitHub, then clone your fork locally:
git clone https://github.com/YOUR_USERNAME/browser.git
cd browser
Replace YOUR_USERNAME with your GitHub username.
2

Run Setup Script

The setup script installs all required tools, configures git hooks, and generates the Xcode project:
./scripts/setup.sh
This script will:
  • Check and install required Homebrew packages
  • Install xcodegen, swiftlint, swiftformat, xcbeautify, and lefthook
  • Set up git hooks for automatic formatting and linting
  • Generate the Xcode project from project.yml
3

Open in Xcode

Open the generated Xcode project:
open Ora.xcodeproj
4

Build and Run

In Xcode:
  1. Select the ora scheme from the scheme selector
  2. Press ⌘R (Product → Run) to build and launch the app
Alternatively, build from the command line:
xcodebuild -scheme ora -destination "platform=macOS"

​
Development Tools

​
XcodeGen

Ora uses XcodeGen to generate the Xcode project from project.yml. This ensures consistent project configuration across all contributors. When to regenerate:
  • After modifying project.yml
  • After pulling changes that update project configuration
  • When adding new files or targets
xcodegen
Never manually edit Ora.xcodeproj settings in Xcode. Always edit project.yml and regenerate the project.

​
SwiftFormat

Automatic code formatting is handled by SwiftFormat. It runs automatically via git hooks, but you can also run it manually: 
swiftformat . --quiet

​
SwiftLint

Code quality and style enforcement is handled by SwiftLint. It also runs automatically via git hooks: 
swiftlint --quiet
To automatically fix issues: 
swiftlint --fix

​
Lefthook

Lefthook manages git hooks. The configuration in lefthook.yml ensures code quality before commits and pushes: Pre-commit hooks:
  • Run SwiftFormat on staged files
  • Run SwiftLint on staged files
  • Automatically stage fixed files
Pre-push hooks:
  • Build the project to catch compilation errors
To reinstall hooks: 
lefthook install

​
Running Tests

Ora includes unit and UI tests to ensure code quality.

​
In Xcode

Press ⌘U (Product → Test) to run all tests.

​
Command Line

Run tests via xcodebuild: 
xcodebuild test -scheme ora -destination "platform=macOS"
All new features should include appropriate tests, and existing tests must continue to pass before submitting a pull request.

​
Build Configurations

Ora has two build configurations defined in project.yml:

​
Debug

  • Uses OraIconDev app icon (distinguishes debug builds)
  • Enables hot reloading via InjectionIII
  • Sets EMIT_FRONTEND_COMMAND_LINES = YES for InjectionIII compatibility
  • Adds -Xlinker -interposable for runtime function replacement
  • Uses ora-debug.entitlements

​
Release

  • Uses OraIcon production app icon
  • No hot reloading support
  • Optimized for performance
  • Uses ora.entitlements

​
Common Issues

​
Homebrew Packages Not Found

If the setup script can’t find required packages, ensure Homebrew is in your PATH: 
eval "$(/opt/homebrew/bin/brew shellenv)"
Add this line to your ~/.zshrc or ~/.bash_profile.

​
Xcode Project Out of Sync

If Xcode shows unexpected errors or missing files:
  1. Close Xcode
  2. Regenerate the project: xcodegen
  3. Reopen Xcode

​
Build Errors After Pulling Changes

Try these steps:
  1. Clean build folder: ⇧⌘K (Product → Clean Build Folder)
  2. Regenerate project: xcodegen
  3. Restart Xcode

​
Git Hooks Not Running

Reinstall lefthook hooks: 
lefthook install

​
Next Steps

Project Architecture

Learn about Ora’s architecture and code organization

Hot Reloading

Set up InjectionIII for instant SwiftUI updates

Contributing Guidelines

Read the contribution guidelines and workflow

Architecture Guide

Learn about the codebase architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us