BUILD.md

OpenMind Build Guide

This guide explains how to build OpenMind from the command line using the provided build automation tools.

Prerequisites

• macOS 14.0 or later
• Xcode 15.0 or later
• Command Line Tools installed (xcode-select --install)

Quick Start

# Initial setup (first time only)
make setup

# Build the app
make build

# Run tests
make test

# Build and run
make dev

Available Make Targets

Basic Commands

• make help - Show all available commands
• make setup - Install dependencies and configure the project
• make build - Build the app for simulator
• make device - Build the app for physical device
• make test - Run all tests with coverage
• make clean - Clean all build artifacts

Code Quality

• make lint - Run SwiftLint to check code style
• make format - Auto-format code with SwiftFormat
• make analyze - Run static analysis

Documentation

• make docs - Generate API documentation with Jazzy

Release

• make archive - Create a release archive
• make release - Build and export for App Store

Development

• make dev - Format, lint, and build (quick development cycle)
• make run - Build and launch in simulator

Build Scripts

Custom Build Script

For more control over the build process:

# Debug build for simulator
./Scripts/build.sh debug simulator

# Release build for device
./Scripts/build.sh release device

The build script provides:

• Detailed logging with color output
• Build time tracking
• Automatic dependency resolution
• Post-build validation
• Optional simulator installation

Test Runner Script

For comprehensive testing:

# Run all tests
./Scripts/test.sh all

# Run only unit tests
./Scripts/test.sh unit

# Run only UI tests
./Scripts/test.sh ui

# Run performance tests
./Scripts/test.sh performance

# Specify custom device
./Scripts/test.sh all "iPhone 15 Pro"

The test script provides:

• Test result collection
• Code coverage reporting
• HTML report generation
• Test failure tracking

Command Line Building with xcodebuild

Basic Build Commands

# List available schemes
xcodebuild -project OpenMind.xcodeproj -list

# Build for simulator
xcodebuild build \
  -project OpenMind.xcodeproj \
  -scheme OpenMind \
  -destination "platform=iOS Simulator,name=iPhone 15"

# Build for device
xcodebuild build \
  -project OpenMind.xcodeproj \
  -scheme OpenMind \
  -destination "generic/platform=iOS"

Testing

# Run unit tests
xcodebuild test \
  -project OpenMind.xcodeproj \
  -scheme OpenMind \
  -destination "platform=iOS Simulator,name=iPhone 15" \
  -enableCodeCoverage YES

# Run specific test class
xcodebuild test \
  -project OpenMind.xcodeproj \
  -scheme OpenMind \
  -only-testing:OpenMindTests/LayoutEngineTests

Code Coverage

# Generate coverage report
xcrun xccov view --report build/TestResults/Coverage.xcresult

# Export coverage as JSON
xcrun xccov view --report --json build/TestResults/Coverage.xcresult > coverage.json

Archiving and Export

# Create archive
xcodebuild archive \
  -project OpenMind.xcodeproj \
  -scheme OpenMind \
  -archivePath build/OpenMind.xcarchive

# Export for App Store
xcodebuild -exportArchive \
  -archivePath build/OpenMind.xcarchive \
  -exportPath build/Export \
  -exportOptionsPlist Scripts/ExportOptions.plist

Continuous Integration

GitHub Actions Example

name: Build and Test

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: macos-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Select Xcode
      run: sudo xcode-select -s /Applications/Xcode.app
    
    - name: Setup
      run: make setup
    
    - name: Build
      run: make build
    
    - name: Test
      run: make test
    
    - name: Upload coverage
      uses: codecov/codecov-action@v3
      with:
        file: build/Coverage/combined_coverage.json

Fastlane Integration

Create a Fastfile for advanced automation:

default_platform(:ios)

platform :ios do
  desc "Build and test"
  lane :test do
    scan(
      project: "OpenMind.xcodeproj",
      scheme: "OpenMind",
      devices: ["iPhone 15"],
      code_coverage: true
    )
  end
  
  desc "Build for release"
  lane :release do
    build_app(
      project: "OpenMind.xcodeproj",
      scheme: "OpenMind",
      export_method: "app-store"
    )
  end
end

Troubleshooting

Common Issues

1. SwiftLint/SwiftFormat not found

   brew install swiftlint swiftformat

2. Module not found errors

   xcodebuild -resolvePackageDependencies

3. Simulator not found

   xcrun simctl list devices

4. Code signing issues

   • Ensure you have a valid development team set in the project
   • Run make setup to configure signing

Debug Build Issues

# Verbose build output
xcodebuild build -project OpenMind.xcodeproj -scheme OpenMind -verbose

# Show build settings
xcodebuild -showBuildSettings -project OpenMind.xcodeproj -scheme OpenMind

# Clean derived data
rm -rf ~/Library/Developer/Xcode/DerivedData/OpenMind-*

Performance Tips

1. Parallel builds: Already enabled in the project
2. Incremental builds: Use derived data path consistently
3. Build time optimization:

   # Analyze build time
   xcodebuild build -showBuildTimingSummary

Advanced Usage

Custom Build Configurations

Edit Scripts/ExportOptions.plist for custom export options.

Environment Variables

• DERIVED_DATA_PATH - Custom derived data location
• BUILD_DIR - Custom build output directory
• XCODE_SCHEME - Override default scheme
• XCODE_CONFIGURATION - Override build configuration

Integration with Other Tools

# Format and lint before building
swiftformat . && swiftlint lint --strict && make build

# Generate documentation after building
make build && make docs

# Full CI simulation
make clean && make format && make lint && make build && make test

Version Information

Current version: v0.2.0

The build system automatically handles:

• Dependency resolution
• Code signing (with valid certificates)
• Build number incrementing (when using release scripts)
• Symbol generation for crash reporting