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)

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

The DVX help has a step-by-step guide for each kind of project
(Technical Reference > SDK Quick Start): building, running, debugging
with DVX.LOG, writing the help file, the binary interface rules, and
packaging.  Technical Reference > Writing Games for DVX
covers game input, timing, the screen and palettes, sound, music,
joysticks, data and save files, and porting a game library to DVX.

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

  docs/dvx_system_reference.html  The DVX help as one page: the user guide,
                                  the SDK Quick Start, Writing Games for
                                  DVX, and the reference for every header,
                                  library and widget
  docs/dvx_basic_reference.html   DVX BASIC: the language, the IDE, the
                                  controls and the include libraries

Inside DVX the same 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
  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
                   dxeGen.sh  runs DJGPP's dxe3gen safely under make -j
  include/
    core/        DVX core headers (types, drawing, windows, widgets)
    shell/       Shell/app loading API
    tasks/       Cooperative task switching API
    sql/         SQLite database wrapper API
    serial/      Serial port, packet, security and secure link APIs
    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 colours
    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 catalogue, 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)

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, SYSTEM/DVXHLPC.EXE, SYSTEM/BASCOMP.EXE, 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
  Widgets:    WIDGETS/<vendor>/<name>/<name>.WGT, .DHS, .BHS and .DEP
  Libraries:  LIBS/<vendor>/<name>/<name>.LIB, .DHS and .DEP

The vendor directory is VENDOR (default local).  DVX loads libraries
first (in .dep order), then widgets, then programs; it rebuilds the
system help from the .DHS/.BHS files when the set of modules changes.

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,
licence, web site, and the packages it needs.  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.
