eric/FTC-Project-Gen
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9bd16f3dd073b8b1404bb46a57e51bc7d7d844b7
FTC-Project-Gen/DEVELOPER.md
Eric Ratliff fd9c573131 Restructured linux to match Windows
2026-01-24 12:39:32 -06:00

280 lines
8.0 KiB
Markdown
Raw Blame History

# Developer Documentation
## Project Structure
```
ftc-project-gen-1.0.0-beta/
├── ftc-new-project # Main entry point (Linux/macOS)
├── ftc-new-project.bat # Main entry point (Windows)
├── VERSION # Version file (1.0.0-beta)
├── README.md # User documentation
├── CHANGELOG.md # Version history
├── DEVELOPER.md # This file
│
├── linux/ # Linux-specific implementation
│ ├── lib.sh # Shared library functions
│ └── templates/ # File templates
│ ├── *.java # Java source templates
│ ├── *.kts # Gradle Kotlin scripts
│ ├── *.template # Templates with placeholders
│ └── *.sh # Helper scripts
│
├── windows/ # Windows-specific implementation
│ ├── lib.bat # Shared library functions
│ └── templates/ # File templates (mirrors Linux)
│
└── tests/ # Test suite
├── run-tests.sh # Test runner
├── unit/ # Unit tests
└── system/ # System/integration tests
```
## Architecture
### Template System
Templates are stored in `linux/templates/` and `windows/templates/`. They come in two types:
1. **Static templates**: Direct copies (e.g., Pose2d.java, Drive.java)
2. **Parameterized templates**: Use placeholders (e.g., settings.gradle.kts.template)
**Supported Placeholders:**
- `{{PROJECT_NAME}}` - Name of the project
- `{{SDK_DIR}}` - Path to FTC SDK
- `{{FTC_VERSION}}` - FTC SDK version tag
- `{{GENERATOR_VERSION}}` - Generator version
### Library Functions (lib.sh)
**Key Functions:**
- `get_generator_version()` - Read VERSION file
- `process_template(input, output)` - Replace placeholders
- `copy_template(src, dest)` - Direct file copy
- `create_project_structure(dir)` - Make directories
- `install_templates(project_dir, template_dir)` - Copy all templates
- `create_deploy_script(dir)` - Generate deployment script
- `setup_gradle_wrapper(dir)` - Configure Gradle
- `is_generator_project(dir)` - Check if dir is generator project
- `get_project_generator_version(dir)` - Read project version
- `upgrade_project(dir, template_dir)` - Upgrade infrastructure files
- `init_git_repo(dir)` - Initialize git
- `check_prerequisites()` - Validate environment
### Main Script Flow
1. Parse command-line arguments
2. Load library functions
3. Export environment variables for templates
4. Handle upgrade mode (if `--upgrade` flag)
5. Check if project exists (error if not upgrading)
6. Check prerequisites (git, java, gradle)
7. Setup/verify FTC SDK
8. Create project structure
9. Install templates
10. Setup Gradle wrapper
11. Initialize git repository
12. Display success message
### Upgrade Process
**What Gets Updated:**
- `build.gradle.kts` - Build configuration
- `settings.gradle.kts` - Gradle settings
- `.gitignore` - Git ignore rules
- `build.sh` / `build.bat` - Build helper script
- `deploy-to-robot.sh` / `deploy-to-robot.bat` - Deploy script
- `.ftc-generator-version` - Version marker
**What's Preserved:**
- All source code in `src/main/java/robot/`
- All tests in `src/test/java/robot/`
- README.md (user may have customized)
- Git history
- Gradle wrapper files
### Testing
**Unit Tests:**
- Template processing correctness
- Version extraction
- Template file existence
- Library function behavior
**System Tests:**
- End-to-end project creation
- Directory structure validation
- File existence checks
- Git repository initialization
- Project builds successfully
- Project tests pass
- Upgrade functionality
- Duplicate detection
**Running Tests:**
```bash
# All tests
./tests/run-tests.sh
# Just unit tests
./tests/run-tests.sh unit
# Just system tests
./tests/run-tests.sh system
```
## Adding New Features
### Adding a New Template
1. Create the template file in `linux/templates/` and `windows/templates/`
2. If it needs variable substitution, use `.template` extension and add placeholders
3. Update `install_templates()` in `lib.sh` / `lib.bat` to copy it
4. Add test to verify template exists
5. Update documentation
**Example:**
```bash
# Create template
cat > linux/templates/MyFile.java.template << 'EOF'
package robot;
// Generated for project: {{PROJECT_NAME}}
public class MyFile {
// ...
}
EOF
# Update lib.sh install_templates()
process_template "$template_dir/MyFile.java.template" "src/main/java/robot/MyFile.java"
# Update tests
REQUIRED_TEMPLATES+=("MyFile.java.template")
```
### Adding a New Placeholder
1. Export the variable in main script before template processing
2. Update `process_template()` to include the new placeholder
3. Update documentation
4. Add test to verify replacement works
**Example:**
```bash
# In ftc-new-project
export TEAM_NUMBER="12345"
# In lib.sh process_template()
sed -e "s|{{TEAM_NUMBER}}|${TEAM_NUMBER}|g" \
...
```
### Upgrading Template System
If you need to modify what files get upgraded:
1. Update `upgrade_project()` function in `lib.sh` / `lib.bat`
2. Add/remove files from the upgrade list
3. Test with existing projects
4. Update CHANGELOG.md
5. Bump version if breaking change
## Version Management
### Bumping Version
1. Update `VERSION` file
2. Update `CHANGELOG.md` with changes
3. Test thoroughly
4. Tag git release: `git tag -a v1.0.0-beta -m "Release 1.0.0-beta"`
5. Generated projects will use new version
### Version Compatibility
Projects track their generator version in `.ftc-generator-version`. This allows:
- Upgrade detection
- Version-specific upgrade logic (if needed)
- Migration paths between major versions
## Testing Strategy
### Pre-Commit Checklist
- [ ] All templates exist in both `linux/` and `windows/`
- [ ] Run `./tests/run-tests.sh` - all pass
- [ ] Create test project manually
- [ ] Build test project: `./gradlew build`
- [ ] Run test project tests: `./gradlew test`
- [ ] Test upgrade on existing project
- [ ] Update CHANGELOG.md
- [ ] Update VERSION if needed
### Release Checklist
- [ ] All tests pass
- [ ] Manual testing on Linux and Windows
- [ ] Documentation updated
- [ ] CHANGELOG.md current
- [ ] VERSION file bumped
- [ ] Git tag created
- [ ] README.md reflects current features
## Common Issues
### Template Processing
**Problem**: Placeholders not replaced
**Solution**: Make sure variable is exported before `process_template()` call
**Problem**: File not found during template install
**Solution**: Check template exists in `templates/` directory
### Testing
**Problem**: System tests fail with "command not found"
**Solution**: Install prerequisites (git, java, gradle)
**Problem**: Generated project doesn't build
**Solution**: Check Gradle configuration templates are valid
### Cross-Platform
**Problem**: Line endings differ between platforms
**Solution**: Use `.gitattributes` to normalize line endings
**Problem**: Path separators (/ vs \)
**Solution**: Use platform-appropriate functions in lib.sh/lib.bat
## Best Practices
1. **Templates are static**: Keep templates simple, move logic to scripts
2. **Test everything**: Add tests for new features
3. **Document changes**: Update CHANGELOG.md
4. **Version carefully**: Breaking changes require major version bump
5. **Preserve user code**: Never modify user source during upgrade
6. **Cross-platform parity**: Keep Linux and Windows in sync
## Future Improvements
Potential areas for enhancement:
- [ ] More template examples (autonomous, advanced subsystems)
- [ ] Template selection during creation (mecanum vs swerve)
- [ ] Web-based project generator
- [ ] CI/CD integration examples
- [ ] Performance optimization for large projects
- [ ] Plugin system for custom templates
- [ ] Migration tools for older FTC projects
## Contributing
1. Fork the repository
2. Create feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Update documentation
6. Submit pull request
## License
MIT License - See LICENSE file for details.
Reference in New Issue View Git Blame Copy Permalink