#######################################################################
# Introduction
#######################################################################

If you are reading this file, then you have most probably obtained and
installed a  distribution  of MAGIC. In the  rest  of this document we
will  assume that the root  of the MAGIC  distribution  is a directory
called MAGICDIR. For example, suppose you obtained  MAGIC from the CVS
repository by typing the following commands:

$ cd foo
$ cvs co magic

Then the root of  the MAGIC distribution  (and hence MAGICDIR for this
document) will  be "foo/magic".  Alternatively  suppose you downloaded
magic.tar.gz and  saved it in the  directory "bar" and  then typed the
following commands:

$ cd bar
$ tar xvfz magic.tar.gz

Then the root of the  MAGIC distribution (and  hence MAGICDIR for this
document) will be "bar/magic".

#######################################################################
# Linux Installation
#######################################################################

MAGIC has been successfully compiled on RedHat 7.1  and RedHat 8.0. On
RedHat 7.1 make sure that gcc is at least  version 3.x and bison is at
least version 1.35. The default  versions of gcc  and bison that  come
packaged with RedHat 7.1 are insufficient. For RedHat 8.0, the default
gcc and bison are OK. Also make  sure that your  shell is tcsh. If you
are using bash, type the following to start using tcsh:

$ tcsh

To compile and run MAGIC, perform the following steps:

Step 1: Set up  the MAGICROOT environment  variable. Type:

$ setenv MAGICROOT MAGICDIR

Step  2:    Make sure  the   OSTYPE environment   variable   is set to
"linux". Type:

$ setenv OSTYPE linux

Step 3: Compile. Type:

$ cd MAGICDIR
$ make

Step 4: Make  sure that  the MAGICDIR/main  directory is in  your path
since the "magic" binary will be created there. Type:

$ setenv PATH ${PATH}:MAGICDIR/main

The setting up of environment variables in  steps 1, 2  and 4 can also
be done  automatically by adding  the  following three  lines to  your
.login file:

setenv MAGICROOT MAGICDIR
setenv OSTYPE linux
setenv PATH ${PATH}:MAGICDIR/main

#######################################################################
# Windows Installation
#######################################################################

MAGIC has been   successfully compiled on  Windows  2000 using  Cygwin
1.3.17.   It   can be reasonably     expected to compile   on  Windows
98/ME/NT/XP using later versions of  Cygwin but we  do not provide any
guarantees.   Make sure your Cygwin  installation   has gcc, bison and
flex.   The default versions  of gcc,  bison  and flex  that come with
Cygwin 1.3.17 are   adequate. Make sure your  shell  is bash. This  is
normally  the default with Cygwin. Also  make  sure that MAGICDIR does
not  have any blanks  in it.   For example,  you can install  MAGIC in
"C:\magic"  but not in  "C:\Documents and Settings\bovik\magic".  Then
perform the following steps to compile and run MAGIC.

Step 1: Set  up the  MAGICROOT environment variable   to  be equal  to
MAGICDIR. Type:

$ export MAGICROOT=MAGICDIR

Step    2:   Set up    the     OSTYPE  environment  variable   to   be
"Windows_NT". Type:

$ export OSTYPE=Windows_NT

Step 3: Compile. Type:

$ cd MAGICDIR
$ make

Step 4: Make  sure that the   MAGICDIR/main directory is  in your path
since the "magic.exe" binary will be created there. Type:

$ export PATH=$PATH:MAGICDIR/main

The setting up of environment  variables in steps  1, 2 and 4 can also
be  done automatically either  from the  Windows  system utility or in
your Cygwin  .bashrc file.  On Windows  2000, you can start the system
utility  as  follows: Click on Start   ->  Settings ->  Control Panel.
Choose the "System" icon and double click.   In the new popup windows,
click on  the "Advanced" tab and  then the "Environment Variables ..."
button.  A new window for creating and modifying environment variables
will  pop up.  Alternatively,  add the  following  three lines to your
.bashrc file.

export MAGICROOT=MAGICDIR
export OSTYPE=Windows_NT
export PATH=$PATH:MAGICDIR/main

Note: The "magic.exe"  binary produced  on  Windows is  a native Win32
binary that can be run directly on any Win32 platform without the need
for Cygwin.  However  in order to  work properly, this binary requires
that the environment variable MAGICROOT be set up properly. Thus it is
preferable that you set up the environment variables using the Windows
system utility. This will make  these environment variables  available
even outside Cygwin, enabling "magic.exe" to be used without Cygwin.

#######################################################################
# Examples
#######################################################################

MAGIC comes  bunched  with a set of   simple examples to  help you get
familiarized with it quickly.  These examples can  be found inside the
"examples" subdirectory. They  consist of a set  of ".pp" and  ".spec"
files  that represent the input files  to MAGIC. In addition there are
two  files   called   "data.regress"   and   "data.ssl" that   contain
information on how to  run  these examples.  Each  line of these   two
"data.*" files  is actually   an  entry  describing one  example.  For
example here is a typical line from "data.regress".

mutex-lock-y-03 yes mutex_lock_03 mutex-y-01.c.pp mutex-lock-03.spec

The first token  (mutex-lock-y-03) is just a name  for  this entry and
has no special  significance.  The  second  token (yes) indicates  the
proper output  that MAGIC should give  if  everything is OK.   A "yes"
means that the property  in this example should  pass and a "no" means
that it should  fail. The third  token (mutex_lock_03) is  the name of
the abstraction that  is checked in  this example. The MAGIC  tutorial
(http://www.cs.cmu.edu/~chaki/magic/tutorial.html)   contains     more
detail about abstractions.  The last tokens are input file names.  For
example, the above example can be run with the following command line:

$ magic --optPred --abstraction mutex_lock_03 mutex-y-01.c.pp mutex-lock-03.spec

In general, given an entry in "data.regress" or "data.ssl" of the form
"A B C D E ...." (the dots indicate that  there could be more than two
input  file names)  the corresponding example  can  be executed by the
following command:

$ magic --optPred --abstraction C D E ...

#######################################################################
# Conclusion
#######################################################################

We  hope you will enjoy installing  and using  MAGIC.  Please send any
questions, comments  and  bug  reports to  chaki+@cs.cmu.edu.  For bug
reports, we  will  appreciate  as  much  additional  info  as possible
including, but not restricted to: (i) platform info - OS and processor
(ii)  command line  and  input files  that  trigger the bug  and (iii)
output showing the bug.

Thanks !!!

#######################################################################
# end of README
#######################################################################
