
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 files 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.
