PLAN Installation Guide

This file contains a high level description of the PLAN software, how to install it, supported architectures, and contact information.

PLAN Software Components

The PLAN software consists of a group of Java 1.1 classfiles. There are essentially three modes of execution:
Router mode
essentially a daemon that runs on your machine, processing packets received from the virtual active network or users. If you plan to establish a semi-permanent router, please let us know so that we can add you to the routing tables of our base network.
Client mode
this mode allows you to inject an active packet into the virtual active network, and receive any output that results. Examples in the rout_tests directory may be run from this mode.
REP mode
(or Read-Eval-Print mode) this mode allows you to test non-network PLAN code by interactively typing in expressions to be evaluated and seeing their printed results. This is useful for verifying that code correctly parses, that expressions behave as you expect them too, etc. Examples in the interp_tests directory may be run in this mode.
There are two ways that you can install the PLAN software. You can simply obtain the class files and execute them directly, or you can obtain all of the source and build it yourself. Note that BOTH distributions contain all of the documents and the sample programs (i.e., all contained within the docs, interp_tests, and rout_tests directories). PLAN relies on ANEP, the Active Network Encapsulation Protocol. See the contact information below for more. The source code for ANEP is provided with the PLAN distribution.

Source installation

PLAN was built using a number of publicly available packages. They are:
  1. JDK 1.1.x -- Java Development Kit
    Sun's site: http://java.sun.com/products/JDK/index.html
    We used the third-party Linux port, available via: http://www.blackdown.org/java-linux/Mirrors.cgi
  2. Pizza, a Substantial Companion to Java, version 0.39
    http://www.cis.unisa.edu.au/~pizza/
  3. JavaCC, the Java Compiler Compiler, version 0.6.1
    This is no longer available at http://www.suntest.com/JavaCC/index.html, you can get it here.
(*Note: JavaCC is only needed if you change the grammar file, Parser.jjt, in any way. Otherwise, the .java files provided in the distribution will serve)

You must first install all of these packages. Please follow the installation instructions given at each of the sites.

Next, unpack all of the PLAN source. For a UNIX platform, you should have obtained PLAN-java-2.1-src.tar.Z. This can be unpacked simply by doing 

    uncompress PLAN-java-2.1-src.tar.Z
    tar -xvf PLAN-java-2.1-src.tar

Note that these operations should be performed in the directory that you would like the source to be unpacked. This shall hereafter be referred to as the ``top level directory.'' This will create 3 directories: ``PLAN'' which contains the PLAN source (this directory shall hereafter be referred to as the ``PLAN directory''), ``ANEP'' which contains the ANEP source, and ``Log'' which contains code for a logging facility used by both ANEP and PLAN.

For Windows, you should have obtained PLAN-java-2.1-src.zip. This may be unpacked with PKzip, or WinZip, or a compatible utility.

Building

The first thing that you must do is make the ANEP and Log packages which PLAN relies on. To build the ANEP package, go to the ANEP directory and read the README file which contains building instructions. For the Log package, simply go to the Log directory and type "javac Log.java" (which assumes the java compiler javac is in your PATH). Now you may build PLAN:

Using make (UNIX, some Windows systems)

The easiest way to build the software is to use the provided makefile. Simple type ``make'' from within the PLAN directory.

This Makefile assumes a couple of things:

Note that when making for Windows, you should make sure that the cleanup.bat file is being invoked, rather than the cleanup shell script (see the Makefile for more details).

Building without make (Windows)

If you don't have access to make and are running DOS/Windows, do the following:

  1. type ``jjtree Parser.jjt''. This will build the Parser.jj file.
  2. type ``cleanup''. This will execute the cleanup.bat script which removes some automatically generated files.
  3. type ``javacc Parser.jj''. This will create the necessary .java files.
  4. type ``build''. This will actually compile all of the .java and .pizza files.
If you modify any of the .pizza or .java files, but do not change the Parser.jjt file, you can safely rebuild the system using only Build.bat.

These instructions assume that the Java and JavaCC executables are in your PATH; particularly java, jjtree, and javacc. In addition, your CLASSPATH must be set up properly to include the JavaCC and Pizza libraries, as indicated in the installation documentation for those packages. Finally, the PLAN, ANEP, and Log packages must also be in your CLASSPATH. This amounts to adding the top level directory of the PLAN distribution to your CLASSPATH (not the PLAN directory, but the directory that it resides in).

Classfile Installation

If you are not interested in acquiring the source code, you can instead just obtain the class files and use those directly. However, you will still need to install the Pizza distribution (see above), since the PLAN code relies on some of the provided Pizza class files. You will not need to install JavaCC.

For UNIX, you should have obtained PLAN-java-2.1.tar.Z. To unpack this file: 

    uncompress PLAN-java-2.1.tar.Z
    tar -xvf PLAN-java-2.1.tar
Note that these operations should be performed in the directory that you would like the source to be unpacked. This shall hereafter be referred to as the ``top level directory.'' This will create 3 directories: ``PLAN'' which contains the PLAN classes (this directory shall hereafter be referred to as the ``PLAN directory''), ``ANEP'' which contains the ANEP classes, and ``Log'' which contains code for a logging facility used by both ANEP and PLAN.

For Windows, you should have obtained PLAN-java-2.1.zip. This may be unpacked with PKzip, or WinZip, or a compatible utility.

You are now ready to execute the PLAN software. Please see the tutorial document for specific instructions.

(*Note: your CLASSPATH must be set up properly to include the Pizza library class files, as indicated in the installation documentation for that package. It must also include the PLAN, ANEP, and Log packages. This amounts to adding the top level directory of the PLAN distribution to your CLASSPATH (not the PLAN directory, but the directory that it resides in)).

Contact Information

PLAN Home Page: http://www.cis.upenn.edu/~switchware/PLAN

ANEP Home Page: http://www.cis.upenn.edu/~switchware/ANEP

Please send bug reports, comments, and suggestions to:
   PLAN-bugs@dsl.cis.upenn.edu

There are also two mailing lists related to PLAN:
PLAN-disc@dsl.cis.upenn.edu (general discussion about PLAN)
PLAN-announce@dsl.cis.upenn.edu(bug fixes, new releases, etc.)
To be put on one or both of the mailing lists, please send mail to:
   PLAN-request@dsl.cis.upenn.edu

Supported Architectures

This version of the PLAN interpreter has been tested on Because PLAN is built from Java, we expect it to be fairly portable. If you are able to use PLAN successfully on other architectures, please let us know, and we can add them to this list.
Unless otherwise stated, all software and documents at this site are:
© Copyright 1997, The SwitchWare Project
Maintained by: PLAN-maint@www.cis.upenn.edu