Jacl
RCS: @(#) $Id: README.jacl,v 1.7.6.1 2000/04/11 05:27:00 mo Exp $

This is the directory where you configure, compile, test, and install 
UNIX versions of Jacl.

The rest of this file contains instructions on how to do this.  The 
release should compile and run either "out of the box" or with trivial 
changes on any UNIX-like system that approximates POSIX, BSD, or 
System V.  We know that it runs on workstations from Sun.  To compile 
for a PC running Windows, see the README file in the ../win directory.

How To Compile And Install Jacl
------------------------------------------------------

(1) Type "./configure".  This runs a configuration script created by
    GNU autoconf, which configures Jacl for your system and
    creates a Makefile.  The configure script allows you to customize
    the Jacl configuration for your site; for details on how you can
    do this, type "./configure --help" or refer to the autoconf
    documentation (not included here).  Jacl's "configure"
    supports the following special switches in addition to
    the standard ones: 

	--with-jdk		By default, the configure script will
                                attempt to find the JDK by searching on
                                the PATH for the javac program. If the
                                javac program can not be found on the
                                PATH or if you do not want to use the
				JDK that it finds, you will need to use
                                this switch to tell configure where
                                it should look for the JDK binaries.

	--with-kaffe		If this switch is given the configure script
				will attempt to configure for use with the
                                Kaffe JVM. See www.transvirtual.com for more
                                info about Kaffe. This switch should be used
                                with the absolute path to the directory where
                                your Kaffe binaries are installed.

	--with-jikes		The JDK ships with a java compiler called
				javac. This compiler works but it is very
				slow. Many people would rather use the
				jikes compiler from IBM because it is much
				faster than javac and it produces better code.
				On my system, a compile with javac takes
				1 minute while a compile with jikes
                                takes less than 3 seconds. If this switch is
                                given with no argument then the configure
                                script will search for jikes on the PATH.
                                If an argument is provided it must be the
                                absolute path name of your jikes executable.
                                See www.research.ibm.com/jikes for more info.

    If you are only going to compile for a single JVM then you
    should just run "./configure" from this directory. If you intend
    to build Jacl for multiple JVMs you should make a sub
    directory for each system you want to build a binary for. For
    instance if you wanted to compile for Sun and Kaffe you
    could make two directories called "Sun" and "Kaffe". At
    this point you will want to run the configure script in the
    directory of each target system. You should do something like
    "cd Sun ; ../configure (your configure options here)".
    You can also use this feature to build two versions of Jacl
    (one that works with JDK1.1 and another that works with JDK1.2)
    on the same system. If Jacl is compiled for JDK1.1 it will
    also run on JDK1.2 but if compiled on JDK1.2 it may not
    work with JDK1.1.

(2) Type "make". This will build two library files called
    jacl.jar and tcljava.jar. The jacl.jar library file
    stores the class files that are only used by jacl.
    The tcljava.jar library file stores the class files
    that are shared between jacl and tclblend.

(3) If the make fails then you'll have to personalize the Makefile
    for your site or possibly modify the distribution in other ways.
    If you need to modify Makefile, there are comments at the beginning 
    of it that describe the things you might want to change and how to 
    change them.

(4) After the make finishes you can quickly test out jacl by typing
    "make shell" which will drop you into a running jacl shell where
    you can enter Tcl commands.

(5) When you are ready to install jacl type "make install" to install
    the jacl.jar and tcljava.jar libraries on your system. Doing the
    install will also create a wrapper script called jaclsh which you
    can use to run jacl without setting the CLASSPATH. After the wrapper
    script has been installed a test program will be run to ensure that
    the installed program is working correctly. If you want to run jacl
    with special arguments you will need to edit the jaclsh script.

Test suite:
-----------

There is a relatively complete test suite for all of the Tcl core in the 
subdirectory "tests".  To use it just type "make test" in this directory.  
You should then see a printout of the test files processed.  If any errors 
occur, you'll see a much more substantial printout for each error.  See the 
README file in the "tests" directory for more information on the test suite.  
Note: don't run the tests as superuser: this will cause several of them to 
fail.

