DVX SDK
=======

Headers, tools and project templates for writing DVX programs, widgets
and libraries in C, and programs in DVX BASIC.

Quick Start
-----------

  ./newProject.sh app hello          a C program
  ./newProject.sh widget myWgt       a C widget (usable from DVX BASIC too)
  ./newProject.sh library myLib      a C library of shared functions
  ./newProject.sh basic myProg       a DVX BASIC program
  ./newProject.sh game myGame        a C game (320x200 screen, frame pacing,
                                     keyboard, joystick, sound, music)
  ./newProject.sh basicgame myGame   a DVX BASIC game (FRAMEWAIT, STICK,
                                     STRIG, PLAY)
  ./newProject.sh control myCtl      a control written in DVX BASIC (usable
                                     from C programs too)

  cd hello
  make                               builds hello.app and hello.hlp
  make install DVX_DIR=/path/to/dvx  copies it into a DVX installation

Help is optional: a project without its .dhs builds without help.  A
widget's, control's, or library's help is only checked by make (DVX
compiles it into its own help when it starts), against help/*.ids.

The DVX C Programming Guide (docs/dvxCGuide.html) walks through each kind
of C project: building, running, debugging with DVX.LOG, writing the help
file, the binary interface rules, and packaging, then every part of the
system, games included.  The DVX BASIC Programming Guide
(docs/dvxBasicGuide.html) does the same for DVX BASIC.  The DVX help has
short versions: Technical Reference > SDK Quick Start and Writing Games
for DVX.

Documentation
-------------

  docs/dvxCGuide.html           DVX C Programming Guide: writing programs,
                                widgets, and libraries in C
  docs/dvxCReference.html       DVX C Library Reference: the architecture,
                                the core library, the shell and tasks, and
                                every widget and library
  docs/dvxBasicGuide.html       DVX BASIC Programming Guide: from a first
                                program to a published one
  docs/dvxBasicReference.html   DVX BASIC Language Reference: the language,
                                the controls, the include libraries, and
                                the IDE

Each opens in a web browser and links to its companion.  Inside DVX the
references' text is in the Help program.

Directory Structure
-------------------

  newProject.sh  Creates a project from a template (see Quick Start)
  sdk.mk         Build rules every project Makefile includes
  secproxy.md    How to run secproxy: a serial cable, an emulator's
                 serial port, or the network; options; the passphrase
  bin/           Host tools used by project builds:
                   dvxres     resource tool (adds icons and text to modules)
                   dvxhlpc    help compiler (.dhs -> .hlp)
                   bascomp    DVX BASIC compiler (.dbp -> .app)
                   mkfont     font maker (TrueType, Type 1, and bitmap
                              fonts -> .DFN, for a program to carry)
                   dvxpkg     add-on package tool: builds, signs, checks,
                              and shows .DPK packages, and makes keys
                   secproxy   the secure-link proxy: runs on Linux at the
                              other end of Terminal's secure link and
                              relays it to a telnet BBS (see secproxy.md)
                   dxeGen.sh  runs DJGPP's dxe3gen safely under make -j
  help/          dvxhelp.ids and dvxbasic.ids: the topic ids of DVX's system
                 help and DVX BASIC help, which sdk.mk checks a widget's,
                 control's, or library's help against
  include/
    core/        DVX core headers (types, drawing, windows, widgets, and
                 dvxBas.h for a library's BASIC bindings: handles that
                 belong to the program that made them)
    shell/       Shell/app loading API
    tasks/       Cooperative task switching API
    sql/         SQLite database wrapper API
    serial/      Serial ports: the interrupt-driven UART driver
    crypto/      Cryptography: X25519 and Diffie-Hellman key exchange,
                 XChaCha20-Poly1305 and XTEA-CTR encryption, SHA-256,
                 HMAC, HKDF, and the random number generator
    seclink/     Reliable packets and the encrypted, multi-channel secure
                 link over a serial port or any byte stream
    texthelp/    Shared text editing helpers for widgets
    listhelp/    Shared list and dropdown helpers for widgets
    richtext/    Styled text and RTF in and out (RichEdit widget)
    fileops/     File operations: drives, attributes, listing, copy/move/delete jobs
    xfer/        File transfer protocols: XMODEM, YMODEM, ZMODEM
    conn/        Serial, modem and secure-link connections behind one interface
    print/       Printing: printer ports, print jobs, page layout
    game/        Games: frame pacing, held keys, timers, 8-bit colors
    joystick/    Joysticks: devices, calibrated axes, buttons, events, drivers
    audio/       Sound: samples, tones, streams, volume, the FM chip and
                 the MIDI port; the sound driver interface
    music/       Music: MOD/S3M/XM/IT modules, MIDI files, live MIDI
    pkg/         Add-on packages: the .DPK format, manifests, signatures,
                 the installed packages, and installing and removing them
    json/        JSON: read a document into a tree, find values by path,
                 quote text for JSON of your own
    http/        Web requests: HTTP GET and POST over the network, run a
                 step at a time, to memory or a file (resuming it)
    pkgnet/      A package server: its catalog, the updates, and
                 fetching packages with what they need for pkg to install
    net/         TCP/IP: dvxNet.h and the standard socket headers
                 (sys/socket.h, netdb.h, ...); set NET = 1 in the
                 project Makefile to put them on the include path
    widget/      Per-widget public API headers
    basic/       BASIC include files (DECLARE LIBRARY modules)
  templates/     The project templates newProject.sh copies
  samples/
    basic/       Example BASIC projects (open in the DVX BASIC IDE)
    c/           The DVX C Programming Guide's example programs, widgets,
                 and libraries (cd into one and run make)

Requirements
------------

  - The DJGPP cross compiler (i586-pc-msdosdjgpp-gcc) and its dxe3gen.
    Projects find it through DJGPP_PREFIX (environment or make command
    line), e.g. make DJGPP_PREFIX=/opt/djgpp.  Without it the SDK looks in
    ../../toolchains/djgpp from this directory: inside a DVX source tree
    that is the toolchain ./installToolchain.sh sets up.
  - A Linux host for the tools in bin/.  On DVX itself the same tools are
    SYSTEM/DVXRES.EXE and SYSTEM/DVXHLPC.EXE (with Developer Tools),
    SYSTEM/BASCOMP.EXE (with DVX BASIC), and SYSTEM/DVXPKG.EXE.

Deployment
----------

`make package` lays out pkg/ exactly as it goes into the DVX directory:

  Programs:   APPS/<vendor>/<name>/<name>.APP and <name>.HLP
  Savers:     SHARED/SAVERS/<vendor>/<name>.APP (a program with SAVER = 1)
  Widgets:    WIDGETS/<vendor>/<name>/<name>.WGT, .DHS, .BHS and .DEP
  Libraries:  LIBS/<vendor>/<name>/<name>.LIB, .DHS, .BHS and .DEP

(each help file and .DEP only when the project has one).  `make install
DVX_DIR=...` copies pkg/ into a DVX directory, into the folders already
there whatever the case of their names.

The vendor directory is VENDOR (default local).  As DVX starts it loads
the libraries with constructors (each after the libraries its .DEP
names), then every widget; a library without constructors loads when
something first uses one of its names, and a program when it is run.  An
add-on that cannot be loaded as DVX starts, or that was built for another
version, is skipped (so is one that needs it) and named in a box once
DVX has started; one loaded later fails only then, and only DVX.LOG says
why.  When a module or a .DHS/.BHS file under LIBS or WIDGETS is added,
removed, or changed (an upgrade over the old one too), DVX rebuilds the
help files built from them as it starts; a help source that does not
compile is left out, and the rest is built.

It also makes <name>.dpk, an add-on package of the same files that
anyone can install with DVX's Software program (or SYSTEM/DVXPKG.EXE
install).  The package name is <vendor>.<name> in lower case; sdk.mk's
PKG_* settings give its title, version, summary, publisher, author,
license, web site, the oldest DVX it runs on, and the packages it needs
(any of them may hold blanks and apostrophes).  Sign it so people can tell
it is yours:

  bin/dvxpkg keygen "Your Name" mykey      (once: mykey.SEC and mykey.KEY)
  make package PKG_KEY=mykey.SEC PKG_VERSION=1.2.0

Give mykey.KEY to the people who install your packages, and keep
mykey.SEC private: anyone who has it can sign packages as you.

Binary Interface Version
------------------------

Every module records the DVX binary interface (ABI) version it was built
for: programs through SHELL_APP_DESCRIPTOR(...), libraries and widgets
through DVX_ABI_STAMP(<file base name>), widget API tables through
WGT_API_HEADER.  DVX refuses a module built for a different version, so
rebuild your modules against the SDK of the DVX release they run on.
