Welcome to DOSContainer

📅 2025-05-07  · ✍️ Bas v.d. Wiel  ·  🏷 announcement

So what is DOSContainer? It’s a software project aimed at those who build and maintain collections of games and applications for the DOS platform. DOS, an abbreviation for Disk Operating System, is a class of operating systems that were popular in the 1980’s and 1990’s for use on IBM-PC and compatible hardware that would go on to grow into the Windows platform we have today. DOS was quite a basic operating system that was command-line driven. The fact that there were dozens of versions from different vendors paired with wildly different hardware platforms didn’t make things easier on the systems’ owners. DOSContainer aims to take the complexity out of the maintenance of large libraries of DOS software.

DOSContainer conceptually borrows a lot from how Docker works. You write a text file called a Manifest in which you declare a number of Layers that together make up a fully configured game or application, combined with parts of a DOS operating system all in the form of a fully usable virtual disk image file.

DOSContainer itself concerns itself with two key aspects:

• Creating a completely valid, 100% period-appropriate hard disk or floppy image file.
• Filling that image file with whatever the manifest-developer specifies.

More on disk image files

A disk image file is a byte-for-byte exact copy of the contents of what would be a physical disk. Should you choose to write the contents of a DOSContainer image file out to an old floppy disk or appropriate hard disk, you can just put it into any period-appropriate PC and it will boot up and start your software flawlessly. The objective is for DOSContainer to make these disk images so accurate that not even the disk repair and analysis toolkits of the time could tell them apart from the real thing.

This goal, which I’m referring to as museum quality is hard. There were many versions of DOS and the documentation to go with them was far from accurate, if even available at all. So a lot of effort goes into analyzing how the actual DOS versions of the time behave under all sort of circumstances and replicating that exact behavior in the image generator code of DOSContainer.

The reason to aim for museum quality, is preservation. It’s not difficult to create some half-baked FAT-formatted disk that some emulators can start up from. What I’m aiming for, is accuracy and authenticity. You obviously won’t notice it when all you want to do is just play a game on an emulator, but you will when you try to pop a DOSContainer disk image into a vintage IBM 5150. It’ll just work, not because of tricks or workarounds but because it’s the real thing.

Layered approach

The software installation takes place through a layered approach, much like how Docker images are built. You start with the absolute bare minimum that a DOS version needs to function: only three system files. That may well be enough for your app or game to function, but sometimes you may need a little more. That’s where layering comes in.

Tools for memory management, a BASIC interpreter, a mouse driver, drivers for things like a CD-ROM all come in the form of layers. By standardizing how these work, we save collection maintainers a lot of work. You just specifiy the exact version of the particular layer you need, and DOSContainer installs it for you into a dozen, or into thousands of your disk images. Should a new version of your mouse driver come out, you update your manifest and rebuild: things just keep working.

Quite a bit does go into the development of a single Layer. It has to work with all kinds of permutations in the environment. DOS ran on at least 5 distinct types of CPU alone, given wildly different amounts of memory, and there were lots of quirks between DOS versions themselves. Just plonking a MOUSE.COM into C:\DRIVERS is the easy bit. Ensuring that it loads into a specific part of memory on a 386 or better while not trying to do so on a 286 or lower because it doesn’t even have that memory to begin with: that’s fun!

Repeating this same trick 5000 times over? Not fun. That’s where DOSContainer comes in.

A bit of history?

DOSContainer started as a proof of concept shell script that would string together a bunch of GNU mtools incantations to create a hard disk image and then plonk a game on there. It worked, but the results were hit-and-miss at best. So I decided to use DOSContainer to teach myself the Rust programming language and do it the right way. The good thing about Rust is that it offers very easy dependency management. I’m not interested in coding my own parser for the TOML format or to deal with the ZIP archive format or downloading things from the internet. There are libraries for that, and Rust makes it incredibly simple to hook into a huge community of already solved problems.

Rust, at the same time, allows me to do the finnicky bit-twiddling that’s required when you’re dealing with low-level operating system code. It also compiles the code down into a single binary that you can just put onto your MiSTerFPGA board, your Raspberry Pi, your Linux laptop, your Windows desktop or your iMac and it will just run. No installation procedures, no dependency or DLL hell, just a single executable that has everything you need.

Current status

Still under heavy construction. I’m aiming the 1.00 release at the original IBM PC and its 160/320KB floppy drives and the 1.xx releases of IBM PC-DOS. Once those are nailed down and the configuration file formats for the Manifest are finalized, I’ll publish a release for testing and start writing a few manifests to work with.

Until that time, you’ll find the occasional blog post here and a growing body of design documents that specify how things work and what problems I’m trying to solve.