Restructured linux to match Windows
This commit is contained in:
Eric Ratliff
279
DEVELOPER.md
Normal file
279
DEVELOPER.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# 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
Block a user