README

The goal of the ZVM project is to write a pure-python implementation
of a Z-machine, a virtual computer architecture that executes
interactive fiction stories written in a special language, called
Z-code.

The current goals of the project include:

    * No user interface: ZVM implements only the actual Z-machine. It
      is meant to be used as the backend in other programs that
      provide a user interface.  (User interface will probably be done
      via the 'glk' API, making ZVM pluggable into existing front-ends.)

    * Compatibility: ZVM will implement a Z-Machine architecture
      according to the official specification.

    * Coverage: Over the years, the Z-machine architecture was revised
      and refined: 8 versions are known to exist. ZVM currently aims
      to support Z-machine versions 1 through 5.

    * Programming language: ZVM is written exclusively in the Python
      programming language, as an importable code module.

    * Readability: speed is not an issue when emulating a 28-year old
      virtual machine on a modern computer, so we always shoot for
      readable code over clever optimizations.

All code is covered by the BSD license, found in the LICENSE file.

Build and Test
==============

To build this code and run the test suite, just do

  $ make && make check

from the top level of the source tree.

Project contents
=================

      README                        this file
      LICENSE                       the BSD license
      Makefile                      used to build C code
      run_tests.py                  script to run automated tests
      run_story.py                  script to execute a story file
      tests/                        automated tests for the module
      stories/                      some sample stories to interpret
      zvm/                          the actual ZVM python module
      docs/                         notes, diagrams, instructions
      cheapglk/                     the CheapGlk Glk library

A Note on C Code
================

Note that while ZVM itself is written exclusively in Python, it does
have the ability to interoperate with Glk front-ends which have been
built as shared libraries.  In order for our testing suites to test
this functionality, we have included a slightly modified version of
Andrew Plotkin's CheapGlk library.