Draft of the Manifest file format

📅 2025-05-22  · ✍️ Bas v.d. Wiel  ·  🏷 design

Now that all components of what makes a disk image are coming together nicely, it’s time to worry about the first version of the Manifest and the file format that goes with it. The idea is for DOSContainer to primarily be easy to use for end users, meaning people who cultivate collections of DOS software. The Manifest is intended to be written by those knowledgeable on particular DOS applications and are more or less a one-off exercise, so it’s more verbose than HwSpec although I’m still trying to keep it as simple as I possibly can. Here goes!

For the initial version of DOSContainer I intend to only support IBM PC-DOS 1.00 and nothing else. Why? Because the PC started at that point in history, and it’s the simplest incarnation of the platform. It’s a foundation from which to build. The manifest format starts out at this point and may get revised later on. That’s why the format has a mandatory version field that’s set to 1 for now. As soon as DOSContainer 1.00 comes out, Manifest version 1 will also be fixed to what it is at that point in time. The format will change with subsequent releases of DOSContainer but the version of the format will only increment when there are changes. I’ll make an effort to allow easy converting of old files to new versions of the format. Now without further ado, the first draft of a Manifest: DONKEY.BAS.

version = 1

[metadata]
application = "DONKEY.BAS"
developer = "Microsoft"
diskspace = "20KiB"
genres = ["driving"]
year = "1981"

[hardware]
graphics = ["hercules","cga"]
sound = ["bleeper"]

[os.ibm]
versions = ["1.00"]

[layers.hgcibm_11]
graphics = ["hercules"]
min_dos = "1.00"
max_dos = "6.22"
url = "https://dosk8s-dist.area536.com/hgcibm_11.zip"
checksum = "78173d19c1f7d96a6cf4ec711cd0d5d3301561b9cdef7875f7ad48368139f12c"

[layers.basica100]
checksum = "96cae63dc9f3eace501413598940d8a7f5ac6c84d5b7b59521c92fc936f88d93"
min_dos = "1.00"
max_dos = "1.00"
os_vendor = "ibm"
url = "https://dosk8s-dist.area536.com/basica_100.zip"

[layers.donkey100]
url = "https://dosk8s-dist.area536.com/donkey_100.zip"
checksum = "4f9bb6eecd3c37d3034cf7f8fdb4f6ccfef2fcac3b3cf053b449860493e92b15"
min_dos = "1.00"
max_dos = "1.00"

At the root level of the file you’ll only find the version field, indicating the format version of the Manifest. This tells DOSContainer which version of the parser to use for this file.

Metadata

The metadata section is not final yet at all. I’m very much open to suggestions. This section is here to allow for easy filtering. The only field here that’s relevant to building of disk images is the diskspace field, which tells DOSContainer how much space the disk image must have available. In this case it’s a tiny game in BASIC. A few KiloBytes for the game itself, and a few for the BASICA.COM BASIC interpreter add up to almost 20KiB. The main point here: prevent DOSContainer from building images for applications that won’t fit on the disk the user has, as specified in their HwSpec. In case of PC-DOS 1.00 we’re always talking about the same 160KiB floppy disk. The DOS system files and the game will fit in there generously.

Hardware

This section is open for later extension. It indicates which classes of hardware are natively supported by the application. In this case we support hercules and cga. If you have graphics hardware in your HwSpec that meets this minimum requirement, the image will build. Got EGA? That’s compatible with CGA, so it will work. If you only have IBM MDA, you’re unable to show graphics and this manifest will not build.

OS version specification

We specify only [os.ibm] because there were no clones in the world at this point in time yet. All we had was the IBM 5150 and PC-DOS 1.00. Nice and simple. Sections like [os.microsoft] will be added later.

Layers

This is where DOSContainer gets interesting. You may know that DONKEY.BAS only supports CGA graphics. That’s what we have layer.hgcibm_11 in there for. It’s got graphics = ["hercules"] so it only gets instantiated when the HwSpec has a Hercules Monochrome card for graphics. It then injects the HGCIBM CGA emulator utility into the disk image, allowing your Hercules card to pretend like it’s CGA and still run the game.

In order to run a BASIC game, you’ll also need a BASIC runtime environment on your system. That’s what the layers.basica100 layer is for. It pulls in BASICA.COM from PC-DOS, giving you the BASIC version that goes with the OS. Later versions of the OS had later versions of the BASIC interpreter as well as the game. The Manifest developer should add additional layers to the Manifest, specifying which DOS-versions to support with it.

ZIP-file format

The ZIP-files currently only contain the binaries that need to be copied into the final disk image. This will likely change before 1.00 release. I’m still looking at ways to glue everything together into a wholesome AUTOEXEC.BAT file so that the game can actually autoboot from the generated disk image. If that doesn’t completely work at version 1.00, I’ll leave it for later though.