BitChat Build Instructions: How to Compile the macOS and iOS App from Source

BitChat can be built using either Xcode directly or the just command-line tool, both compiling the macOS target without requiring a code signing identity.

This guide covers the complete BitChat build instructions for developers who want to compile the permissionless messaging app from the permissionlesstech/bitchat repository. Whether you prefer IDE-based workflows or terminal commands, you'll have a runnable binary in minutes.

Building BitChat with Xcode

The repository contains a standard Xcode workspace at bitchat.xcodeproj that supports both macOS and iOS targets.

Prerequisites

• macOS with a full Xcode installation (not just Command Line Tools)
• Xcode 15 or later for simulator support

Step-by-Step Xcode Build

1. Open the project:

   open bitchat.xcodeproj

2. Select the macOS scheme — choose "bitchat (macOS)" from the scheme dropdown.

3. Build without signing using xcodebuild:

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

   This command mirrors the implementation in the Justfile at Justfile#L33-L35. The build outputs to a local .DerivedData directory without modifying source files.

4. Launch the built app:

   open .DerivedData/Build/Products/Debug/bitchat.app

Building BitChat with Just

The repository includes a Justfile that wraps Xcode commands in a repeatable, scriptable interface. This is the preferred method for CI/CD and quick iteration.

Available Just Commands

Command	Purpose
just check	Verifies Xcode installation and prints version
just build	Compiles macOS target with CODE_SIGNING_ALLOWED=NO
just run	Builds and launches the .app
just test	Runs SwiftPM test suite (swift test)
just test-ios	Runs iOS tests on iPhone 17 simulator
just clean	Removes .DerivedData and .build artifacts
just nuke	Deep clean including nested package caches

The clean and nuke recipes are defined in Justfile#L49-L55 to ensure no tracked source files are touched.

Typical Development Workflow

# Verify environment

just check

# Build macOS binary

just build

# Build and run in one step

just run

# Clean rebuild

just clean && just build

# Run test suite

just test

Advanced Build Configuration

Enabling Code Signing for Device Builds

For signed builds on physical devices, create a local configuration file:

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

Edit Configs/Local.xcconfig to inject your Apple Developer Team ID. The template derives APP_GROUP_ID and other identifiers automatically, as documented in README.md#L14-L24.

Customizing iOS Simulator Selection

If the default iPhone 17 simulator is unavailable, list valid destinations:

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

Then modify the test-ios command in your local environment. See README.md#L41-L45 for details.

Verifying Source Integrity

Before building, optionally verify the source using SOURCE-MANIFEST.txt:

# Follow the cryptographic verification steps in

cat docs/VERIFYING-A-BUILD.md

This procedure is outlined in docs/VERIFYING-A-BUILD.md#L17-L31 and provides tamper-evident assurance for security-conscious builds.

Key Build Files Reference

File Path	Role
Justfile	Command definitions for just check, just build, just run, etc.
bitchat.xcodeproj/project.pbxproj	Xcode project configuration with macOS and iOS schemes
Configs/Local.xcconfig.example	Template for signed build configuration

Summary

• Two build paths: Use Xcode GUI for visual debugging or just for terminal-based workflows
• No signing required: CODE_SIGNING_ALLOWED=NO enables immediate development builds
• Located in Justfile: All build logic is transparent and modifiable
• Clean separation: Build artifacts go to .DerivedData, never touching source files
• Verified builds: Optional SOURCE-MANIFEST.txt verification for supply-chain security

Frequently Asked Questions

Do I need an Apple Developer account to build BitChat?

No. The default BitChat build instructions use CODE_SIGNING_ALLOWED=NO, which produces a fully functional macOS binary without any Apple Developer account. You only need a Team ID for signed device builds or App Store distribution.

What is just and why does BitChat use it?

just is a command runner similar to Make but simpler. The Justfile in the BitChat repository encapsulates repetitive Xcode commands into memorable recipes like just build and just run, reducing typing errors and ensuring consistent flags across team members.

Where does the compiled app actually live?

After a successful build, bitchat.app resides at .DerivedData/Build/Products/Debug/bitchat.app. The just run command automatically locates and opens this path. Use just clean or just nuke to remove these artifacts without affecting your source checkout.

Can I build BitChat on Linux or Windows?

No. BitChat is a native macOS and iOS application built with Swift and Xcode. The source code, build system, and UI frameworks are Apple-platform specific. You must build on macOS with a full Xcode installation.

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