From 014402d3ccb141ea26719357b16621eb99567d5a Mon Sep 17 00:00:00 2001 From: Tom Hicks Date: Tue, 27 Jan 2026 07:05:56 -0800 Subject: [PATCH] Adds documentation of building and using our dev container. --- .plans/DockerForDevkitARM.md | 38 ++++++++++++- README.md | 107 ++++++++++++++++++++++++----------- docker/README.md | 106 ++++++++++++++++++++++++++++++++-- 3 files changed, 212 insertions(+), 39 deletions(-) diff --git a/.plans/DockerForDevkitARM.md b/.plans/DockerForDevkitARM.md index fba0cf2..ad1679b 100644 --- a/.plans/DockerForDevkitARM.md +++ b/.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. diff --git a/README.md b/README.md index 0af226f..d7f289e 100644 --- a/README.md +++ b/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. - -### 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 -``` +**Note**: The `config` file is in `.gitignore` and will never be committed. ## 🔧 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 -- More coming soon... +All builds run in isolated containers with complete toolchains. See [docker/README.md](docker/README.md) for detailed container documentation. + +**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 diff --git a/docker/README.md b/docker/README.md index ac11638..0d763ff 100644 --- a/docker/README.md +++ b/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 [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: