Jacl

RCS: @(#) $Id: README.jacl,v 1.3 1999/03/02 15:23:47 hylands Exp $
 
1. Introduction
---------------

Jacl (which stands for Java Application Command Language) is a
platform independent scripting language for Java. The feature set and
functionality of Jacl are structured to mirror the scripting language
Tcl version 8.0. In addition to the write-once-run-anywhere
philosophy, Jacl provides it's user with two other key concepts.
First, Jacl enables users to write Tcl extensions entirely in Java.
Extension writers can use the classes supplied in tcl.lang.*, as well
as any other classes, to write portable extensions.  Second, Jacl
includes the Java Package, which provides a direct Tcl interface to
Java Objects.  For example, the Java Package contains a Tcl command,
java::info, that provides a Jacl user with information about the
public methods, fields, etc. of a given Java class or object.  The
Java Package enables the user to script Java.

2. Documentation
----------------

The best way to get started with Jacl is to look at the demos provided
in this release.  The "docs" directory contains additional
information.  See the "diffs.txt" file in this directory for a list of
Tcl features and the extent to which they are implemented in Jacl.
Also, look at the Scriptics Jacl and Tcl Blend page at
http://www.scriptics.com/java
for other useful information.


3. Requirements
---------------

The Jacl distribution requires the Java Development Kit 1.1 or
greater. Jacl has been tested on Win95, WinNt, Solaris, IRIX,
Linux, and Mac. It should work on any other systems that have
a correctly implemented Java VM.

Jacl 1.1.1 will run under JDK1.2fcs, see known_issues.txt for
a list of known problems and bugs.

4. Installation
---------------

If you have a binary release of Jacl, follow the instructions in the
INSTALL.txt file, located in this directory.

If you have a source release of Jacl, and you are compiling under
UNIX, change to the "unix" subdirectory.  If you are compiling under
Windows, then change to the "win" directory.  Then, for installation
instructions, see the README file in that directory.

5. License Agreement
---------------------

See the file "license.terms" for information on usage and 
redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.

6. Contact Information
----------------------

Jacl 1.0 was released by the now defunct SunScript group at Sun Labs.
The majority of the Jacl/Tcl Blend developers spun out of Sun Labs
into Scriptics.

Jacl 1.1.1 was developed primarily by people outside of Scriptics, with
assistance by Scriptics.  Currently, the Jacl is available
via the Scriptics CVS repository at
http://www.scriptics.com/software/netcvs.html


7. Tcl newsgroup
----------------

There is a network news group "comp.lang.tcl" intended for the exchange
of information about Tcl, Tk, and related applications.  You should
use this newsgroup to ask questions, give bug reports, or post fixes
for Jacl & Tcl Blend.   The developers of Jacl & Tcl Blend as well as
many avid users of Tcl Blend & Jacl use comp.lang.tcl as a forum.

8. Support and bug fixes
------------------------

Unfortunately, Scriptics, University of Minnesota and UC Berkeley
cannot offer direct technical support for Jacl and Tcl Blend.  We
prefer that you send bug reports and fixes to the comp.lang.tcl
newsgroup rather than to any one individually.  We'll see anything on
comp.lang.tcl, and in addition, someone else who reads comp.lang.tcl
may be able to offer a solution.

When reporting bugs, please provide a short Tcl script that we can use
to reproduce the bug.  Make sure that the script runs with bare-bones
Tcl and doesn't depend on any extensions or other programs,
particularly those that exist only at your site.  Also, please include
three additional pieces of information with the script:
    (a) How do we use the script to make the problem happen (e.g.
	what things do we click on, in what order)?
    (b) What happens when you do these things (presumably this is
        undesirable)?
    (c) What did you expect to happen instead?
    (d) What platform are you running on (Machine, OS, etc.)?
    (e) What releases of Tcl products are you using?

9. Regular expressions
----------------------

The regular expression features of Tcl are now available in the
binary version of Jacl.  We actually used a commercial regular
expression package from ORO, Inc.  While this resulted in our ability
to give you regular expression features months ahead of schedule, it
unfortunantly means we can't offer the same features in the source
release of Jacl.  If you would like to use the ORO regular expression
package with Jacl but you must have a modifiable source base you will
need to work out a deal with Sun and ORO.

Please note that there are certain differences between how Tcl regular
expressions are supposed to work and how the ORO package works.  As a
result some scripts that rely on certain regular expression
constructs will not be portable between Jacl and the C version of
Tcl.  It is our plan to eventually do a full port of the Tcl regular
expression package for complete compatibility.

Between the Jacl 1.0 release, and the Jacl 1.1.1 release, it looks
like ORO, Inc. went out of business.  Formerly, their website was
http://www.oroinc.com/

10. Using Jacl in applets
-------------------------

Currently there are many issues that make it difficult to run Jacl as
an applet inside popular web browsers:

a) For remote applets, both Netscape and IE disallow the
   introspection of class members.  This makes it impossible to use
   any of the following commands: java::new, java::call, java::prop,
   java::field, etc.

b) You can install Jacl as a local Java package on your machine to
   get around the restriction mentioned in (a), but then Netscape
   will not read any of the Jacl library scripts, such as init.tcl,
   because it does not allow your applet to read from local disks.

   (a) and (b) together make it difficult to run Jacl as either a
   remote or a local applet.

c) Netscape 4.0.x does not yet support the JDK 1.1 event model.  This
   makes it impossible to create event handlers for any AWT widgets
   created by the java::new command.

Due to these current difficulties, we have decided not to support the
use of Jacl inside applets.


The Jacl 1.0 & Tcl Blend 1.0 team at Sun Script
-----------------------------------------------

Ray Johnson - Project Manager
Melissa Hirschl
Ioi Lam
Bryan Surles
Special thanks to Scott Stanton who implemented Tcl Blend.


The Jacl 1.1.1 & Tcl Blend 1.1.1 team
---------------------------------
Mo DeJong (University of Minnesota)
Christopher Hylands (UC Berkeley)
John Reekie (UC Berkeley)
Bryan Surles (Scriptics)
