How to Set Up a Development Environment on FreeDOS

Writing software for FreeDOS means working with tools built for the same real-mode x86 environment covered elsewhere on this blog — this walks through installing a free, still-actively-usable C compiler and building a first program.

Step 1: install Open Watcom, a free, capable DOS-targeting C/C++ compiler

Download the Open Watcom installer, run it, and select
the DOS target platform during installation.

Open Watcom remains actively maintained and freely available specifically because it continues to be the most practical modern choice for genuine DOS software development, supporting both 16-bit real-mode and 32-bit protected-mode (DOS extender) targets.

Step 2: set up the environment variables Open Watcom needs

SET WATCOM=C:\WATCOM
SET PATH=%PATH%;%WATCOM%\BINW
SET INCLUDE=%WATCOM%\H

Adding these lines to AUTOEXEC.BAT makes the compiler and its headers available from any directory, rather than needing to reference full paths every time.

Step 3: write a minimal C program

/* hello.c */
#include <stdio.h>

int main(void) {
    printf("Hello from FreeDOS!\n");
    return 0;
}

Step 4: compile it for real-mode DOS

wcl -l=dos hello.c

wcl is Open Watcom’s compile-and-link driver; -l=dos targets a standard 16-bit real-mode DOS executable — the most broadly compatible target for software meant to run on genuinely old hardware or accurate emulation.

Step 5: run the compiled program

hello.exe

Step 6: write and assemble a simple assembly program, if going lower-level

; hello.asm
.MODEL SMALL
.STACK 100h
.DATA
    msg DB 'Hello from assembly!$'
.CODE
main:
    mov ax, @data
    mov ds, ax
    mov ah, 09h
    lea dx, msg
    int 21h
    mov ah, 4Ch
    int 21h
END main

wasm hello.asm
wlink name hello.exe file hello.obj

wasm is Open Watcom’s assembler — useful for the kind of direct interrupt-level programming covered in the FreeDOS interrupts deep-dive, where C’s abstractions aren’t what you actually want.

Step 7: use a build automation batch file for anything beyond a single file

@ECHO OFF
wcl -l=dos -fe=myprogram.exe main.c helper.c utils.c

A simple batch file wrapping the compile command saves retyping a growing list of source files and flags as a project grows beyond a single-file program.

Step 8: debug with Open Watcom’s included debugger

wd hello.exe

wd provides source-level debugging for programs compiled with debug information (-d2 compiler flag) — genuinely useful rather than a token feature, for anything beyond the simplest programs.

Why Open Watcom specifically, rather than a more modern cross-compiler

Open Watcom targets real DOS execution environments natively and directly, understanding real-mode segmented memory and DOS’s actual calling conventions without needing a compatibility shim — a genuinely different (and for DOS-specific work, more appropriate) approach than cross-compiling with a modern toolchain never designed with 16-bit real-mode DOS as a first-class target. For anyone actually writing software meant to run well within DOS’s own constraints, rather than just barely running under it, a DOS-native toolchain like this one remains the more direct, better-supported path.

How a commercial 1980s compiler ended up free and open source decades later

The Watcom C/C++ compiler traces back to Watcom International, founded in 1981 out of the University of Waterloo’s Computer Systems Group, with the compiler itself first released in 1988 — for years, one of the most respected optimizing compilers available for DOS and OS/2 development. Ownership changed twice: Powersoft acquired Watcom in 1994, and Powersoft itself merged into Sybase in 1995, which continued selling the compiler commercially before discontinuing sales entirely in 2000. In 2003, SciTech Software — itself a Watcom customer with a direct stake in the compiler’s continued existence — negotiated with Sybase to release the compiler’s source as an open-source project under a new name, Open Watcom, under the Sybase Open Watcom Public License. That two-decade path from commercial DOS-era product to freely available open-source tool is exactly why a genuinely capable, actively-targetable DOS compiler still exists at all today.

Keeping a stable compiler version once your build actually works

Open Watcom’s last release from the original openwatcom.org team was version 1.9 in June 2010, with a community-maintained 2.0 fork continuing development afterward once that original team’s own activity slowed — worth knowing if you’re troubleshooting a build issue and comparing notes against something written online, since behavior, bundled headers, and default flags can differ meaningfully between the 1.9 lineage and the newer community fork. Once a specific installed version reliably builds your actual project, note that exact version deliberately rather than assuming “the compiler” is a single, unchanging target across every guide or forum post you might reference later.

Where to look when a build works on one machine but not another

A project that compiles cleanly on one FreeDOS installation but fails on another, despite seemingly identical source, usually traces to a version mismatch in exactly the environment variables this guide sets up in Step 2 — a different WATCOM path, a stale INCLUDE pointing at headers from a different installed version, or a PATH picking up a different, older wcl binary than the one you think is active. Confirming wcl -v reports the version you expect, directly on the machine exhibiting the problem, is worth doing before assuming anything about the source code itself is at fault.

Related:

Sources: