diff --git a/.plans/DockerForVitaSDK.md b/.plans/DockerForVitaSDK.md new file mode 100644 index 0000000..a681e92 --- /dev/null +++ b/.plans/DockerForVitaSDK.md @@ -0,0 +1,362 @@ +# Docker Build Environment Plan for VitaSDK (PS Vita) + +**Status**: Planning / Research +**Last Updated**: 2026-01-27 + +--- + +## Overview + +PS Vita homebrew development uses **VitaSDK**, a completely separate toolchain from devkitPro. This requires a different container approach but follows similar principles: extend official base images and install all available packages for a complete development environment. + +**Key Differences from devkitPro**: +- Separate ecosystem with its own toolchain (vita-toolchain) +- Different package manager: `vdpm` (shell-based) instead of `dkp-pacman` +- Different build system: CMake with Vita-specific macros +- Official Docker images: `vitasdk/vitasdk` (not on devkitPro organization) +- Output formats: SELF (executable), VPK (installable package archive) + +--- + +## PS Vita Platform Capabilities + +### Hardware Features +- **Networking**: ✅ Built-in Wi-Fi (802.11 b/g/n) + - Optional 3G modem (discontinued in 2013, limited availability) + - Bluetooth 2.1+EDR +- **Screenshots**: ✅ Native system-level screenshot capability +- **Cameras**: ✅ Dual 0.3MP cameras (front and back) + - VGA resolution (640×480 @ 60fps) + - Can capture photos and videos +- **Display**: 5-inch OLED touchscreen (original) or LCD (slim) +- **CPU**: Quad-core ARM Cortex-A9 MPCore +- **GPU**: Quad-core PowerVR SGX543MP4+ +- **RAM**: 512 MB system RAM, 128 MB VRAM + +### Project Fit Assessment +✅ **Networking**: Yes - Wi-Fi built-in, suitable for Nextcloud uploads +✅ **Screenshots**: Yes - native system capability for game captures +✅ **Cameras**: Yes - can take photos with built-in cameras +✅ **Homebrew Scene**: Active community with VitaSDK +✅ **Container Support**: Official Docker images available + +**Priority**: **HIGH** - Meets all requirements (networking + screenshots + cameras) + +--- + +## VitaSDK Ecosystem + +### Official Resources +- **Website**: https://vitasdk.org/ +- **GitHub Organization**: https://github.com/vitasdk (15 repositories) +- **Docker Repository**: https://github.com/vitasdk/docker +- **Package Repository**: https://github.com/vitasdk/packages (updated frequently) +- **Samples Repository**: https://github.com/vitasdk/samples (335 stars) +- **Documentation**: https://docs.vitasdk.org/ + +### Toolchain Components +- **vita-toolchain**: ARM-based cross-compiler (MIT license) +- **newlib**: PS Vita port of C library (GPL-2.0) +- **vita-headers**: System headers (233 stars, 94 forks) +- **buildscripts**: CMake-based build system (65 stars) +- **taihen**: Plugin framework +- **libvita2d**: 2D graphics library + +### Package Management +- **Tool**: vdpm (Vita SDK Package Manager) +- **Type**: Shell-based installer scripts +- **Repository**: https://github.com/vitasdk/packages +- **Installation**: Bootstrap with `./install-all.sh` from vdpm repo +- **Build Format**: vita-makepkg (similar to Arch Linux makepkg) + +### Build System +- **Primary**: CMake with Vita-specific macros + - `vita_create_self()` - Creates SELF executable + - `vita_create_vpk()` - Creates VPK package +- **Output Formats**: + - SELF: Signed ELF executable format + - VPK: Installable package archive (SELF + data + metadata) + +--- + +## Official Docker Images + +### Available on Docker Hub +```bash +# Search results show multiple official images +docker.io/vitasdk/vitasdk # Main official image +docker.io/vitasdk/vitasdk-softfp # Soft float variant +docker.io/vitasdk/buildscripts # Build tools base image +``` + +### Base Image Structure +From `github.com/vitasdk/docker`: + +**Main Dockerfile**: +- Base: `vitasdk/buildscripts:latest` +- Installs: git, curl, bash, make, pkgconf, cmake, sudo +- Uses multi-stage build to clone and install vdpm +- Installs all packages via `vdpm/install-all.sh` +- Environment: `VITASDK=/usr/local/vitasdk` + +**Non-root Dockerfile**: +- Same base, but creates unprivileged user +- Adds sudo access for package installation +- Better for local development (matches host UID) + +--- + +## Container Strategy + +### Approach +Unlike devkitPro platforms, VitaSDK already provides comprehensive official images with all packages pre-installed. Our strategy should be: + +**Option 1: Use Official Images Directly** (Recommended) +- Use `vitasdk/vitasdk:latest` as-is +- No custom Dockerfile needed +- Pull official image when needed +- Simplest approach, maintained by VitaSDK team + +**Option 2: Extend Official Images** (If customization needed) +- Base: `FROM vitasdk/vitasdk:latest` +- Add project-specific tools or scripts +- Pin to specific tag for reproducibility +- Only if we need additional packages + +### Tagging Strategy +If we publish custom images: +- Format: `tomusan/vitasdk-vita:` or `tomusan/vitasdk-vita:-v` +- Example: `tomusan/vitasdk-vita:20251231` or `tomusan/vitasdk-vita:20251231-v1.0.0` +- Follow same conventions as devkitPro containers + +--- + +## Package Ecosystem Research + +### Known Libraries (from vdpm) +- **zlib**: Compression library +- **freetype**: Font rendering +- **libvita2d**: 2D graphics library (Vita-specific) +- **taihen**: Plugin framework (Vita-specific) + +### Additional Research Needed +- [ ] Query vdpm package list for available networking libraries +- [ ] Check for curl, libcurl support +- [ ] Verify SSL/TLS libraries (mbedtls, openssl, etc.) +- [ ] Check for image format libraries (PNG, JPEG) +- [ ] Verify XML/JSON parsing libraries +- [ ] Document complete package list similar to devkitPro research + +### How to Query Packages +```bash +# Run official container and list packages +podman run --rm vitasdk/vitasdk:latest bash -c "cd /usr/local/vitasdk && find . -name '*.a' -o -name '*.so'" + +# Or check vdpm repository +# Clone https://github.com/vitasdk/packages and inspect package definitions +``` + +--- + +## Hardware Requirements + +### Hacked Console Required +PS Vita homebrew requires modified firmware: +- **HENkaku**: Firmware 3.60 +- **h-encore**: Firmware 3.65-3.68 +- **Trinity**: Firmware 3.69-3.70 + +This is similar to 3DS requiring custom firmware (CFW). Not a blocker for development, but users need hacked consoles to run homebrew. + +--- + +## Implementation Plan + +### Phase 1: Research & Validation +- [ ] Test official `vitasdk/vitasdk` image locally +- [ ] Create simple "Hello World" program +- [ ] Build VPK package and test on hardware/emulator +- [ ] Document build process +- [ ] Query complete package list from vdpm +- [ ] Verify networking library availability (curl, SSL/TLS) + +### Phase 2: Integration Planning +- [ ] Determine if custom Dockerfile is needed (likely not) +- [ ] Create build scripts for Vita platform + - `scripts/build-vita.sh` - Build project using container + - `scripts/container-shell-vita.sh` - Interactive development shell +- [ ] Update main `scripts/build-container.sh` to handle VitaSDK +- [ ] Document Vita-specific build flags and configuration + +### Phase 3: Project Integration +- [ ] Create Vita source directory structure +- [ ] Implement Nextcloud client for Vita +- [ ] Test screenshot upload functionality +- [ ] Test camera photo upload functionality +- [ ] Integrate with main project build system + +--- + +## Platform Priority Assessment + +**Priority: HIGH** + +Justification: +- ✅ Full networking support (Wi-Fi built-in) +- ✅ Native screenshot capability for game captures +- ✅ Dual cameras for photo capture +- ✅ Active homebrew community and toolchain +- ✅ Official Docker images available +- ✅ Similar form factor to 3DS (handheld gaming device) +- ✅ Fits project goals perfectly + +**Recommendation**: Add PS Vita alongside 3DS, Switch, and Wii U as HIGH priority platform. + +--- + +## Differences from devkitPro Platforms + +| Aspect | devkitPro | VitaSDK | +|--------|-----------|---------| +| **Organization** | devkitPro | vita-dev (separate) | +| **Toolchain** | devkitARM/A64/PPC | vita-toolchain (ARM) | +| **Package Manager** | dkp-pacman (Arch-style) | vdpm (shell scripts) | +| **Build System** | Native makefiles + CMake | CMake with Vita macros | +| **Docker Hub** | devkitpro/* | vitasdk/* | +| **Package Format** | .pkg.tar.xz | vita-makepkg scripts | +| **Output Format** | .elf, .nro, .rpx | .self, .vpk | +| **Install Path** | /opt/devkitpro | /usr/local/vitasdk | + +--- + +## Container Usage Examples + +### Using Official Image Directly +```bash +# Pull official image +podman pull vitasdk/vitasdk:latest + +# Build project +podman run --rm -v .:/project:z -w /project/vita \ + vitasdk/vitasdk:latest \ + cmake -B build && cmake --build build + +# Interactive shell for development +podman run --rm -it -v .:/project:z -w /project \ + vitasdk/vitasdk:latest \ + bash +``` + +### If Custom Image Needed +```dockerfile +# vita.Dockerfile +FROM vitasdk/vitasdk:latest + +# Add any project-specific tools +RUN apk add --no-cache \ + vim \ + tree \ + htop + +# Set working directory +WORKDIR /project +``` + +--- + +## Community & Support + +### Official Channels +- **Discord**: Active VitaSDK community server +- **Matrix**: Bridge to Discord +- **IRC**: #vitasdk on libera.chat +- **Forums**: Various homebrew forums + +### Related Projects +- **VitaShell**: File manager (reference for file operations) +- **Adrenaline**: PSP emulator (advanced homebrew example) +- **RetroArch**: Multi-emulator (networking reference) +- Various homebrew games and apps using VitaSDK + +--- + +## Hardware Specifications + +| Component | Specification | +|-----------|---------------| +| **CPU** | Quad-core ARM Cortex-A9 MPCore | +| **GPU** | Quad-core PowerVR SGX543MP4+ | +| **RAM** | 512 MB + 128 MB VRAM | +| **Display** | 5" OLED/LCD touchscreen, 960×544 (qHD) | +| **Storage** | Proprietary memory cards (4-64 GB) | +| **Cameras** | Front/back 0.3MP (VGA @ 60fps) | +| **Connectivity** | Wi-Fi b/g/n, Bluetooth 2.1+EDR, (3G optional) | +| **Battery** | 2210 mAh (3-5 hours gameplay) | +| **Input** | Touchscreen, rear touchpad, dual analog sticks, buttons, Sixaxis motion | + +--- + +## References + +### Official Documentation +- [VitaSDK Website](https://vitasdk.org/) - Main landing page +- [VitaSDK GitHub](https://github.com/vitasdk) - Organization with all repos +- [VitaSDK Docker](https://github.com/vitasdk/docker) - Official Dockerfile source +- [VitaSDK Packages](https://github.com/vitasdk/packages) - Available libraries +- [VitaSDK Samples](https://github.com/vitasdk/samples) - Example code +- [VitaSDK Documentation](https://docs.vitasdk.org/) - API reference + +### Docker Images +- [Docker Hub - vitasdk/vitasdk](https://hub.docker.com/r/vitasdk/vitasdk) +- [Docker Hub - vitasdk/buildscripts](https://hub.docker.com/r/vitasdk/buildscripts) + +### Hardware Information +- [PlayStation Vita - Wikipedia](https://en.wikipedia.org/wiki/PlayStation_Vita) - Comprehensive hardware specs +- [PS Vita Dev Wiki](https://wiki.henkaku.xyz/) - Homebrew development wiki + +### Community Resources +- VitaSDK Discord Server - Active developer community +- [/r/vitahacks](https://reddit.com/r/vitahacks) - Reddit community + +--- + +## Next Steps + +When ready to implement PS Vita support: + +1. **Test Official Image**: + ```bash + podman pull vitasdk/vitasdk:latest + podman run --rm -it vitasdk/vitasdk:latest bash + ``` + +2. **Create Hello World**: + - Simple CMakeLists.txt + - Basic main.c with vita2d graphics + - Build VPK package + +3. **Research Networking Libraries**: + - Query vdpm for available packages + - Test curl/libcurl availability + - Verify SSL/TLS support + +4. **Determine Custom Dockerfile Need**: + - If official image has everything → use directly + - If missing tools → create custom Dockerfile extending official image + +5. **Update Main Plan**: + - Add PS Vita to DockerForDevkitARM.md platform summary + - Note it uses separate VitaSDK ecosystem + - Include in Phase 3 implementation alongside Wii U + +--- + +## Notes + +- VitaSDK is completely independent from devkitPro - different organization, different toolchain +- Official images already include most/all packages via vdpm install-all +- May not need custom Dockerfile at all - official image might be sufficient +- PS Vita was discontinued in 2019, but homebrew scene remains active +- Estimated 15-16 million units sold worldwide (smaller than 3DS but larger than Wii U) +- Active indie game development continues as of 2026 +