##### About #####

This repository contains the files comprising JAMScript, an extension
implementing transaction introspection in the SpiderMonkey JavaScript
interpreter. This project is being built and maintained by Rich Joiner
(joiner@cs.wisc.edu) at the University of Wisconsin-Madison. This work
is done under the advisement of Professors Tom Reps and Somesh Jha.

This project is based on the Transcript system built and designed by
Mohan Dhawan and Vinod Ganapathy at Rutgers University, and Chung-chieh
Shan at the University of Tsukuba. Many thanks to them for their
helpfulness along the way.

The latest version of the repository can be obtained via the Git
repository hosted at the following address.

https://github.com/blackoutjack/jamscript

##### Getting started #####

The patch files are targeted to Firefox version 17.0.3esr. (The same patch files have also been verified to work with version 17.0.5esr.) The system
has been developed on Ubuntu version 12.04 with Linux kernel
3.2.0-65-generic, though Firefor version 17.0.3esr on other operating
systems will likely work fine. See the doc/INSTALL.bash for instructions
on obtaining, patching and running the supported version of Firefox on
Ubuntu. Build instructions for FreeBSD 9.0 are also included in
doc/INSTALL-FREEBSD.

##### Files #####

The following subdirectories are included in this package.

doc/: Documentation on building and using the system.
patch/: Diffs for patching the SpiderMonkey/Firefox source; see
  doc/INSTALL.bash for instructions on applying the patches.
txjs/: Contains libTx.js, a JavaScript library used for processing
  transactions. Also included is policy-template.js, an example
  implementation of a policy file.
tests/: A suite of tests; see below for information on running
util/: Some ancillary scripts generating patches and moving files
  around. 

######## Testing #########

The tests/js/ directory contains a myriad of small JavaScript files and
the expected output in the corresponding .exp files. These tests can
be run with the Python script at tests/run.py as follows.

./tests/run.py

You may need to alter some of the paths in tests/config.py to conform
with your system. The script was tested with this repository checked
out as a subdirectory of the $JAMPKG called jamscript/, and the current
settings reflect that.

There is also an in-browser test suite available separately from the
Git repository hosted at the following URL.

https://github.com/blackoutjack/jamtests

Instructions for running these tests (manually and by automation) are
included in the README file for that repository.