Adds Dockerfile for the 3ds build container.
This commit is contained in:
222
docker/README.md
Normal file
222
docker/README.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# 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
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user