Getting Started With FLEX

Here are the steps for setting the configuration files and having the Flex infrastructure running on your machine. There are instructions for using Flex sources or binaries downloaded from the web (Flex home page), or for using the CVS archive on flex-cvs.csail.mit.edu.

You can either download the highlighted files, or you can alternatively click the files, then cut and paste to the appropriate .rc file (for configuration files) or run the commands (for the checkout).

0. Decide what version of FLEX you want.

If you grab sources/binaries from the web, make sure you are getting the proper version of FLEX. If you fetch FLEX using CVS, then the following CVS tags correspond to released versions of FLEX:

CVS BUG ALERT: Using HEAD as a tag in CVS doesn't actually work correctly. If you want to check out the HEAD release of FLEX from CVS, substitue '-A' for '-r HEAD' in any CVS command you use.

1. Using FLEX sources/binaries downloaded from the web

You can download either the FLEX sources and compile them or you can directly download the compiled sources. Both FLEX sources and binaries are available on the web from the FLEX home page.

• If you download the FLEX binaries (and not install the sources), add the downloaded Harpoon.jar file to your CLASSPATH by including the following command to your .cshrc (or .bashrc):
  • For csh:  setenv CLASSPATH Harpoon.jar:$CLASSPATH
  • For bash:  export CLASSPATH=Harpoon.jar:$CLASSPATH

  Then skip to step 5. You will need JDK 1.2 for this to work.

• If you download the FLEX source archive (and not use CVS access), get the harpoon.tgz file from the FLEX home page, and then do:

  Commands:

  mkdir -p Harpoon/Code cd Harpoon/Code tar xzvf harpoon.tgz

  Then skip to step 4.

• Otherwise, if you are going to use CVS access to FLEX, continue to step 2.

2. Setting up the configuration files

• (required) Configure the remote-shell and editor settings of CVS.

  For csh:	setenv CVS_RSH ssh setenv CVSEDITOR emacs
  For bash:	export CVS_RSH=ssh export CVSEDITOR=emacs

  Effects: sets the CVS environment variables for remote shell and editor.

  Add these statements to your ~/.cshrc or ~/.bashrc file (respectfully) so that these variables are set every time you log-in.

• (may be required) It's a good idea to make sure the CLASSPATH environment variable is set to something sane. Unfortunately, the details are a bit arcane and vary for each java installation. Something roughly similar to the following should be in your ~/.cshrc or ~/.bashrc file:

  For csh:	setenv JAVA_HOME <path to your JDK installation> setenv CLASSPATH .:$JAVA_HOME/lib/rt.jar
  For bash:	export JAVA_HOME=<path to your JDK installation> export CLASSPATH=.:$JAVA_HOME/lib/rt.jar

  Effects: sets the CLASSPATH environment variable.

• (optional) Append the cvsrc file to your .cvsrc:

Command: cat cvsrc >> ~/.cvsrc

Effects: Sets default flags for cvs commands.

• (optional) Install the JDE java development environment for emacs.

  For the FLEX emacs JDE-mode customizations to work properly, the path to the harpoon sources must end with Harpoon/Code. If you follow our suggestion that your source be placed in ~/Harpoon/Code you will have no problems.

  • If you are running a debian system use the command
    apt-get install jde
  • If you are local to LCS append the emacsrc.jde file to your .emacs:

  Command:  cat emacsrc.jde >> ~/.emacs

  Effects: sets up emacs JDE mode.

  Notes: If you are not working on lesser-magoo.lcs.mit.edu, then you have to copy the directory lesser-magoo.lcs.mit.edu:/home/cananian/lib/emacs to your machine as ~/lib/emacs. Then modify the above emacsrc.jde file by replacing the 3 references to Scott's ~/lib/emacs with references to your ~/lib/emacs.

• (optional) Tweak emacs modes and colors by appending the emacsrc file to your .emacs:

Command:  cat emacsrc >> ~/.emacs

Effects: sets emacs modes and colors.

3. Using FLEX sources from the CVS archive on flex-cvs.csail.mit.edu

CVS BUG REMINDER: Using HEAD as a tag in CVS doesn't actually work correctly. If you want to check out the HEAD release of FLEX from CVS, substitue '-A' for '-r HEAD' in any CVS command you use.

• (Requires an account on flex-cvs.csail.mit.edu) For read/write access, run the script first-cvs-checkout (or just run the few commands from it) to get the FLEX sources:

  Commands:

  cd test -d Harpoon || mkdir Harpoon cd Harpoon cvs -d :ext:flex-cvs.csail.mit.edu:/data/cvs checkout -r <cvs tag> Code

  Effects: checks out the FLEX distribution from flex-cvs.csail.mit.edu to your machine in ~/Harpoon, with read-write access.

  Notes:  This will invoke ssh (since CVS_RSH is set to ssh in the previous step) to check out from a different machine. Also, if your username is different on the two machines, then go in the first-cvs-checkout file and replace `:flex-cvs.csail.mit.edu:' with `:<your username>@lm.lcs.mit.edu:'. Read info cvs -> Repository -> Remote Repositories for more information on how this works.

• For anonymous read-only access to the source archive, run the script anon-checkout to get the FLEX sources:

  Commands:

  cd test -d Harpoon || mkdir Harpoon cd Harpoon cvs -d :pserver:cvsguest@flex-cvs.csail.mit.edu:/data/cvs login cvs -d :pserver:cvsguest@flex-cvs.csail.mit.edu:/data/cvs checkout -r <cvs tag> Code

  Effects: checks out the FLEX distribution from lesser-magoo.lcs.mit.edu to your machine in ~/Harpoon, with read-only access.

  Notes: Use 'cvsguest' as your password when prompted; you should only have to enter this once. The code is checked out using the pserver protocol, read-only. Read info cvs -> Repository -> Remote Repositories for more information on how this works.

4. Compiling the sources

• Run GNU make from ~/Harpoon/Code to build the class files:

Command:  cd ~/Harpoon/Code && make

Effects: Builds the class files in ~/Harpoon/Code/harpoon

Notes: Here you definitely need gmake (GNU make) version 3.77 or later, not some other make. The command make --version should tell you what version of make you have. On some machines, GNU make may be named gmake. (Version 3.77 of make is needed due to the use of target-specific variables.)

5. Installing GNU Classpath

Although this is not required to use FLEX for analysis, if you wish to compile executables with FLEX you will need to install the GNU project's implementation of the Java standard class libraries. Information on how to do so is on its own page.

6. Testing everything went OK

• Try to run something:

Command:  java harpoon.Main.Main harpoon.Main.Main

Effects: Converts the harpoon.Main.Main class to the FLEX intermediate representation, and pretty-prints it.

7. Doing more

You probably want to go on now to checkout and build the Runtime which will walk you through the steps to build an actual running executable from a Java program. Be sure to read the README and REQUIRED files in the Runtime module. If you selected FLEX version 3.2 or later in step 0, then you probably also want to read this information on getting and using the GJ compiler in order to be maximally productive.

Finally, if you're interested in working with our Real-time Java implementation, you will want to go on to install and build the Realtime code.

Verbatim copying and distribution is permitted in any medium, provided this notice is preserved.

cananian HTML Last updated: 21 July 2003