Restructured linux to match Windows

2026-01-24 12:39:32 -06:00
parent b1593a4f87
commit fd9c573131
30 changed files with 3120 additions and 1746 deletions
--- a/README.md
+++ b/README.md
@@ -1,295 +1,187 @@
-# FTC Project Generator
+# FTC Project Generator 1.0.0-beta

-Generate clean, testable FTC robot projects. Keep YOUR code separate from the FTC SDK bloat.
+Clean, testable FTC robot projects with shared SDK architecture.

-## Philosophy
+## Version 1.0.0-beta

-**Normal FTC Way:** Clone their repo, modify their code  
-**This Way:** Your code is clean, FTC SDK is just a dependency
+This is the beta release focusing on stability, testing, and upgrade capabilities.

-One shared SDK, multiple clean projects. Test on PC, deploy when ready.
+## Features
+
+- ✓ Clean project structure separate from FTC SDK
+- ✓ Instant testing on PC (no robot required)
+- ✓ Shared SDK across multiple projects
+- ✓ Linux and Windows support
+- ✓ Project upgrade capabilities
+- ✓ Comprehensive unit and system tests
+- ✓ Template-based file generation

 ## Quick Start

+### Linux/macOS
 ```bash
-# Create your first project
+# Create new project
 ./ftc-new-project my-robot

-# Create another project (reuses same SDK!)
-./ftc-new-project another-bot
+# Upgrade existing project
+./ftc-new-project my-robot --upgrade

-# Use specific FTC version
-./ftc-new-project test-bot --version v10.0.0
-```
-
-## What It Does
-
-1. **Checks/clones FTC SDK** (once, shared across projects)
-2. **Creates YOUR clean project** with:
-   - Minimal structure
-   - Test scaffolding
-   - Example subsystem
-   - Composite build to SDK
-3. **Ready to code** - tests run immediately
-
-## Generated Project Structure
-
-```
-my-robot/
-├── build.gradle.kts          # Your build (references SDK)
-├── settings.gradle.kts       # Composite build setup
-├── gradlew                   # Gradle wrapper
-├── README.md                 # Project-specific docs
-└── src/
-    ├── main/java/robot/
-    │   ├── Pose2d.java              # Utility classes
-    │   ├── subsystems/
-    │   │   └── Drive.java           # Example subsystem
-    │   ├── hardware/
-    │   │   └── MecanumDrive.java    # Hardware impl stub
-    │   └── opmodes/
-    │       └── TeleOp.java          # FTC OpMode
-    └── test/java/robot/
-        └── subsystems/
-            └── DriveTest.java       # Unit test
-
-Separate (shared):
-~/ftc-sdk/                    # FTC SDK (one copy for all projects)
-```
-
-## Usage
-
-### Development (Day-to-Day)
-
-```bash
+# Enter and test
 cd my-robot
-
-# Run tests
-./gradlew test
-
-# Watch mode (auto-rerun on save)
 ./gradlew test --continuous
-
-# Write code, tests pass → you're good!
 ```

-### Deployment (When Ready for Robot)
+### Windows
+```batch
+REM Create new project
+ftc-new-project.bat my-robot

-```bash
-# 1. Deploy your code to SDK
-./gradlew deployToSDK
+REM Upgrade existing project
+ftc-new-project.bat my-robot --upgrade

-# 2. Build APK
-cd ~/ftc-sdk
-./gradlew build
-
-# 3. Install to robot
-# Use Android Studio's deploy button, or:
-adb install FtcRobotController/build/outputs/apk/debug/FtcRobotController-debug.apk
+REM Enter and test
+cd my-robot
+gradlew test --continuous
 ```

-## Multiple Projects
-
-The beauty: **one SDK, many projects**
-
-```bash
-# Create project 1
-./ftc-new-project swerve-bot
-
-# Create project 2 (reuses SDK!)
-./ftc-new-project mecanum-bot
-
-# Create project 3 (still same SDK!)
-./ftc-new-project test-chassis
-```
-
-Each project:
- Has its own git repo
- Tests independently
- Deploys to shared SDK
- Can have different license
- Is YOUR code, not FTC's
-
-## Commands Reference
-
-```bash
-# Basic usage
-./ftc-new-project <name>
-
-# Specify FTC version
-./ftc-new-project <name> --version v10.1.1
-
-# Custom SDK location
-./ftc-new-project <name> --sdk-dir ~/my-ftc
-
-# Get help
-./ftc-new-project --help
-```
-
-## Environment Variables
-
-```bash
-# Set default SDK location
-export FTC_SDK_DIR=~/ftc-sdk
-
-# Now just:
-./ftc-new-project my-robot
-```
-
-## Pattern: Subsystems
-
-Every generated project follows this pattern:
-
-```java
-// Your subsystem
-public class MySubsystem {
-    private final Hardware hardware;
-    
-    public MySubsystem(Hardware hardware) {
-        this.hardware = hardware;
-    }
-    
-    // Business logic here - tests on PC
-    public void doSomething() {
-        hardware.doThing();
-    }
-    
-    // Inner interface - implement for robot
-    public interface Hardware {
-        void doThing();
-    }
-}
-
-// Test (inline mock)
-class MySubsystemTest {
-    static class MockHardware implements MySubsystem.Hardware {
-        boolean didThing = false;
-        public void doThing() { didThing = true; }
-    }
-    
-    @Test
-    void test() {
-        MockHardware mock = new MockHardware();
-        MySubsystem sys = new MySubsystem(mock);
-        sys.doSomething();
-        assertTrue(mock.didThing);
-    }
-}
-
-// Hardware impl (for robot)
-public class RealHardware implements MySubsystem.Hardware {
-    private DcMotor motor;
-    
-    public RealHardware(HardwareMap map) {
-        motor = map.get(DcMotor.class, "motor");
-    }
-    
-    public void doThing() {
-        motor.setPower(1.0);
-    }
-}
-```
-
-## Why This Is Better
-
-**Traditional FTC:**
- Clone 200MB repo
- Your code mixed with SDK
- Hard to test
- Hard to share
- Stuck with their structure
-
-**This Way:**
- Your project: ~50KB
- SDK: shared, separate
- Easy to test (runs on PC)
- Easy to share (just your code)
- Your structure, your license
-
-## FAQ
-
-**Q: Can I use multiple FTC versions?**  
-A: Yes! Different projects can reference different SDK dirs.
-
-**Q: What if I want to update the SDK?**  
-A: `cd ~/ftc-sdk && git pull && git checkout v10.2.0`  
-   Or specify new version when creating project.
-
-**Q: Does this work with Android Studio?**  
-A: For deployment, yes. For development, use whatever you want (Sublime, vim, etc).
-
-**Q: Can I put my project on GitHub with a different license?**  
-A: Yes! Your code is separate. Just don't include SDK files.
-
-**Q: What about Control Hub having multiple programs?**  
-A: Each project creates OpModes. Deploy multiple projects to SDK, build once, all show up on Control Hub.
-
 ## Installation

+### Linux/macOS
 ```bash
-# Extract the generator
-tar xzf ftc-project-generator.tar.gz
-cd ftc-project-gen
-
-# Option 1: Run install script (recommended)
-./install.sh             # Shows options
-sudo ./install.sh        # System-wide install
-
-# Option 2: Manual symlink
-sudo ln -s $(pwd)/ftc-new-project /usr/local/bin/
-
-# Option 3: Add to PATH
-echo "export PATH=\$PATH:$(pwd)" >> ~/.bashrc
+# Option 1: Add to PATH
+echo 'export PATH=$PATH:/path/to/ftc-project-gen' >> ~/.bashrc
 source ~/.bashrc

-# Verify installation
-ftc-new-project --help
+# Option 2: Symlink
+sudo ln -s /path/to/ftc-project-gen/ftc-new-project /usr/local/bin/
+
+# Option 3: Use directly
+./ftc-new-project my-robot
 ```

-## The Magic
+### Windows
+```batch
+REM Add directory to PATH or use directly
+ftc-new-project.bat my-robot
+```

-When you run tests, your code uses **interfaces** and **mocks** - no FTC SDK needed.
+## Project Structure

-When you deploy, your code gets copied to SDK's TeamCode and built with the real FTC libraries.
+```
+ftc-project-gen-1.0.0-beta/
+├── ftc-new-project              # Linux main script
+├── ftc-new-project.bat          # Windows main script
+├── linux/                       # Linux-specific support files
+│   ├── templates/              # File templates
+│   │   ├── Pose2d.java
+│   │   ├── Drive.java
+│   │   ├── DriveTest.java
+│   │   ├── MecanumDrive.java
+│   │   ├── TeleOp.java
+│   │   ├── build.gradle.kts
+│   │   ├── settings.gradle.kts.template
+│   │   ├── gitignore.template
+│   │   ├── README.md.template
+│   │   ├── build.sh
+│   │   └── deploy-to-robot.sh
+│   └── lib.sh                  # Shared functions
+├── windows/                    # Windows-specific support files
+│   ├── templates/              # File templates
+│   │   └── (mirrors linux templates)
+│   └── lib.bat                 # Shared functions
+├── tests/                      # Test suite
+│   ├── unit/                   # Unit tests
+│   └── system/                 # System/integration tests
+├── VERSION                     # Version file
+└── README.md
+```

-Your code stays clean. SDK is just a build tool.
-
-## Example Session
+## Development

+### Running Tests
 ```bash
-# Create project
-$ ./ftc-new-project my-bot
->>> Checking FTC SDK...
-SDK directory exists, checking version...
-✓ SDK already at version v10.1.1
->>> Creating project: my-bot
-✓ Project created: my-bot
+# Run all tests
+./tests/run-tests.sh

-# Develop
-$ cd my-bot
-$ ./gradlew test
-BUILD SUCCESSFUL
-2 tests passed
+# Run specific test suite
+./tests/run-tests.sh unit
+./tests/run-tests.sh system

-# Add code, tests pass...
-
-# Ready to deploy
-$ ./gradlew deployToSDK
-Code deployed to TeamCode - ready to build APK
-
-$ cd ~/ftc-sdk
-$ ./gradlew build
-BUILD SUCCESSFUL
-
-# Install to robot...
+# Run specific test
+./tests/run-tests.sh unit test_template_rendering
 ```

-Clean, simple, modular. As it should be.
+### Testing Philosophy
+- **Unit tests**: Test individual functions and template rendering
+- **System tests**: Test end-to-end project creation, building, and upgrading
+- **Regression tests**: Ensure generated projects build and pass their own tests

-## Credits
+## Upgrading

-Built by frustrated mentors who think the standard FTC setup is backwards.
+### What Gets Updated
+When you run with `--upgrade`:
+- ✓ Build configuration files (build.gradle.kts, settings.gradle.kts)
+- ✓ Helper scripts (build.sh, deploy-to-robot.sh)
+- ✓ .gitignore
+- ✗ Your source code (never touched)
+- ✗ Your tests (never touched)
+
+### Upgrade Process
+```bash
+# Backup recommended but not required (git protects you)
+cd my-robot
+git status  # Make sure you've committed your work
+
+# Run upgrade
+ftc-new-project my-robot --upgrade
+
+# Review changes
+git diff
+
+# Test
+./gradlew test
+```
+
+## Architecture
+
+### Template System
+Files are stored as templates in `templates/` directories. Templates can contain placeholders:
+- `{{PROJECT_NAME}}` - Replaced with project name
+- `{{SDK_DIR}}` - Replaced with SDK directory path
+- `{{FTC_VERSION}}` - Replaced with FTC SDK version
+
+### Upgrade System
+Projects track their generator version in `.ftc-generator-version`. During upgrade:
+1. Check if project exists
+2. Verify it's a generator project
+3. Update only infrastructure files
+4. Preserve user code
+5. Update version marker
+
+### Cross-Platform Support
+- Linux: Bash scripts with POSIX compliance
+- Windows: Batch scripts with delayed expansion
+- Shared logic where possible
+- Platform-specific implementations in separate directories
+
+## Contributing
+
+### Adding New Templates
+1. Create template file in `linux/templates/` and `windows/templates/`
+2. Use placeholders for variable content
+3. Update `lib.sh`/`lib.bat` to include new template
+4. Add tests for the new template
+5. Update documentation
+
+### Running Tests Before Commit
+```bash
+./tests/run-tests.sh
+```
+
+All tests must pass before submitting changes.

 ## License

-MIT - do whatever you want. Unlike FTC's forced BSD license nonsense.
+MIT License - See individual project files for details.
+
+Copyright (c) 2026 Nexus Workshops LLC