# CxIDE — Build Guide

## Prerequisites

| Tool | Minimum | Check |
|------|---------|-------|
| macOS | 14.0+ (Sonoma) | `sw_vers -productVersion` |
| Swift | 5.9+ | `swift --version` |
| Xcode | 15.0+ | `xcodebuild -version` |
| Clang++ | Apple clang 15+ | `clang++ --version` |
| Git | 2.x | `git --version` |

## Quick Start

```bash
# First-time setup (validates toolchain, installs hooks)
./scripts/setup.sh

# Build (debug)
./scripts/build.sh

# Build (release)
./scripts/build.sh release

# Run tests
./scripts/test.sh

# Lint
./scripts/lint.sh

# Clean
./scripts/clean.sh
```

## Build Targets

### 1. C++ CodeEngine (static library)

The C++ analysis engine compiles into `libCxEngine.a`:

```bash
# Manual compilation
clang++ -std=c++17 -O2 -c Core/CodeEngine.cpp -o .build/CodeEngine.o
clang++ -std=c++17 -O2 -fobjc-arc -c Core/SwiftEngineWrapper.mm \
    -I Core -o .build/SwiftEngineWrapper.o
ar rcs .build/libCxEngine.a .build/CodeEngine.o .build/SwiftEngineWrapper.o
```

**Source files:**
- `Core/CodeEngine.hpp` — C++ header (EngineConfig, Token, SymbolInfo, AnalysisReport)
- `Core/CodeEngine.cpp` — Full Swift tokenizer, symbol extraction, complexity metrics
- `Core/SwiftEngineWrapper.h` — Objective-C interface (40+ methods)
- `Core/SwiftEngineWrapper.mm` — ObjC++ bridge implementation

### 2. CxIDE App (Xcode / SwiftUI)

Open the project in Xcode and build normally, or use `xcodebuild`:

```bash
# If using an .xcodeproj
xcodebuild -scheme CxIDE -configuration Debug build

# SwiftUI previews
# Open any View file in Xcode and use the Canvas (⌥⌘P)
```

**Key dependencies within the project:**
- SwiftUI + AppKit (macOS window management)
- Foundation (file I/O, Process for code execution)
- The C++ engine is linked via the ObjC++ bridging header

### 3. CxSwiftAgent (SPM executable)

```bash
cd CxSwiftAgent

# Debug build
swift build

# Release build
swift build -c release

# Run tests
swift test

# Run the agent (HTTP mode)
.build/release/cx-swift-agent --port 3001 --workspace /path/to/project

# Run the agent (stdio mode — for MCP clients)
.build/release/cx-swift-agent --stdio
```

**Docker build:**
```bash
cd CxSwiftAgent
docker build -t cx-swift-agent .
docker run -p 3001:3001 -v /path/to/project:/workspace cx-swift-agent
```

## Build Configurations

### Debug (default)
- `-g -O0 -DDEBUG` for C++
- Assertions enabled
- Full debug symbols

### Release
- `-O2 -DNDEBUG` for C++
- Optimizations enabled
- Static linking for agent binary

## C++ Engine Configuration

The engine is configurable at runtime via `EngineConfig` / `CppAnalysisConfig`:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `maxLineLength` | 120 | Warn on lines exceeding this |
| `maxNestingDepth` | 5 | Maximum brace nesting depth |
| `maxFunctionLength` | 50 | Lines before a function is "too long" |
| `minCommentRatio` | 0.05 | Minimum comment-to-code ratio |
| `maxPrintStatements` | 5 | Warn on excessive prints |
| `detectForceUnwraps` | true | Flag `!` unwraps |
| `detectForceTry` | true | Flag `try!` |
| `detectForceCast` | true | Flag `as!` |
| `detectDuplicateLines` | true | Find repeated code |
| `detectTodoFixme` | true | Extract TODO/FIXME markers |
| `detectRetainCycles` | true | Warn on missing `[weak self]` |

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `swift not found` | Install Xcode or download Swift from swift.org |
| `clang++ not found` | Run `xcode-select --install` |
| C++ compilation errors | Ensure C++17 support: `clang++ -std=c++17` |
| ObjC++ bridge errors | Check `-fobjc-arc` flag and bridging header path |
| Agent build fails | Verify `Package.swift` targets macOS 14+ |
| Tests timeout | CxSwiftAgent tests need write access to `/tmp` |