How to Set Up the Development Environment for Bitchat: Complete Swift Setup Guide

Set up the bitchat development environment by cloning the repository, installing Xcode 15+ and Swift 5.9, configuring Local.xcconfig from the example, and building with just build or Xcode.

Bitchat is a Swift-based, peer-to-peer messaging application that supports iOS, macOS, and optional Tor networking via the Arti XCFramework. This guide walks through the complete development environment setup for contributing to or extending permissionlesstech/bitchat, using the repository's documented workflow and tooling.

Prerequisites for Bitchat Development

Before cloning the repository, ensure your system meets these requirements:

• Xcode 15 or later with Swift 5.9+
• Swift Package Manager (bundled with Xcode)
• just command runner (optional but recommended): brew install just
• Git for source control

The bitchat project uses SPM for dependency management and includes pre-built local packages in the localPackages/ directory.

Step 1: Clone and Open the Repository

Fetch the source code and open the Xcode project:

git clone https://github.com/permissionlesstech/bitchat.git
cd bitchat
open bitchat.xcodeproj

The bitchat.xcodeproj file is generated from the Swift package manifest. Opening it triggers automatic package resolution for dependencies declared in Package.swift.

Step 2: Configure Local Build Settings

Bitchat uses xcconfig files for environment-specific build variables. Create your local configuration from the provided template:

cp Configs/Local.xcconfig.example Configs/Local.xcconfig

Open Configs/Local.xcconfig to customize:

• API endpoint URLs
• Feature flags
• Compiler definitions

This file is gitignored by default, preventing accidental commits of local credentials or debug settings.

Step 3: Enable Clear-Net for Faster Local Testing (Optional)

By default, bitchat routes all traffic through Tor using the Arti framework. For rapid iteration on simulators or trusted local networks, you can disable Tor with the BITCHAT_DEV_ALLOW_CLEARNET flag.

Add to Configs/Local.xcconfig:

BITCHAT_DEV_ALLOW_CLEARNET = YES

Warning: As documented in [docs/TOR-INTEGRATION.md](https://github.com/permissionlesstech/bitchat/blob/main/docs/TOR-INTEGRATION.md), this exposes your traffic to network observers. Never use this flag in production builds or when testing with sensitive data.

Step 4: Resolve Swift Packages

Xcode automatically resolves dependencies on first build. To resolve manually via command line:

swift package resolve

The Package.swift manifest declares three local packages:

• BitLogger – structured logging utilities
• BitFoundation – shared data types and extensions
• Arti – pre-built Tor client XCFramework in localPackages/Arti/

No additional steps are needed for the Arti framework; Xcode links it automatically via the package manifest.

Step 5: Build and Run Bitchat

Using Xcode

Select your target platform (iOS Simulator or macOS) and press ⌘ R to build and run.

Using Just Commands

The Justfile provides consistent shortcuts for common tasks:

# Build the default scheme

just build

# Run the full test suite

just test

# Build and launch iOS simulator

just run-ios

All targets are defined in the repository's Justfile, which wraps xcodebuild with sensible defaults.

Step 6: Run Tests

Execute the comprehensive XCTest suites covering protocol handling, view models, and BLE mesh logic:

just test

Or run specific tests with xcodebuild:

xcodebuild test \
  -scheme bitchat \
  -destination 'platform=iOS Simulator,name=iPhone 15,OS=latest' \
  -only-testing:bitchatTests/ChatViewModelTests

Test files reside in bitchatTests/ with mirror structure to the source tree.

Step 7: Verify Build Reproducibility (Recommended)

For production builds or security audits, follow [docs/VERIFYING-A-BUILD.md](https://github.com/permissionlesstech/bitchat/blob/main/docs/VERIFYING-A-BUILD.md). This ensures your compiled binary matches the published source exactly—a critical step for a privacy-focused messaging app.

Key Project Structure

Understanding where code lives accelerates development:

Directory	Purpose
bitchat/Services/	Core networking stack (Nostr transport, Noise encryption, gateways)
bitchat/Services/BLE/	Bluetooth Low Energy mesh networking implementation
bitchatTests/	XCTest suites for unit and integration testing
Configs/	Build configuration templates and local overrides
localPackages/	Vendored dependencies including Arti.xcframework

Rapid Development Workflow Example

Complete setup from fresh clone to running tests:

# 1. Clone

git clone https://github.com/permissionlesstech/bitchat.git && cd bitchat

# 2. Configure

cp Configs/Local.xcconfig.example Configs/Local.xcconfig

# Edit Local.xcconfig to add: BITCHAT_DEV_ALLOW_CLEARNET = YES

# 3. Build and test

just build
just test

# 4. Launch in simulator

just run-ios

Summary

• Install Xcode 15+ with Swift 5.9 to meet baseline requirements
• Copy Local.xcconfig from the example file to enable customizable builds
• Add BITCHAT_DEV_ALLOW_CLEARNET = YES for clear-net development speed (never for release)
• Use just commands for reproducible builds, tests, and simulator launches
• Reference Package.swift for dependency structure and Justfile for automation
• Verify release builds per docs/VERIFYING-A-BUILD.md for binary authenticity

Frequently Asked Questions

What happens if I skip the Local.xcconfig step?

The build will fail with missing configuration values. The Configs/Local.xcconfig.example template provides required placeholder definitions that Xcode expects during compilation. Without creating Local.xcconfig, preprocessor macros and bundle identifiers remain undefined.

Can I develop bitchat without Tor?

Yes, but only for development. Set BITCHAT_DEV_ALLOW_CLEARNET = YES in Local.xcconfig to route traffic directly over HTTPS instead of through the Arti Tor client. This dramatically improves build-test cycles but removes anonymity protections. The flag is compile-time only and disabled in release configurations.

Do I need to rebuild the Arti XCFramework?

No. The pre-built Arti.xcframework in localPackages/Arti/ is ready for immediate use. Rebuilding requires Rust toolchain setup and is unnecessary for application development. The Swift package in Package.swift handles linking automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}