# Instructions for Installing the AHEAD Tool Suite (ATS)

This is release @VERSION@ of the @PREFIX@ tool suite. There are different sets of instructions to follow for different platforms. Here are your options:

- Operating systems: Windows or Linux. Linux has the simplest instructions; Windows has additional requirements, which are indicated in blue in the instructions below.

Perform all non-highlighted instructions below and any highlighted instructions that are specific to your needs. If you don't have the required software, please install it before installing the AHEAD tool suite. The latest versions of these tools that are known to have worked with AHEAD are in red. We do not support backward compatibility with previous versions of these tools.

> 1. JDK (@JDKREL@) from http://java.sun.com/
> Don't forget to download the J2SE documentation, too.

> 2. Cygwin (@CYGREL@) from http://www.cygwin.com/

> > Note: when you install cygwin, make sure that you install gcc so that you can run the model checker tool of modelexplorer.

> 3. Ant (@ANTREL@) from http://jakarta.apache.org/ant/

Now, make sure that you have included the pre-requisite software in your PATH (or, on Windows, Path). You should be able to run the Java tools and Ant from the command line and, for Windows systems, you should be able to run CYGWIN commands from the command line.
If everything looks good, it's time to install the AHEAD tool suite. Please follow these instructions: (note: if you are reading this file, you may have already done steps 1-3).

> 1. Change directory to where you'd like to install the suite. The installation will create a sub-directory named @NAME@ which will contain the distribution.
> 2. Unpack the file that you downloaded, i.e.,

> > > unzip @NAME@.zip

> 3. You should now have a sub-directory named @NAME@ and it should contain the following files and sub-directories:

> > build/bin .... a directory with executable programs;
> > build/lib .... a directory containing jar files;
> > docs ......... a directory with documentation (read this!);
> > dsl .......... a directory in which to place layers/features;
> > equations .... a directory in which to place AHEAD equations
> > (this directory is presently empty)
> > miscellaneous. a directory in which to place other things;
> > README.html .. a copy of this file;
> > setperms ..... a script to set file permissions in @NAME@.

> 4. On Linux installations, change the permissions on your installation as follows:

> > sh @NAME@/setperms

> 6. Follow the instructions on either Windows Scripts or Linux Scripts.
> 7. Installation is complete.

In order to run the "@PREFIX@" tools, your PATH (or, on Windows, Path) setting must include the bin sub-directory from your @NAME@ installation, as well as the paths for the pre-requisite software. If this is the case, you're ready to go!
We strongly recommend reading the documentation in the docs sub-directory! A good starting point is the "index.html" file.

# Windows Scripts

By far the biggest problem in installation is getting the path and classpath variables right. Here is a DOS batch script that sets the path and classpath variables correctly. Of course, you will need to fill in the details. Keep reading, as there's more. REMEMBER: MAKE SURE THAT THE ACTUAL PATHS IN THE SCRIPT BELOW ARE CORRECT.

> @echo off
> rem ---- change the values of the following properties to reflect
> rem ---- your environment.

> set WIN_HOME=C:\WINDOWS\system32
> set JAVA_HOME=C:\Program Files\Java\jdk@JDKREL@
> set CYGWIN_HOME=C:\bin\cygwin
> set AHEAD_HOME=C:\Java\@NAME@
> set ANT_HOME=C:\Java\apache-ant-@ANTREL@

> rem ---- the following paths are computed from the above
> set JCC_HOME=%AHEAD_HOME%\miscellaneous\javacc
> set PATH=.
> set PATH=%PATH%;%AHEAD_HOME%\build\bin
> set PATH=%PATH%;%JAVA_HOME%\bin
> set PATH=%PATH%;%ANT_HOME%\bin
> set PATH=%PATH%;%JCC_HOME%\bin
> set PATH=%PATH%;%CYGWIN_HOME%\bin
> set PATH=%PATH%;%WIN_HOME%
> rem ---- after this point, you can add any additional path settings
> rem ---- here are the ones that I use, which of course, you should
> rem ---- replace or delete. Note: quoted elements in paths should
> rem ---- be the last in the list. bash makes this assumption!
> set CLASSPATH=.
> rem add any additional classpath entries add here
> cmd

### WARNING1: modelexplorer and ant

The following bug appears in running ModelExplorer, which seems to find incompatible versions of ant and prevents ModelExplorer from being used. It also appears in building ATS under bash. The fix is the following edit: cd to ANT_HOME/bin. Make the first few lines of ant.bat to be

@echo off
set classpath=

these edits make your classpath empty. The ant bash script will supply the correct files.

### WARNING2: javacc

The following bug also has disappeared recently, and I am retaining a discussion of it for history (as it seemingly took forever to track down). It is still a problem if you cannot run javacc under bash (see below for exact test). The problem involves strange interactions between bash (CYGWIN), Windows, and Java. The above batch file fixes all but one. If you have installed javacc, you will need to correct the %JCC_HOME%\bin\javacc file. Its contents as distributed is:

> #!/bin/sh
> java -classpath `dirname $0`/lib/javacc.jar javacc "$@"

Well, this doesn't work. You should change it to:

> #!/bin/sh
> java -classpath <full-path-to-javacc.jar> javacc "$@"

Where the <full-path> looks like c:/Java/javacc-@JCCREL@/bin/lib/javacc.jar

Without this fix, you can't invoke javacc from bash. That is, the following will execute javacc if you make the above changes, it won't otherwise:

> > bash
> > javacc
> <normal javacc marquee>

Now, go to final comments (click here).

### WARNING3: CYGWIN and base

Recent installations of CYGWIN do not install sh.exe, but do install bash.exe. You can tell you have a problem if you create a bash prompt, and cannot run ant, where you get an error message like:

bad interpreter: No such file or directory

Check your CYGWIN installation directory, and if sh.exe is not present, this is likely the problem. The fix is to install sh.exe using CYGWIN, and recently it has been listed in CYGWIN under the name ash (a Bourne Shell workalike).

There is one other work around: where ever bin/sh is referenced, you can replace it with /bin/bash. But this can only be a temporary fix.

# Linux Scripts

> #!/bin/sh/

> # ---- please set the correct paths on the variables below

> export JAVA_HOME=/usr/local/jdk@JDKREL@
> export AHEAD_HOME=/usr/local/ahead
> export ANT_HOME=/usr/local/apache-ant-@ANTREL@
> # ---- the following is preset
> export JCC_HOME=${AHEAD_HOME}/miscellaneous/javacc
> export PATH=${PATH}:${AHEAD_HOME}/build/bin
> export PATH=${PATH}:${JAVA_HOME}/bin
> export PATH=${PATH}:${ANT_HOME}/bin
> export PATH=${PATH}:${JCC_HOME}/bin
> # ---- after this point, you can add any additional path settings
> # ---- here are the ones that I use, which of course, you should
> # ---- replace or delete.
> export CLASSPATH=.
> # add any additional classpath entries add here

Now, proceed to the next and last section.

# Finally

Before you proceed, you must make sure that your classpath is set correctly. Virtually all of the problems in installation deal with incorrect classpaths. Here are the tests: make sure that you can run each of the following -- that is, you get a normal error output from the tool, as opposed to "there is no such tool". Try these tests in this order:

> javac |  | is javac working?
> javacc |  | is javacc working?
> ant |  | is ant working?
> gcc |  | is gcc working?
> jampack |  | is AHEAD working?
> bash |  | is bash working? (for windows only)
> javacc |  | is javacc working under bash (windows only)

ATS relies on Ant and CYGWIN only to a minimal extent. The ATS modelexplorer tool relies directly on Ant, but no other tool does. CYGWIN could be eliminated too, if absolutely necessary. For such details, contact Don Batory (batory@cs.utexas.edu).