FTC-Project-Gen/GETTING_STARTED.md

Getting Started with FTC Project Generator 1.0.0-beta

Quick Validation Checklist

Use this checklist to verify everything works:

☐ 1. Extract and Navigate

cd ftc-project-gen-1.0.0-beta

☐ 2. Run Tests

./tests/run-tests.sh

Expected: All tests pass (green ✓)

☐ 3. Create Test Project

./ftc-new-project demo-robot

Expected: Success message, directory created

☐ 4. Verify Project Structure

cd demo-robot
ls -la

Expected: See src/, build.gradle.kts, README.md, etc.

☐ 5. Build the Project

./gradlew build

Expected: BUILD SUCCESSFUL

☐ 6. Run Project Tests

./gradlew test

Expected: 3 tests pass

☐ 7. Test Continuous Mode

./gradlew test --continuous

Expected: Tests run, waits for changes Press Ctrl+C to exit

☐ 8. Test Upgrade

cd ..
# Edit VERSION file: change to 1.0.1-beta
./ftc-new-project demo-robot --upgrade

Expected: Upgrade successful message

☐ 9. Review Upgrade Changes

cd demo-robot
git diff

Expected: See changes to build files, no changes to src/

☐ 10. Test Duplicate Detection

cd ..
./ftc-new-project demo-robot

Expected: Error message suggesting --upgrade

Installation Options

Option 1: System-wide (Recommended)

sudo ./install.sh

Then use from anywhere:

ftc-new-project my-robot

Option 2: User Install

mkdir -p ~/.local/bin
INSTALL_DIR=~/.local/bin ./install.sh

Add to ~/.bashrc if needed:

echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
source ~/.bashrc

Option 3: Use Directly

./ftc-new-project my-robot

Next Steps After Validation

For Daily Use

1. Create your actual project:

   ftc-new-project team-1234-robot
   

2. Start developing:

   cd team-1234-robot
   ./gradlew test --continuous
   

3. Edit code:

   • Open in your IDE (IntelliJ IDEA, VS Code, etc.)
   • Edit src/main/java/robot/subsystems/Drive.java
   • Edit src/test/java/robot/subsystems/DriveTest.java
   • Watch tests auto-run

For Windows Support

1. Create windows/lib.bat:

   • Port functions from linux/lib.sh
   • Follow same structure
   • Use Windows path separators

2. Create ftc-new-project.bat:

   • Port from ftc-new-project
   • Use delayed expansion
   • Call windows/lib.bat functions

3. Test on Windows:

   • Run through same checklist
   • Verify templates work
   • Test upgrade functionality

For Future Development

1. Read documentation:

   • README.md - User guide
   • QUICKSTART.md - Quick start
   • DEVELOPER.md - Contributing
   • CHANGELOG.md - History

2. Make improvements:

   • Add new templates
   • Enhance test coverage
   • Improve error messages

3. Share with team:

   • Commit to version control
   • Tag releases
   • Distribute to FTC mentors/students

Troubleshooting

Tests Fail

Problem: Tests don't pass Solution:

1. Check git, java, gradle installed
2. Run ./gradlew clean build
3. Check /tmp/gradle-*.log for details

Project Won't Build

Problem: ./gradlew build fails Solution:

1. Check Java version: java -version (need 11+)
2. Try ./gradlew clean build --refresh-dependencies
3. Delete .gradle/ directory and try again

Upgrade Doesn't Work

Problem: Upgrade command fails Solution:

1. Verify .ftc-generator-version exists
2. Check you're in parent directory
3. Ensure project name is correct

Templates Not Found

Problem: Template errors during creation Solution:

1. Verify templates directory exists
2. Check all templates present
3. Verify permissions (readable)

Validation Criteria

Your installation is working if:

• ✓ All tests pass
• ✓ Demo project creates successfully
• ✓ Demo project builds
• ✓ Demo project tests pass
• ✓ Upgrade works
• ✓ Duplicate detection works

Ready to Ship?

Once you've verified:

1. Tests pass
2. Projects create and build
3. Upgrade works
4. Documentation is clear

You're ready for 1.0.0-beta release! 🎉

Getting Help

If you encounter issues:

1. Check DEVELOPER.md for architecture details
2. Review test output for specifics
3. Check generated project logs
4. Review template files for errors

Success Looks Like

A successful validation means:

• You can create projects in seconds
• Projects build immediately
• Tests run instantly on PC
• Upgrade preserves your code
• Multiple projects share one SDK

Welcome to clean FTC development! 🤖