Build for DOS
./build.sh --dos compiles the samples, lib/ and zerocore to 32-bit DOS programs that run on a 386.
bflat's own compiler can make 32-bit x86 code, but only for a Pentium 4 or later, because it always
uses SSE2 for floating point. So the DOS build starts from the WebAssembly route's LLVM bitcode, which
isn't tied to a processor until the last step. Run it on DOS is the short
version of this guide.
Get the tools
./setup.sh --dos
This downloads NativeAOT-LLVM (shared with --wasm), FreeDOS 1.4 with its mouse driver CuteMouse, and
the HX DOS extender 2.23 into tools/, about 75 MB. It also checks for what it can't download:
- A clang with the x86 target. The WASI SDK's clang doesn't have it. On macOS, Xcode's is used; on
Linux, the system's. Set
DOS_CLANGto choose another. - Python 3, for the tools in
dos/. - An emulator: Bochs or QEMU (
qemu-system-i386).brew install bochson macOS,sudo apt install bochs(orqemu-system-x86) on Ubuntu.
Build
./build.sh --dos # the DOS samples, into bin/dos/*.exe
./build.sh --dos Casts # just one
Simd and Kernels aren't built: they benchmark SIMD instructions, which a 386 doesn't have. To build a
program of your own, add its name to DOS_SAMPLES in build.sh.
The build compiles the sample to LLVM bitcode as for WebAssembly, compiles that for a 386 with clang
(-march=i386), and links it with dos/runtime.c into a 32-bit Windows console program, which the HX
DOS extender runs under DOS. runtime.c is the C library there isn't.
After linking, build.sh disassembles each program and fails if it finds an instruction a 386 or 387
lacks. That needs llvm-objdump; without one it says the check was skipped.
Run in an emulator
./run.sh --dos Casts # prints the output, exits with the program's code
./run.sh --dos --window Vga # shows the DOS screen
./run.sh --dos Quiz < answers.txt # standard input from a file
./test.sh --dos # every DOS sample, on an emulated 386 with 4 MB
run.sh --dos boots FreeDOS from one disk and gives the machine a second disk, D:, with the program
(as PROGRAM.EXE), the HX runtime and a batch file that runs it. Without --window there is no
screen: the output goes to a file on D:, which is printed afterwards, and run.sh exits with the
program's exit code. A run that hasn't finished after DOS_TIMEOUT seconds (default 120) is stopped
and exits with 125. With --window, the emulator's window shows the DOS screen and stays at the
prompt: type PROGRAM to run it again, and close the window to end.
Standard input from a file or a pipe goes onto D: as IN.TXT, and the program reads it with <.
With --window, the program reads the keyboard.
Bochs or QEMU
Use Bochs to test. Its i386 processor model refuses instructions a 386 doesn't have. QEMU's 486
model refuses the Pentium Pro's and SSE instructions but runs the 486's own (bswap, cmpxchg,
xadd), so it can't tell a 386 program from a 486 one. run.sh and test.sh use Bochs when it is
installed. These variables change the machine:
| Variable | Default | What |
|---|---|---|
DOS_EMULATOR |
bochs if installed, else qemu |
the emulator |
DOS_CPU |
i386 (Bochs), 486 (QEMU) |
the processor model |
DOS_MEMORY |
4 |
the machine's memory, in MB |
DOS_IPS |
50000000 |
Bochs only: instructions per second |
DOS_BOCHS_DISPLAY |
sdl2 |
Bochs's display library for --window |
Bochs's i386 model limits which instructions run, not how fast. At the default it runs several
times faster than a real 386; DOS_IPS=6000000 is about a 386DX-33.
Memory
A program needs 2 MB or more. Each one reserves 256 KB for its stack and 256 KB for the shadow stack
NativeAOT-LLVM's code keeps. Most samples run with 2 MB; Strings needs more for its arenas and runs
with 4 MB. Memory really does run out here, so consider arenas created with
stopOnOutOfMemory: true (see Catch arena mistakes).
Run on a real machine or another emulator
Copy the program together with HDPMI32.EXE, DPMILD32.EXE and DKRNL32.DLL from
tools/dos/hx-2.23, and start it through the loader:
DPMILD32 CASTS.EXE
Or load HXLDR32.EXE once; after that CASTS.EXE runs by its name. The mouse needs a mouse driver
loaded in DOS, such as CuteMouse.
The machine needs 2 MB of memory or more, and a 386 with a 387 math coprocessor, or a 486DX or later. All floating point uses 387 instructions and there is no software fallback, so a 386 or 486SX without a coprocessor isn't supported.
What's different
- Failure messages go to standard output, since DOS's command line can't redirect anything else. A failed cast or an index out of range ends the program with exit code 134.
- Floating point is the 387's, set to 53-bit precision.
+ - * /andSqrton doubles match other targets. Alongabove 2^53 converted todouble,floatarithmetic, andExp,Log,Pow,Sinand the like can differ in the last digits. - 32-bit pointers and one thread, as on WebAssembly.
- C# can call only the C functions
dos/runtime.cdefines.[DllImport("libc")]of anything else fails to link.
Watch out for
- Tested on macOS only, with Xcode's clang (Apple clang 21) and Bochs 3.1.
build.sh --dosis written to work on Linux too but hasn't been run there, and CI doesn't run it. - The compiler versions are a set, as for WebAssembly: the DOS build compiles the same bitcode.
See also: Draw on the VGA screen, How the targets work, and Build for WebAssembly.