source: CIVL/INSTALL@ eba7953

                    CIVL Installation Instructions

------------------------- Binary Distribution -------------------------

For most users, this will be the easiest way to install and use CIVL.

1. Install a Java 7 SDK if you have not already.  Go to
http://www.oracle.com/technetwork/java/javase/downloads/ for the
latest from Oracle.  On linux, you can optionally sudo apt-get install
openjdk-7-jdk.

2. Download the approrpriate complete binary distribution from
http://vsl.cis.udel.edu/civl.  

3. Unzip and untar the downloaded file if this does not happen
automatically.  This should result in a folder named
CIVL-TAG, where TAG is some version id string.  This folder
contains the following:

 - README : this file
 - bin : containing one executable sh script called "civl"
 - lib : containing civl-TAG.jar and native libraries
         used by CIVL
 - doc : containing some documentation about CIVL
 - licenses : licenses for CIVL and included libraries
 - examples : some example CIVL programs

4. For OS X, move the CIVL-TAG folder into /Applications.  For
linux, move it into /usr/local.

5. Put the civl script in your path however you like to put things
in your path.   Either move it to a directory in your path,
or create a symlink to it, or edit your .profile or equivalent
to put it in your path.

Now you should be able to run CIVL from the command line by 
typing "civl <filename>".  Type just "civl" for usage information.

------------------------- Source Installation -------------------------

We recommend using the Eclipse IDE for Java/EE developers.

1. Install prerequisite projects ABC, SARL and GMC. 
   Make sure that the three projects are put in the workspace
   directory where CIVL will be put. 

        a. Install the C front-end ABC, http://vsl.cis.udel.edu/abc,
           following the instructions in its INSTALL file for Eclipse
           installation.  This should result in a project named ABC
           in your Eclipse workspace.  Build the abc.jar from within
           Eclipse by right-clicking (or ctrl-clicking on OS X) on the
           build.xml file and selecting Run As->Ant Build.
        
        b. Install the symbolic algebra and reasoning library SARL,
           http://vsl.cis.udel.edu/sarl, following the instructions in
           its INSTALL file for Eclipse installation.  This should
           result in a project named SARL in your Eclipse workspace.
           Build the sarl.jar from within Eclipse by right-clicking (or
           ctrl-clicking) on the build.xml file and selecting
           Run As->Ant Build.

        c. Install the generic model checking utilities package GMC,
           http://vsl.cis.udel.edu/gmc in Eclipse.  This one is pure
           Java, so is easy.  This should result in a project named GMC
           in your Eclipse workspace.  Build the gmc.jar from within Eclipse
           by right-clicking (or ctrl-clicking) on the build.xml file and
           selecting Run As->Ant Build.

2. From within Eclipse, select New Project...from SVN.  The archive is
svn://vsl.cis.udel.edu/civl.  After entering that, open it up and
select the "trunk". (It is simplest to just check out the trunk for
the Eclipse project.)

3. Check out the trunk, and create the project using the New Java
Project Wizard as usual, naming it "CIVL".  The .project, .classpath,
and other Eclipse meta-data are already in the SVN archive, saving you
a bunch of work.

4. Download the tgz archive of VSL dependencies from 
   http://vsl.cis.udel.edu/tools/vsl_depend,
   choosing the right .tgz according to your platform:
        
        vsl_linux32-1.0.tgz     - 32-bit linux
        vsl_linux64-1.0.tgz     - 64-bit linux
        vsl_osx64-1.0.tgz       - 64-bit osx
        
   Unzip the .tgz file and you will have the folder vsl.
   Move vsl to /opt (you might need to use “sudo” for this.
   Also, if you don't already have a directory called /opt, 
   you will have to create it with mkdir /opt).

   Suppose that you put the .tgz file (or .tar file if your browser
   unzipped it automatically to a .tar file) in the directory $Download.
   You can use the following commands:

                $ cd $Download
                $ tar xzf YourTgzOrTarFile vsl
                $ sudo mv vsl /opt

   Now you can type "ls /opt/vsl", and the output should be

                README.txt    lib        licenses    src

5. Create a file build.properties in the directory where build.xml is in.
   Copy and paste the content from properties/build.properties.osx or 
   properties/build.properties.linux depending on your platform.
   If your workspace directory is the default setting of Eclipse, 
   i.e., HOME/Documents/workspace for osx or HOME/workspace for linux, 
   then you dont have to anything.
   Otherwise, you need to edit the entry "workspace" to point to the
   corresponding directory where you put the projects ABC, SARL and GMC.

6. Navigate to Preferences -> Java -> Build Path -> ClassPath 
   Variables, and then select “New…” to create a classpath variable VSL, 
   and specify its value to be /opt/vsl. Navigate to Preferences -> Run/Debug 
   -> String Substitution -> New…, and then define an entry vsl_lib and 
   set its value to be /opt/vsl/lib.

7. Do a clean build.  Everything should compile.  Generate the civl.jar
   by right-clicking (or ctrl-click on OS X) the build.xml file and
   Run As->Ant Build.  

8. Go to Run->Run Configurations.... Create a new JUnit configuration.
   Name it CIVL Tests. Select "Run all tests in the selected project..."
   and navigate to the folder "test" in the CIVL project.
   The Test runner should be JUnit 4. Under the Arguments tab, type
   "-ea" (without the quotes) in the VM arguments area (to enable assertion
   checking). Under the Environment tab, create an entry 
   DYLD_LIBRARY_PATH (OS X) or LD_LIBRARY_PATH (linux), 
   specify its value by clicking Variables… and choose vsl_lib from the list, 
   or you may type ${vsl_lib} in the value entry.

9. An example of how to set up a single test from within Eclipse:
   create a new Run Configuration via the Run->Run
   Configurations... menu.  Create a new "Java Application"
   configuration.  Call it "CIVL barrier2".  The Project is CIVL.  The
   main class is edu.udel.cis.vsl.civl.CIVL.  Under the Arguments tab,
   set the Program arguments to "examples/barrier2.cvl" (without the
   quotes).  Modify the VM arguments and the Environment as in the step
   above.  You should now be able to run the test by clicking "Run".