188 lines
4.7 KiB
Markdown
188 lines
4.7 KiB
Markdown
# FTC Project Generator 1.0.0-beta
|
|
|
|
Clean, testable FTC robot projects with shared SDK architecture.
|
|
|
|
## Version 1.0.0-beta
|
|
|
|
This is the beta release focusing on stability, testing, and upgrade capabilities.
|
|
|
|
## 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 new project
|
|
./ftc-new-project my-robot
|
|
|
|
# Upgrade existing project
|
|
./ftc-new-project my-robot --upgrade
|
|
|
|
# Enter and test
|
|
cd my-robot
|
|
./gradlew test --continuous
|
|
```
|
|
|
|
### Windows
|
|
```batch
|
|
REM Create new project
|
|
ftc-new-project.bat my-robot
|
|
|
|
REM Upgrade existing project
|
|
ftc-new-project.bat my-robot --upgrade
|
|
|
|
REM Enter and test
|
|
cd my-robot
|
|
gradlew test --continuous
|
|
```
|
|
|
|
## Installation
|
|
|
|
### Linux/macOS
|
|
```bash
|
|
# Option 1: Add to PATH
|
|
echo 'export PATH=$PATH:/path/to/ftc-project-gen' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
|
|
# 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
|
|
```
|
|
|
|
### Windows
|
|
```batch
|
|
REM Add directory to PATH or use directly
|
|
ftc-new-project.bat my-robot
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
```bash
|
|
# Run all tests
|
|
./tests/run-tests.sh
|
|
|
|
# Run specific test suite
|
|
./tests/run-tests.sh unit
|
|
./tests/run-tests.sh system
|
|
|
|
# Run specific test
|
|
./tests/run-tests.sh unit test_template_rendering
|
|
```
|
|
|
|
### 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
|
|
|
|
## Upgrading
|
|
|
|
### 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 License - See individual project files for details.
|
|
|
|
Copyright (c) 2026 Nexus Workshops LLC
|