+------------------------------------------------------------------------------+
| McScM - Read Me                                                              |
+------------------------------------------------------------------------------+


      McScM (Model Checker for Systems of Communicating fifo Machines) is
      a small framework for implementing model-checking algorithms in the
      context of infinite-state systems of the form "finite control plus
      infinite data". The main constituent is the verify tool for the
      safety verification of systems of communicating fifo machines (CFM).
      The goal of verify is the model-checking of network protocols
      (given as CFM) with respect to a given set of undesired behaviours
      or "bad" states. The main difference to other tools for communicating
      automata is the modeling of asynchronous, reliable fifo channels
      which is indispensable for checking protocols that presuppose a
      reliable connection between the peers (for example as supplied by
      TCP or MPI).  Further, the verify tool allows to choose among
      distinct verification algorithms which are themselves highly
      parametrizable.  This leads to a generic approach that can easily
      be adapted to a variety of concrete safety verification problems.
      In addition, McScM includes a tool for supervisory control that
      helps to fix unsafe protocols.


The latest version and pointers to underlying theoretical publications can be
found at the following webpage:

      http://altarica.labri.fr/forge/projects/mcscm

The tool is distributed as source-code and as pre-compiled binary releases for
several platforms (see below).


Authors / Copyright / Licensing
--------------------------------------------------------------------------------

This open-source software is released under a 2-clause BSD-like license.  Please
refer to the files AUTHORS and LICENSE for further details.


First Steps
--------------------------------------------------------------------------------

To get a first impression of the verify tool, run the shell script benchmark.sh
located in the test/ directory.  This script compares the model-checking engines
available in the McScM framework, on a set of example protocols.  It can be used
to make comparative benchmarks of

  * the model-checking algorithms (with the default trace-checking engine):
    ./test/benchmark.sh -t 30 -e 'absint, armc, cegar, lart'

  * the influence of different trace-checking engines on the CEGAR approach:
    ./test/benchmark.sh -t 30 -e 'cegar(_)'

The option `-t 30' specifies a timeout of 30 seconds for each verification run.
For more details on how to use this script, run it with the `-h' option.


Please consult the user manuals verify(1), control(1) and scm(5), located in the
man/ directory, for more details on the included tools.  On Unix-like systems,
use the man(1) command to display these manuals (e.g., man ./man/verify.1).  The
binary releases also include html and pdf versions of the manuals.  Answers to
some frequently asked questions can be found in the file FAQ.


Binary Releases
--------------------------------------------------------------------------------

We distribute the tool, along with a set of example SCM models, pre-compiled for
Linux and MacOS.

Linux: compiled and tested under GNU/Linux 2.6
       includes statically and dynamically linked binaries for x86-32 and x86-64

MacOS: compiled and tested under MacOS X 10.6
       includes dynamically linked binaries for x86-32 and x86-64

Please contact the authors for requesting packages prepared for other platforms.


File layout:

   --+
     +-bin/
     |   +- verify.native          the safety verification tool
     |  [+- verify.native.static   static version (linux only)]
     |   +- control.native         the supervisory control tool
     |  [+- control.native.static  static version (linux only)]
     |
     +-examples/                   a set of example protocols
     |
     +-man/                        the manuals (roff, ascii, html and ps)
     |
     +-test/benchmark.sh           the benchmark script
     |
     +- AUTHORS
     +- FAQ
     +- LICENSE
     +- README


Source Code Releases
--------------------------------------------------------------------------------

The tool is programmed in Objective Caml and uses several 3rd-party libraries:

   - camllib, fixpoint, latticeAutomata, scm by B. Jeannet & T. Le Gall
     http://gforge.inria.fr/projects/bjeannet/
     all licensed under LGPL

* Build requirements:

  <required>    Objective Caml 3.12 or later       http://caml.inria.fr/ocaml/
  [optional]    Mdocml's mandoc 1.10.5 or later    http://mdocml.bsd.lv/

* Build instructions:

  1) adjust config.mk to your local installation (if Objective Caml 3.12 tools
     are not in your PATH)

  2) run `make' (or `make all' to also build documentation and manuals)

  As an alternative to steps 1 and 2, you may adjust config.mk variables on the
  make command-line, for instance `make OCAMLBUILD=<path to ocamlbuild 3.12>'.


--------------------------------------------------------------------------------
$LastChangedDate: 2011-10-20 00:54:34 +0200 (Thu, 20 Oct 2011) $
