How to Run BitChat on Different Operating Systems: macOS, iOS Simulator, and Cross-Platform Workflows

BitChat runs natively on macOS and iOS simulator through Xcode, with streamlined cross-platform commands available via the just task runner.

BitChat is a Swift-based peer-to-peer chat application built by permissionlesstech. Because it relies on Apple-specific frameworks like UIKit, AppKit, and CoreBluetooth, running BitChat requires the Xcode toolchain—limiting native execution to macOS and iOS environments. This guide covers every supported method to run BitChat on different operating systems, from direct Xcode builds to automated just workflows.

---

Running BitChat on macOS

The simplest way to run BitChat is opening bitchat.xcodeproj in Xcode and selecting the "bitchat (macOS)" scheme.

From the Xcode GUI

1. Open bitchat.xcodeproj
2. Select bitchat (macOS) from the scheme dropdown
3. Press ⌘ R to build and run

From the Command Line

xcodebuild -project bitchat.xcodeproj -scheme "bitchat (macOS)" -configuration Debug CODE_SIGNING_ALLOWED=NO build

This compiles the native macOS client without modifying source files or entitlements. The resulting binary is placed in Xcode's DerivedData directory (already ignored by Git).

---

Running BitChat on iOS Simulator

BitChat ships with a dedicated "bitchat (iOS)" scheme for simulator testing.

List Available Simulators

xcodebuild -showdestinations -project bitchat.xcodeproj -scheme "bitchat (iOS)"

Build and Run on a Specific Device

xcodebuild -project bitchat.xcodeproj -scheme "bitchat (iOS)" -destination 'platform=iOS Simulator,name=iPhone 17,OS=latest' test

Replace iPhone 17 with any simulator returned by the showdestinations command. The default target assumes iPhone 17 with the latest OS version.

---

Cross-Platform Workflow with Just

The Justfile provides OS-agnostic shortcuts for developers who prefer command-line workflows or automated builds.

Install Just

brew install just

Available Commands

Command	Action
just check	Run static analysis and lint checks
just run	Build and launch the macOS scheme
just build	Compile macOS scheme without running
just clean	Remove .DerivedData/ and .build/ artifacts
just test	Execute SwiftPM test suite on macOS
just test-ios	Run tests on iPhone 17 simulator

All just commands operate safely—they never modify source files or Git history.

Example Workflow

just check    # Verify code quality

just run      # Launch macOS app

just test-ios # Validate on iOS simulator

just clean    # Clean build artifacts

---

Linux and Windows Limitations

BitChat cannot run natively on Linux or Windows. The codebase depends on Apple-exclusive APIs documented in ARCHITECTURE_V2.md, including:

• UIKit and AppKit for user interfaces
• CoreBluetooth for peer-to-peer networking
• Xcode toolchain for compilation

Developers on non-Apple platforms have three alternatives:

1. macOS virtual machine with Xcode installed
2. CI/CD service providing macOS runners (GitHub Actions, Buildkite)
3. Remote macOS development environment for builds and testing

---

Key Project Files

Understanding these files helps troubleshoot platform-specific issues:

File	Purpose
Justfile	Task automation (just run, just test-ios, etc.)
README.md	Primary documentation for macOS/iOS/just workflows
Package.swift	Swift Package Manager manifest for command-line builds
bitchat.xcodeproj/project.pbxproj	Xcode project definitions for both schemes
bitchatTests/	Test suite executed via just test or just test-ios

---

Summary

• macOS: Open bitchat.xcodeproj and run the bitchat (macOS) scheme, or use just run
• iOS Simulator: Target any simulator with xcodebuild using the bitchat (iOS) scheme, or run just test-ios
• Cross-platform: Install just to abstract Xcode commands across environments
• Linux/Windows: Require macOS VM or CI service due to Apple framework dependencies

---

Frequently Asked Questions

Can I run BitChat on Windows or Linux directly?

No. BitChat requires Apple's UIKit, AppKit, and CoreBluetooth frameworks, which are exclusive to Apple's platforms. You must use a macOS virtual machine, remote macOS environment, or CI service with Xcode support.

What is the fastest way to build and run BitChat?

Use just run from the repository root. This single command triggers the macOS scheme build and launch without opening Xcode, making it ideal for rapid iteration.

How do I run tests on a different iOS simulator?

First list available destinations with xcodebuild -showdestinations, then substitute your device name in the -destination flag. For example: platform=iOS Simulator,name=iPhone 15 Pro,OS=17.5.

Does running BitChat modify source files or Git history?

No. All documented workflows—including direct xcodebuild commands and just tasks—are read-only operations. The just clean command only removes build artifacts in .DerivedData/ and .build/ directories.

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