2 Commits

Author SHA1 Message Date
Eric Ratliff
26f3229b1e docs: update README for v1.1.0 features
Document proxy support and Android Studio integration added in v1.1.0.

New sections:
- Proxy Support: --proxy and --no-proxy flags, HTTPS_PROXY env var
  auto-detection, air-gapped/offline installation workflows
- Android Studio Setup: complete guide including Shell Script plugin
  installation, opening projects, and using run configurations
- Troubleshooting: Android Studio plugin issues, proxy debugging

Updated sections:
- Quick Start: add weevil setup and weevil doctor as step 1
- Command Reference: environment commands (doctor, setup, uninstall),
  global proxy flags
- Features: highlight Android Studio integration and proxy support
- Project Status: current version 1.1.0, updated "What Works" list

Expanded troubleshooting for common issues: adb not found, proxy
connectivity, Android Studio run configuration errors.

All existing content preserved. Tone stays practical and student-focused.
2026-02-01 20:56:52 -06:00
Eric Ratliff
9ee0d99dd8 feat: add Android Studio integration (v1.1.0)
Generate .idea/ run configurations for one-click build and deployment
directly from Android Studio. Students can now open projects in the IDE
they already know and hit the green play button to deploy to their robot.

Run configurations generated:
- Build: compiles APK without deploying (build.sh / build.bat)
- Deploy (auto): auto-detects USB or WiFi connection
- Deploy (USB): forces USB deployment (deploy.sh --usb)
- Deploy (WiFi): forces WiFi deployment (deploy.sh --wifi)
- Test: runs unit tests (./gradlew test)

Both Unix (.sh) and Windows (.bat) variants are generated. Android Studio
automatically hides the configurations whose script files don't exist, so
only platform-appropriate configs appear in the Run dropdown.

workspace.xml configures the project tree to hide internal directories
(build/, .gradle/, gradle/) and expand src/ by default, giving students
a clean view of just their code and the deployment scripts.

Technical notes:
- Uses ShConfigurationType (not the old ShellScript type) for Android
  Studio 2025.2+ compatibility
- All paths use $PROJECT_DIR$ for portability
- INTERPRETER_PATH is /bin/bash on Unix, cmd.exe on Windows
- upgrade.rs regenerates all .idea/ files so run configs stay in sync
  with any future deploy.sh flag changes

Requires Shell Script plugin (by JetBrains) to be installed in Android
Studio. README.md updated with installation instructions.

Files modified:
- src/project/mod.rs: generate_idea_files() writes 5 XML files per platform
- src/commands/upgrade.rs: add .idea/ files to safe_to_overwrite
2026-02-01 20:56:03 -06:00

273
README.md
View File

@@ -26,6 +26,8 @@ This approach works against standard software engineering practices and creates
- ✅ Generate all build/deploy scripts automatically - ✅ Generate all build/deploy scripts automatically
- ✅ Enable proper version control workflows - ✅ Enable proper version control workflows
- ✅ Are actually testable and maintainable - ✅ Are actually testable and maintainable
- ✅ Work seamlessly with Android Studio
- ✅ Support proxy/air-gapped environments
Students focus on building robots, not navigating SDK internals. Students focus on building robots, not navigating SDK internals.
@@ -39,6 +41,7 @@ my-robot/
├── src/ ├── src/
│ ├── main/java/robot/ # Your robot code lives here │ ├── main/java/robot/ # Your robot code lives here
│ └── test/java/robot/ # Unit tests (run on PC!) │ └── test/java/robot/ # Unit tests (run on PC!)
├── .idea/ # Android Studio integration (auto-generated)
├── build.sh / build.bat # One command to build ├── build.sh / build.bat # One command to build
├── deploy.sh / deploy.bat # One command to deploy ├── deploy.sh / deploy.bat # One command to deploy
└── .weevil.toml # Project configuration └── .weevil.toml # Project configuration
@@ -46,6 +49,9 @@ my-robot/
### 🚀 Simple Commands ### 🚀 Simple Commands
```bash ```bash
# Set up development environment
weevil setup
# Create a new robot project # Create a new robot project
weevil new awesome-robot weevil new awesome-robot
@@ -60,6 +66,9 @@ cd awesome-robot
### 🔧 Project Management ### 🔧 Project Management
```bash ```bash
# Check system health
weevil doctor
# Upgrade project infrastructure # Upgrade project infrastructure
weevil upgrade awesome-robot weevil upgrade awesome-robot
@@ -69,8 +78,36 @@ weevil config awesome-robot --set-sdk /path/to/different/sdk
# Check SDK status # Check SDK status
weevil sdk status weevil sdk status
# Remove installed components
weevil uninstall --dry-run
weevil uninstall
``` ```
### 🌐 Proxy Support (v1.1.0)
Work behind corporate firewalls or in air-gapped environments:
```bash
# Use HTTP proxy for all downloads
weevil --proxy http://proxy.company.com:8080 setup
weevil --proxy http://proxy.company.com:8080 new my-robot
# Bypass proxy (for local/direct connections)
weevil --no-proxy setup
# Proxy auto-detected from HTTPS_PROXY/HTTP_PROXY environment variables
export HTTPS_PROXY=http://proxy:8080
weevil setup # Uses proxy automatically
```
### 💻 Android Studio Integration (v1.1.0)
Projects work seamlessly with Android Studio:
- **One-click deployment** - Run configurations appear automatically in the Run dropdown
- **Clean file tree** - Internal directories hidden, only your code visible
- **No configuration needed** - Just open the project and hit Run
See [Android Studio Setup](#android-studio-setup) for details.
### ✨ Smart Features ### ✨ Smart Features
- **Per-project SDK configuration** - Different projects can use different SDK versions - **Per-project SDK configuration** - Different projects can use different SDK versions
- **Automatic Gradle wrapper** - No manual setup required - **Automatic Gradle wrapper** - No manual setup required
@@ -78,6 +115,8 @@ weevil sdk status
- **Zero SDK modification** - Your SDK stays pristine - **Zero SDK modification** - Your SDK stays pristine
- **Git-ready** - Projects initialize with proper `.gitignore` - **Git-ready** - Projects initialize with proper `.gitignore`
- **Upgrade-safe** - Update build scripts without losing code - **Upgrade-safe** - Update build scripts without losing code
- **System diagnostics** - `weevil doctor` checks your environment health
- **Selective uninstall** - Remove specific components without nuking everything
--- ---
@@ -96,30 +135,49 @@ export PATH="$PATH:$(pwd)/target/release"
``` ```
### Prerequisites ### Prerequisites
- Rust 1.70+ (for building) - Rust 1.70+ (for building Weevil)
- Java 11+ (for running Gradle) - Java 11+ (for running Gradle)
- Android SDK with platform-tools (for deployment) - Android SDK with platform-tools (for deployment)
- FTC SDK (Weevil can download it for you) - FTC SDK (Weevil can install it for you)
--- ---
## Quick Start ## Quick Start
### 1. Create Your First Project ### 1. Set Up Your Environment
```bash
# Check what's installed
weevil doctor
# Install everything automatically
weevil setup
# Or install to custom location
weevil setup --ftc-sdk ~/my-sdks/ftc --android-sdk ~/my-sdks/android
```
Weevil will:
- Download and install FTC SDK
- Download and install Android SDK (if needed)
- Set up Gradle wrapper
- Verify all dependencies
### 2. Create Your First Project
```bash ```bash
weevil new my-robot weevil new my-robot
cd my-robot cd my-robot
``` ```
Weevil will: Weevil generates:
- Download the FTC SDK if needed (or use existing) - Clean project structure
- Generate your project structure - Android Studio run configurations
- Set up Gradle wrapper - Example test files
- Initialize git repository - Build and deploy scripts
- Create example test files - Git repository with `.gitignore`
### 2. Write Some Code ### 3. Write Some Code
Create `src/main/java/robot/MyOpMode.java`: Create `src/main/java/robot/MyOpMode.java`:
@@ -146,7 +204,7 @@ public class MyOpMode extends LinearOpMode {
} }
``` ```
### 3. Test Locally (No Robot!) ### 4. Test Locally (No Robot!)
```bash ```bash
./gradlew test ./gradlew test
@@ -154,7 +212,7 @@ public class MyOpMode extends LinearOpMode {
Write unit tests in `src/test/java/robot/` that run on your PC. No need to deploy to a robot for every code change! Write unit tests in `src/test/java/robot/` that run on your PC. No need to deploy to a robot for every code change!
### 4. Deploy to Robot ### 5. Deploy to Robot
```bash ```bash
# Build APK # Build APK
@@ -172,8 +230,93 @@ Write unit tests in `src/test/java/robot/` that run on your PC. No need to deplo
--- ---
## Android Studio Setup
### Opening a Weevil Project
1. Launch Android Studio
2. Choose **Open** (not "New Project")
3. Navigate to your project directory (e.g., `my-robot`)
4. Click OK
Android Studio will index the project. After a few seconds, you'll see:
- **Clean file tree** - Only `src/`, scripts, and essential files visible
- **Run configurations** - Dropdown next to the green play button shows:
- **Build** - Builds APK without deploying
- **Deploy (auto)** - Auto-detects USB or WiFi
- **Deploy (USB)** - Forces USB connection
- **Deploy (WiFi)** - Forces WiFi connection
- **Test** - Runs unit tests
### First-Time Setup: Shell Script Plugin
**Important:** Android Studio requires the Shell Script plugin to run Weevil's deployment scripts.
1. Go to **File → Settings** (or **Ctrl+Alt+S**)
2. Navigate to **Plugins**
3. Click the **Marketplace** tab
4. Search for **"Shell Script"**
5. Install the plugin (by JetBrains)
6. Restart Android Studio
After restart, the run configurations will work.
### Running from Android Studio
1. Select a configuration from the dropdown (e.g., "Deploy (auto)")
2. Click the green play button (▶) or press **Shift+F10**
3. Watch the output in the Run panel at the bottom
**That's it!** Students can now build and deploy without leaving the IDE.
### Platform Notes
- **Linux/macOS:** Uses the Unix run configurations (`.sh` scripts)
- **Windows:** Uses the Windows run configurations (`.bat` scripts)
- Android Studio automatically hides the configurations for the other platform
---
## Advanced Usage ## Advanced Usage
### Proxy Configuration
#### Corporate Environments
```bash
# Set proxy for all Weevil operations
weevil --proxy http://proxy.company.com:8080 setup
weevil --proxy http://proxy.company.com:8080 new robot-project
# Or use environment variables (auto-detected)
export HTTPS_PROXY=http://proxy:8080
export HTTP_PROXY=http://proxy:8080
weevil setup # Automatically uses proxy
```
#### Air-Gapped / Offline Installation
If you're on an isolated network without internet:
1. **Download SDKs manually on a connected machine:**
- FTC SDK: `git clone https://github.com/FIRST-Tech-Challenge/FtcRobotController.git`
- Android SDK: Download from https://developer.android.com/studio
- Gradle: Download distribution from https://gradle.org/releases/
2. **Transfer to isolated machine via USB drive**
3. **Install using local paths:**
```bash
weevil setup --ftc-sdk /path/to/FtcRobotController --android-sdk /path/to/android-sdk
```
#### Bypass Proxy
```bash
# Force direct connection (ignore proxy environment variables)
weevil --no-proxy setup
```
### Multiple SDK Versions ### Multiple SDK Versions
Working with multiple SDK versions? No problem: Working with multiple SDK versions? No problem:
@@ -203,10 +346,27 @@ This updates:
- Build scripts - Build scripts
- Deployment scripts - Deployment scripts
- Gradle configuration - Gradle configuration
- Android Studio run configurations
- Project templates - Project templates
**Your code in `src/` is never touched.** **Your code in `src/` is never touched.**
### System Maintenance
```bash
# Check what's installed
weevil doctor
# See what can be uninstalled
weevil uninstall --dry-run
# Remove specific components
weevil uninstall --only 1 # Removes FTC SDK only
# Full uninstall (removes everything Weevil installed)
weevil uninstall
```
### Cross-Platform Development ### Cross-Platform Development
All scripts work on Windows, Linux, and macOS: All scripts work on Windows, Linux, and macOS:
@@ -220,9 +380,11 @@ All scripts work on Windows, Linux, and macOS:
**Windows:** **Windows:**
```cmd ```cmd
build.bat build.bat
deploy.bat --wifi deploy.bat
``` ```
**Android Studio:** Works identically on all platforms
--- ---
## Project Configuration ## Project Configuration
@@ -231,9 +393,10 @@ Each project has a `.weevil.toml` file:
```toml ```toml
project_name = "my-robot" project_name = "my-robot"
weevil_version = "1.0.0" weevil_version = "1.1.0"
ftc_sdk_path = "/home/user/.weevil/ftc-sdk" ftc_sdk_path = "/home/user/.weevil/ftc-sdk"
ftc_sdk_version = "v10.1.1" ftc_sdk_version = "v10.1.1"
android_sdk_path = "/home/user/.weevil/android-sdk"
``` ```
You can edit this manually or use: You can edit this manually or use:
@@ -273,6 +436,7 @@ git push
1. **Unit Tests** - Test business logic on your PC 1. **Unit Tests** - Test business logic on your PC
```bash ```bash
./gradlew test ./gradlew test
# Or from Android Studio: select "Test" and click Run
``` ```
2. **Integration Tests** - Test on actual hardware 2. **Integration Tests** - Test on actual hardware
@@ -293,7 +457,7 @@ cd robot
# Check SDK location # Check SDK location
weevil config . weevil config .
# Set SDK to local path # Set SDK to local path (if different from .weevil.toml)
weevil config . --set-sdk ~/ftc-sdk weevil config . --set-sdk ~/ftc-sdk
# Build and deploy # Build and deploy
@@ -301,15 +465,29 @@ weevil config . --set-sdk ~/ftc-sdk
./deploy.sh ./deploy.sh
``` ```
**Android Studio users:** Just open the project. The `.idea/` folder contains all run configurations.
--- ---
## Command Reference ## Command Reference
### Environment Commands
| Command | Description |
|---------|-------------|
| `weevil doctor` | Check system health and dependencies |
| `weevil setup` | Install FTC SDK, Android SDK, and dependencies |
| `weevil setup --ftc-sdk <path>` | Install to custom FTC SDK location |
| `weevil uninstall` | Remove all Weevil-managed components |
| `weevil uninstall --dry-run` | Show what would be removed |
| `weevil uninstall --only <N>` | Remove specific component by index |
### Project Commands ### Project Commands
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| `weevil new <name>` | Create new FTC project | | `weevil new <name>` | Create new FTC project |
| `weevil new <name> --ftc-sdk <path>` | Create with specific SDK |
| `weevil upgrade <path>` | Update project infrastructure | | `weevil upgrade <path>` | Update project infrastructure |
| `weevil config <path>` | View project configuration | | `weevil config <path>` | View project configuration |
| `weevil config <path> --set-sdk <sdk>` | Change FTC SDK path | | `weevil config <path> --set-sdk <sdk>` | Change FTC SDK path |
@@ -322,6 +500,13 @@ weevil config . --set-sdk ~/ftc-sdk
| `weevil sdk install` | Download and install SDKs | | `weevil sdk install` | Download and install SDKs |
| `weevil sdk update` | Update SDKs to latest versions | | `weevil sdk update` | Update SDKs to latest versions |
### Global Flags
| Flag | Description |
|------|-------------|
| `--proxy <url>` | Use HTTP proxy for all network operations |
| `--no-proxy` | Bypass proxy (ignore HTTPS_PROXY env vars) |
### Deployment Options ### Deployment Options
**`deploy.sh` / `deploy.bat` flags:** **`deploy.sh` / `deploy.bat` flags:**
@@ -343,6 +528,7 @@ weevil config . --set-sdk ~/ftc-sdk
- Creates standalone Java project structure - Creates standalone Java project structure
- Generates Gradle build files that reference FTC SDK - Generates Gradle build files that reference FTC SDK
- Sets up deployment scripts - Sets up deployment scripts
- Creates Android Studio run configurations
2. **Build Process** 2. **Build Process**
- Runs `deployToSDK` Gradle task - Runs `deployToSDK` Gradle task
@@ -355,12 +541,18 @@ weevil config . --set-sdk ~/ftc-sdk
- Connects to Control Hub (USB or WiFi) - Connects to Control Hub (USB or WiFi)
- Installs APK using `adb` - Installs APK using `adb`
4. **Proxy Support**
- reqwest HTTP client respects `--proxy` flag and HTTPS_PROXY env vars
- git2/libgit2 gets temporary proxy env vars during clone/fetch
- Gradle wrapper reads HTTPS_PROXY natively
### Why This Approach? ### Why This Approach?
**Separation of Concerns:** **Separation of Concerns:**
- Your code: `my-robot/src/` - Your code: `my-robot/src/`
- Build infrastructure: `my-robot/*.gradle.kts` - Build infrastructure: `my-robot/*.gradle.kts`
- FTC SDK: System-level installation - FTC SDK: System-level installation
- IDE integration: Auto-generated, auto-upgraded
**Benefits:** **Benefits:**
- Test code without SDK complications - Test code without SDK complications
@@ -368,6 +560,7 @@ weevil config . --set-sdk ~/ftc-sdk
- SDK updates don't break your projects - SDK updates don't break your projects
- Proper version control (no massive SDK in repo) - Proper version control (no massive SDK in repo)
- Industry-standard project structure - Industry-standard project structure
- Students use familiar tools (Android Studio)
--- ---
@@ -382,6 +575,7 @@ cargo test
# Run specific test suites # Run specific test suites
cargo test --test integration cargo test --test integration
cargo test --test project_lifecycle cargo test --test project_lifecycle
cargo test --test proxy_integration
cargo test config_tests cargo test config_tests
``` ```
@@ -392,6 +586,8 @@ cargo test config_tests
- ✅ Build script generation - ✅ Build script generation
- ✅ Upgrade workflow - ✅ Upgrade workflow
- ✅ CLI commands - ✅ CLI commands
- ✅ Proxy configuration and network operations
- ✅ Environment setup and health checks
--- ---
@@ -400,11 +596,11 @@ cargo test config_tests
### "FTC SDK not found" ### "FTC SDK not found"
```bash ```bash
# Check SDK status # Check system health
weevil sdk status weevil doctor
# Install SDK # Install SDK
weevil sdk install weevil setup
# Or specify custom location # Or specify custom location
weevil new my-robot --ftc-sdk /custom/path/to/sdk weevil new my-robot --ftc-sdk /custom/path/to/sdk
@@ -416,6 +612,10 @@ Install Android platform-tools:
**Linux:** **Linux:**
```bash ```bash
# Weevil can install it for you
weevil setup
# Or install manually
sudo apt install android-tools-adb sudo apt install android-tools-adb
``` ```
@@ -425,7 +625,7 @@ brew install android-platform-tools
``` ```
**Windows:** **Windows:**
Download Android SDK Platform Tools from Google. Download Android SDK Platform Tools from Google or run `weevil setup`.
### "Build failed" ### "Build failed"
@@ -437,6 +637,9 @@ cd my-robot
# Check SDK path # Check SDK path
weevil config . weevil config .
# Verify system health
weevil doctor
``` ```
### "Deploy failed - No devices" ### "Deploy failed - No devices"
@@ -451,6 +654,24 @@ weevil config .
2. Find Control Hub IP (usually 192.168.43.1 or 192.168.49.1) 2. Find Control Hub IP (usually 192.168.43.1 or 192.168.49.1)
3. Try `./deploy.sh -i <ip>` 3. Try `./deploy.sh -i <ip>`
### Android Studio: "Unknown run configuration type ShellScript"
The Shell Script plugin is not installed. See [Android Studio Setup](#android-studio-setup) for installation instructions.
### Proxy Issues
```bash
# Test proxy connectivity
weevil --proxy http://proxy:8080 sdk status
# Bypass proxy if it's causing issues
weevil --no-proxy setup
# Check environment variables
echo $HTTPS_PROXY
echo $HTTP_PROXY
```
--- ---
## Contributing ## Contributing
@@ -490,6 +711,7 @@ Like the boll weevil that bores through complex cotton bolls to reach the valuab
3. **Testability** - Enable TDD and proper testing workflows 3. **Testability** - Enable TDD and proper testing workflows
4. **Simplicity** - One command should do one obvious thing 4. **Simplicity** - One command should do one obvious thing
5. **Transparency** - Students should understand what's happening 5. **Transparency** - Students should understand what's happening
6. **Tool compatibility** - Work with tools students already know
--- ---
@@ -511,22 +733,27 @@ Built with frustration at unnecessarily complex robotics frameworks, and hope th
## Project Status ## Project Status
**Current Version:** 1.0.0 **Current Version:** 1.1.0
**What Works:** **What Works:**
- ✅ Project generation - ✅ Project generation
- ✅ Cross-platform build/deploy - ✅ Cross-platform build/deploy
- ✅ SDK management - ✅ SDK management and auto-install
- ✅ Configuration management - ✅ Configuration management
- ✅ Project upgrades - ✅ Project upgrades
- ✅ Local testing - ✅ Local unit testing
- ✅ System diagnostics (`weevil doctor`)
- ✅ Selective uninstall
- ✅ Proxy support for corporate/air-gapped environments
- ✅ Android Studio integration with one-click deployment
**Roadmap:** **Roadmap:**
- 📋 Package management for FTC libraries - 📋 Package management for FTC libraries
- 📋 Template system for common robot configurations - 📋 Template system for common robot configurations
- 📋 IDE integration (VS Code, IntelliJ) - 📋 VS Code integration
- 📋 Team collaboration features - 📋 Team collaboration features
- 📋 Automated testing on robot hardware - 📋 Automated testing on robot hardware
- 📋 Multi-robot support (manage multiple Control Hubs)
--- ---