docs/DEVELOPER_GUIDE.md

iOSDiag Developer Guide

Getting Started

Prerequisites

• Rust 1.70+ (install via rustup)
• Cargo (included with Rust)
• Linux or macOS (Windows support via WSL2)
• usbmuxd daemon (for USB device support)

Installation

# Clone the repository
git clone https://github.com/yourusername/iosdiag.git
cd iosdiag

# Build the project
cargo build --release

# Run tests
cargo test

# Generate documentation
cargo doc --open

Project Structure

iosdiag/
├── Cargo.toml                 # Workspace configuration
├── crates/
│   ├── iosdiag-core/         # Core library
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs        # Library root
│   │       ├── error.rs      # Error types
│   │       ├── config.rs     # Configuration
│   │       ├── logging.rs    # Logging setup
│   │       ├── util/         # Utilities
│   │       ├── transport/    # Device communication
│   │       ├── security/     # Pairing & crypto
│   │       ├── services/     # iOS services
│   │       ├── collectors/   # Evidence gathering
│   │       ├── normalize/    # Data normalization
│   │       ├── inference/    # Analysis engine
│   │       └── report/       # Report generation
│   └── iosdiag-cli/          # CLI application
│       ├── Cargo.toml
│       └── src/
│           └── main.rs       # CLI entry point
├── kb/                        # Knowledge base
│   ├── kb_version.json       # KB metadata
│   └── rules/                # Diagnostic rules
├── docs/                      # Documentation
│   ├── ARCHITECTURE.md
│   ├── PROTOCOL_GUIDE.md
│   └── DEVELOPER_GUIDE.md
└── tests/                     # Integration tests

Development Workflow

Adding a New Collector

1. Create a new file in src/collectors/:

// src/collectors/example.rs
use crate::collectors::{Collector, EvidenceItem};
use async_trait::async_trait;

pub struct ExampleCollector;

#[async_trait]
impl Collector for ExampleCollector {
    async fn collect(&self) -> Result<Vec<EvidenceItem>, CollectorError> {
        // Implementation
    }
}

2. Register in src/collectors/mod.rs:

pub mod example;
pub use example::ExampleCollector;

3. Add to collector registry in src/lib.rs:

pub fn create_collectors() -> Vec<Box<dyn Collector>> {
    vec![
        Box::new(ExampleCollector),
        // ... other collectors
    ]
}

Adding a New Diagnostic Rule

1. Create YAML rule in kb/rules/:

# kb/rules/example.yaml
rules:
  - id: example_issue
    category: example
    severity: high
    condition: "example.value > 100"
    hypothesis: "Example issue detected"
    explanation: "This is an example issue"
    next_steps:
      - "Step 1"
      - "Step 2"

2. Load rule in inference engine:

let rules = load_rules_from_yaml("kb/rules/example.yaml")?;
engine.add_rules(rules);

Adding a New Service Client

1. Create service module in src/services/:

// src/services/example.rs
use crate::transport::IoStream;

pub struct ExampleService {
    stream: Box<dyn IoStream>,
}

impl ExampleService {
    pub async fn new(stream: Box<dyn IoStream>) -> Result<Self> {
        Ok(ExampleService { stream })
    }

    pub async fn get_data(&self) -> Result<ExampleData> {
        // Implementation
    }
}

2. Register in src/services/mod.rs:

pub mod example;
pub use example::ExampleService;

Testing

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_example() {
        let result = some_function();
        assert_eq!(result, expected_value);
    }
}

Integration Tests

Create tests in tests/ directory:

// tests/integration_test.rs
use iosdiag_core::*;

#[tokio::test]
async fn test_full_workflow() {
    // Test implementation
}

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with output
cargo test -- --nocapture

# Run integration tests only
cargo test --test '*'

Code Style

Formatting

# Format code
cargo fmt

# Check formatting
cargo fmt -- --check

Linting

# Run clippy
cargo clippy

# Run with all warnings
cargo clippy -- -W clippy::all

Documentation

# Generate and open documentation
cargo doc --open

# Check documentation
cargo doc --no-deps

Debugging

Logging

Enable logging with environment variable:

RUST_LOG=debug cargo run

Log levels:

• error: Error messages
• warn: Warning messages
• info: Informational messages
• debug: Debug messages
• trace: Detailed trace messages

Debugging with GDB

# Build with debug symbols
cargo build

# Run with GDB
gdb ./target/debug/iosdiag-cli

# Set breakpoint
(gdb) break main
(gdb) run

Debugging with LLDB

# Run with LLDB
lldb ./target/debug/iosdiag-cli

# Set breakpoint
(lldb) breakpoint set --name main
(lldb) run

Performance Profiling

Using Flamegraph

# Install flamegraph
cargo install flamegraph

# Generate flamegraph
cargo flamegraph

# View result
open flamegraph.svg

Using Perf

# Build with debug symbols
cargo build --release

# Run with perf
perf record -g ./target/release/iosdiag-cli

# View results
perf report

Continuous Integration

GitHub Actions

Create .github/workflows/ci.yml:

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - run: cargo test
      - run: cargo clippy
      - run: cargo fmt -- --check

Release Process

Version Bumping

Update version in Cargo.toml:

[package]
version = "1.0.0"

Building Release

# Build release binary
cargo build --release

# Create tarball
tar czf iosdiag-1.0.0.tar.gz target/release/iosdiag-cli

# Create .deb package
cargo deb

Publishing

# Publish to crates.io
cargo publish

Troubleshooting

Common Issues

Issue: Device not found

• Solution: Ensure usbmuxd is running: sudo systemctl start usbmuxd

Issue: Permission denied

• Solution: Add user to plugdev group: sudo usermod -a -G plugdev $USER

Issue: Compilation errors

• Solution: Update Rust: rustup update

Issue: Test failures

• Solution: Check environment variables and dependencies

Contributing

Code Review Checklist

• Code follows style guidelines
• Tests are included
• Documentation is updated
• No breaking changes
• Performance impact assessed
• Security implications reviewed

Pull Request Process

1. Fork the repository
2. Create feature branch: git checkout -b feature/name
3. Make changes and commit: git commit -am 'Add feature'
4. Push to branch: git push origin feature/name
5. Create Pull Request
6. Address review comments
7. Merge when approved

Resources

• Rust Book
• Tokio Documentation
• Apple Developer Documentation
• iOS Protocol Documentation

---

Last Updated: 2026-02-10
Version: 1.0.0