# DVX Tools

Host-native utilities that run on the development machine during the
build. These tools are not DXE modules and do not cross-compile; they
build with the system GCC. They produce binaries, icons, resource
blocks, help files, and raw image data that get embedded into DXE
apps, widgets, and libraries.

All tools build into `bin/host/` with `make`. Two of them (the
resource tool and the help compiler) are also cross-compiled for DOS
and shipped to `bin/system/` as DOS executables so they can run on
the target as well.


## dvxres -- Resource Tool

Manages resource blocks appended to DXE3 files (`.app`, `.wgt`,
`.lib`). Resources are invisible to `dlopen` because they sit after
the DXE3 image, in a separately indexed block. The runtime reads them
via `dvxResOpen`/`dvxResRead`/`dvxResClose` (see
`src/libs/kpunch/libdvx/dvxResource.c`).

### Usage

```
dvxres add   <file> <name> <type> <data|@file>
dvxres build <file> <manifest.res>
dvxres list  <file>
dvxres get   <file> <name> [outfile]
dvxres strip <file>
```

| Command | Description |
|---------|-------------|
| `add`   | Add or replace a single resource in a DXE file. Existing entries with the same name are overwritten. |
| `build` | Replace all resources in a DXE file with the entries listed in a manifest. Any previously attached resources are removed first. |
| `list`  | Dump a table of every resource in a DXE file (name, type, size). |
| `get`   | Extract a named resource to a file, or to stdout if no output path is given. |
| `strip` | Truncate the file to remove the appended resource block. The DXE image itself is left unchanged. |

### Resource Types

| Keyword            | Type constant      | Description |
|--------------------|--------------------|-------------|
| `icon` or `image`  | `DVX_RES_ICON`     | Image data (BMP for icons, PNG/JPEG/GIF for images used by apps). |
| `text`             | `DVX_RES_TEXT`     | Null-terminated string. Used for metadata: `author`, `copyright`, `publisher`, `description`, `version`, `name`. |
| `binary`           | `DVX_RES_BINARY`   | Arbitrary binary data, application-defined. |

For `add` with type `text`, the `<data>` argument is the literal
string value. For `icon` or `binary`, the `<data>` argument is a file
path; a leading `@` is stripped if present.

### Manifest File Format (.res)

Plain-text UTF-8 (ASCII preferred), one resource per line:

```
# Comments start with '#'
# Fields: name type data
name        type    data

# Examples:
icon32      icon    icon32.bmp
name        text    "My App"
author      text    "Scott Duensing"
copyright   text    "Copyright 2026 Scott Duensing"
description text    "Editor with syntax highlighting"
appdata     binary  data/config.bin
```

Each non-empty, non-comment line has three whitespace-delimited
fields: `name`, `type`, `data`. For text values, double quotes around
the data are stripped. For icon/binary values, the data is a file
path relative to the current working directory when `dvxres build`
was invoked.

Names are limited to 31 characters (32 including the terminator) and
are truncated silently.

### Examples

```
# Attach a single icon to a freshly-built app
dvxres add bin/apps/kpunch/myapp/myapp.app icon32 icon icon32.bmp

# Rebuild the full resource block from a manifest
dvxres build bin/apps/kpunch/myapp/myapp.app myapp.res

# List every resource in a module
dvxres list bin/widgets/kpunch/button/button.wgt

# Extract an icon for inspection
dvxres get bin/apps/kpunch/myapp/myapp.app icon32 recovered.bmp

# Strip all resources from a file (useful for diffing the raw DXE)
dvxres strip bin/apps/kpunch/myapp/myapp.app
```

### File Format

Resources are appended after the DXE3 image:

```
[DXE3 image]                       <-- untouched, what dlopen sees
[resource data entries]            <-- sequential, variable length
[resource directory]               <-- fixed-size 48-byte entries
[footer]                           <-- 16 bytes: magic, dir offset, count
```

The footer sits at `EOF - 16` bytes. Magic value is `0x52585644`
(`"DVXR"` little-endian). Each directory entry (48 bytes) holds a
32-byte name, a `uint32_t` type, a `uint32_t` absolute file offset,
a `uint32_t` size, and a `uint32_t` reserved field.

### Binaries

* Host: `bin/host/dvxres`
* Target: `bin/system/DVXRES.EXE` (DOS executable, for use inside the
  running system)


## dvxhlpc -- Help Compiler

Compiles hypertext help source files (`.dhs` = "DVX Help Source")
into the binary `.hlp` format consumed by the DVX help viewer. The
compiler also emits an equivalent HTML file so the same content can
be browsed outside the system.

### Usage

```
dvxhlpc -o <output.hlp> [-i <imagedir>] [--html <out.html>] [--quiet] <input.dhs> [@filelist] ...
```

| Flag          | Purpose |
|---------------|---------|
| `-o <file>`   | Required. Path of the compiled `.hlp` output. |
| `-i <dir>`    | Optional. Directory where referenced images live. Defaults to the working directory. |
| `--html <file>` | Optional. Also emit a standalone HTML rendering of the help content. |
| `--quiet`     | Suppress progress output. |
| `@<list>`     | Response file: each line names an additional `.dhs` input file. Lines starting with `#` and blank lines are ignored. |
| `<input.dhs>` | One or more input source files. Order matters for topic discovery. |

### Five-Pass Compilation

1. Parse each source file; collect topics, table-of-contents entries,
   index entries, and image references.
2. Word-wrap text and list-item records to a fixed width.
3. Build a deduplicated string table.
4. Generate a trigram-based search index for full-text search.
5. Serialize the binary `.hlp` file (and, if requested, the HTML).

### Source Format (.dhs)

`.dhs` is a line-oriented markup format. Documents are divided into
topics, each with a unique ID and title. Topics can link to one
another, include images, and be grouped into table-of-contents
sections. Widget and library help files use `.bhs` ("BASIC help
source") files with the same format but a BASIC-oriented syntax
vocabulary. See existing sources under
`src/libs/kpunch/libdvx/*.dhs` for examples.

### Examples

```
# Compile the system reference help file
dvxhlpc -o bin/apps/kpunch/progman/dvxhelp.hlp \
        --html docs/dvx_system_reference.html \
        -i src/libs/kpunch/libdvx \
        src/libs/kpunch/libdvx/sysdoc.dhs \
        src/libs/kpunch/libdvx/arch.dhs \
        src/libs/kpunch/libdvx/apiref.dhs

# Response file (one filename per line)
dvxhlpc -o out.hlp @inputs.txt
```

### Binaries

* Host: `bin/host/dvxhlpc`
* Target: `bin/system/DVXHLPC.EXE` (DOS executable)

The help compiler is also linked into the loader as an object file so
help files can be rebuilt on first boot if the module set has
changed.


## mkicon -- Application Icon Generator

Generates 32x32 24-bit BMP pixel-art icons for the bundled
applications. Each icon is drawn procedurally by dedicated code so no
external image assets are needed.

### Usage

```
mkicon <output.bmp> <type>
```

Available types:

| Type      | Description |
|-----------|-------------|
| `noicon`  | Grey square with a red diagonal X and a question mark. Used as a fallback. |
| `clock`   | Clock face with hour and minute hands. |
| `notepad` | Paper with folded corner and text lines. |
| `cpanel`  | Gear wheel with eight teeth. |
| `dvxdemo` | Coloured diamond shape. |
| `imgview` | Landscape in a picture frame. |
| `basic`   | BASIC "B" glyph flanked by code brackets. |
| `help`    | Blue book with a question mark. |
| `iconed`  | Pixel grid with a pencil. |
| `resedit` | Document window with stacked resource rows. |

### Example

```
mkicon icon32.bmp clock
```

Used by app Makefiles to generate `icon32.bmp` when no hand-drawn
icon exists.

### Binary

`bin/host/mkicon`


## mktbicon -- Toolbar Icon Generator

Generates 16x16 24-bit BMP toolbar icons for the DVX BASIC IDE.

### Usage

```
mktbicon <output.bmp> <type>
```

Available types: `open`, `save`, `run`, `stop`, `code`, `design`,
`debug`, `stepinto`, `stepover`, `stepout`, `runtocur`.

### Example

```
mktbicon tb_run.bmp run
```

### Binary

`bin/host/mktbicon`


## mkwgticon -- Widget Toolbox Icon Generator

Generates 24x24 24-bit BMP icons representing each widget type in the
DVX BASIC visual form designer's toolbox.

### Usage

```
mkwgticon <output.bmp> <type>
```

Supported widget types (one BMP per widget):

```
button    label      textbox    checkbox   radio      dropdown
combobox  listbox    listview   treeview   image      imgbtn
canvas    slider     spinner    progress   timer      frame
hbox      vbox       splitter   scrollpane tabctrl    toolbar
statusbar separator  spacer     terminal   wrapbox    datactrl
dbgrid
```

### Example

```
mkwgticon wgt_button.bmp button
```

### Binary

`bin/host/mkwgticon`


## bmp2raw -- VGA Splash Converter

Converts a 320x200 256-colour BMP into the raw VGA splash image
format used by the bootstrap loader. The loader displays this raw
image in VGA mode 13h before switching into the configured VESA mode.

### Usage

```
bmp2raw <input.bmp> <output.raw>
```

Input must be exactly 320x200 at 8 bits per pixel. Output is a flat
64768-byte file:

* 768 bytes of palette (256 entries of 3 bytes, VGA 6-bit RGB values)
* 64000 bytes of pixel data (320x200 in top-to-bottom scanline order)

### Example

```
bmp2raw assets/splash.bmp bin/system/SPLASH.RAW
```

### Binary

`bin/host/bmp2raw`


## bascomp -- DVX BASIC Compiler (host)

Command-line compiler for DVX BASIC projects. Takes a `.dbp` project
file and produces a standalone `.app` DXE binary. The compiler links
against `basstub.app`, which is the runtime stub that hosts the
compiled BASIC bytecode.

### Usage

```
BASCOMP <project.dbp> [-o <output.app>] [-release]
```

| Flag             | Purpose |
|------------------|---------|
| `<project.dbp>`  | Required. Path to the project file. |
| `-o <output>`    | Output path. Defaults to the project name with `.app` extension. |
| `-release`       | Strip debug information and obfuscate form and control identifiers before emitting the binary. |

The `-release` flag enables two internal passes inside the compiler:

* **strip** -- removes debug variable info and debug UDT definitions
  from the emitted module, mangles procedure names that are not
  needed for name-based dispatch.
* **obfuscate** -- renames form and control identifiers to short
  generated tokens (`C1`, `C2`, ...) throughout the module and in
  the raw `.frm` text resources.

These are implemented in
`src/apps/kpunch/dvxbasic/compiler/strip.{c,h}` and
`src/apps/kpunch/dvxbasic/compiler/obfuscate.{c,h}` and run
automatically when `-release` is passed.

### Example

```
BASCOMP iconed/iconed.dbp -o bin/apps/kpunch/iconed/iconed.app -release
```

The compiler lives under `src/apps/kpunch/dvxbasic/stub/bascomp.c`
(the main-less library form of the BASIC stack is shared with the
IDE).

### Binaries

* Host: `bin/host/bascomp`
* Target: `bin/system/BASCOMP.EXE` (DOS executable)


## proxy -- SecLink Serial Bridge

Separate Linux-side program; see `src/tools/proxy/README.md`.


## Shared Files

| File             | Description |
|------------------|-------------|
| `bmpDraw.h` / `bmpDraw.c` | Minimal 24-bit BMP canvas and pixel-art primitives shared by mkicon, mktbicon, and mkwgticon. |
| `dvxResWrite.h`  | Resource-writing helper used by `dvxres`. |
| `hlpcCompile.h`  | Public interface of the help-compiler core, used both by the standalone `dvxhlpc` binary and by the loader (for boot-time recompilation). |


## Build

```
make            # build every host tool
make clean      # remove bin/host/ and bin/system/
```

Uses the system GCC with `-O2 -Wall -Wextra -Werror`. The resource
tool, help compiler, and BASIC compiler are additionally cross-compiled
with the DJGPP toolchain (`i586-pc-msdosdjgpp-gcc`) so they can ship as
DOS executables inside `bin/system/`. (`bascomp` is built by the
`src/apps/kpunch/dvxbasic/Makefile`, not this directory's Makefile.)

The targets are host-native only; they do not need the DJGPP
toolchain for the non-DOS binaries.
