Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/permissionlesstech/bitchat/llms.txt

Use this file to discover all available pages before exploring further.

Building Bitchat requires a Mac with full Xcode installed — Command Line Tools alone are not sufficient. The project targets macOS 13+ and iOS 16+, and all build recipes keep artifacts in a repository-local .DerivedData/ directory so nothing spills into your system Xcode caches.

​
Prerequisites

  • Full Xcode — install from the Mac App Store. Command Line Tools (xcode-select --install) are not enough; xcodebuild must resolve to a full Xcode installation. If you have both, point the selector at Xcode: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer.
  • just (optional but recommended) — a command runner that wraps the common xcodebuild invocations in short, memorable aliases:
brew install just
Run just check first to confirm your environment is ready, then use whichever recipe you need: 
just check              # Validate the development environment
just build              # Build macOS app without signing
just run                # Build and run the macOS app
just dev-run            # Alias for just run (backward-compatible)
just test               # Run the SwiftPM test suite
just test-ios           # Run tests on iPhone 17 simulator
just clean              # Remove repo-local build artifacts only
just nuke               # Also remove nested package build caches
just info               # Print project and platform info
just check-clean-safety # Verify the clean recipe won't touch source files
just build and just run use the bitchat (macOS) scheme and write all output to the ignored .DerivedData/ directory. They never patch source, project, configuration, or entitlement files.
just clean and just nuke never invoke git and never restore or remove tracked files. Both recipes only delete .DerivedData/, .build/, and (for nuke) nested localPackages/.build caches. They are safe to run at any time — uncommitted work is always preserved.

​
Using Xcode

Open the project file directly from the repository root: 
open bitchat.xcodeproj
Select a scheme (bitchat (macOS) or bitchat (iOS)) from the scheme picker in the Xcode toolbar, then use Product → Build (⌘B) or Product → Run (⌘R) as usual.

​
Code Signing for Device Builds

Simulator and unsigned builds work without any Apple Developer account. For signed builds targeting a physical device, create a local configuration file from the provided example: 
cp Configs/Local.xcconfig.example Configs/Local.xcconfig
Open Configs/Local.xcconfig and replace the placeholder team ID with your own Apple Developer Team ID. The entitlement files already reference $(APP_GROUP_ID), so no tracked project or entitlement files need to be edited. Local.xcconfig is listed in .gitignore and will never be committed.

​
Command-Line Builds

xcodebuild -project bitchat.xcodeproj -scheme "bitchat (macOS)" -configuration Debug CODE_SIGNING_ALLOWED=NO build
If iPhone 17 is not installed, run the List available simulators command above and substitute a destination that appears in its output.

​
SwiftPM

The repository also has a SwiftPM package (Package.swift) that covers the core logic. You can run the test suite directly without Xcode: 
swift test
This is equivalent to just test and does not require a signing identity or simulator.

​
Build Artifacts

All Xcode builds are directed to .DerivedData/ at the repository root (listed in .gitignore). SwiftPM writes to .build/. Neither directory is tracked.
  • just clean removes .DerivedData/ and .build/
  • just nuke does the same and also removes .build/ directories inside localPackages/ and the .cache/ directory
Bluetooth mesh behavior requires physical Bluetooth-capable devices. Simulators render the full UI correctly, but peers cannot discover or connect to each other over Bluetooth on a simulator — use real hardware to test mesh networking.

Build docs developers (and LLMs) love

Get started for freeTalk to us