# 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 ```bash # 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/`: ```rust // 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, CollectorError> { // Implementation } } ``` 2. Register in `src/collectors/mod.rs`: ```rust pub mod example; pub use example::ExampleCollector; ``` 3. Add to collector registry in `src/lib.rs`: ```rust pub fn create_collectors() -> Vec> { vec![ Box::new(ExampleCollector), // ... other collectors ] } ``` ### Adding a New Diagnostic Rule 1. Create YAML rule in `kb/rules/`: ```yaml # 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: ```rust 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/`: ```rust // src/services/example.rs use crate::transport::IoStream; pub struct ExampleService { stream: Box, } impl ExampleService { pub async fn new(stream: Box) -> Result { Ok(ExampleService { stream }) } pub async fn get_data(&self) -> Result { // Implementation } } ``` 2. Register in `src/services/mod.rs`: ```rust pub mod example; pub use example::ExampleService; ``` ## Testing ### Unit Tests ```rust #[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: ```rust // tests/integration_test.rs use iosdiag_core::*; #[tokio::test] async fn test_full_workflow() { // Test implementation } ``` ### Running Tests ```bash # 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 ```bash # Format code cargo fmt # Check formatting cargo fmt -- --check ``` ### Linting ```bash # Run clippy cargo clippy # Run with all warnings cargo clippy -- -W clippy::all ``` ### Documentation ```bash # Generate and open documentation cargo doc --open # Check documentation cargo doc --no-deps ``` ## Debugging ### Logging Enable logging with environment variable: ```bash 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 ```bash # Build with debug symbols cargo build # Run with GDB gdb ./target/debug/iosdiag-cli # Set breakpoint (gdb) break main (gdb) run ``` ### Debugging with LLDB ```bash # Run with LLDB lldb ./target/debug/iosdiag-cli # Set breakpoint (lldb) breakpoint set --name main (lldb) run ``` ## Performance Profiling ### Using Flamegraph ```bash # Install flamegraph cargo install flamegraph # Generate flamegraph cargo flamegraph # View result open flamegraph.svg ``` ### Using Perf ```bash # 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`: ```yaml 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`: ```toml [package] version = "1.0.0" ``` ### Building Release ```bash # 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 ```bash # 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](https://doc.rust-lang.org/book/) - [Tokio Documentation](https://tokio.rs/) - [Apple Developer Documentation](https://developer.apple.com/) - [iOS Protocol Documentation](https://github.com/libimobiledevice/libimobiledevice) --- **Last Updated**: 2026-02-10 **Version**: 1.0.0