# DVX -- DOS Visual eXecutive

DVX is a windowed GUI environment and application platform for DOS.
It provides a Motif-inspired desktop, a cooperative multitasking kernel,
a widget toolkit, a compiled BASIC language with a visual form designer,
and a small set of bundled applications.

The system is a compositor built on VESA VBE video modes: the linear
framebuffer where the card has one, its 64 KB bank window where it does
not. A dirty-rectangle compositor keeps redraw cost proportional
to what actually changes on screen, so the desktop is responsive even at
1024x768 on modest hardware.


## What's Included

* **DVX Shell** -- desktop, app lifecycle manager, Task Manager, crash
  recovery. The shell is the program the user interacts with and the
  host for all running applications.
* **Widget toolkit** -- 31 widget types as plug-in modules: buttons,
  labels, text inputs, list boxes, tree views, tab controls, sliders,
  spinners, progress bars, canvases, scroll panes, splitters, an ANSI
  terminal, and more.
* **DVX BASIC** -- a Visual Basic 3 compatible language with a visual
  form designer, per-procedure code editor, project management, and a
  bytecode compiler and VM. BASIC programs compile to standalone DVX
  applications.
* **Help system** -- a full hypertext help viewer with table of contents,
  keyword index, full-text search, and inline images. Help files are
  compiled from a plain-text source format.
* **Serial / networking stack** -- an ISR-driven UART driver, HDLC
  packet framing with CRC-16 and Go-Back-N reliable delivery, 1024-bit
  Diffie-Hellman key exchange, and XTEA-CTR encryption, plus a Linux
  bridge that connects a virtual serial port to a telnet BBS.
* **Control Panel** -- themes, wallpapers, video mode, mouse
  configuration, all with live preview.
* **Bundled applications** -- Program Manager (desktop launcher),
  Notepad, Clock, Image Viewer, DVX Demo, Control Panel, DVX BASIC
  IDE, Help Viewer, Resource Editor, Icon Editor, Help Editor, BASIC
  Demo.


## Target Hardware

* DOS with a 386-class CPU or newer (486 recommended, Pentium for best
  performance)
* A VESA BIOS (VBE 1.2 or newer; a VBE driver such as UniVBE for cards
  without one in ROM).  A linear framebuffer (VBE 2.0) is faster;
  without one DVX writes through the 64 KB bank window
* 4 MB of extended memory minimum; 8 MB or more recommended
* Any resolution the video card reports at 8, 15, 16, or 32 bits per
  pixel (24 is not supported). 640x480, 800x600, and 1024x768 are the common cases.
* Two-button mouse; scroll wheel supported if a compatible driver is
  loaded


## Building and Deploying

```
./installToolchain.sh   # once, after a fresh clone: fetch the toolchain
make                    # build everything
make test               # host test suites, goldens and the lint gate
make test-dos           # run the real DOS build in 86Box (see below)
make clean              # remove all build artifacts
./mkcd.sh               # build and produce a CD-ROM ISO image
```

Everything the build and the tests need that is not a standard Linux
package lives in `toolchains/`, which is not kept in git.
`./installToolchain.sh` downloads each piece, checks it against a
pinned SHA-256, and unpacks it there (no sudo, nothing outside the
project); run it again with `--force` to reinstall:

* DJGPP (GCC 12.2.0) and the CWSDPMI stub -- the DOS cross compiler
* UPX 4.2.4 -- packs `SETUP.EXE` to about half its size
* 86Box 6.0 and its ROM set, FreeDOS 1.3 boot files and CuteMouse,
  and DOSBox Staging 0.83.0 -- the emulator test harness
* cppcheck 2.21, built from source -- used by the static gate
* lrzsz 0.12.20 -- the Terminal tests' ZMODEM peer

It needs curl, tar, bzip2, xz, unzip, make, g++, mtools, and xvfb-run.
To build with a different DOS toolchain, pass `DJGPP_PREFIX=...`,
`CWSDSTUB=...`, and `UPX=...` to `make`.

`make` builds in dependency order: core, tasks, loader, helpers,
host tools, widgets, shell, task manager, apps. Build output goes to
`bin/` and intermediate objects to `obj/`.

`make test-dos` boots FreeDOS in 86Box (headless, under Xvfb), runs
`DVX /SCRIPT=...` for every script in `src/test/dos/scripts`, and
compares the screenshots with the goldens. `EMULATOR=dosbox` uses
DOSBox Staging instead (much faster); `SCRIPTS="boot apps"` runs a
subset. The emulators never touch your home directory. See
`src/test/dos/runDos.sh --help`.

`make dist` builds the release media in `dist/`: a CD image
(`DVX.ISO`: `SETUP.EXE` with the DVX package appended, and
`README.TXT`) and a set of floppy images (`make dist FLOPPY=720K`;
360K, 720K, 1.2M, 1.44M (default), 2.88M, or a number of bytes per
disk). On the target machine, type `SETUP` on the CD or Disk 1: Setup
installs DVX in a hard-disk folder (and can add it to AUTOEXEC.BAT);
the `SETUP.EXE` it leaves in that folder uninstalls. `./mkcd.sh` wraps
`bin/` as it is into an ISO image, for running DVX straight from a CD
in an emulator. Holding Shift while DVX starts (or `DVX /SAFE`) starts
it in 640x480 safe video mode.


## Directory Layout

```
dvxgui/
  assets/       logo and splash artwork
  bin/          build output (runtime tree; mirrors what ships)
  config/       shipped DVX.INI, ASSOC.INI, themes, and wallpapers
  dist/         release media from `make dist` (not in git)
  docs/         HTML exports of the built-in help content
  LICENSE.txt   MIT license
  installToolchain.sh  fetches the toolchain and test tools into toolchains/
  Makefile      top-level build
  mkcd.sh       build-and-package script
  src/
    apps/       bundled applications
    include/    shared include files (BASIC library declarations)
    installer/  SETUP.EXE, the package tool and make dist
    libs/       core libraries (GUI, tasks, shell, helpers, serial, SQL)
    loader/     bootstrap executable
    sdk/        SDK project templates, build rules and newProject.sh
    tools/      host-native development tools and the BASIC compiler
    widgets/    widget plug-in modules
  toolchains/   DJGPP, CWSDPMI, emulators, cppcheck (not in git; see
                installToolchain.sh)
```

An installed DVX (and `bin/`) keeps program files and user files apart:

```
DVX.EXE  SETUP.EXE  SETUP.LST
SYSTEM/      tools, SPLASH.RAW, and the shipped DVX.INI and ASSOC.INI
LIBS/  WIDGETS/
APPS/<vendor>/<app>/   a program, its help, and DATA/ (files it ships)
SHARED/      FONTS, SOUNDS, THEMES, WPAPER: shipped for every program
USER/        everything written while DVX runs (back up this folder)
  DVX.INI  ASSOC.INI  DVX.LOG
  FONTS/ SOUNDS/ THEMES/ WPAPER/   the user's own (found before SHARED's)
  APPS/<vendor>/<app>/   each program's settings and saved files
  DOWNLOAD/  Terminal's downloads
```

`SET DVXUSER=D:\MYDVX` puts the user folder elsewhere (when DVX's disk
cannot be written it goes in TEMP). Only DVX's own package fills
SHARED; programs keep their own files with them. The package never
holds USER, so an upgrade replaces every program file and leaves the
user's alone. `claudeDocs/folderLayout.md` has the reasoning.

See `src/tools/README.md` for the host-side development tools
(resource tool, icon generators, help compiler, proxy), and
`src/apps/kpunch/README.md` for the SDK contract applications must
follow.  `make` also writes the SDK to `bin/sdk`: headers, host tools,
and a template for each kind of module (`bin/sdk/newProject.sh app
NAME`); the SDK Quick Start in the system help walks through it.


## Documentation

Full reference documentation ships with the system as browsable help:

* `docs/dvx_system_reference.html` -- system API, widget catalog
* `docs/dvx_basic_reference.html`  -- DVX BASIC language reference
* `docs/dvx_help_viewer.html`      -- help viewer guide

The same content is available from inside DVX via the Help Viewer and
Program Manager.


## License

MIT. See `LICENSE.txt`.