Dali VM packages

This section describes the organization of packages in the Dali Virtual Machine programming model, and outlines the steps to take to write your own package as an extension to Dali.

(The code currently resides in the SourceSafe repository, in the project named RVM-pkgs.)

Overview

The Dali Virtual Machine has been split up into a number of separate packages, each one implementing a set of RVM commands. This enhances the modularity of the code and allows the user to avoid loading the entire Dali command space when only a subset is needed.

At the core of the VM is the Rvmbasic package. It defines the abstractions for bit and byte images, as well as simple arithmetic operations on these types. All other RVM packages use the Rvmbasic, and therefore require it to be loaded (by executing the Tcl "package require Rvmbasic" command).

This document describes the files in a typical RVM package. A template package is provided to serve as an example RVM package on which new RVM package can be based. Its implementation is trivial, as its only purpose is to demonstrate the package structure. It should be used in conjunction with this page to learn the proper organization of the code, and can then actually be used as a template to modify into a new package.

Source file overview

The following files are needed for each package (package name designated by <pkg>):

• package/<pkg>/<pkg>init.c
  • The command array is initialized here. It defines the commands that will be registered for the Tcl interpreter to recognize.
  • The DLL's initialization procedure is defined here. It includes function calls to require Rvmbasic, to register the new commands, and to register the new package.
• package/<pkg>/<pkg>Int.h
  • This header file declares the functions, variables, macros, etc., that are only used internally within the package. These are usually local helper functions and such.
  • This file will be included by the various *.c files in this directory. <pkg>Int.h contains the "include rvm<pkg>.h" line, bringing in the rest of the definitions, which are external to the package.
• package/<pkg>/*.c
  • These are the various implementation files. Most will define the functions for the package's commands, but some may define local helper functions. Most of these should include <pkg>Int.h.
• include/rvm<pkg>.h
  • Any new types are defined here (such as ConvKernel, ImageMap). If a new type is defined, macros should be defined (and subsequently used in the implementation) to facilitate storing these variables in the global hashtable. (NOTE: the prefix for the Tcl variable name MUST be 14 characters long. This should be fixed, if possible.)
  • The function prototypes for all the package's commands are given here.

Compiling and linking

The makefile needs to be modified to compile the package into a DLL:

• win/makefile.vc
  • One section should list the object files associated with the package's *.c files.
  • Another section should specify how to make the package's DLL. It should link all of the package's object files (defined in the section mentioned above). If this package references other packages, those packages LIBs should be linked in as well (note that all packages link in RVMBASICLIB, for good measure). If this package will be referenced by others, it should include the option -def:$(TMPDIR)\rvm<pkg>.def to generate the file to facilitate later linking. If this is the case, the makefile should also contain a section to specify how to make the .def file.
  • Another section should specify the implicit rule to make object files out of the source files in the package's directory.
• unix/makefile
  • *** No work has been done on compiling these packages under UNIX. ***

Writing your own package

You can easily create a new package by modifying the template through the following steps:

• Replace all occurences of "template" with your package's name. This applies to filenames, source code, and the makefile. Note: be careful about being consistent with case (e.g. all caps, initial cap, all lowercase).
• Be sure to fill in the gaps outlined by comments with the words "FILL IN HERE".
• The rest of the code should be developed according to your needs, but in keeping with the guidelines and conventions from "Source file overview".

Last Updated : Sunday, 15 November 1998 01:42 AM -0500