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.
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 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@
set CYGWIN=nodosfilewarningrem ---- 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
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!
rem add any additional classpath entries add here
cmd
To run the AHEAD tools on MacOSX, add the following to file .profile in your home directory:
# AHEAD tools
export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Home
export AHEAD_HOME=/usr/local/ahead
export ANT_HOME=${AHEAD_HOME}/miscellaneous/apache-ant-@ANTREL@
export JCC_HOME=${AHEAD_HOME}/miscellaneous/javacc
export PATH=${PATH}:${AHEAD_HOME}/build/bin:${JAVA_HOME}/bin:${ANT_HOME}/bin:${JCC_HOME}/bin
export CLASSPATH=.
2013. There is something wrong with Apache Ant 1.9.0. You'll get an error about "central directory" and "64-bit" errors in reading .jar files. The only solution to this, at this time, is to avoid using Ant 1.9.0.
2007. The following bugs also have disappeared recently, and I am retaining a discussion of it for history (as it seemingly took forever to track down). This section can be skipped.
The following bug is 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.
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).
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.
#!/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.
Warning. If you are running on a windows platform, there are build scripts that get very upset if the text files are in dos format. Before you build ATS, run the dosFix.script before the ant build:
fop/> bash dosFix.script
fop/> ant
// builds ATS
In fact, any script S you might need to run: >
bash dos2unix S
This may be due to a major release of Cygwin.
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).