310 lines
7.1 KiB
Markdown
310 lines
7.1 KiB
Markdown
# 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
|
||
|