Merge pull request 'Add 3DS Docker Development Environment with CIA Support' (#23) from docker-for-devkitarm into develop

Reviewed-on: #23

.gitignore

@@ -70,3 +70,5 @@ third-party/build/
 *.tmp
 *.bak
 *.cache
+
+test-builds

.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:<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
+

README.md

@@ -62,9 +62,55 @@ git clone https://git.tomusan.com/your-username/nextcloud-share.git
 cd nextcloud-share
 ```
 
-### 2. Configure Test Environment
+### 2. Build the 3DS Development Container
 
-Copy the example configuration file:
+Build the container image (first time only, or when Dockerfile changes):
+
+```bash
+./scripts/build-container.sh 3ds
+```
+
+This creates a complete 3DS development environment with:
+- devkitARM GCC 15.2.0
+- All 47 available 3DS portlibs
+- CIA creation tools (bannertool, makerom, ctrtool)
+- Build time: ~10-15 minutes on first build
+
+**Note**: The container is built once and reused. You only rebuild when the Dockerfile changes.
+
+### 3. Compile Your 3DS Project
+
+```bash
+# From within your project directory
+cd your-3ds-project
+podman run --rm -v .:/project:z tomusan/devkitarm-3ds:latest make
+
+# Or specify a path
+podman run --rm -v ~/my-game:/project:z tomusan/devkitarm-3ds:latest make
+```
+
+**Output files**: `.3dsx` (homebrew), `.elf` (debug), `.smdh` (metadata), `.cia` (installable)
+
+### 4. Interactive Development Shell
+
+For debugging or manual builds:
+
+```bash
+# Current directory
+./scripts/container-shell.sh
+
+# Specific project
+./scripts/container-shell.sh ~/my-3ds-game
+
+# With extra volumes or environment
+./scripts/container-shell.sh ~/my-game -v /data:/data:z -e DEBUG=1
+```
+
+Inside the container, all devkitARM tools are available in PATH. Run `make` to build, `exit` to leave.
+
+### 5. Configure Test Environment (Optional)
+
+For testing with real Nextcloud servers, copy the example configuration:
 
 ```bash
 cp config.example config
@@ -79,40 +125,37 @@ NEXTCLOUD_USER=your-username
 NEXTCLOUD_PASSWORD=your-password
 ```
 
-**Note**: The `config` file is in `.gitignore` and will never be committed. Each developer should create their own local config.
+**Note**: The `config` file is in `.gitignore` and will never be committed.
-
-### 3. Build Using Podman
-
-#### Build the 3DS version:
-
-```bash
-# Build the container image (first time only)
-podman build -f docker/devkitarm.Dockerfile -t nextcloud-share-3ds .
-
-# Compile the project
-podman run --rm -v ./:/project:z nextcloud-share-3ds make -C 3ds
-
-# Output files will be in 3ds/build/
-```
-
-#### Run tests:
-
-```bash
-podman run --rm -v ./:/project:z nextcloud-share-3ds make test
-```
-
-#### Interactive development shell:
-
-```bash
-podman run --rm -it -v ./:/project:z nextcloud-share-3ds bash
-```
 
 ## 🔧 Building
 
-Detailed build instructions for each platform will be added as they are implemented. See platform-specific README files:
+### Using Development Containers
 
-- [3ds/README.md](3ds/README.md) - Nintendo 3DS build instructions
+All builds run in isolated containers with complete toolchains. See [docker/README.md](docker/README.md) for detailed container documentation.
-- More coming soon...
+
+**Available containers:**
+- **3DS**: `tomusan/devkitarm-3ds:latest` - Nintendo 3DS with full CIA support
+
+**Quick build commands:**
+```bash
+# Build 3DS container (first time)
+./scripts/build-container.sh 3ds
+
+# Compile a 3DS project
+podman run --rm -v ~/my-game:/project:z tomusan/devkitarm-3ds:latest make
+
+# Interactive shell
+./scripts/container-shell.sh ~/my-game
+```
+
+**Build performance:**
+- First build: ~10-15 minutes (downloads and compiles tools)
+- Subsequent builds: Instant (uses build cache)
+- Container rebuilds: Only needed when Dockerfile changes
+
+Platform-specific build instructions:
+- [docker/README.md](docker/README.md) - Container usage and CIA creation
+- More platforms coming soon...
 
 ## ⚙️ Configuration
 

docker/.dockerignore

@@ -0,0 +1,62 @@
+# Docker build context exclusions
+# Keep build context minimal for faster builds
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Build artifacts
+*.o
+*.elf
+*.3dsx
+*.cia
+*.smdh
+*.nro
+*.nso
+*.rpx
+*.rpl
+*.dol
+*.wad
+*.vpk
+*.self
+build/
+dist/
+*.log
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Documentation and plans (not needed in container)
+docs/
+.plans/
+*.md
+!docker/*.md
+
+# Config files (copied separately if needed)
+*.json
+*.toml
+*.yaml
+*.yml
+!package.json
+
+# Node modules and dependencies
+node_modules/
+venv/
+__pycache__/
+*.pyc
+
+# Cache directories
+.cache/
+.ccache/
+*.cache
+
+# Temporary files
+tmp/
+temp/
+*.tmp

docker/3ds.Dockerfile

@@ -0,0 +1,122 @@
+# Nintendo 3DS Development Container
+# Based on official devkitPro devkitARM image
+# Contains ALL available 3DS portlibs for complete development environment
+
+FROM devkitpro/devkitarm:20251231
+
+LABEL maintainer="nextcloud-share contributors"
+LABEL description="Complete Nintendo 3DS development environment with all available portlibs"
+LABEL org.opencontainers.image.base.name="devkitpro/devkitarm:20251231"
+LABEL org.opencontainers.image.title="Nintendo 3DS Development Container"
+LABEL platform="3ds"
+LABEL toolchain="devkitARM"
+
+# Update package database
+RUN dkp-pacman -Sy --noconfirm
+
+# Install 3DS development group (includes devkitARM, libctru, citro3d, citro2d, tools)
+RUN dkp-pacman -S --needed --noconfirm 3ds-dev
+
+# Install ALL available 3DS portlibs (alphabetical for clarity)
+# List verified from devkitpro/devkitarm:20251231 on 2026-01-27
+RUN dkp-pacman -S --needed --noconfirm \
+    3ds-box2d \
+    3ds-bulletphysics \
+    3ds-bzip2 \
+    3ds-curl \
+    3ds-flac \
+    3ds-flite \
+    3ds-freetype \
+    3ds-giflib \
+    3ds-jansson \
+    3ds-libarchive \
+    3ds-libconfig \
+    3ds-libfribidi \
+    3ds-libiconv \
+    3ds-libid3tag \
+    3ds-libjpeg-turbo \
+    3ds-libjson-c \
+    3ds-liblua51 \
+    3ds-liblzma \
+    3ds-libmad \
+    3ds-libmodplug \
+    3ds-libogg \
+    3ds-libopus \
+    3ds-libpng \
+    3ds-libsidplay \
+    3ds-libtheora \
+    3ds-libvorbisidec \
+    3ds-libxmp \
+    3ds-libzstd \
+    3ds-lz4 \
+    3ds-mbedtls \
+    3ds-mikmod \
+    3ds-mpg123 \
+    3ds-opusfile \
+    3ds-physfs \
+    3ds-sdl \
+    3ds-sdl_gfx \
+    3ds-sdl_image \
+    3ds-sdl_mixer \
+    3ds-sdl_ttf \
+    3ds-tinyxml2 \
+    3ds-wildmidi \
+    3ds-wslay \
+    3ds-yaml_cpp \
+    3ds-zlib && \
+    dkp-pacman -Scc --noconfirm
+
+# Install system build tools for development
+# Note: devkitarm-cmake is already installed as part of 3ds-dev group
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ccache \
+    ninja-build \
+    python3 \
+    python3-pip \
+    curl \
+    wget \
+    jq \
+    git \
+    zip \
+    unzip && \
+    rm -rf /var/lib/apt/lists/*
+
+# Configure ccache for faster rebuilds
+ENV CCACHE_DIR=/project/.ccache
+ENV CCACHE_MAXSIZE=2G
+
+# Add devkitARM compiler to PATH
+ENV PATH="${DEVKITARM}/bin:/usr/lib/ccache:${PATH}"
+
+# Build and install bannertool for CIA file creation
+RUN git clone --recursive https://github.com/diasurgical/bannertool.git /tmp/bannertool && \
+    cd /tmp/bannertool && \
+    make && \
+    cp output/linux-x86_64/bannertool /opt/devkitpro/tools/bin/ && \
+    chmod +x /opt/devkitpro/tools/bin/bannertool && \
+    cd / && \
+    rm -rf /tmp/bannertool
+
+# Build and install makerom and ctrtool for CIA file creation
+RUN git clone https://github.com/3DSGuy/Project_CTR.git /tmp/Project_CTR && \
+    cd /tmp/Project_CTR/makerom && \
+    make deps && make && \
+    cp bin/makerom /opt/devkitpro/tools/bin/ && \
+    chmod +x /opt/devkitpro/tools/bin/makerom && \
+    cd /tmp/Project_CTR/ctrtool && \
+    make deps && make && \
+    cp bin/ctrtool /opt/devkitpro/tools/bin/ && \
+    chmod +x /opt/devkitpro/tools/bin/ctrtool && \
+    cd / && \
+    rm -rf /tmp/Project_CTR
+
+# Set working directory
+WORKDIR /project
+
+# Verify installation
+RUN arm-none-eabi-gcc --version && \
+    make --version && \
+    cmake --version
+
+# Show installed 3DS packages on container startup
+CMD ["bash", "-c", "echo 'Nintendo 3DS Development Container Ready' && echo 'devkitARM:' && arm-none-eabi-gcc --version | head -n1 && echo '' && echo '3DS packages installed:' && dkp-pacman -Qq | grep '^3ds-' | wc -l && echo 'packages' && bash"]

docker/README.md

@@ -0,0 +1,316 @@
+# Nintendo 3DS Development Container
+
+Complete Docker/Podman container for Nintendo 3DS homebrew development with full CIA file creation support.
+
+## Features
+
+- **Complete devkitARM toolchain** - GCC 15.2.0 for ARM development
+- **All 47 3DS portlibs** - Every available library including graphics, audio, networking, physics, and compression
+- **CIA Creation Tools**:
+  - `bannertool` - Creates banner and icon files for CIA packages
+  - `makerom` - Assembles final CIA installation files
+  - `ctrtool` - Inspects and validates CIA structure
+  - `3dstools` - Includes 3dsxtool, smdhtool, mkromfs3ds
+- **Build optimization** - ccache for faster rebuilds
+- **Modern build tools** - CMake, Ninja, Python 3
+
+## Quick Start
+
+### Using Helper Scripts (Recommended)
+
+The easiest way to use these containers is with the provided helper scripts:
+
+**1. Build the container:**
+```bash
+./scripts/build-container.sh 3ds
+```
+
+**2. Open interactive shell:**
+```bash
+# Current directory
+./scripts/container-shell.sh
+
+# Specific project
+./scripts/container-shell.sh ~/my-3ds-game
+
+# With additional volumes or environment
+./scripts/container-shell.sh ~/my-game -v /data:/data:z -e DEBUG=1
+```
+
+### Manual Container Usage
+
+If you prefer to use podman/docker commands directly:
+
+**Building the Container:**
+```bash
+# Using Podman (recommended for rootless operation)
+podman build -t tomusan/devkitarm-3ds:latest -f docker/3ds.Dockerfile .
+
+# Using Docker
+docker build -t tomusan/devkitarm-3ds:latest -f docker/3ds.Dockerfile .
+```
+
+Build time: ~10-15 minutes on first build (downloads and compiles bannertool, makerom, ctrtool)
+
+**Compiling a 3DS Project:**
+
+Basic compilation (produces .3dsx homebrew file):
+```bash
+podman run --rm -v ./your-project:/project:z tomusan/devkitarm-3ds:latest make
+```
+
+With CIA file creation:
+```bash
+# Most 3DS projects with proper Makefile configuration
+podman run --rm -v ./your-project:/project:z tomusan/devkitarm-3ds:latest make
+```
+
+Clean and rebuild:
+```bash
+podman run --rm -v ./your-project:/project:z tomusan/devkitarm-3ds:latest bash -c "make clean && make"
+```
+
+**Interactive Shell:**
+
+For debugging or manual builds:
+```bash
+podman run -it --rm -v ./your-project:/project:z tomusan/devkitarm-3ds:latest bash
+```
+
+## Helper Scripts
+
+### build-container.sh
+
+Builds and tags development containers with automatic runtime detection (podman/docker).
+
+**Usage:**
+```bash
+./scripts/build-container.sh <platform> [version]
+```
+
+**Examples:**
+```bash
+# Build with default version (0.1.0)
+./scripts/build-container.sh 3ds
+
+# Build with custom version
+./scripts/build-container.sh 3ds 0.2.0
+
+# Show help
+./scripts/build-container.sh --help
+```
+
+**Features:**
+- Auto-detects podman/docker runtime
+- Validates semantic versioning (X.Y.Z format)
+- Tags both version and latest
+- Colored output with build status
+- Shows usage examples after successful build
+
+**Environment Variables:**
+- `CONTAINER_RUNTIME` - Override runtime (podman or docker)
+
+### container-shell.sh
+
+Opens an interactive bash shell in the development container with your project mounted.
+
+**Usage:**
+```bash
+./scripts/container-shell.sh [project-path] [podman-args...]
+```
+
+**Examples:**
+```bash
+# Shell in current directory
+./scripts/container-shell.sh
+
+# Shell in specific project
+./scripts/container-shell.sh ~/my-3ds-game
+
+# With additional volume mount
+./scripts/container-shell.sh ~/my-game -v /data:/data:z
+
+# With environment variable
+./scripts/container-shell.sh ~/my-game -e DEBUG=1
+
+# Multiple extra arguments
+./scripts/container-shell.sh ~/my-game -v /data:/data:z -e DEBUG=1 --network=host
+```
+
+**Features:**
+- First argument = project path (defaults to current directory)
+- All additional arguments passed to podman/docker run
+- Auto-detects podman/docker runtime
+- Colored output with container information
+- Project mounted at `/project` with working directory set
+
+**Environment Variables:**
+- `CONTAINER_RUNTIME` - Override runtime (podman or docker)
+
+## Output Files
+
+A complete 3DS build produces:
+
+- **`.3dsx`** - Homebrew Launcher executable format
+- **`.elf`** - Executable with debug symbols
+- **`.smdh`** - Icon and metadata for Homebrew Launcher
+- **`banner.bnr`** - Banner displayed when CIA is selected on home menu
+- **`icon.icn`** - Icon file for CIA package
+- **`.cia`** - Installable file for 3DS home menu
+
+## CIA File Creation
+
+The container includes all tools needed for complete CIA file creation:
+
+### Manual CIA Creation Workflow
+
+If your Makefile doesn't include CIA generation:
+
+```bash
+podman run --rm -v ./your-project:/project:z tomusan/devkitarm-3ds:latest bash -c '
+  # Build the application
+  make
+  
+  # Create banner (requires banner.png and audio.wav in assets/)
+  bannertool makebanner -i assets/banner.png -a assets/audio.wav -o build/banner.bnr
+  
+  # Create icon (requires icon.png in assets/)
+  bannertool makesmdh -s "App Title" -l "Description" -p "Author" \
+    -i assets/icon.png -o build/icon.icn
+  
+  # Create CIA file (requires app.rsf in assets/)
+  makerom -f cia -o output.cia -target t -exefslogo \
+    -elf output.elf -rsf assets/app.rsf \
+    -banner build/banner.bnr -icon build/icon.icn \
+    -DAPP_TITLE="App Title" \
+    -DAPP_PRODUCT_CODE="CTR-P-XXXX" \
+    -DAPP_UNIQUE_ID="0x12345"
+'
+```
+
+### Validating CIA Files
+
+```bash
+# Inspect CIA structure
+podman run --rm -v ./your-project:/project:z tomusan/devkitarm-3ds:latest \
+  ctrtool -i output.cia
+```
+
+## Installed Libraries
+
+The container includes all available 3DS portlibs:
+
+**Graphics & UI:**
+- citro3d, citro2d - 3DS GPU libraries
+- SDL, SDL_gfx, SDL_image, SDL_mixer, SDL_ttf
+- freetype, libpng, libjpeg-turbo, giflib
+
+**Audio:**
+- libopus, opusfile, libvorbisidec, libogg
+- flac, libmad, libmodplug, libxmp, mikmod, mpg123
+- wildmidi, libid3tag
+
+**Networking:**
+- curl, mbedtls, wslay
+
+**Data Formats:**
+- json-c, jansson, yaml_cpp, tinyxml2
+- libarchive, bzip2, liblzma, lz4, libzstd, zlib
+
+**Physics & Math:**
+- box2d, bulletphysics
+
+**Other:**
+- libconfig, libfribidi, libiconv, liblua51
+- physfs, libsidplay, libtheora
+
+## Container Environment
+
+```bash
+DEVKITPRO=/opt/devkitpro
+DEVKITARM=/opt/devkitpro/devkitARM
+PATH includes:
+  - ${DEVKITARM}/bin (ARM toolchain)
+  - /opt/devkitpro/tools/bin (bannertool, makerom, ctrtool)
+  - /usr/lib/ccache (build cache)
+```
+
+## Testing
+
+Verified working with:
+- **60/61 official 3ds-examples** - 98.4% success rate
+- **Checkpoint** - Real-world save manager application with full CIA creation
+
+## Troubleshooting
+
+### Permission Issues with Podman
+
+The `:z` flag in volume mounts sets proper SELinux context:
+```bash
+-v ./project:/project:z
+```
+
+### Container Size
+
+Expected size: ~1.6 GB (includes all libraries and build tools)
+
+### Build Cache
+
+To speed up rebuilds, the container uses ccache. The cache is stored in your project at `.ccache/`:
+```bash
+# Clean cache if needed
+rm -rf ./your-project/.ccache
+```
+
+### Common Errors
+
+**"makerom: command not found"**
+- Rebuild container with latest Dockerfile (includes makerom build steps)
+
+**"bannertool: command not found"**
+- Rebuild container with latest Dockerfile (includes bannertool build steps)
+
+**CIA creation fails silently**
+- Check that all required files exist:
+  - `assets/app.rsf` - CIA metadata
+  - `assets/banner.png` and `assets/audio.wav` - Banner resources
+  - `assets/icon.png` - Icon resource
+  - `output.elf` - Compiled application
+
+## Version Information
+
+- **Base Image**: devkitpro/devkitarm:20251231
+- **devkitARM**: GCC 15.2.0
+- **CMake**: 3.31.6
+- **GNU Make**: 4.3
+- **3DS Packages**: 47 portlibs installed
+
+## Building from Source
+
+The Dockerfile includes build steps for:
+
+1. **bannertool** (diasurgical/bannertool)
+   - Cloned with `--recursive` for submodules
+   - Built with system make
+   - Installed to `/opt/devkitpro/tools/bin/`
+
+2. **makerom & ctrtool** (3DSGuy/Project_CTR)
+   - Cloned from active fork
+   - Built dependencies first with `make deps`
+   - Built tools with `make`
+   - Installed to `/opt/devkitpro/tools/bin/`
+
+## Additional Resources
+
+- [devkitPro Documentation](https://devkitpro.org/)
+- [3DS Homebrew Development](https://www.3dbrew.org/wiki/Homebrew_Development)
+- [Checkpoint Repository](https://github.com/BernardoGiordano/Checkpoint) - Example of complete CIA project
+- [3ds-examples](https://github.com/devkitPro/3ds-examples) - Official examples
+
+## License
+
+This container configuration is provided as-is. Individual tools and libraries maintain their respective licenses:
+- devkitARM: GPL/proprietary tools
+- bannertool: Custom license
+- makerom/ctrtool: Custom license
+- Portlibs: Various open source licenses

scripts/build-container.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# Build development containers for various platforms
+# Usage: ./scripts/build-container.sh <platform> [version]
+#
+# Platforms: 3ds, switch, wiiu, wii, gamecube, nds, gba
+# Version: Semantic version (default: 0.1.0)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Print colored message
+print_msg() {
+    local color=$1
+    shift
+    echo -e "${color}$*${NC}"
+}
+
+# Print usage
+usage() {
+    cat << EOF
+Usage: $0 <platform> [version]
+
+Build development container for specified platform.
+
+Platforms:
+  3ds         Nintendo 3DS (devkitARM)
+  switch      Nintendo Switch (devkitA64) - Not yet implemented
+  wiiu        Nintendo Wii U (devkitPPC) - Not yet implemented
+  wii         Nintendo Wii (devkitPPC) - Not yet implemented
+  gamecube    Nintendo GameCube (devkitPPC) - Not yet implemented
+  nds         Nintendo DS (devkitARM) - Not yet implemented
+  gba         Game Boy Advance (devkitARM) - Not yet implemented
+
+Version:
+  Semantic version tag (default: 0.1.0)
+  Example: 0.1.0, 1.0.0, 0.2.0-beta
+
+Examples:
+  $0 3ds              # Build 3DS container with version 0.1.0
+  $0 3ds 0.2.0        # Build 3DS container with version 0.2.0
+  $0 switch           # Build Switch container (when implemented)
+
+Environment Variables:
+  CONTAINER_RUNTIME   Container runtime to use (podman or docker, default: auto-detect)
+
+EOF
+    exit 1
+}
+
+# Detect container runtime
+detect_runtime() {
+    if [ -n "$CONTAINER_RUNTIME" ]; then
+        echo "$CONTAINER_RUNTIME"
+        return
+    fi
+    
+    if command -v podman &> /dev/null; then
+        echo "podman"
+    elif command -v docker &> /dev/null; then
+        echo "docker"
+    else
+        print_msg "$RED" "Error: Neither podman nor docker found in PATH"
+        print_msg "$YELLOW" "Please install podman (recommended) or docker"
+        exit 1
+    fi
+}
+
+# Build container
+build_container() {
+    local platform=$1
+    local version=$2
+    local dockerfile="docker/${platform}.Dockerfile"
+    local image_name="tomusan/devkitarm-${platform}"
+    
+    if [ ! -f "$PROJECT_ROOT/$dockerfile" ]; then
+        print_msg "$RED" "Error: Dockerfile not found: $dockerfile"
+        print_msg "$YELLOW" "This platform may not be implemented yet."
+        exit 1
+    fi
+    
+    local runtime
+    runtime=$(detect_runtime)
+    
+    print_msg "$BLUE" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    print_msg "$GREEN" "Building ${platform} container"
+    print_msg "$BLUE" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo
+    print_msg "$YELLOW" "Platform:   $platform"
+    print_msg "$YELLOW" "Version:    $version"
+    print_msg "$YELLOW" "Runtime:    $runtime"
+    print_msg "$YELLOW" "Dockerfile: $dockerfile"
+    print_msg "$YELLOW" "Image:      ${image_name}:${version}"
+    print_msg "$YELLOW" "            ${image_name}:latest"
+    echo
+    
+    cd "$PROJECT_ROOT"
+    
+    # Build with both version and latest tags
+    print_msg "$GREEN" "Starting build..."
+    echo
+    
+    "$runtime" build \
+        -t "${image_name}:${version}" \
+        -t "${image_name}:latest" \
+        -f "$dockerfile" \
+        .
+    
+    local exit_code=$?
+    
+    if [ $exit_code -eq 0 ]; then
+        echo
+        print_msg "$BLUE" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        print_msg "$GREEN" "✓ Build successful!"
+        print_msg "$BLUE" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo
+        print_msg "$GREEN" "Tagged images:"
+        print_msg "$YELLOW" "  ${image_name}:${version}"
+        print_msg "$YELLOW" "  ${image_name}:latest"
+        echo
+        print_msg "$GREEN" "To use this container:"
+        print_msg "$YELLOW" "  $runtime run --rm -v ./your-project:/project:z ${image_name}:latest make"
+        echo
+        print_msg "$GREEN" "For interactive shell:"
+        print_msg "$YELLOW" "  $runtime run -it --rm -v ./your-project:/project:z ${image_name}:latest bash"
+        echo
+    else
+        echo
+        print_msg "$RED" "✗ Build failed with exit code $exit_code"
+        exit $exit_code
+    fi
+}
+
+# Main
+main() {
+    if [ $# -lt 1 ]; then
+        usage
+    fi
+    
+    local platform=$1
+    local version=${2:-0.1.0}
+    
+    # Validate platform
+    case "$platform" in
+        3ds)
+            ;;
+        switch|wiiu|wii|gamecube|nds|gba)
+            print_msg "$RED" "Error: Platform '$platform' is not yet implemented"
+            print_msg "$YELLOW" "Currently only '3ds' is available"
+            exit 1
+            ;;
+        *)
+            print_msg "$RED" "Error: Unknown platform '$platform'"
+            echo
+            usage
+            ;;
+    esac
+    
+    # Validate version format (basic semantic versioning)
+    if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9]+)?$ ]]; then
+        print_msg "$RED" "Error: Invalid version format '$version'"
+        print_msg "$YELLOW" "Expected format: X.Y.Z or X.Y.Z-label (e.g., 0.1.0, 1.0.0, 0.2.0-beta)"
+        exit 1
+    fi
+    
+    build_container "$platform" "$version"
+}
+
+main "$@"

scripts/container-shell.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+# Open interactive shell in 3DS development container
+# Usage: ./scripts/container-shell.sh [project-path] [podman-args...]
+#
+# All arguments after project-path are passed to podman/docker run before the container name
+# This allows mounting additional volumes, setting environment variables, etc.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Print colored message
+print_msg() {
+    local color=$1
+    shift
+    echo -e "${color}$*${NC}"
+}
+
+# Print usage
+usage() {
+    cat << 'EOF'
+Usage: ./scripts/container-shell.sh [project-path] [podman-args...]
+
+Open interactive bash shell in 3DS development container with project mounted.
+
+Arguments:
+  project-path    Path to project directory (default: current directory)
+  podman-args     Additional arguments passed to podman/docker run
+
+Examples:
+  # Shell in current directory
+  ./scripts/container-shell.sh
+
+  # Shell in specific project
+  ./scripts/container-shell.sh ~/my-3ds-game
+
+  # With additional volume mount
+  ./scripts/container-shell.sh ~/my-game -v /data:/data:z
+
+  # With environment variable
+  ./scripts/container-shell.sh ~/my-game -e DEBUG=1
+
+  # Multiple extra arguments
+  ./scripts/container-shell.sh ~/my-game -v /data:/data:z -e DEBUG=1 --network=host
+
+Inside the container:
+  - Project is mounted at /project
+  - Working directory is /project
+  - All devkitARM tools are in PATH
+  - Run 'make' to build your project
+  - Run 'exit' or Ctrl+D to leave
+
+Environment Variables:
+  CONTAINER_RUNTIME   Container runtime to use (podman or docker, default: auto-detect)
+
+EOF
+    exit 1
+}
+
+# Detect container runtime
+detect_runtime() {
+    if [ -n "$CONTAINER_RUNTIME" ]; then
+        echo "$CONTAINER_RUNTIME"
+        return
+    fi
+    
+    if command -v podman &> /dev/null; then
+        echo "podman"
+    elif command -v docker &> /dev/null; then
+        echo "docker"
+    else
+        print_msg "$RED" "Error: Neither podman nor docker found in PATH"
+        print_msg "$YELLOW" "Please install podman (recommended) or docker"
+        exit 1
+    fi
+}
+
+# Main
+main() {
+    # Show help
+    if [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+        usage
+    fi
+    
+    # Determine project path
+    local project_path="${1:-.}"
+    shift || true  # Remove first arg if present, don't fail if no args
+    
+    # Resolve absolute path
+    project_path=$(cd "$project_path" 2>/dev/null && pwd) || {
+        print_msg "$RED" "Error: Project path does not exist: ${1:-.}"
+        exit 1
+    }
+    
+    # Collect remaining arguments for podman/docker run
+    local extra_args=("$@")
+    
+    local runtime
+    runtime=$(detect_runtime)
+    
+    local image_name="tomusan/devkitarm-3ds:latest"
+    
+    print_msg "$BLUE" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    print_msg "$GREEN" "3DS Development Container Shell"
+    print_msg "$BLUE" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo
+    print_msg "$YELLOW" "Project:  $project_path"
+    print_msg "$YELLOW" "Runtime:  $runtime"
+    print_msg "$YELLOW" "Image:    $image_name"
+    if [ ${#extra_args[@]} -gt 0 ]; then
+        print_msg "$YELLOW" "Extra:    ${extra_args[*]}"
+    fi
+    echo
+    print_msg "$GREEN" "Type 'exit' or press Ctrl+D to leave the container"
+    echo
+    print_msg "$BLUE" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo
+    
+    # Run container with interactive shell
+    # Project mounted to /project, any extra args passed to podman/docker run
+    "$runtime" run -it --rm \
+        -v "$project_path:/project:z" \
+        "${extra_args[@]}" \
+        "$image_name" \
+        bash
+}
+
+main "$@"