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

> Follow these BitChat build instructions to compile the macOS and iOS app from source using Xcode or the just command-line tool. Build without code signing.

- Repository: [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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](https://github.com/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**:

   ```bash
   open bitchat.xcodeproj
   ```

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

3. **Build without signing** using `xcodebuild`:

   ```bash
   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`](https://github.com/permissionlesstech/bitchat/blob/main/Justfile#L33-L35). The build outputs to a local `.DerivedData` directory without modifying source files.

4. **Launch the built app**:

   ```bash
   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`](https://github.com/permissionlesstech/bitchat/blob/main/Justfile#L49-L55) to ensure no tracked source files are touched.

### Typical Development Workflow

```bash

# 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:

```bash
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`](https://github.com/permissionlesstech/bitchat/blob/main/README.md#L14-L24).

### Customizing iOS Simulator Selection

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

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

```

Then modify the `test-ios` command in your local environment. See [`README.md#L41-L45`](https://github.com/permissionlesstech/bitchat/blob/main/README.md#L41-L45) for details.

### Verifying Source Integrity

Before building, optionally verify the source using [`SOURCE-MANIFEST.txt`](https://github.com/permissionlesstech/bitchat/blob/main/SOURCE-MANIFEST.txt):

```bash

# Follow the cryptographic verification steps in

cat docs/VERIFYING-A-BUILD.md

```

This procedure is outlined in [`docs/VERIFYING-A-BUILD.md#L17-L31`](https://github.com/permissionlesstech/bitchat/blob/main/docs/VERIFYING-A-BUILD.md#L17-L31) and provides tamper-evident assurance for security-conscious builds.

## Key Build Files Reference

| File Path | Role |
|-----------|------|
| [`Justfile`](https://github.com/permissionlesstech/bitchat/blob/main/Justfile) | Command definitions for `just check`, `just build`, `just run`, etc. |
| [`bitchat.xcodeproj/project.pbxproj`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat.xcodeproj/project.pbxproj) | Xcode project configuration with macOS and iOS schemes |
| [`Configs/Local.xcconfig.example`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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.