# 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:<date>` or `tomusan/vitasdk-vita:<date>-v<semver>`
- 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