Welcome to ZVM
===============

This is a work-in-progress.  More information about this project can
be found at

       http://code.google.com/p/zvm


What is ZVM?
============

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.


Code
====

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

You can check out the latest code from Subversion here:

       http://zvm.googlecode.com/svn/trunk


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.  The build system used to create
this library is SCons, a Python-based build system which can be
downloaded here:

     http://www.scons.org/

The SCons build scripts included in this distribution have been tested
successfully on Windows using Microsoft Visual Studio .NET 2003, and
on Linux using gcc.

To build everything, just type "scons" at the root directory of the
project.

Project contents:

      README                        this file
      LICENSE                       the BSD license
      SConstruct                    SCons script 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

Note that there's also a /wiki directory at the top level of the
repository, which contains our live wiki pages.