Add 3DS Docker Development Environment with CIA Support #23

maj · 2026-01-27T15:20:34Z

maj commented

2026-01-27 15:20:34 +00:00

Overview

Implements Issue #5 - Complete containerized build environment for Nintendo 3DS homebrew development with full CIA file creation support.

What This PR Adds

Docker Container (`docker/3ds.Dockerfile`)

Base: devkitpro/devkitarm:20251231
All 47 3DS portlibs: Graphics (citro3d, SDL), audio (opus, vorbis), networking (curl, mbedtls), physics (box2d), compression, and more
CIA Creation Tools:
- bannertool - Banner and icon generation (built from diasurgical/bannertool)
- makerom - CIA package assembly (built from 3DSGuy/Project_CTR)
- ctrtool - CIA validation and inspection (built from 3DSGuy/Project_CTR)
- 3dstools - Includes 3dsxtool, smdhtool, mkromfs3ds
Build Optimization: ccache for faster rebuilds
Modern Tools: CMake 3.31.6, Ninja, Python 3
Size: ~1.6 GB

Helper Scripts

scripts/build-container.sh: Build and tag containers with version management
- Auto-detects podman/docker
- Semantic versioning validation
- Colored output with build status
scripts/container-shell.sh: Interactive development shell
- Mounts project to /project
- Pass-through for additional podman/docker arguments
- Environment variable support

Documentation

docker/README.md: Comprehensive container usage guide
- Quick start with helper scripts
- Manual podman/docker commands
- Complete CIA creation workflow
- All 47 installed libraries categorized
- Troubleshooting section
Updated README.md: New Quick Start section with container workflow
Updated .plans/DockerForDevkitARM.md: Marked Phase 1 as implemented

Testing & Validation

✅ 60/61 official 3ds-examples (98.4% success rate)
- Only failures: 1 needs ImageMagick (tested separately), 1 needs video file
✅ Checkpoint (real-world save manager application)
- Successfully built all formats: .3dsx, .elf, .smdh
- Created banner.bnr and icon.icn with bannertool
- Generated complete 1.1 MB CIA file with makerom
- Validated CIA structure with ctrtool

File Structure

docker/
├── 3ds.Dockerfile          # Complete 3DS dev environment
├── README.md               # Container usage documentation
└── .dockerignore           # Build optimization

scripts/
├── build-container.sh      # Container build script
└── container-shell.sh      # Interactive shell helper

.plans/
└── DockerForDevkitARM.md   # Updated with completion status

Output Files

Container produces complete 3DS homebrew packages:

.3dsx - Homebrew Launcher format
.elf - Debug symbols
.smdh - Icon and metadata
banner.bnr - Home menu banner
icon.icn - CIA icon
.cia - Installable home menu format

Usage Examples

# Build the container (first time)
./scripts/build-container.sh 3ds

# Interactive shell in your project
./scripts/container-shell.sh ~/my-3ds-game

# Direct compilation
podman run --rm -v ~/my-game:/project:z tomusan/devkitarm-3ds:latest make

Dependencies

Podman or Docker (auto-detected)
No local devkitARM installation required
No platform SDKs needed

Breaking Changes

None - This is new functionality.

Future Work (Phase 2 & 3)

Extract to separate container repository
Publish to DockerHub for easier distribution
Additional platforms: Switch, Wii U, Wii, GameCube, NDS, GBA, PS Vita

Testing Checklist

Container builds successfully
All 47 portlibs installed and verified
bannertool, makerom, ctrtool functional
Tested with 60 official examples
Validated with real-world application (Checkpoint)
Complete CIA workflow verified
Helper scripts tested
Documentation complete

Closes #5

Note: This PR builds on the shared library infrastructure from PR #4. The container provides a complete, isolated development environment requiring zero local toolchain installation.

## Overview Implements Issue #5 - Complete containerized build environment for Nintendo 3DS homebrew development with full CIA file creation support. ## What This PR Adds ### Docker Container (`docker/3ds.Dockerfile`) - **Base**: `devkitpro/devkitarm:20251231` - **All 47 3DS portlibs**: Graphics (citro3d, SDL), audio (opus, vorbis), networking (curl, mbedtls), physics (box2d), compression, and more - **CIA Creation Tools**: - `bannertool` - Banner and icon generation (built from diasurgical/bannertool) - `makerom` - CIA package assembly (built from 3DSGuy/Project_CTR) - `ctrtool` - CIA validation and inspection (built from 3DSGuy/Project_CTR) - `3dstools` - Includes 3dsxtool, smdhtool, mkromfs3ds - **Build Optimization**: ccache for faster rebuilds - **Modern Tools**: CMake 3.31.6, Ninja, Python 3 - **Size**: ~1.6 GB ### Helper Scripts - **`scripts/build-container.sh`**: Build and tag containers with version management - Auto-detects podman/docker - Semantic versioning validation - Colored output with build status - **`scripts/container-shell.sh`**: Interactive development shell - Mounts project to `/project` - Pass-through for additional podman/docker arguments - Environment variable support ### Documentation - **`docker/README.md`**: Comprehensive container usage guide - Quick start with helper scripts - Manual podman/docker commands - Complete CIA creation workflow - All 47 installed libraries categorized - Troubleshooting section - **Updated `README.md`**: New Quick Start section with container workflow - **Updated `.plans/DockerForDevkitARM.md`**: Marked Phase 1 as implemented ### Testing & Validation - ✅ **60/61 official 3ds-examples** (98.4% success rate) - Only failures: 1 needs ImageMagick (tested separately), 1 needs video file - ✅ **Checkpoint** (real-world save manager application) - Successfully built all formats: .3dsx, .elf, .smdh - Created banner.bnr and icon.icn with bannertool - Generated complete 1.1 MB CIA file with makerom - Validated CIA structure with ctrtool ## File Structure ``` docker/ ├── 3ds.Dockerfile # Complete 3DS dev environment ├── README.md # Container usage documentation └── .dockerignore # Build optimization scripts/ ├── build-container.sh # Container build script └── container-shell.sh # Interactive shell helper .plans/ └── DockerForDevkitARM.md # Updated with completion status ``` ## Output Files Container produces complete 3DS homebrew packages: - `.3dsx` - Homebrew Launcher format - `.elf` - Debug symbols - `.smdh` - Icon and metadata - `banner.bnr` - Home menu banner - `icon.icn` - CIA icon - `.cia` - Installable home menu format ## Usage Examples ```bash # Build the container (first time) ./scripts/build-container.sh 3ds # Interactive shell in your project ./scripts/container-shell.sh ~/my-3ds-game # Direct compilation podman run --rm -v ~/my-game:/project:z tomusan/devkitarm-3ds:latest make ``` ## Dependencies - Podman or Docker (auto-detected) - No local devkitARM installation required - No platform SDKs needed ## Breaking Changes None - This is new functionality. ## Future Work (Phase 2 & 3) - Extract to separate container repository - Publish to DockerHub for easier distribution - Additional platforms: Switch, Wii U, Wii, GameCube, NDS, GBA, PS Vita ## Testing Checklist - [x] Container builds successfully - [x] All 47 portlibs installed and verified - [x] bannertool, makerom, ctrtool functional - [x] Tested with 60 official examples - [x] Validated with real-world application (Checkpoint) - [x] Complete CIA workflow verified - [x] Helper scripts tested - [x] Documentation complete ## Related Issues Closes #5 --- **Note**: This PR builds on the shared library infrastructure from PR #4. The container provides a complete, isolated development environment requiring zero local toolchain installation.

maj added 8 commits 2026-01-27 15:20:35 +00:00

Creates milestones, labels, and issues on gitea. 7e2c013cdc

Adds reference api info for gitea to gitignore. 631046df34

feat(config): implement configuration system and contributing guide (#6 , #4 ) 092299ff33

Adds plans for docker containers to build for nintendo systems. 44ae8b436a

Adds initial plan for Docker containers to build using VitaSDK. 51c18cd986

Adds Dockerfile for the 3ds build container. d1f98c92dd

Adds scripts to work with our dev containers. 815f865060

Adds documentation of building and using our dev container. 014402d3cc

maj merged commit 092b823959 into develop

2026-01-28 18:33:44 +00:00

maj referenced this issue from a commit