Awesome

Awesome DOS

Family of operating systems for x86-based personal computers including IBM PC DOS and MS-DOS that were popular during the 1980s and early 1990s.

<img src="logo.svg" align="right" width="100">

A curated list of references for development of DOS applications and learning about the system itself. This includes list of compilers, tutorials, videos, links to free and paid books and source code to DOS operating systems and DOS games. The goal of this list is to collect information and act as a starting point for someone who wants to start out retro-programming for the DOS platform.

Contents

• Development tools
• Tutorials and programming resources
• Books
• Videos
• Source code
  • Open source DOS operating systems
  • Open source DOS libraries
  • Open source DOS games
• Drivers and emulators

Development tools

• bcc - Bruce's Compiler - Bruce's C compiler is a simple C compiler that produces 8086 assembler for tiny/small memory models.
• DJGPP - DJ Delorie's complete 32-bit C/C++ development environment for Intel 80386. Used for Quake.
• GCC IA-16 toolchain - A 16-bit counterpart to DJGPP, a GCC-based toolchain for developing 16-bit (8086 to 80286, a.k.a. IA-16) DOS applications, currently maintained by TK Chia.
• Open Watcom - Formerly commercial C/C++ development environment for 16- and 32-bit DOS and Windows. The current official version is 1.9. A GitHub fork is also available. Used for Doom I-II, Warcraft I-II, Duke Nukem 3D, Full Throttle, Dark Forces and Retro City Rampage.
  • The documentation is very valuable in order to understand working with both version 1.9 and the V2 fork.
  • Arch Wiki page
• Open Watcom V2 - GitHub fork which is actively maintained and is ported to 64-bit Windows and Linux.
• Turbo C 2.01 - C IDE and compiler from Borland first released in 1987.
• Turbo C++ 1.01 - C++ IDE and compiler from Borland released in 1991.
• Turbo C++ 3.0 - C++ IDE and compiler from Borland released in 1992.
  • Online version.
• DIV Games Studio 2 - IDE to develop DOS games in 2d, mode 7 and 3d. Released in 1998.
  • Online version.
• T3X - A small, portable, procedural, block-structured, recursive, almost typeless, and to some degree object-oriented programming language by Nils M. Holm.
• SmallerC - Portable self-hosting C compiler capable of producing executables for a number of platforms, including real and protected mode DOS programs, by Alexei A. Frounze.
• Small-C Toolkit - A self-hosting Small-C Compiler Toolkit for DOS(8086) with: K&R C Compiler, Make, Linker, Assembler. First released in 1982 by Jim E. Hendrix.

Memory managers

• 386MAX - Memory manager for DOS PCs with 386 or higher CPUs, released by Qualitas company in 1992. Source code was released in June 2022 on GitHub with GPL-3.0 license.

Scripting languages and interpreters for DOS

• DOjS - JavaScript programming environment for MS-DOS, FreeDOS or any DOS-based Windows (like 95, 98, ME).
• Lua for DOS - Online demo of Lua 5.3.5, compiled for MS-DOS on the Intel 80486 processor.
• Micropython for FreeDOS - FreeDOS ad-hoc module for micropython.
• perldos - Perl for DOS.
• PythonD - Python for DOS, including multi-threading, networking and OpenGL.

Tutorials and programming resources

History

• The Life of MS-DOS by Brendan Byers - History of the DOS family including CP/M, Q-DOS/86-DOS, MS-DOS and PC-DOS. Article also includes a diagram of the timeline and family tree of DOS operating systems.

Compiling

• 80x86 16-bit Compiling How-to by Alexei A. Frounze - 16-bit compilation tutorial for Borland/Turbo C/C++ and Open Watcom. Goes into depth of memory addressing and memory models.
• 32bit DOS development with Open Watcom - 32-bit compilation tutorial for Open Watcom.
• How to build DOS COM files with GCC by Chris Wellons - Build process of Chris Wellons's DOS Defender game using DJGPP. Goal was to create a 32-bit 80386 COM executable.

General

• David Brackeen - 256-Color VGA Programming in C - Tutorial series to learn how to create graphics on DOS, written in 1996.
• 640k Really is Enough for Anyone by Robert W. Oliver II - Short article about getting Turbo C running on FreeDOS and moving a pixel around.

• Just keeping it real... old skool style - Scali's OpenBlog - Blog post about Scali's journey of doing CGA, EGA and VGA programming.

• Alex Russell's Dos Game Programming in C for Beginners - DOS game programming tutorial series including a primer on C, graphics, animation, input handling and collision detection. This series contains a tutorial for making buffered input handling. Last chapter contains full source code of a Break Out game on DOS.
• The Artevida Game Programming Tutorials - Kevin Matz's almost book-length treatment of DOS system programming and VGA programming fundamentals using C/C++ and 80x86 assembly. Unfortunately it is incomplete and was abandoned since 2001.
• PC Game Programmer's Encyclopedia - Collection of guides covering assembly, sound (Sound Blaster, Gravis UltraSound, PC Speaker, GameBlaster, Adlib), input, memory (EMS, XMS, DMA Transfers), PIT, VGA, SVGA, algorithms and file formats.
• The Art of Demomaking by flipcode - Series from 1999 that introduces to graphics programming under DOS. The home site contains other late 90s/early 2000s game programming articles as well.
• Programming MS-DOS with Power - DOS Programming, Undocumented DOS, and DOS Secrets - System programming tutorials like disk handling, interrupts, inputs, sound, graphics.
• Programmer's Heaven (InfoMagic)(March 1997) CD-ROM - Source code and files for the following topics: MS-DOS, networking, C, C++, Pascal, Visual Basic, Delphi, 3D, PC speaker, Soundblaster, Gravis Ultrasound, MIDI and many more.

DOS API

• bios.h header documentation by Digital Mars - API documentation for routines accessing BIOS operations directly (disk operations, BIOS keyboard, printer, time, memory, serial, interrupts).
• dos.h header documentation by Digital Mars Part 1 Part 2 - API documentation of functions for interfacing with the DOS operating system itself.

Interrupts

• Ralph Brown's Interrupt List - HTML version - List of every documented and undocumented interrupt call known, accessible through search, categories and interrupt numbers.
  • Original in downloadable .zip files from Ralph Brown's website

Memory

• A look back at memory models in 16-bit MS-DOS - Raymond Chen's explanation of segmented memory, including near- and far pointers.

Video

• Values for standard video mode - List of all known video modes including BIOS interrupt numbers, text/pixel resolution, number of colors and video memory addresses.

CGA

• Color Graphics Adapter: Notes - Document describing the hardware, memory map, register I/O and hardware clones of the IBM's original CGA.

VGA

• VGA Hardware - OSDev wiki - Hardware guide for VGA cards that is also relevant for modern graphics cards including NVidia and ATI.
• Graphical programming in Assembly (DOS) - A VGA programming tutorial that also shows the list of video modes (text, CGA, EGA, VGA, SVGA) in a table at the beginning.
• VGA programming lessons - VGA programming tutorial series in Pascal and Assembly.

SVGA

• DOS Super VGA / VESA programming notes - by Myles - VESA article with history at the beginning and short mention of the VESA VBE standard, but unfortunately the example codes aren't even available through Wayback Machine.
• VESA Video Modes - OSDev wiki - Tutorial about querying VESA modes.
• DJGPP VESA guide - Tutorial about querying VESA modes.
• High-res high-speed VESA tutorial - Series of tutorials that include drawing pixels in VESA mode (protected or real).
• C code sample for drawing in VESA 2.0 mode - Just code listing for drawing an ellipse in VESA mode.

Sound

• Programming Sound Cards CD - A 1995 CD-ROM containing source code for Adlib, Gravis, Pro-Audio, Roland and Sound Blaster sound cards. The description for the folders on the CD-ROM is listed on the back of the CD-ROM case.

PC Speaker

• Making some noise with the PC speaker! - by Mark Feldman - Very short tutorial on using the PIT for generating PC speaker frequency.
• Frequencies of Musical Notes - Freqency table usable to parameterize the PC speaker.
• Sound Programming with PC Speaker - Chapter 23 of A to Z of C - PC speaker programming chapter of the "A to Z of C" book with source code.

AdLib/OPL2

• Yamaha YM3812 (OPL2) sound chip Wikipedia article - Best starting point to learn about the OPL2 sound chip besides 8-bit guy's YouTube video.
• The Ad Lib Music Synthesizer Card Programming Guide - by Tero Töttö - Reference of OPL2 operations and registers.

Sound Blaster/OPL3

• Programmer's Guide to the Yamaha YMF 262/OPL3 FM Music Synthesizer - Reverse-engineered reference on OPL3.
• Sound Blaster 16 Programming Document 3.5 by Ethan Brodsky - Programming the Sound Blaster 16 DSP CT1341 chip for recording and playback of digitized audio.
  • version 3.4 on GameDev.net archive
• Soundblaster Programming Information v0.90 - List of Sound Blaster models and registers.

Other

• Table of DOSBox cyclecounts according to processor types - A table for setting the appropriate DOSBox cycle count according to CPU types (IBM XT 88, 286, 386, 486, Pentium I, Pentium II). Comes handy when you are developing a DOS game and want to simulate the environment where you intend to execute it.

Books

Free

• Game Engine Black Book: Wolfenstein 3D - by Fabien Sanglard - Fabien Sanglard's walkthrough on the game engine architecture of id Software's Wolfenstein 3D on the IBM PC's hardware. Contains forewords by John Carcmack, Tom Hall and John Romero.
• Game Engine Black Book: Doom - by Fabien Sanglard - Fabien Sanglard's walkthrough on the game engine architecture of id Software's original Doom on Intel 486 system and game console ports. Contains forewords by John Carcmack, Dave Taylor and John Romero.
• A to Z of C - a book on C/DOS programming by K. Joseph Wesley and R. Rajesh Jeba Anbiah - Non-profit book on programming in C on DOS. DOS system programming starts from Part II.
• Michael Abrash's Graphics Programming Black Book Special Edition - Collection of Michael Abrash's Dr. Dobb's Journal graphics programming articles and his work on the graphics subsystem of Quake (mirror).

Paid

• Tricks of the Game-Programming Gurus - by Andre Lamothe, John Ratcliff and Denise Tyler - Comprehensive DOS game development book about starting out. Topics include keyboard, mouse- and joystick input handling, creating 2D and 3D VGA graphics, raycaster rendering, sound and music, game algorithms, Interrupt Service Routines (ISR), timers, artificial intelligence, networked multiplayer through serial port and null-modem cable, tooling, parallax scrolling and optimization techniques.
  • Ebook available from online libraries to borrow (required due to licensing): Open Library link, Internet Archive link
• More Tricks of the Game Programming Gurus - by Greg Anderson - Companion book to Tricks of the Game Programming Gurus, continuing where the original left off. Topics include SVGA, Binary Space Partition (BSP), UI, voxel graphics, memory management in real and protected mode, advanced sound programming, debugging and optimization techniques.
  • Ebook available from online libraries to borrow (required due to licensing): Open Library link, Internet Archive link

Videos

• Why DOS Was (and Is) a Thing - FreeDOS - Historical talk starting from Unix, going through CPM, DOS 1.x, DOS 2.x, DOS 3.x, DOS 4.x, DOS 6.x, Windows 3.1, Windows 95 and ending with FreeDOS.
• CGA Graphics - Not as bad as you thought! - by 8-bit Guy - History and technical details about IBM's CGA system. Also describes 4-color RGBI and 16-color Composite modes.
• How Oldschool Sound/Music worked - by 8-bit Guy - Video about PC speaker, FM synthesizers in NES and Commodore 64, Yamaha OPL chip in AdLib and Sound Blaster sound cards, PCM samples and MOD music.
• Let's Code - MS DOS - by root42 - DOS programming tutorial series including VGA, SoundBlaster and VGA Mode X.
• LGR - Evolution of PC Audio - As Told by Secret of Monkey Island - Comparison of playing the intro theme of Secret of Monkey Island through PC speaker, IBM PCjr/Tandy, AdLib, Game Blaster, Roland LAPC-1/MT-32, Gravis Ultrasound, Roland SCC-1 MIDI, SB16 Waveblaster/AWE32 and CD quality digital audio.
• Porting Retro City Rampage to MS-DOS: From PS4 to 1.44MB Floppy - GDC talk. Brian Provinciano's presentation on porting Retro City Rampage from PlayStation 4 to DOS. Topics include optimization, using interrupts, timing, PC speaker sound, joystick, memory management and fixed-point math.
• DOS Executables Explained - Nostalgia Nerd - Video about DOS executable formats including .COM, .BAT and .EXE.
• Why does DOS use 8.3 Filenames? - Nostalgia Nerd - Video about the 8.3 limitation of filenames under DOS, FAT partitioning scheme, NTFS, VFAT, FatGo, and LFN.EXE.
• What is DOS Protected Mode? / DOS Extenders- Nostalgia Nerd - Video about how PC memory looks like, conventional memory, extender memory and reasons for the need of DOS Protected Mode Interface (DPMI) and extenders like DOS/4GW.
• MS-DOS has been Open-Sourced! We Build and Run it! - Dave's Garage - Former Microsoft employee David Plummer tells stories about development of MS-DOS and compiles MS-DOS 4.00 source code which has been open-sourced by Microsoft.

Source code

Open source DOS operating systems

• MS-DOS - GitHub repository of the original source code for MS-DOS v1.25, v2.0 and v4.0, open-sourced by Microsoft.
• FreeDOS - FreeDOS is an open source DOS-compatible operating system that you can use to play classic DOS games, run legacy business software, or develop embedded systems. Any program that works on MS-DOS should also run on FreeDOS.

Open source DOS libraries

• Allegro 4.2 - Game development library for DOS, Windows and Linux. 4.2 version supports DOS platform.
  • Allegro 4.2.1 PDF documentation.
• LoveDOS - A framework for making 2D DOS games in Lua. API based on a subset of the LÖVE API.
• DOS-VGA-Game - Marco A. Marrero's DOS VGA/hardware library implemented in assembly and Turbo Pascal.
• DIGPAK sound drivers source code - Original source code for the DIGPAK sound drivers uploaded to GitHub by John W. Ratcliff.

Open source DOS games

Homebrew games with source code

List of all homebrew DOS games: http://www.doshaven.eu

• DOS Defender - Christopher Wellons's x86 real mode DOS Asteroids clone created as an entry for Lundum Dare #31.
• Dungeons of Noudar - First-person 2.5D dungeon-crawler on protected mode. Written in C++, includes software rendering, fixed point math, test coverage and sound (PC speaker, Adlib, OPL2LPT).
• Emeritus Pong - Pong clone for DOS, Windows and Linux. Uses PC speaker for sound on DOS.
• Floppy Bird - Flappy Bird clone written in 16 bit assembly. Not a DOS program, but a PC-Booter application instead (although it's also possible to build a COM executable for DOS).
• George M. Tzoumas's collection of MS-DOS games and utilities - Turbo Pascal with few games in C and C++. Games include Nibbles, Connect Four, Ms Pacman clone and two arcade/platform games. One of them (ra2) was written using Allegro. Utilities are all written in Turbo Pascal, these include game system routines, file and disk utilities and terminate-and-stay-resident programs (TSR).
• Gold Mine Run! - Platformer written in C using DJGPP.
• Gridfighter 3D - '80s style arcade shooter written in Quickbasic. Also the very first known DOS game that supports Oculus Rift VR headset.
  • GitHub repository
• Hangman - Hangman clone written in Basic. Runs on at least 80286 processors and uses EGA graphics.
• Magenta's Maze - 3D maze game using CGA graphics with algebra as theme.
  • Source code download link
• Mario - Super Mario Bros clone written in Turbo Pascal.
• NetHack - Descendant of the original NetHack rougelike game first released in 1987 available on multiple platforms.
• Piskworks - Gomoku clone written in C. Works on DOS, ZX Spectrum, ZX81, ZX80, APPLE1, AS400 and Windows.
• Plutonium Caverns - Overhead puzzle game written in C. Web version uses DOSBox ported to Emscripten to embed DOSBox into HTML5. However, the original executable is also downloadable and buildable with Open Watcom.
• Ptakovina - Tetris clone written in C. Runs on DOS, Unix/Linux, ZX Spectrum and Windows.
• sudoku86 - Sudoku clone written in C. Runs on 8086/8088 CPU, uses CGA, MCGA or VGA graphics and uses a mouse.
• Tetris - Tetris clone written in assembly.
  • Source code download link
• Towers of Hanoi - Tower of Hanoi puzzle game written in Turbo Pascal. Originally released in 1996.
• x86 pong - Text-mode Pong clone written in C. Runs as PC-Booter game and under DOS.
• zmiy - Text-mode Snake clone written in C. Runs on 8086 DOS.

Freeware games with source code

• Cyberdogs - Top-down 2D shooter playing as a mercenary to earn money. Written in Turbo Pascal. Supports two player mode.
  • Source code download link
  • C-Dogs - Sequel to the original Cyberdogs. Ronny Wester, the original creator no longer maintains the website for the original C-Dogs, but multiple ports exists, including cdogs-sdl.

Commercial games with published source code

• Abuse - Sci-fi side-scrolling platform game. Regarded as an innovative cult classic by most people. Supports SVGA mode up to 1280x1024 resolution. Written in C, the architecture includes a Lisp-scripting engine.
  • Source code download link
• Beneath a Steel Sky - Point-and-click adventure game set in a dystopian future. Written in assembly.
  • Source code download link
• Catacomb - 2D top-down shooter developed by Softdisk (later becoming id Software). Supports EGA and CGA graphics. Written in Turbo Pascal and assembly.
• Catacomb 3D - First-person shooter in fantasy setting developed by Softdisk (later becoming id Software). Features pseudo-3D graphics with raycasting technique. Supports EGA graphics. Written in C and assembly. Compiled with Borland C++ 3.1.
• Commander Keen in Keen Dreams - Side-scrolling platform game developed by id Software. Keen Dreams is the Commander Keen game created between Keen 3 and Keen 4 (often considered "Keen 3.5"), but was not widely released. Written in C and assembly.
• Descent - First sci-fi FPS/space shooter to feature entirely true 3D graphics. Written in C and assembly.
• Descent II - Sequel to Descent. Written in C and assembly.
• Doom - Sci-fi FPS developed by id Software where you fight demons from hell on Mars. The DOS-specific code for Doom could not be published because of a dependency to the licensed DMX sound library, hence why it's cleaned up and only the Linux source is there. However, the Heretic and Hexen projects contain the original DOS code in a way where DMX-related code is removed.
• Duke Nukem 3D - FPS developed by Apogee featuring the iconic character Duke Nukem. Written in C. Compiled with Watcom C/C++ 10.0.
  • Source code download link
• Heretic - Dark fantasy FPS running on id Software's Doom engine.
• Hexen: Beyond Heretic - Indirect sequel to Heretic.
  • Original SourceForge link for Heretic/Hexen.
• Hovertank 3D - FPS developed by id Software. Features pseudo-3D graphics with raycasting technique, before Catacomb 3D and Wolfeinstein 3D. Written in C and assembly.
• Quake - FPS developed by id Software set in a fully 3D world. Written in C. Compiled with DJGPP for DOS.
  • Quake Engine Code Review series - Code analysis by Fabien Sanglard.
• Rise of the Triad: Dark War - FPS developed by Apogee. It was developed as a follow-up to Wolfenstein 3D, but was altered and became a standalone game instead. Uses a heavily modified Wolfenstein 3D engine. Written in C.
• Sopwith - Side-scrolling shoot 'em up created by David L. Clark in 1984. The game involves piloting a Sopwith biplane, attempting to bomb enemy buildings while avoiding fire from enemy planes and various other obstacles.
  • MaiZure's Projects - Decoded: Sopwith - Code analysis by MaiZure.
• Wolfenstein 3D - FPS developed by id Software set in the Nazi German prison Castle Wolfenstein. Features pseudo-3D graphics with raycasting technique. Written in C and assembly.

Drivers and emulators

Sound card emulators

• SBEMU - A TSR that emulates Sound Blaster and OPL3 in pure DOS using modern PCI-based (onboard and add-in card) sound cards. Supports both real mode and protected mode games!
• VSB - A fork of SBEMU (see above), which also aims to offer Sound Blaster emulation for modern PC hardware, in both real mode and protected mode games.