weevil/GETTING_STARTED.md

# Getting Started with Weevil Development

## Prerequisites

1. **Rust** (if not installed):
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

2. **Git** (should already have this)

3. **Gradle** (for now - will be embedded later):
```bash
# Ubuntu/Debian
sudo apt install gradle

# Or use sdkman
curl -s "https://get.sdkman.io" | bash
sdk install gradle 8.9
```

## Initial Setup

```bash
# Navigate to the weevil directory
cd ~/Desktop/FTC_Decode/weevil

# Build the project (this will download all dependencies)
cargo build

# Run tests to verify everything works
cargo test
```

## Usage Examples

### 1. Check if it compiles
```bash
cargo check
```

### 2. Run with arguments (dev mode)
```bash
# Show help
cargo run -- --help

# Show version
cargo run -- --version

# Check SDK status
cargo run -- sdk status

# Create a new project (will try to download SDKs)
cargo run -- new test-robot
```

### 3. Build release binary
```bash
cargo build --release

# The binary will be at: target/release/weevil
# You can copy it to your PATH:
sudo cp target/release/weevil /usr/local/bin/

# Then use it directly:
weevil --help
weevil new my-robot
```

### 4. Run tests
```bash
# Run all tests
cargo test

# Run specific test
cargo test test_help_command

# Run tests with output
cargo test -- --nocapture

# Run ignored tests (like project creation)
cargo test -- --ignored
```

## Development Workflow

### Quick Iteration
```bash
# 1. Make changes to src/*.rs files
# 2. Check if it compiles
cargo check

# 3. Run relevant tests
cargo test

# 4. Try it out
cargo run -- sdk status
```

### Adding New Features

1. **Add a new command:**
   - Add to `Commands` enum in `src/main.rs`
   - Create handler in `src/commands/`
   - Add to match statement in `main()`

2. **Add a new template:**
   - Create file in `templates/` directory
   - Access via `TEMPLATES_DIR` in `src/templates/mod.rs`
   - Files are automatically embedded at compile time!

3. **Add tests:**
   - Unit tests: Add `#[cfg(test)]` module in same file
   - Integration tests: Add to `tests/` directory

## Common Issues

### "error: could not find Cargo.toml"
You're not in the weevil directory. Run: `cd ~/Desktop/FTC_Decode/weevil`

### "gradle: command not found"
Install gradle (see prerequisites). We'll embed gradle-wrapper.jar later to avoid this.

### Compilation errors with include_dir
The templates directory must exist: `mkdir -p templates`

### Tests failing
Some tests are marked `#[ignore]` until we build mock SDKs. That's expected.

## Next Steps

### Phase 1: Get Basic Functionality Working
1. ✅ Project compiles
2. ✅ CLI works with --help, --version
3. ✅ SDK status command works
4. ⏳ Project creation creates basic structure
5. ⏳ Generated projects can build with gradle

### Phase 2: Complete Templates
1. Copy template files from ftc-project-gen
2. Convert to Tera template syntax ({{variable}})
3. Test template rendering

### Phase 3: Full SDK Management
1. Complete FTC SDK download/update
2. Complete Android SDK download/update
3. Embed gradle-wrapper.jar in binary

### Phase 4: Deploy Functionality
1. ADB detection and communication
2. APK building
3. Installation to Control Hub

### Phase 5: Polish
1. Progress bars for downloads
2. Better error messages
3. Windows testing
4. Create releases

## Debugging Tips

### See what's being compiled
```bash
cargo build -vv
```

### Check dependencies
```bash
cargo tree
```

### Format code
```bash
cargo fmt
```

### Lint code
```bash
cargo clippy
```

### Generate documentation
```bash
cargo doc --open
```

## Performance

### Check binary size
```bash
cargo build --release
ls -lh target/release/weevil
```

### Profile build
```bash
cargo build --release --timings
```

## Questions?

The code is well-commented. Start reading from:
1. `src/main.rs` - Entry point and CLI definition
2. `src/commands/new.rs` - Project creation logic
3. `src/project/mod.rs` - Project builder
4. `src/templates/mod.rs` - Template engine

Each module has its own documentation. Rust's type system will guide you!