Remote debugging under Linux (Ubuntu)

While OpenWatcom-v2 has a native linux port of the TUI watcom debugger WD, it isn't currently working reliably. This page will guide you through the process of setting up the windows-based GUI debugger WDW and connecting it to the DOS VM for a remote debugging of a DOS app.

Installing pre-requisites

To run windows programs, we first need to install Wine, which, as we know, is "not an emulator" of windows. Under ubuntu we do that by running sudo apt-get install wine -y.

Then we need to install the DOS VM. First, we need to enable the relevant PPA: sudo add-apt-repository ppa:dosemu2/ppa Now we can do sudo apt-get install dosemu2 -y which will install the VM called dosemu2. Check that VM is actually working, by running dosemu. If that booted into DOS, then type exit to exit back.

Setting up virtual COM port

Now we need wine and dosemu2 to communicate via the virtual COM port. For that, we first need to choose a file name of our virtual port. For example, it can be /tmp/com1. You can use any other writeable location and the name.

Configuring wine

Run wine regedit and navigate to HKEY_LOCAL_MACHINE\Software\Wine\Ports. There we create a "String Value" with the name "COM1" and Value Data set to the name of our COM port file, which was /tmp/com1. And we close regedit window.

Configuring dosemu2

We need to create the configuration file ~/.dosemu/dosemurc and write this line into it: $_com1 = "pts /tmp/com1". This line instructs dosemu2 to create that file as a pts device (pts is "Pseudo Tty Slave" in unix terminology) and use it as COM1. Now since we know that it is dosemu2 who creates the virtual port, we need to remember to always run it before running wine. So that once wine is started, the serial port is already there.

Configuring debugee app

First, we need to make sure the app is compiled and linked with -d3 flag or similar to get a debug info within. Using -d3 only during compilation is not enough: you need it passed to the linker as well, or the debug info is going to be missing. So we can have this setup in our makefile:

CC = wcc386
LD = wcl
CFLAGS = -bt=dos4g -d3
LDFLAGS = -l=dos4g -d3

Now we need to put the debugger-related files into the same dir with our app. The needed files are:

• cw.trp
• cwstub.exe
• cwhelp.exe
• serserv.exe

These file are taken from rel/binw directory of a watcom build.

Now we can create the debug.sh file (in the same app dir) with this line: dosemu -K . -E "serserv /tr=cw". This instructs our DOS VM to use current directory . as a disk drive, and execute the command serserv /tr=cw from that drive. That command starts a debugging server that is going to use COM1 to talk with the debugger, and use cw.trp to debug the app via the Causeway debug API.

Starting the debug session

As we remember, we need to start dosemu2 beforehand to allow it to create our virtual COM port. So we just run debug.sh script prepared on the previous step, or we run dosemu -K . -E "serserv /tr=cw" directly. If you see the below:

Open Watcom Serial Debug Server
Version 2.0 beta May 21 2025 11:23:20 (16-bit)
Copyright (c) 2002-2025 The Open Watcom Contributors. All Rights Reserved.
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved.
Source code is available under the Sybase Open Watcom Public License.
See https://github.com/open-watcom/open-watcom-v2#readme for details.
Press 'q' to exit

then your setup is correct so far.

Now we need to start WDW. Navigate to rel/binnt of the OW build, and run this: wine ./wdw.exe /tr=ser <exe_file_name> /download. Note that the argument order is important: /download must be after the file name, or it will try to open the file locally, instead of downloading it via the debug connection.

If everything works as expected, WDW will load and display the app's source code. In DOS window these lines will appear:

115200 baud
Session started

CauseWay API version = 4.05

This means the debugger is connected to the debug server, and both are ready for your debugging session.