Adds documentation of building and using our dev container.

.plans/DockerForDevkitARM.md

@@ -2,11 +2,47 @@
 
 **Issue**: #5 - Create Docker build environment for devkitARM  
 **Branch**: `docker-for-devkitarm`  
-**Status**: Planning  
+**Status**: ✅ **IMPLEMENTED** (Phase 1 Complete)  
+**Completed**: 2026-01-27  
 **Last Updated**: 2026-01-27
 
 ---
 
+## Implementation Summary
+
+Successfully implemented complete 3DS development container with full CIA file creation capability.
+
+**What Was Delivered:**
+- ✅ **3DS Container** (`docker/3ds.Dockerfile`)
+  - Based on `devkitpro/devkitarm:20251231`
+  - All 47 available 3DS portlibs installed
+  - bannertool (banner/icon creation)
+  - makerom and ctrtool (CIA assembly and validation)
+  - 3dstools (3dsxtool, smdhtool, mkromfs3ds)
+  - ccache, ninja, python3, and build tools
+  - Container size: ~1.6 GB
+
+- ✅ **Build Scripts**
+  - `scripts/build-container.sh` - Build and tag containers
+  - `scripts/container-shell.sh` - Interactive development shell
+
+- ✅ **Documentation**
+  - `docker/README.md` - Comprehensive container usage guide
+  - Updated main README.md with Quick Start section
+
+- ✅ **Testing & Validation**
+  - Tested with 60/61 official 3ds-examples (98.4% success rate)
+  - Validated with Checkpoint (real-world save manager)
+  - Complete CIA workflow verified (creates all files: .3dsx, .elf, .smdh, banner.bnr, icon.icn, .cia)
+  - CIA validation with ctrtool confirms proper structure
+
+**Completion Date**: January 27, 2026
+
+**Phase 2 (Future)**: Extract to separate container repo and publish to DockerHub
+**Phase 3 (Future)**: Additional platforms (Switch, Wii U, Wii, GameCube, NDS, GBA, PS Vita)
+
+---
+
 ## Overview
 
 We need containerized build environments for multiple game console platforms (3DS, Switch, Wii U, etc.). Each container will extend the official devkitPro base image and install **ALL available platform-specific libraries and tools** from dkp-pacman. This ensures developers have a complete, batteries-included build environment without local toolchain installation.

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/README.md

@@ -16,8 +16,32 @@ Complete Docker/Podman container for Nintendo 3DS homebrew development with full
 
 ## Quick Start
 
-### Building the Container
+### 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 .
@@ -28,31 +52,101 @@ 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
+**Compiling a 3DS Project:**
 
-**Basic compilation** (produces .3dsx homebrew file):
+Basic compilation (produces .3dsx homebrew file):
 ```bash
 podman run --rm -v ./your-project:/project:z tomusan/devkitarm-3ds:latest make
 ```
 
-**With CIA file creation**:
+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**:
+Clean and rebuild:
 ```bash
 podman run --rm -v ./your-project:/project:z tomusan/devkitarm-3ds:latest bash -c "make clean && make"
 ```
 
-### Interactive Shell
+**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: