Running os8088

Run it from source

The source code comes with 86Box configurations you can use on your Mac, Linux or Windows PC to run the operating system. You can see all the available configurations in the table further down this page.

If you want to go this route, start by cloning the repo using the following command:

git clone https://github.com/jggonz/os8088.git

If you're on a Mac with an M chip, you can install the required tools (nasm, python3, and qemu-system-i386) by running tools/setup-macos.sh which leverages Homebrew behind the scenes. This script also fetches the 86Box ROM sets since those are not bundled with 86Box.

Now you can run the following make commands to run the various available configurations. Each one assembles the floppy images it needs, then launches 86Box:

XT Configurations

286, 386s, 486s and Pentiums

Configurations for specific programs

The following configurations spin up an emulator and let you try some of the included apps:

The Frotz and RunCPM disks are assembled from files you need to get by running tools/getstories.py and tools/getruncpm.py

Writing to real media

If you have a real XT, you want the 360KB images: os8088-360.img for drive A: and apps360.img for drive B:. Write them to double-density 5.25" disks with dd, one disk at a time:

dd if=os8088-360.img of=/dev/fd0 bs=512

Check the device name before you press Return. dd writes to whatever you put after of= and asks no questions, so name the wrong device and you lose that disk. Run diskutil list on macOS or lsblk on Linux first, and unmount the drive before you write to it.

Use a genuine 360KB drive if you can. A 1.2MB drive can write these disks, but it writes thinner tracks, and period hardware often can't read them back. If your XT won't boot a disk that looks fine on your modern machine, that's usually why.

Put the boot disk in A: and the software disk in B: and switch the machine on. The software disk in B: is optional, but you'll probably want to try some of the apps.

On a Mac there is an easier way than dd: the disk imager, described next.

Writing media with the disk imager

The source tree ships a disk imager for macOS. It finds the drives you have plugged in, lists the images that fit each one, and writes the one you pick -- a floppy, a USB stick, a CD-R, or a CompactFlash card for an XT-class machine. It never writes until you have typed the target disk's identifier back at it, and it reads every byte back afterwards and compares checksums, so a stick or card that silently drops data is caught on your desk rather than at the machine.

Build the images first, then start it:

make          # the floppy images
make live     # the live USB image and live CD (needs the C compiler; it fetches it)
make imager   # scan the attached drives and choose what to write

If you downloaded a release instead of building, point it at the unzipped folder: python3 tools/os88imager.py --images ~/Downloads/os8088. --scan lists devices and images and writes nothing.

CompactFlash cards, XTIDE and the Book8088

A CompactFlash card is how os8088 gets onto a Book8088, the 8088 laptop that boots CompactFlash through the XTIDE Universal BIOS, and onto any XT with an XTIDE card. There is one thing to know. A modern PC derives a drive's geometry from the image's own partition table; an XTIDE BIOS reports the card's geometry instead. The live image is laid out for 16 heads and 63 sectors per track, so on a card the BIOS sees differently it answers Not bootable.

The imager asks one extra question when the target is a card reader: the heads and sectors the booting BIOS reports. For cards over about 500MB it suggests the answer, since XTIDE computes it from the card's size. For smaller cards the geometry is the card's own and you type it from the card's datasheet -- a 256MB SanDisk card, for example, reports 16 heads and 32 sectors, and a Book8088 boots the image written that way. The imager cannot read it itself, because a USB card reader does not pass the card's identity through. The image file on your Mac is not changed; the ten bytes that name a geometry are rewritten on the way to the card, and the checksum printed second is the one the read-back is checked against.

Only the first 32MB of the card is used. The rest is left alone. On other platforms, or with dd, the same rewrite is one command:

python3 tools/os88disk.py --retarget os8088-usb.img --geometry 16/32 -o cf.img

The imager only offers drives that could be the right answer. Internal disks, the disk macOS is running from, non-USB disks and read-only media are filtered out rather than warned about. The selected device is checked again before and after it is unmounted, and an identity change aborts the write.

Building from source

If you'd rather build the floppy images yourself instead of downloading them, clone the repo and run make:

git clone https://github.com/jggonz/os8088.git
cd os8088
make

That puts the four core floppy images in build/, ready to mount in an emulator or write to a real disk.

You'll need nasm, python3 and qemu-system-i386 installed first. On a Mac, tools/setup-macos.sh installs them for you. 86Box is optional, and only needed if you want to run the machine configurations above.

A few other targets worth knowing about:

The kernel is compiled with a cpu 8086 directive to make sure that we don't accidentally ship a kernel with assembly meant for newer chips and break XT compatibility. The build also passes NASM -w+error, so a newer instruction stops the build instead of slipping through as a warning.

Without that, you wouldn't find out until a real XT choked on it. So if the build works, it runs on an 8088.