SPIN README

Contents

1. General Description of Spin
2. Downloading and Installation
   • Unix systems
   • Windows95/WindowsNT PC's
3. Related software (gcc, tcl/tk)
4. Updates of the Spin sources
5. Spin documentation
6. Theoretical Background
7. Mailing List
8. Spin Workshops

1. General Description

Spin supports dynamically growing and shrinking numbers of asynchronous processes, supports both rendezvous and buffered message passing, and communication through shared memory.

The Spin software is distributed through the netlib server. All files can be found on the host netlib.bell-labs.com in directory /netlib/spin -- or via the following URLs:

	http://netlib.bell-labs.com/netlib/spin/index.html
	http://netlib.bell-labs.com/netlib/spin/whatispin.html

The software includes a random simulator, interactive and guided simulation options, and formal verification based on either exhaustive or reduced reachability analysis. The software contains efficient implementations of partial order reduction techniques, and (as an option) the supertrace storage technique to handle very large verification problems.

Included is also an X-windows interface to the Spin system, called 'xspin', written in Tcl/Tk.

There are many thousands of installations of the Spin software. The mailing list information at the end of this file contains information about the newsletter and annual workshops.

2. Downloading Spin

• On UNIX systems, directly compile Spin from the: C-sources + Xspin, docs, and examples
  For installation notes see 2a below.
• On Windows95/WindowsNT PCs: 32-bit precompiled Spin + Xspin, and examples
  For installation notes see 2b below.

2a. Installation Notes for Unix Systems

Installing Spin (Unix)

Spin should compile without warnings. You do not have to do anything special unless you are on a Solaris system or a PC (in that case, read the comments in the makefile first). Install the executable version of spin in a directory that is within your default search path (such as your home bin directory, or /usr/local/bin etc.)

You may have to adapt the makefile to pick up an ANSI C standard C compiler (for instance, the Gnu C compiler, gcc). (If you need to install gcc, yacc, or Tcl/Tk, see below under: Related Software)

If all else fails, you can also compile everything with the following two lines:

	yacc -v -d spin.y
	cc -o spin *.c

	 -DSOLARIS

To test the basic sanity of the Spin executable, do:

	$ cd Test
	$ spin -V
	Spin Version 2.9.0 -- 14 July 1995
	$ spin hello
	passed first test!
	1 processes created
	$ spin -a loops
	$ cc -o pan pan.c	# or: gcc -ansi -o pan pan.c
	$ pan
	(Spin Version 2.9.0 -- 14 July 1995)
	...no errors, check:
	      17 states, stored
	       5 states, matched
	      22 transitions (= stored+matched)
	       0 atomic steps
	...
	$ pan -a
	...1 error, check:
	      14 states, stored (16 visited)
	       2 states, matched
	      18 transitions (= visited+matched)
	       0 atomic steps
	...
	$ cc -DNP -o pan pan.c	# non-progress cycle detection
	$ pan -l
	...no errors, check:
	      30 states, stored (43 visited)
	      35 states, matched
	      78 transitions (= visited+matched)
	       0 atomic steps
	$ spin -t -p loops
	...prints error-trace from pan -a above
	$ rm -f pan*  loops.trail	# clean up debris from tests

Installing Xspin (Unix)

	$ spin -V

To obtain Tcl/Tk, see 'related software' below.

The current version of Xspin is compatible with

	Tk version 4.2 - Tcl version 7.6

	Tk version 8.0 - Tcl version 8.0

Xspin 3.0 prints the version numbers of Spin, Xspin, and Tcl/Tk when it starts up. You can also check separately which version of Tcl/Tk you have installed by executing the following commands in `wish' (a Tcl/Tk command):

	info tclversion
	puts $tk_version

Xspin can also make use the graph layout program 'dot' if it is available on your system (not required, but nice if it's there -- xspin will automatically recognize if 'dot' is installed.) For information on 'dot,' see also 'related software.'

To install Xspin on Unix, cd to directory Xspin,

• (a) change the 1st line of the xspin script to point to the executable `wish' command on your system that you want to use. make sure this pathname (it must be a full path) is less than 30 characters long
• (b) copy the file into a directory within your search path and make it executable, for instance:

  	cp xspin* /usr/local/bin/xspin
  	chmod +x /usr/local/bin/xspin
  

• (c) make sure that an executable version of `spin' itself is also within your search path, and is up to date.
• (d) if you use `gcc' instead of `cc' to compile `spin' you should use `gcc' with xspin as well. do so at the start of the file xspin* -- the correct place is indicated at the start (it's an editable script file)

	xspin

	xspin promela_spec

	xspin Test/leader

2b. Installation Notes for PC's (Windows95 and WindowsNT)

Installing Spin (Windows95/WindowsNT)

If you run Spin from the system prompt (i.e., if you're not using Xspin), use the standard MS-DOS prompt. If you use the Korn-shell from, for instance, the MKS toolkit, some of the argument parsing will give problems (i.e., you can then not reliably quote an argument that contains spaces, such as an LTL formulae)

If you want to compile Spin from its sources for the PC, you will need a version of 'yacc,' plus the normal c-compiler. (See related software on where to get public versions.) A c-compiler and c-preprocessor will be needed in either case to be able to run verifications though, so it is wise to make sure these are installed before you try running Spin.

Install all of: gcc.exe, cpp.exe, go32.exe, and spin.exe in the gcc\bin directory, which should be part of the search path you setup in the autoexec.bat file on your PC (as per the instructions from the gcc readme.1st file). In any case, do not keep spin.exe in the same directory as the Promela files you'll be working on.

Installing Xspin (Windows95/WindowsNT)

To run Xspin, you need the PC version of Tcl/Tk (see related software.) Note: Tcl/Tk is works on Windows95 or WindowsNT, but not on Windows 3.1.

The easiest way to start Xspin is to name it

	xspin.tcl

Another way to force xspin to startup is to first start `wish' from the Start Menu, under Programs, then to select the larger window that comes up (the command window), and to cd to the directory where you've stored the XSpin file. Then you can start it up by typing:

	source xspin.tcl	# or whatever else you've named this

Be careful: don't store the executable for spin itself (spin.exe) in the same directory as the tcl/tk source for xspin -- for some reason wish does not call spin.exe correctly in that case. Place spin.exe in a directory with executables within your search path (e.g., in gcc\bin where gcc.exe also lives).

The PC installation assumes that you have a command called "cpp.exe" available (which comes with the gnu-c installation), which is the traditional name of the C preprocessor. To complicate your life somewhat, if you have a copy of the Borland C++ compiler installed, you'll notice that this cplusplus compiler was also named cpp.exe -- that's not the cpp you want of course. To avoid the name clash, you either have to edit the Spin source code to give it the full path name of the 'real' cpp.exe and recompile, or use Spin with the command-line option -Pxxxx where xxxx is the path for cpp.exe. Nothing much in Spin will work without access to cpp.exe. You can however do a lot without gcc.exe. The latter is required only for verifications and for the FSM views in Xspin.

3. Related Software

GCC

	http://www.simtel.net/pub/simtelnet/gnu/djgpp/v2
and
	http://www.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu

	http://www.simtel.net/pub/simtelnet/gnu/djgpp/v2/readme.1st

	gcc.exe, cpp.exe, and the 32bit extender go32.exe

	from:	/pub/simtelnet/gnu/djgpp/
	file:	v2/djdev201.zip
	file:	v2gnu/gcc2721b.zip
	file:	v2gnu/bnu27b.zip

TCL/TK Wish

	ftp.smli.com

	/pub/tcl

  	http://sunscript.sun.com/

YACC (optional)

	ftp.cs.berkeley.edu
	file: ~ftp/ucb/4bsd/byacc.tar.Z

DOT (optional)

	http://www.research.att.com/sw/tools/graphviz/

	A Technique for Drawing Directed Graphs,
	by Gansner, Koutsofios, North and Vo,
	IEEE-TSE, March, 1993.

4. Updates of the Spin Sources

5. Spin Documentation

• - A standard manual page for Spin can be found in:

  	Spin.html, and
  	Pan.html.
  

• - Online references are at:

  	Online ManPages
  

• - Basic manuals are included in:

  	Manual.html		(language and tool)
  	Quick.html		(by Rob Gerth, Eindhoven Univ./Intel)
  

  Additional information can be found in the files

  	GettingStarted.html	(mostly on xspin)
  	Roadmap.html		(mostly on spin)
  	WhatsNew.html		(mostly on promela)
     	Exercises.html		(routine use)
  

  Some of the documentation assumes that you only have access to vanilla spin, if you have Xspin working, start with GettingStarted If you have only plain spin working, start with Roadmap and Exercises and in both cases proceed with Manual and then (later) WhatsNew.html
• - For a quick introduction to Spin, a tutorial can be found in:

     Design and Validation of Computer Protocols, a Tutorial,
     Computer Networks, Vol 25, No. 9, Apr. 1993, pp. 981-1017.
  

  An overview paper appeared in:

     The Spin Model Checker,
     IEEE Trans. on Software Eng. Vol. 23, No. 5, May 1997, pp. 279-295.
  

• - A detailed description of the software and its applications (the main Spin documentation) can be found in:

      Design and Validation of Computer Protocols,
      Gerard J. Holzmann, Prentice Hall, 1991, ISBN 0-13-539925-4.
  

  The book contents is available online in Acrobat PDF format, and in standard Postscript format. There is also a Japanese translation of the book.

  Included in the Spin sources distribution tar-file (see 2. above):

     Errata on the printed version are in:  Doc/Book.Errata
     Answers to selected exercises:	  Doc/Book.answers
     More explanation on chapter 6 is in:   Doc/Book.Ch6.add
     Spin examples used in the book are in: Doc/Book.samples
  

  other examples, not in the book, can be found in the Test/ directory from the distribution.

	http://netlib.bell-labs.com/netlib/spin/XXX/papers.html