177 lines
7.7 KiB
Markdown
177 lines
7.7 KiB
Markdown
# 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`.
|