Getting Started with LAPIS

Getting Started with LAPIS

1. Get an Account

Get a graphics account from Rob. You'll get your account information by email. Make sure you can log into your graphics account by ssh'ing to graphics.lcs.mit.edu:

	ssh graphics.lcs.mit.edu

Change your graphics password immediately.

2. Get the Tools

Collect the tools you need to compile LAPIS. These tools are already installed on the graphics lab workstations, but you may need to adjust your search path to point to them, by following the instructions below. If you want to compile LAPIS on Athena or your home machine, you may need to download these tools and install them locally.

Java JDK 1.4

On the graphics lab workstations, Java 1.4 can be found either under /usr/java or /usr/java2 (unfortunately it's in different places on different machines). Put its bin directory on your PATH, and test that you can run it with:

	java -version

ANT 1.5

ANT is the build tool we use. On the graphics lab workstations, ANT can be found in /j6/lapis/tools/jakarta-ant-1.5.1. Put its bin directory on your PATH, and test that you can run it with:

	ant -version

Eclipse 2.1 (optional)

A number of people in the LAPIS group like using Eclipse to develop Java code, since it includes CVS access, a source-level debugger, and some nice code refactoring support. Eclipse runs on Linux and Windows, but not on IRIX.

If you prefer to use Emacs or some other editor for now, skip the Eclipse instructions.

To start Eclipse on Linux:

(a) Put /j6/lapis/tools/eclipse on your PATH.

(b) cd ~ to go your home directory (or wherever you want Eclipse to store your workspace). Always start Eclipse from this directory, because it stores the state of your project in a subdirectory called workspace. If you start Eclipse from the wrong place, it won't be able to find workspace in the current directory, and it will (unhelpfully) create a new one.

(c) Run eclipse.

To start Eclipse on Windows:

(a) If you're using a Windows box in the graphics lab, you must first connect to the network drive containing Eclipse. Open a Windows Explorer window, choose Tools / Map Network Drive, and map a drive letter to \\picture\j6.

(b) Create a shortcut to the Eclipse executable (right-click on the desktop, then New Shortcut). The Eclipse executable is located at Y:\lapis\tools\eclipse-win32\eclipse.exe (assuming you mapped the j6 network drive to Y:). On your home machine, of course, the location would be different.

(c) Bring up the properties for the shortcut and change its Start In: directory to %HOME%, your home directory. (You have to do this so that Eclipse puts your workspace in your home directory, rather than the public tools directory.)

(d) Run the shortcut.

Cygwin (optional)

If you want to develop LAPIS on a Windows machine, and you don't want to use Eclipse, you'll have to install CVS and ssh on your Windows box. The easiest way to get them is by installing Cygwin. When the Cygwin installation lets you select which packages you want to install, make sure you pick both cvs and ssh.

3. Check out LAPIS from CVS

Eclipse instructions

If you're running Eclipse, follow these instructions to check out LAPIS into your Eclipse workspace.

(a) Go to Window / Show View / Other... In the dialog box, open CVS, select CVS Repositories, and click OK.

(b) The CVS Repositories pane will appear in the upper left corner. Right-click on it and select New Repository Location.

(c) Fill in the following entries:

Host: graphics.lcs.mit.edu
Repository path: /j6/lapis/cvs
User: your graphics account user name
Password: your graphics account password
Connection type: extssh

Then click Finish.

(d) Open :extssh..., then open HEAD, then select lapis. Right-click on it and select Check Out As Project.

Command-line instructions

If you're not running Eclipse, follow these instructions to check out LAPIS.

(a) Set your environment variables to point to the CVS repository. On a graphics workstation, use:

	setenv CVSROOT /j6/lapis/cvs

For remote access from Athena or home, use:

	setenv CVSROOT graphics.lcs.mit.edu:/j6/lapis/cvs
	setenv CVS_RSH ssh

(b) Check out LAPIS using:

	cvs checkout lapis

4. Compile LAPIS

Eclipse instructions

If you're using Eclipse, LAPIS is compiled automatically when you check it out, and whenever you make an edit. At first, you'll probably see hundreds of warnings that we haven't eliminated yet. You can disable the warnings for now using Window / Preferences / Java / Compiler.

Command-line instructions

If you're not using Eclipse, you need to compile LAPIS with ANT:

	cd lapis
        ant

Here are some useful ant options:

ant all compiles all source files if any of them have changed (this is the default if you just say ant)
ant swing compiles entire lapis.swing package if any of it has changed
ant lapis compiles all lapis packages except lapis.swing if any of them have changed
ant clean deletes all class files.

When you want to do a total recompile, use ant all, or just ant. If ant all isn't fast enough to use all the time, then use or ant swing or ant lapis instead, depending on whether you're working on UI code or infrastructure code.

5. Run LAPIS

Eclipse instructions

Command-line instructions

From your lapis directory:

	bin/lapis

Eclipse Plugin instructions

To run LAPIS as an Eclipse plugin, follow these steps.

(a) Switch to Java editing perspective (Window / Open Perspective / Java).

(b) Click on lapis in the Package Explorer to make it the active project.

(c) Select Run / Run... to bring up the Run dialog.

(d) Select Run-time Workbench and click New to make a new run configuration.

(e) On the Arguments pane, fill in the following entries:

Name: LAPIS Plugin
VM arguments: -Dlapis.dir=your lapis directory

(f) On the Plug-ins and Fragments pane, select "Choose plug-ins and fragments to launch from list", then make sure all the plug-ins and fragments are selected.

(g) Click Run. Eclipse will run another copy of itself, with the LAPIS plugin installed.

(h) If the LAPIS pane isn't already showing in the new Eclipse window, open it up (Window / Show View / Other / Other / LAPIS Pane).

(i) At present, the LAPIS pane only works with the XML editor. If you don't have a project in the new Eclipse window, create a simple project (File / New / Project / Simple). Then create a new XML file (File / New / File / foo.xml). Type or copy some text into it. Then write a pattern in the LAPIS pane, click GO, and look at what's highlighted.

6. Read about LAPIS coding conventions

Read our coding conventions guide for an overview of the LAPIS packages and a guide to how to develop new LAPIS code.