SPIN README

Overview of this File

1. Downloading Spin
2. Installing Spin
   • on Unix systems
   • on Windows PC's
3. Related software (gcc, cpp, go32, wish, dot, ltl2ba)

Spin is distributed in source form to encourage research in formal verification, and to help a support friendly and open exchange of algorithms, ideas, and tools. The software itself has a copyright from Lucent Technologies and Bell Laboratories, and is distributed for research and educational purposes only (i.e., no guarantee of any kind is implied by the distribution of the code, and all rights are reserved by the copyright holder). For this general use of Spin, no license is required.

Commercial applications of the Spin software is also allowed, but it requires a basic license. Refer to the Spin Public license page for details.

1. Downloading Spin

• http://spinroot.com/spin/Bin/index.html

• Unix systems:
  download the following tar-file with sources, the graphical interface Xspin, documentation and examples:
  • http://spinroot.com/spin/Src/spin351.tar.gz
  Continue at 1a below.

• PCs (Windows95/98/2000/NT/XP):
  download the following zip file, with a precompiled Spin executable, the graphical interface Xspin, and some examples:
  • http://spinroot.com/spin/Src/pc_spin351.zip
  Continue at 1b below.

1a. Installing Spin on a Unix System

Place the *.tar.gz file in clean directory, cd to that directory. If you have a standard Unix system, unpack the archive, and compile the executable as follows:

	gunzip *.tar.gz
	tar -xf *.tar
	cd Src3.5
	make

If you are on a SOLARIS system, first edit the makefile and add -DSOLARIS to the compiler directives in the makefile first. You may also have to edit the makefile to pick up your preferred ANSI C compiler (e.g, gcc). You minimally need to have a working C compiler and a copy of yacc to use the makefile.

Spin should compile without warnings. 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.)

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

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

On Unix systems Spin assumes that the standard C preprocessor cpp is stored in file "/lib/cpp". On some systems this is different: check the comments in the makefile for details if you run into this problem.

Testing

To test the basic sanity of the Spin executable, cd to the Test directory and follow the instructions in file README.tests

Adding Xspin

Xspin is an optional, but highly recommended, graphical user interface to Spin, written in Tcl/Tk. To obtain Tcl/Tk, see Related software below. The Xspin source can be found the Xspin3.5 directory.

The current version of Xspin is compatible with

	Tk version 4.2 - Tcl version 7.6, and
	Tk version 8.3 - Tcl version 8.3

Xspin 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

You can find out which version of Spin you have by typing, at a Unix command prompt:

	$ spin -V

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

To install Xspin on Unix, cd to directory Xspin3.5 from the distribution,

1. Rename xspin35*.tcl into a more convenient form (like xspin or xspin.tcl) and follow the instructions at the top of this xspin.tcl file. Minimally: you must change the first line of this file to point to the executable `wish' command on your system that you want to use. If you use another C-compiler than the default (gcc), you should update the global variable CC inside xspin as well. Follow the instructions inside the xspin.tcl file to do so.
2. copy the file into a directory within your search path and make it executable, for instance:

   	cp xspin.tcl /usr/local/bin/xspin
   	chmod +x /usr/local/bin/xspin
   

3. make sure that an executable version of `spin' itself is also within your search path, and is up to date (check by trying: spin -V).
On Unix, invoke the program by typing

	xspin	# or xspin.tcl if you keep the extension...
or
	xspin promela_spec

For example:
	cd Test
	xspin leader

Check the online Help menus in xspin for more details on routine use.

1b. Installing Spin on a Windows PC

If you just need to update the Spin executable itself, download a new version from http://spinroot.com/spin/Bin/index.html If you need more files, e.g. a new copy of Xspin, download http://spinroot.com/spin/Src/pc_spin351.zip Extract the files from pc*.zip, and copy spin*.exe into the directory where all your commands reside and that is within your default search path (e.g., c:/cygwin/bin/, or c:\apps\spin\) You can find out what your search path is set to by typing 'set' at an MS-DOS prompt -- this prints a list of all defined variables in your environment, including the search path that is used to find executable commands.

If you use Spin from the command line (i.e., without Xspin), be warned that some command shells, e.g., the MKS Korn-shell, have none-standard rules for argument parsing (i.e., you can not reliably quote an argument that contains spaces, such as an LTL formula). In most cases this will not be much of a problem, except with the conversion of LTL formula with the Spin -f option. You can circumvent this by using -F instead of -f, to read the formula from a file instead of the command line.

To run Spin, even from the precompiled version, you need a working C-compiler and a C-preprocessor, because Spin generates its model checking software as C-source files that require compilation before a verification can be performed. This guarantees fast model checking, because each model checker can be optimized to the specific model being checked. Check, for instance, if you can compile and run a minimal C program succesfully, e.g.: #include int main(void) { printf("hello\n"); }

To find a public version of a C compiler and some instructions on how to install it see Related software.

Adding Xspin

To run Xspin on the PC, you need the PC version of Tcl/Tk, which you can find under Related software.

The xspin*.tcl source is contained in the .zip file of the distribution. Copy the file as is into a directory where you plan to work, or put a shortcut to this file on the Desktop or in the Start Menu. If you keep the extension .tcl, make sure it is recognized as a 'wish' file by the system, so that xspin starts when you double click the xspin*.cl script.

Under cygwin, copy the xspin*.tcl file to /bin/xspin/xspin.tcl and make it executable -- check the first few lines of xspin.tcl to make sure the location of xspin matches what you have on your system (it is currently setup for c:/cygwin/bin/xspin). You can now use xspin as a normal Unix-style command, and you can pass the name of a filename to it, for instance as:

	xspin leader

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

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

and you should be up and running.

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. 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 do a reasonable number of things without gcc.exe though (like simulations). The C-compiler is required for all verifications and for the automata views in Xspin.

2. Related Software

Pointers to public domain versions of some related software packages are discussed below:
• Gcc,
• Cpp,
• Yacc,
• Tcl/Tk wish,
• Dot, and
• Ltl2Ba.

GCC

On Unix you probably have gcc, or an equivalent, installed. On the PC you need either a copy of Visual Studio (for the cl command), or an installation of gcc with minimally the executables: gcc.exe, and cpp.exe in your search path, together with all the standard C library routines and header files. You can get good free version of all these files with the cygwin toolkit, which is mostly self-installing and available from: http://www.cygwin.com

Tcl/Tk Wish

To run Xspin you'll need Tcl/Tk. Tcl/Tk was written by John Ousterhout (john.ousterhout@eng.sun.com) and is public domain. It can be obtained (for PCs or Unix) from cygwin, or from:

	www.tcl.tk

More details can be found in netnews-group: comp.lang.tcl

Yacc (optional)

To compile Spin itself from its sources on a PC, you'll need to have a copy of yacc installed. A public domain version for a PC can be obtained from:

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

(You don't need yacc on the PC's if you use the pre-compiled version of Spin for the pc in the pc*.zip file from the distribution) Look at the file make_distr.bat for an example on how to perform the compilation.

Dot (optional)

Dot is a graph layout tool developed by Stephen North and colleagues at AT&T (email: north@research.att.com). Xspin can make use of Dot to beautify the layout of the state-machines in the automata-view option (recommended!). To obtain Dot, see

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

The are both PC and Unix versions of Dot available. For documentation of Dot see:

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

Ltl2Ba (optional)

A faster method to generate very small never claims from LTL formulae, developed by Denis Oddoux and Paul Gastin is available online in source form:

	http://spinroot.com/spin/Src/ltl2ba.tar.gz

Or can be obtained from the authors website via:

	http://verif.liafa.jussieu.fr/ltl2ba/

The C source code can easily be linked with Spin, or run as a standalone tool.

An alternative converter is the ``Temporal Massage Parlor'' written by Kousha Etessami. This translator is written in ML, and is also available in source form via http://www.bell-labs.com/topic/swdist/)

---

Spin HomePage

(Page Updated: 1 October 2002)