##### about #####

This repository contains the files constituting the JavaScript Model-
Checker, a.k.a. JAM. This project is being built and maintained by Rich
Joiner (joiner@cs.wisc.edu) at the University of Wisconsin-Madison.
The idea was concieved and prototyped by Matt Fredrikson, also of
UW-Madison, while working with Philip Porras and Hassen Saïdi at SRI.
This work is done under the advisement of Professors Tom Reps and
Somesh Jha.

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

https://github.com/blackoutjack/jamweaver

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

As of yet, the dependencies and build scripts are specific to the Ubuntu
Linux platform. The system has been developed on Ubuntu 14.04 with Linux
kernel 3.13.0-39-generic, though other versions of this OS will likely
work (once dependencies are installed).

For dependency installation, review INSTALL.bash and DEPENDENCIES.mk in
the doc/ directory. INSTALL.bash handles environmental setup (installing
packages with apt-get and setting the JAMPKG environment variable,
e.g.). Then DEPENDENCIES.mk can be invoked as a makefile to download and
install 3rd-party resources. (This currently needs to be done from the
$JAMPKG directory: ``make -C $JAMPKG -f doc/DEPENDENCIES.mk [target]''.)

Once the environment and dependencies are in place, you can build the
system by invoking ``make'' (within $JAMPKG). See doc/RUNNING for
running tests included in the jamtests repository, and doc/POLICIES for
formulating policies.

The JAM analysis creates JavaScript files instrumented with transaction
blocks; to run these programs, you'll need to build a specially modified
version of Firefox that supports transactions. The required files and
instructions to do that can be obtained via the Git repository hosted at
the following address.

https://github.com/blackoutjack/jamscript

There is also a suite of applications (the input and output of the
weaver) that can be obtained here:

https://github.com/blackoutjack/jamtests

For a default configuration, clone the jamscript and jamtests
repositories, respectively, into jamscript/ and tests/ subdirectories
of the jamweaver repository. To adjust to a different setup, alter the
JAMSCRIPT_DIR and TESTS_DIR variables in util/config.py.

##### Files #####

The directory structure of JAM is briefly described below.

doc/: Documentation for installing and running JAM.
  INSTALL.bash: instructions/script for environment setup
  DEPENDENCIES.mk: a script to install third-party dependencies
  RUNNING: instructions for invoking JAM
  POLICIES: description of policy structure and language

util/: Scripts, mostly for generating, collecting and analyzing results
  and performance statistics. See doc/RUNNING for details.

cache/: This (initially empty) directory will be populated with a XSB
  query cache, so that subsequent invocations of JAM will avoid calls
  to the semantics module that have previously been evaluated. The cache
  can be cleared by running ``make cacheclean.''

output/: This directory will contain the output of a JAM analysis. A
  new subdirectory prefixed with the name of the input JavaScript file
  will be created for each run. For example, after running JAM on
  snote.js for the first time, the output can be found in
  output/snote-0. The subdirectories will contain much more information
  when running JAM with the -g (debug) flag.

bin/: Contains the executable files for running the JAM analysis. (These
  are created by ``make.'') See doc/RUNNING for more information.

lib/: Contains binaries of the various XSB and C modules (also created
  by ``make'') used by JAM.

closure-patch/: This directory contains patches for the Google closure
  tool that enables it to parse and manipulate the transactional
  instrumentation that is woven by the analysis. These patches are
  automatically applied when ``make -f doc/DEPENDENCIES.mk closure'' is
  invoked.