PlanB/build-containers
3
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

84
.gitignore vendored
View File

@@ -0,0 +1,84 @@
# OS artifacts
.DS_Store
Thumbs.db
# Editor / IDE
.vscode/
.idea/
*.swp
*.swo
# Python virtual environments (if any shared tools use Python)
venv/
.env/
.env.*
# Node / Yarn (if any asset tools use JS)
node_modules/
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Build outputs (general)
build/
dist/
out/
tmp/
temp/
# Compiled binaries (if any helper tools are built locally)
*.o
*.obj
*.dll
*.so
*.dylib
*.exe
# CMake
CMakeFiles/
CMakeCache.txt
cmake_install.cmake
Makefile
# Docker
# (We do NOT ignore Dockerfiles or scripts)
docker-compose.override.yml
*.tar
*.img
*.layer
# Generated toolchain artifacts
toolchain/
sdk/
cache/
downloads/
# macOS metadata
.AppleDouble
.LSOverride
# Backup files
*~
*.bak
*.old
*.orig
# Temporary editor files
*.tmp
*.temp
# Archives
*.zip
*.7z
*.tar.gz
*.tar.bz2
*.tar.xz

22
LICENSE Normal file
View File

@@ -0,0 +1,22 @@
MIT License
Copyright (c) 2026 Tom Hicks
Copyright (c) 2026 Plan B Game Studios
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

346
README.md
View File

@@ -1,87 +1,309 @@
# Project Template # PlanB Toolchain Containers
This repository is a starter template. 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.
Replace this README with documentation specific to your project once you begin development.
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
``` **Toolchain:**
node --version - 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)
``` **Notes:**
nvm install --lts KOS is built from source and requires a multi‑stage build process.
``` The container will pin GCC/binutils versions for reproducibility.
(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.
--- ---
## 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
``` **Notes:**
corepack enable The ps2toolchain build process is deterministic when pinned to specific commits.
```
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
```
--- ---
## 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. **Toolchain:**
For Node.js projects, a common choice is: - nxdk (modern open‑source SDK)
``` **Build Tools:**
FROM node:24 - 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.