PlanB/build-containers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Adds initial readme and gitignore.

Browse Source
This commit is contained in:
Tom Hicks
2026-01-29 00:03:26 -08:00
parent 1a203e5a26
commit ef7877b034
3 changed files with 390 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

346
README.md
View File

@@ -1,87 +1,309 @@
# Project Template
# PlanB Toolchain Containers
This repository is a starter template.
Replace this README with documentation specific to your project once you begin development.
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.
The notes below apply only if you choose to build a Node.js project using this template.
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.
---
## If your project will use Node.js
# Supported Platforms and Toolchains
Use Node 22 or newer for development.
This section documents the toolchains, SDKs, and build systems available for each platform. It serves as a reference for implementing the corresponding containers.
Check your version:
## Dreamcast
```
node --version
```
**Toolchain:**
- KallistiOS (KOS)
- kos-ports (optional libraries)
If your version is older than 22, update using nvm:
**Build Tools:**
- GCC cross‑compiler targeting SH‑4
- binutils for SH‑4
- newlib
- optional libraries via kos‑ports (libpng, zlib, ogg/vorbis, SDL)
```
nvm install --lts
```
(Optional) Make the new version your default:
```
nvm alias default <version>
```
After running `yarn init`, you may add a minimum Node version requirement to your `package.json`:
```json
"engines": {
"node": ">=22"
}
```
This helps ensure you do not accidentally use an outdated Node version.
**Notes:**
KOS is built from source and requires a multi‑stage build process.
The container will pin GCC/binutils versions for reproducibility.
---
## If your project will use Yarn (Berry)
## PlayStation 2
This template assumes modern Yarn (Yarn 4+), managed by Corepack.
**Toolchain:**
- ps2toolchain
- ps2sdk
- optional: ps2-packer
Enable Corepack:
**Build Tools:**
- GCC cross‑compiler targeting EE
- binutils for EE
- newlib
- optional IOP toolchain
- cmake‑based or make‑based build scripts
```
corepack enable
```
Update Yarn to the latest stable version:
```
corepack prepare yarn@stable --activate
```
Install dependencies:
```
yarn install
```
If you want Yarn to error (instead of warn) when the Node version does not satisfy the `engines` field, add this to `.yarnrc.yml`:
```yaml
enableStrictEngineChecks: true
```
**Notes:**
The ps2toolchain build process is deterministic when pinned to specific commits.
---
## If your project will use containers
## Original Xbox
If you plan to build or deploy using Docker, choose a base image that matches your development environment.
For Node.js projects, a common choice is:
**Toolchain:**
- nxdk (modern open‑source SDK)
```
FROM node:24
```
**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.
---
## Replace this README
## 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
Once you know what your project will be (Node, C++, Python, etc.), replace this file with documentation specific to your build, run, and deployment steps.