Key Configuration Files in Bitchat: A Complete Guide to Swift Package and Build Settings

Bitchat uses nine essential configuration files—located in Package.swift, Configs/, entitlements, and project root—to manage Swift package dependencies, build variants, code signing, linting, and static analysis.

The permissionlesstech/bitchat repository follows standard iOS/macOS development patterns with a configuration hierarchy that separates production defaults from developer-specific overrides. Understanding these files is critical for building, signing, and contributing to the app.

Package.swift: Swift Package Manager Entry Point

Package.swift sits at the repository root and declares everything the Swift Package Manager (SPM) needs to resolve dependencies and build targets.

According to the bitchat source code, this file defines:

• Platforms: Minimum iOS and macOS deployment versions
• Products: The executable and library outputs
• Dependencies: External Swift packages
• Targets: Source modules and their interdependencies

Any contributor modifying dependencies or adding new modules must edit this file. SPM regenerates the Xcode project integration automatically when Package.resolved changes.

Build Configuration Files in Configs/

The Configs/ directory contains a layered xcconfig system inspired by Apple's build setting inheritance patterns.

Release.xcconfig

Configs/Release.xcconfig holds production-grade build settings referenced by multiple targets. Key values defined here include:

• MARKETING_VERSION — The user-facing app version
• IPHONEOS_DEPLOYMENT_TARGET / MACOSX_DEPLOYMENT_TARGET — Minimum OS versions
• PRODUCT_BUNDLE_IDENTIFIER — Base bundle ID pattern
• DEVELOPMENT_TEAM — Apple Developer Team ID placeholder
• APP_GROUP_ID — Shared container identifier for app extensions

As implemented in bitchat.xcodeproj/project.pbxproj, release builds inherit directly from this file.

Debug.xcconfig

Configs/Debug.xcconfig extends Release.xcconfig with development-specific behavior. It conditionally includes an optional override:

// Debug.xcconfig includes this directive:
// #include? "Local.xcconfig"
//
// The '?' makes the include optional—builds succeed without it.

This layering ensures debug builds match release settings unless explicitly overridden.

Local.xcconfig.example

Configs/Local.xcconfig.example provides a template for per-developer customizations. Copy this to Local.xcconfig (gitignored) and set:

• DEVELOPMENT_TEAM — Your personal Apple Developer Team ID
• PRODUCT_BUNDLE_IDENTIFIER — Team-specific bundle ID
• APP_GROUP_ID — Team-specific app group

This pattern keeps secrets and team identifiers out of version control while allowing seamless local builds.

Entitlements: Sandbox and Capability Declaration

Two entitlement files declare the security capabilities required by bitchat's Bluetooth and app-group features:

File	Platform	Capabilities
bitchat/bitchat.entitlements	iOS	App Groups, Bluetooth
bitchat/bitchat-macOS.entitlements	macOS	App Groups, Bluetooth

These files are referenced by their respective targets in project.pbxproj. Missing or mismatched entitlements cause runtime failures when accessing protected APIs.

Code Quality Configuration

.swiftlint.yml

The root-level .swiftlint.yml configures SwiftLint rules for consistent code style. It typically:

• Excludes generated directories (DerivedData, .build)
• Disables rules that conflict with the project's patterns
• Sets severity thresholds for CI enforcement

Run linting manually with:

# Strict mode fails the build on any violation

swiftlint lint --strict

.periphery.yml and .periphery.baseline.json

These files configure Periphery dead-code detection:

• .periphery.yml — Exclusion patterns for known-used symbols (XIBs, selectors, etc.)
• .periphery.baseline.json — Stored false-positives to prevent regression noise

Execute analysis with:

periphery scan --format github-actions

Xcode Project Wiring

bitchat.xcodeproj/project.pbxproj ties the configuration hierarchy together by:

1. Assigning Debug.xcconfig to the Debug build configuration
2. Assigning Release.xcconfig to the Release build configuration
3. Linking entitlement files to their respective targets
4. Referencing source files, resources, and framework dependencies

Manual edits to this file are discouraged; use Xcode's UI or xcodeproj tools to avoid corruption.

Reading Build-Time Values in Swift

Configuration values flow from xcconfig → Info.plist → runtime. Access them through Bundle:

import Foundation

// Injected via PRODUCT_BUNDLE_IDENTIFIER in xcconfig
let bundleID = Bundle.main.bundleIdentifier ?? "unknown"
print("Running with bundle identifier: \(bundleID)")

// Custom keys can be added to Info.plist and referenced similarly
if let appGroup = Bundle.main.object(forInfoDictionaryKey: "AppGroupID") as? String {
    print("App group container: \(appGroup)")
}

Summary

• Package.swift — Declares SPM dependencies and build targets
• Configs/Release.xcconfig — Production build defaults
• Configs/Debug.xcconfig — Development settings with optional local overrides
• Configs/Local.xcconfig.example — Template for personal developer settings
• bitchat/bitchat.entitlements and bitchat/bitchat-macOS.entitlements — Required capabilities for iOS/macOS
• .swiftlint.yml — Code style enforcement rules
• .periphery.yml and .periphery.baseline.json — Dead-code analysis configuration
• bitchat.xcodeproj/project.pbxproj — Xcode project wiring all configurations to targets

Frequently Asked Questions

How do I set up my local development environment in bitchat?

Copy Configs/Local.xcconfig.example to Configs/Local.xcconfig, then edit the DEVELOPMENT_TEAM, PRODUCT_BUNDLE_IDENTIFIER, and APP_GROUP_ID values with your Apple Developer credentials. The file is gitignored by default, so your changes stay local.

Why does bitchat use both Package.swift and an Xcode project?

Package.swift manages Swift package dependencies and cross-platform build logic, while bitchat.xcodeproj provides iOS/macOS-specific configurations including code signing, entitlements, and xcconfig inheritance chains that SPM cannot fully express.

What happens if I delete .periphery.baseline.json?

Periphery will flag all previously-baselined dead-code warnings as new violations. Regenerate the baseline with periphery scan --format json > .periphery.baseline.json after confirming the detected symbols are truly unused.

Can I modify build settings directly in Xcode instead of the xcconfig files?

You can, but changes made in Xcode's build settings UI write to project.pbxproj and override the xcconfig hierarchy. This fragments configuration and complicates team collaboration. Prefer editing the xcconfig files for settings that should be version-controlled.

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