FTC-Project-Gen/README.md

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

# 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

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

# 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

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

# 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

# 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

./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