Jacl

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. 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. Jacl also includes a
compiler named TJC (Tcl to Java compiler) that converts Tcl to
Java bytecode that is executed directly in the JVM.

Jacl 1.4 is considered stable (only bug fixes will be applied
going forward) and is considered ready for evaluation in production
environments.

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

The Tcl/Java project website includes a getting started page that
provides a good intro to interacting with Java from Tcl. The website
can be viewed locally by opening docs/website/index.html in a web
browser, or online at the following URL:

http://tcljava.sourceforge.net

The "New Features" page describes features and functionality
added to a specific Tcl/Java release.

docs/Topics/WhatsNew.html

One can also find demos included in this release that provide
examples of how to integrate Tcl and Java. The manual page
at docs/website/manual.html provides a useful API reference.

See the "diffs.txt" file in this directory for a list of
Tcl features and the extent to which they are implemented in Jacl.

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

Jacl requires JDK 1.4 or newer and has been tested on a
Win95, WinNT, Solaris, IRIX, and Linux systems. It should
also work on other systems that have a correctly implemented
Java VM. Jacl has been tested on JDK 1.5. See the
known_issues.txt file for a list of known problems.

4. Build/Installation
---------------

A unified build system that works under both Unix and Windows
is used to build Jacl. Build instructions are located here:

docs/Topics/BuildJaclUnix.html

or

docs/Topics/BuildJaclWin.html

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. Getting Help
----------------

Users of Tcl Blend or Jacl should subscribe and post questions
to the tcljava-user mailing list at SourceForge. This mailing
list provides a forum to ask questions or post scripts that are
causing you trouble. Basically, any Jacl or Tcl Blend related
question is on topic for this mailing list.

http://lists.sourceforge.net/lists/listinfo/tcljava-user

There is also a mailing list for Jacl and Tcl Blend developers.
If you have a specific question about some implementation feature,
have a patch for Jacl or Tcl Blend, or are interested in implementing
some feature, then you should post a note to the developers
mailing list.

http://lists.sourceforge.net/lists/listinfo/tcljava-dev

Note that you will have to subscribe to the mailing lists before
posting to them. Some people think this subscription requirement
is somehow "unfriendly", but without it the mailing list would
be full of spam. It only takes a moment to subscribe and you
can unsubscribe at any time. Posts from users that are not subscribed
to the mailing list will be automatically rejected.

In addition to the mailing lists, you can ask about Jacl or Tcl Blend
or on the Tcl newsgroup. The network news group "comp.lang.tcl"
intended for the exchange of information about Tcl, Tk, and
related applications. It can also be useful to do a google groups
search on comp.lang.tcl for Jacl or Tcl Blend related questions.

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
these 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?
    (d) What platform are you running on (Machine, OS, etc.)?
    (e) What releases of Tcl products are you using?

7. 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.

For these reasons, Jacl does not work in applets and will not
be supported.

8. Development History
----------------------

Jacl 1.0 was released by the now defunct SunScript group at
Sun Labs. Newer versions of Jacl have been developed by Mo DeJong.

