iosdiag / docs /DEVELOPER_GUIDE.md

Upload docs/DEVELOPER_GUIDE.md with huggingface_hub

1579bdd verified 9 months ago

7.51 kB

# 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<Vec<EvidenceItem>, 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<Box<dyn Collector>> {
    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<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`:
```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

	# 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<Vec<EvidenceItem>, 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<Box<dyn Collector>> {
	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<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`:
	```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