7.1 KiB
PlanB Toolchain Containers
This repository contains the Dockerfiles, build scripts, and supporting assets used to create a unified set of containerized toolchains for a wide range of retro consoles and modern platforms. The goal is to provide reproducible, isolated, and future‑proof build environments that eliminate host‑specific dependencies and ensure consistent results across machines and over time.
All images produced from this repository are published under the planbgames namespace on Docker Hub.
Project Goals
- Provide deterministic, isolated toolchains for each supported platform.
- Pin toolchain versions to guarantee reproducible builds.
- Avoid host contamination by performing all builds inside containers.
- Maintain a clean separation between shared tooling and platform‑specific logic.
- Support automated CI pipelines for multi‑platform builds.
- Keep the repository auditable, minimal, and easy to extend.
Repository Structure
build-containers/
base/ # Common base image for all toolchains
shared/ # Shared scripts and asset-processing tools
dreamcast/ # KallistiOS toolchain
ps2/ # ps2sdk and ps2toolchain
xbox/ # nxdk
gba/ # devkitARM
snes/ # WLA-DX, bass, and supporting tools
genesis/ # SGDK
pce/ # HuC and PCEAS
pcecd/ # HuC CD toolchain
dotnet/ # Open-source .NET SDK runtime environment
desktop/ # Windows, Linux, macOS cross-compilers
android/ # Android NDK/SDK build environment
ios/ # iOS cross-build environment (user-supplied SDK)
.gitignore
README.md
Each platform directory contains its own Dockerfile and any scripts required to build or configure the toolchain. The base directory defines the foundational environment shared by all images.
Supported Platforms and Toolchains
This section documents the toolchains, SDKs, and build systems available for each platform. It serves as a reference for implementing the corresponding containers.
Dreamcast
Toolchain:
- KallistiOS (KOS)
- kos-ports (optional libraries)
Build Tools:
- GCC cross‑compiler targeting SH‑4
- binutils for SH‑4
- newlib
- optional libraries via kos‑ports (libpng, zlib, ogg/vorbis, SDL)
Notes:
KOS is built from source and requires a multi‑stage build process.
The container will pin GCC/binutils versions for reproducibility.
PlayStation 2
Toolchain:
- ps2toolchain
- ps2sdk
- optional: ps2-packer
Build Tools:
- GCC cross‑compiler targeting EE
- binutils for EE
- newlib
- optional IOP toolchain
- cmake‑based or make‑based build scripts
Notes:
The ps2toolchain build process is deterministic when pinned to specific commits.
Original Xbox
Toolchain:
- nxdk (modern open‑source SDK)
Build Tools:
- Clang/LLVM
- lld linker
- nxdk libraries (pgraph, hal, etc.)
- cmake‑based build system
Notes:
nxdk supports modern C/C++ standards and is actively maintained.
Game Boy Advance
Toolchain:
- devkitARM (part of devkitPro)
Build Tools:
- GCC cross‑compiler targeting ARM7TDMI
- binutils
- libgba
- grit (image conversion)
- mmutil (audio conversion)
Notes:
devkitARM is stable and widely used for GBA development.
Super Nintendo (SNES)
Toolchains:
- WLA‑DX (assembler/linker suite)
- bass (alternative assembler)
- optional: pvsneslib for C‑based development
Build Tools:
- assemblers for 65c816
- graphics conversion tools (SuperFamiconv)
- optional: cc65 for C‑based workflows
Notes:
Most SNES development is assembly‑driven; containers will include both assemblers.
Sega Genesis / Mega Drive
Toolchain:
- SGDK (Sega Genesis Development Kit)
Build Tools:
- GCC cross‑compiler targeting m68k
- binutils for m68k
- SGDK libraries and build scripts
- resource conversion tools (rescomp)
Notes:
SGDK requires a specific GCC version for compatibility.
PC Engine / TurboGrafx‑16
Toolchains:
- HuC (C compiler)
- PCEAS (assembler)
Build Tools:
- HuC compiler
- PCEAS assembler
- graphics conversion utilities (pcegfx)
Notes:
HuC is older but stable; containerization ensures reproducibility.
PC Engine CD
Toolchain:
- HuC with CD‑ROM extensions
- ISO building tools (mkisofs variants)
Build Tools:
- CD‑specific build scripts
- ADPCM encoders (optional)
Notes:
CD builds require additional filesystem tools.
Modern Platforms
Linux
Toolchain:
- GCC
- Clang
- CMake
- Ninja
- pkg‑config
- optional: SDL2, OpenGL, Vulkan
Notes:
Linux builds are straightforward and fully container‑friendly.
Windows
Toolchain Options:
- MinGW‑w64 cross‑compiler
- LLVM/Clang targeting Windows
- MSVC is not legally redistributable in containers
Notes:
MinGW‑w64 provides a fully open cross‑compiler suitable for container builds.
macOS
Toolchain:
- osxcross (requires user‑provided macOS SDK)
- LLVM/Clang targeting macOS (user‑provided SDK)
Notes:
macOS builds are supported only when the user supplies the SDK manually.
Android
Toolchain:
- Android NDK
- Android SDK command‑line tools
- Gradle
- CMake + Ninja for native builds
Notes:
Android builds are fully container‑friendly and reproducible.
iOS
Toolchain:
- ios‑cross toolchains (requires user‑provided SDK)
- LLVM/Clang targeting iOS (user‑provided SDK)
Notes:
iOS builds are supported only when the user supplies the SDK.
.NET Runtime and SDK
The open‑source .NET SDK from Microsoft is treated as its own build target.
Toolchain:
- .NET SDK (LTS and STS versions)
- optional workloads (Android, WASM, etc.)
Notes:
.NET is a host‑side runtime and should not be bundled into console toolchain containers.
A dedicated .NET container allows independent versioning and avoids duplication.
Docker Hub Namespace
All images built from this repository are intended to be pushed to:
docker.io/planbgames/<image>
Examples:
planbgames/base
planbgames/dreamcast
planbgames/ps2
planbgames/xbox
planbgames/gba
planbgames/snes
planbgames/genesis
planbgames/pce
planbgames/pcecd
planbgames/dotnet
planbgames/android
planbgames/desktop
Versioning and tagging conventions will be documented as the project evolves.
Building Images
Each directory contains a Dockerfile that can be built directly:
docker build -t planbgames/base:latest base/
docker build -t planbgames/dreamcast:latest dreamcast/
Additional build scripts will be added to streamline multi‑image builds and CI workflows.
Future Work
Planned additions include:
- Automated CI pipelines for building and publishing all toolchains
- Versioned tags for stable toolchain releases
- Additional console environments
- Asset‑processing utilities shared across toolchains
- Documentation for each toolchain’s usage patterns