==================
| TclBlend Shell |
==================

+----------------+
| How to compile |
+----------------+

There are 3 patches and 2 new files in this package to create a Java based
shell for TclBlend.  The patches are for

      src/tclblend/tcl/lang/Interp.java
      src/tclblend/tcl/lang/Util.java
      unix/Makefile.in

in the TclBlend source distribution.  The two new files are:

      src/tclblend/tcl/lang/Shell.java
      src/tclblend/tcl/lang/ConsoleEvent.java

After applying the patch and adding the new files to the TclBlend source
distribution, run "configure" and "make" as usual to compile TclBlend.

The TclBlend shell can be started by typing:

    java -classpath $CLASSPATH tcl.lang.Shell

CLASSPATH environment variable should include to "tclblend.jar" and
"tcljava.jar".

+--------------+
| Dependencies |
+--------------+

The patch can be applied directly to the current TclBlend source from the
Scriptics CVS repository.

However, one should also apply the TclBlend patch mentioned in bug report
#4352.  Without the patch in #4352, the TclBlend shell will crash upon startup.

If one wants to use JDK 1.2.2+, it is highly recommended that Tcl 8.3 is used
with TclBlend.  There is one known bug in Tcl 8.2 that will cause the JDK to
core dump after one issues a "exec" call in the Tcl script.

+--------------+
| What it does |
+--------------+

In the original TclBlend distribution, the user starts with a regular "tclsh"
or "wish" native program running a native Tcl interpreter.  Then using "package
require java", the native shell loads a JVM into the shell's address space.
After that, the user can execute Java based Tcl commands in the JVM in the
shell.  The execution sequence is:

    native Tcl interp ->
        load TclBlend ->
            load JVM ->
                execute TclJava commands

For Jacl, there is a Java based shell since Jacl is pure Java.  The Java based
shell starts a Jacl interpreter and executes user given commands in the Jacl
interpreter.  The execution sequence for the Jacl shell is:

    start JVM ->
        load Jacl ->
            start Jacl interp ->
                execute TclJava commands

The TclBlend shell package provides a Java based shell for TclBlend.  The
execution sequence for the TclBlend shell is:

    start JVM ->
        load the TclBlend Shell ->
            load TclBlend ->
                load native Tcl interp ->
                    execute TclJava commands

+----------------+
| How to test it |
+----------------+

The TclBlend Shell should run any scripts written for a native Tcl interpreter
and scripts written for TclJava.  To test this capability, run "make tests" in
the TclBlend source distribution and the native Tcl source distribution.  Then
start the shell by entering:

      java tcl.lang.Shell

After seeing the prompt, cd to the "tests" directory of Tcl and execute "source
all.tcl".  This demonstrates running Tcl scripts for the native Tcl.

Start the shell and cd to the "tests" directory of TclJava source
distribution.  Execute "source all".  This demostrates running Tcl scripts
written for TclJava.

One may need to set up some options to tell the shell how to load the native
Tcl interpreter.  Here is an example script that can be modified to suit
individual needs:

#! /bin/sh
prefix=/opt/tcldev
TCL_LIBRARY=${prefix}/lib/tcl8.2
CLASSPATH=${CLASSPATH}:/opt/jdk/jre/lib/rt.jar:/opt/jdk/jre/lib:.:${prefix}/lib/
tclblend.jar:${prefix}/lib/tcljava.jar:${prefix}/tcljava/unix/tests
LD_LIBRARY_PATH=${prefix}/lib
echo envs:
echo ${LD_LIBRARY_PATH}
echo ${PATH}
echo ${TCL_LIBRARY}
echo ${CLASSPATH}

/opt/jdk/jre/bin/java -Djava.library.path=/opt/tcldev/lib -cp ${CLASSPATH} tcl.lang.Shell

+-------------------------------+
| TclBlend shell vs. Jacl shell |
+-------------------------------+

This TclBlend shell is essentially the same shell as the one included in the
original Jacl source distribution.  The TclBlend shell is modified from the
original Jacl shell is modified by making all method invokation to the Interp
class in a Tcl thread safe way and remove references to Jacl specific class
files such as Channel, StdChannel and TclIO.

In fact, the TclBlend shell can also be used as the Jacl shell.  To do this,
just start the Java program using the Jacl.jar instead of the TclBlend.jar.
There is also a patch to patch the "Shell.java" and "ConsoleEvent.java" files
in the Jacl source to make it identical to the "Shell.java" and
"ConsoleEvent.java" files included in this package.

For example:

    java -classpath $CLASSPATH:jacl.jar:tcljava.jar tcl.lang.Shell

starts the shell and loads Jacl.  But

    java -classpath $CLASSPATH:tclblend.jar:tcljava.jar tcl.lang.Shell

starts the same shell and loads TclBlend with the native Tcl.

+-----------+
| Why do it |
+-----------+

The purpose of the TclBlend shell is to demonstrate how one can use the native
Tcl interpreter within a Java application.  This is useful when one needs to
embed a Tcl interpreter into a Java application, but cannot use Jacl nor starts
a native Tcl program.  For example, one may want to use Expect or some other
Tcl extensions that are not available in Jacl.  Using TclBlend, it is possible
to have a fully functional native Tcl interpreter inside a Java program.

+--------------------------+
| Suggestion and questions |
+--------------------------+

If there is any suggestion and question regarding this subjetct, please email:

  jwu@extremenetworks.com