coco-dev

May 31, 2026 · View on GitHub

This repo implements a simplified environment for developing Tandy Color Computer applications. It implements a Docker image that includes the following tools:

Motivation

This repo is motivated in part by the need to keep the tools in sync between different computers. Because the Dockerfile contains all of the dependencies in a single place creating and sharing a reproducible development environment becomes possible.

Requirements

On Mac systems you must share /Users with Docker. To do this:

  • From the Docker menu select Preferences...
  • Click on the File Sharing tab
  • Click on +
  • Select /Users
  • Click Apply & Restart

Using coco-dev

Shell

# Start the Docker application if it is not already running
git clone https://github.com/jamieleecho/coco-dev.git
coco-dev/coco-dev

This will create a Linux shell in your home directory. You can cd into your target folder and use typical development commands such as lwasm, lwlink, decb, os9 and cmoc

Dev Containers

coco-dev can be used as a base image for Visual Studio Code Dev Containers. To get started, simply copy the example .devcontainer folder to the root of your project folder and open the folder in VS Code. See the documentation for more information.

Running MAME headlessly

The image includes a headless, CoCo 3-only build of MAME (the mame binary, in addition to the mame-tools utilities). It is compiled with only the coco3 driver, so it boots a CoCo 3 but is much smaller than a full MAME build. The container sets SDL_VIDEODRIVER=dummy and SDL_AUDIODRIVER=dummy so MAME runs without a display or sound card.

ROMs are not included. The CoCo 3 system ROM is copyrighted and cannot be distributed, so you must supply it at run time via -rompath. MAME expects a coco3.zip containing the CoCo 3 ROM inside the rompath directory.

A typical non-interactive run that boots a disk image and exits after a fixed amount of emulated time looks like:

mame coco3 \
  -rompath /path/to/roms \
  -flop1 /path/to/nos9.dsk \
  -flop2 /path/to/test.dsk \
  -video none -sound none \
  -seconds_to_run 60

Lua plugins and language files are installed under /usr/local/share/mame (-pluginspath /usr/local/share/mame/plugins) for driving MAME with -autoboot_script/-script automation.

Building coco-dev

# Start the Docker application if it is not already running
git clone https://github.com/jamieleecho/coco-dev.git
cd coco-dev
make build

Run make help to see the available targets. After building, make test runs a quick smoke test that exercises CMOC, BasTo6809, mcbasic, Java Grinder, and the CoCo 3 MAME build against the built image.

The image is a multi-stage build: a shared foundation stage (apt packages, the Python venv, lwtools and toolshed) followed by one stage per tool, which BuildKit compiles in parallel. Compile-heavy stages use a ccache cache mount, so rebuilding unchanged sources locally is fast.

Building MAME from source is the slow part of the image build. A few of MAME's core source files need ~2 GB of RAM each in the compiler, so the job count is deliberately conservative: it defaults to MAME_JOBS=2 (~4 GB peak). If your Docker host has plenty of RAM you can speed the build up by raising it, e.g.:

make build MAME_JOBS=4

Because the tool stages build concurrently, MAME's compile now overlaps with the other tools', so size MAME_JOBS against the RAM you have free during the build, not in isolation. If the build is killed for memory, lower it (down to MAME_JOBS=1) or increase the memory allotted to Docker (Docker Desktop → Settings → Resources).