
These install notes are grouped in three parts.
The first part is what is necessary to have a machine
ready environment. In other words, it is about what software
is necessary for running. The second part is the CVS repository
structure and which module is what. The third part is actually 
how to get the Tomcat/Jasper environment with a line debugger
hookup. This works from two IDEs, VAME 1.4 and Eclipse.
I would suggest Eclipse for it has CVS support and also 
it represents the future of VAME anyway.

Note: these instructions were originally written for use with Windows;
builds are analagous for *NIX with the following exception: Eclipse
(http://www.eclipse.org) may not be available for your platform, so
builds are done using Ant (1.4.1) from the command line).

PART I 
------------

1) Install Sun JDK 1.3.1. 

I put it under c:\jdk1.3.1. 
I believe you can install it someplace else because
the scripts are using the JRE which get automatically
installed some under c:/Program Files/...

2) Install Eclipse (or Ant), I use the JDK version, version 0.9.

3) Your favorite Java environment for command line...
    so that you will be able to modify Tomcat/Jasper...
    I use Emacs/CygWin Unix Emulation/JDE under 
    Emacs...
    
PART II
------------

CVS repository has the following structure so far.

	bsf, the BSF 2.3 version. 
	    	I already checked in my debug-aware release.
		
	bsf_debug, this is the JavaScript Debug Interface (JSDI).
		It has no dependency on BSF.
		It is used by BSF though, so it needs to be on BSF project 
		build path.
		For now, it is important to get it separate.
		The reason is that it allows to control what the RMI registry
		is allowed to download code from.
		In bsf_debug, there is the JSDI classes and the 
		RMI stubs & skeletons generated by rmic.

	jsdb, this is the line debugger.
		It needs bsf_debug in its build path.

	scripts is the set of scripts necessary to get stuff running
	
		Policy files for the debugger & tomcat
		Starting scripts for the line debugger and tomcat
		Also a script for building RMI stubs.
		
		Other files as well such as this INSTALL NOTES 
		and a ToDo file as well.

PART III: Getting it to run...
-------------

Once Tomcat/Jasper is there, it is time to get the scripts and put
them somewhere. It will be your working directory.

Then, time to start Eclipse...
Open the repository perspective... and connect to the server
by clicking on the repository tab and then right-cliking in the pane.
Enter all the information about CVS repository. 

Once logged-in, you will see a view of the repository with 
	Project Versions
	Streams
	
Under streams, you will see all the CVS modules.
By right-clicking them, you will be able to add them to your Workspace.
Add the following:

		- bsf
		- bsf_debug
		- jsdb
		- scripts
		
Once done that, make sure the build path are ok.
Do this by right-clicking on the project in the Navigator pane,
select properties...

		- bsf depends on bsf_debug and rhino (or other languages)
		- jsdb depends on bsf_debug
		
Then, everything should compile fine but for all engines under
BSF, other than javascript one.

Note: *NIX users may choose to build from the command line using Ant.

Now you are about to start executing. 

If this does not work for you, you can change the port,
but you will have to go in e_jsdb.bat and e_jakarta.bat
to change the variable VAME_PORT to whatever you chose
the port to be. The default is 4444.

You will need two command shell windows... one for the 
Tomcat/Jasper and one for the line debugger.
The e_jsdb.bat and e_jakarta.bat are scripts to respectively
start the line debugger and the jakarta server.

YOU NEED TO GO EDIT THE VARIABLES AT THE 
START OF THOSE BAT FILES.

Note: there are also e_jsdb.sh and e_jakarta.sh for *NIX.

When the line debugger starts it attempts to find the Debug 
Manager... it will loop until it does.

When Tomcat starts... it does nothing.
You have to hit a JSP using BSF for BSF to register its debug
manager. 
Currently, the example calendar is modified to do a bunch of 
JavaScript.... so go on hit that one at //localhost:8080/...

Once this is done, you should see that debugger prompt "<"
The left-angled bracket shows you that the debugger is ready 
for input but it is not in a callback from the server. 
When showing a right-angled bracket, the debugger is responding
to a callback, typically a breakpoint has been hit or a stepping command
has returned. More commands work in callback mode.

Type "usage" to see the potential commands...

Load a JSP... 

	< load /examples/jsp/cal/cal1.jsp

Then, set a breakpoint 

	< br cal1:17

Check everything is ok throug

		< list breakpoints
		< list buffers
	
Then, go it refresh in your browser on the calendar page...
The debugger will be now be in callback mode and other 
commands are possible.
Try

		list frames
		show frame
		show object
		list
		up / down with list


POLICY FILES...

   BSF.POLICY
   ----------
   bsf.policy which is the policy file taken if there is no
   security manager. 

   Make sure the first grant reflects a root directory for the 
   hierarchy where all the bsf & rhino code is. The first grant
   grants all permission to code from BSF and scripting languages. The second
   grant is for the Tomcat and Jasper.

	grant codeBase "file:/${bsf.home}/-" {
		permission java.security.AllPermission;
	};
	grant codeBase "file:/${catalina.home}/-" {
		permission java.security.AllPermission;
	};

   Also, make sure the socket range includes the socket for the 
   rmiregistry... otherwise, no connection will be possible to register
   the debug manager.

	grant {
    		permission java.net.SocketPermission "*:1024-65535",
        		"resolve,connect,accept,listen";
	}

   Also, make sure there is enough permission for loading the BSF/scripting 
   language stubs/skeletons for the BSF_DEBUG_SERVER.

	grant {
    		permission java.io.FilePermission
        		"c:\\Eclipse\\jakarta\\Caches\\Target\\-", "read";
	}

   CATALINA.POLICY
   ---------------
   It is the standard TOMCAT policy found ~tomcat/dist/conf/catalina.policy
   with added permissions for BSF/Rhino code

	grant codeBase "file:/${bsf.home}/-" {
		permission java.security.AllPermission;
	};
	grant codeBase "file:/${catalina.home}/-" {
		permission java.security.AllPermission;
	};

