Java-Linux 1.1.1 HOWTO
  Karl Asha, karl@blackdown.org
  18 May 1997

  This is a draft version of the JDK-1.1.1 Howto for Linux.
  ______________________________________________________________________

  Table of Contents:

  1.      Installing the JDK 1.1.1

  1.1.    Overview

  1.2.    Required Libraries

  1.3.    Retrieving the JDK 1.1.1 for Linux

  1.4.    Installing the JDK 1.1.1 for Linux

  1.5.    Required System Settings

  1.6.    Motif - Static vs. Dynamic

  1.7.    Problems and Bug Reporting

  1.8.    Further Reading

  2.      JDK-1.1.1 Release Notes

  2.1.    jdb

  3.      Using Java Binary Format Support in the Linux kernel

  3.1.    Configuring the Kernel

  3.2.    Making Use of Java Binary Support

  3.3.    Further Reading

  4.      Netscape and Java

  4.1.    Netscape 3.0

  4.2.    Netscape 4.0

  5.      Marimba's Tuner, Transmitter, and Bongo
  ______________________________________________________________________

  1.  Installing the JDK 1.1.1

  1.1.  Overview

  The JDK 1.1.1 package for Linux is available from an extensive list of
  volunteer mirror sites.

  It is assumed that the end user's system is capable of running ELF
  binaries. At this point, ELF is now beyond the scope of this document.

  1.2.  Required Libraries

  The current build of the JDK 1.1.1 for linux is packaged with the
  neccessary Standard C Library and Linux Dynamic Loader Library needed
  to operate the supporting binaries.

  The end user is responsible for ensuring that the XFree86 Libraries
  are installed on his system.

  The JDK 1.1.1 for Linux was created under the following environment.

     Libary Revisions

     o  libc version 5.4.13

     o  ld.so version 1.8.5

     o  XFree86 version 3.1.2

  In case your system requires an updated XFree86 installation, the
  required packages can be found at
  <ftp://tsx-11.mit.edu/pub/linux/packages/X11/>. Please view the README
  file there for more information on the XFree86 distribution.

  For a summary of which libraries are currently installed on your
  system, type ldconfig -v.

  Technical details, programming information, and installation
  instructions for these packages is beyond the scope of this document.

  1.3.  Retrieving the JDK 1.1.1 for Linux

  Three different packages for using Java under Linux can be found on
  mirror sites. Please visit http://www.javasoft.com
  <http://www.javasoft.com> for licensing information on bundling the
  JRE with your own Java applications.

  The JavaSoft documentation, demonstration classes, and src.zip for the
  JDK 1.1.1 are distributed in a separate package.
  (jdk1.1.1-doc+demo.tar.gz)

     JDK - Java Developer's Kit
        This package includes everything neccessary to run and compile
        Java programs under Linux.

     JRE - Java Runtime Environment
        The JRE is a runtime system meant to be bundled with
        applications.  It includes everything needed to run (but not
        compile or debug) Java programs. The JRE includes all character
        converters for full internationalization support.

     RT - Separated Java Runtime Environment
        In the RT package, the internationalization support and basic
        runtime VM are separated into two directories, rt and i18n.  The
        rt directory provides everything needed to execute Java
        applications in ISO-Latin-1 environments. The i18n directory
        contains the optional byte to character converters for different
        global character encoding schemes. In the JRE package, these two
        directores are combined into one.

  The current list of recognized mirrors is available at
  <http://www.blackdown.org/java-linux/Mirrors.html>.

  1.4.  Installing the JDK 1.1.1 for Linux

  By tradition, all one needs to do in order to install the JDK is to
  select a directory, such as /usr/local/, and unpack the selected
  archive. Once installed, adding (in this case)
  /usr/local/jdk1.1.1/bin/ to your PATH will allow you to make use of
  the Developer's Kit.

  Unfortunately, controversy recently surrounded the selection of a home
  for the JDK when used under Linux. The location, in all honesty, is
  merely a matter of decoration. What remains important is that you set
  the JDK_HOME variable to point to a directory that contains the bin/,
  lib/, and classes/ subdirectories of the JDK.

  All future packages distributed by the Java-Linux community will rely
  on this variable to find the neccessary support binaries and class
  libraries.

  1.5.  Required System Settings

     CLASSPATH Settings
        The CLASSPATH environment variable is used to tell the JDK where
        to look for classes. Sometimes, an incorrect setting may impede
        successful execution of the JDK tools. If you experience any
        problems using the JDK, make sure that the CLASSPATH variable is
        not set before you try running java, javac, or the appletviewr.

     Device Permissions
        Before using the JDK, ensure that the special device /dev/zero
        is world readable and writeable. In order to do this, simply
        issue the following command as the superuser:

        chmod 666 /dev/zero

     Swap Space
        The JDK attempts to pre allocate a large chunk of memory when it
        starts.  Always be certain that your system has at least 20
        Megabytes of free swap space before running any of the
        executables provided with the Java Developers Kit.

        You can control the amount of memory the java interpreter uses
        by experiementing with the -mx and -ms flags. Further
        information on these settings is available from the JDK manual
        pages.

  1.6.  Motif - Static vs. Dynamic

  Prior to the JDK 1.1.1, two separate packages were released to the
  Java-Linux community, one of which was statically linked with Motif.

  Although the JDK 1.1.1 dynamically linked with Motif is not currently
  supported, there are ways to make use of your Motif shared libraries.

  Setting the NS_JAVA environment variable to a non-zero value, such as
  to be used. This scheme allows you to use the JDK without having the
  XFree86 distribution installed. It also allows use of a shared Motif
  library.

  In order to use your shared Motif libraries, you must make use of the
  LD_PRELOAD environment variable. Preloaded libraries must include
  Motif and all neccessary XFree86 libraries.

         For example:

           export NS_JAVA=true
           export LD_PRELOAD=/usr/X11R6/lib/libXm.so.2.0:\
           /usr/X11R6/lib/libX11.so.6.1

  1.7.  Problems and Bug Reporting

  If you discover a what might be a bug while working with the JDK 1.1.1
  for Linux, please send email to Steve Byrne, sbb@gnu.ai.mit.edu.

  Along with your bug report, please include the output of 'ldconfig
  -v', which kernel version you have installed on your machine, and any
  available stack traces.

  1.8.  Further Reading

  Up to date HOWTOs, mailing lists, supported product lists, and other
  Java-Linux services are available from The Blackdown Organization, at
  http://www.blackdown.org/java-linux.html
  <http://www.blackdown.org/java-linux.html>.

  Please forward any questions or suggestions about these resources to
  karl@blackdown.com.

  A wealth of Java information is available directly from JavaSoft, at
  http://www.javasoft.com <http://www.javasoft.com>.

  2.  JDK-1.1.1 Release Notes

  2.1.  jdb

  The debugger ("jdb") packaged with the JDK requires an active network
  interface to function. Since most dialup machines only have the
  loopback ("127.0.0.1") interface active when not connected to the
  internet, the jdb runs into problems. The jdb attempts to connect to
  the address that corresponds to your machine's hostname, finds that it
  either can't look it up, or can't reach the address specified in
  /etc/hosts, and fails to start up.

  One solution to the problem is to change or alias the address of your
  hostname to ("127.0.0.1"). A more sensible answer is to use a dummy
  device that corresponds to the name and address you have specified for
  your machine in /etc/hosts.

  Following is an excerpt from the Network Administrator's Guide that
  will summarize and clarify the functionality of the dummy device
  driver.

  The dummy interface is really a little exotic, but rather useful
  nevertheless. Its main benefit is with standalone hosts, and machines
  whose only IP network connection is a dial-up link. In fact, the
  latter are standalone hosts most of the time, too.

  The dilemma with standalone hosts is that they only have a single
  network device active, the loopback device, which is usually assigned
  the address 127.0.0.1.  On some occasions, however, you need to send
  data to the `official' IP address of the local host. For instance,
  consider the laptop vlite, that has been disconnected from any network
  for the duration of this example.  An application on vlite may now
  want to send some data to another application on the same host.
  Looking up vlite in /etc/hosts yields an IP-address of 191.72.1.65, so
  the application tries to send to this address. As the loopback
  interface is currently the only active interface on the machine, the
  kernel has no idea that this address actually refers to itself! As a
  consequence, the kernel discards the datagram, and returns an error to
  the application.

  This is where the dummy device steps in. It solves the dilemma by
  simply serving as the alter ego of the loopback interface.  In the
  case of vlite, you would simply give it the address 191.72.1.65 and
  add a host route pointing to it. Every datagram for 191.72.1.65 would
  then be delivered locally. The proper invocation is:

  ______________________________________________________________________

             # ifconfig dummy vlite
             # route add vlite

  ______________________________________________________________________

  3.  Using Java Binary Format Support in the Linux kernel

  3.1.  Configuring the Kernel

  In order to make use of Java binary format support with Linux, you
  must configure a kernel with 'Kernel support for ELF binaries'.

     Java Support Compiled Into the Kernel

     o  If Java support is not compiled as a module, the location of
        your java applications can be specified using the Linux system
        control interface. Otherwise, the java and appletviewer
        applications are expected to be found in /usr/bin.

        echo "/usr/local/java/bin/java" > /proc/sys/kernel/java-interpreter
        echo "/usr/local/java/bin/appletviewer" > /proc/sys/kernel/java-appletviewer

     Java Support Compiled as a Module

     o  If Java support is compiled as a module, the module expects to
        find the java and appletviewer applications in /usr/bin. To work
        around this, simply edit /usr/src/linux/fs/binfmt_java.c and
        modify the following definitions to reflect your setup.

                      #define _PATH_JAVA      "/usr/bin/java"
                      #define _PATH_APPLET    "/usr/bin/appletviewer"

  3.2.  Making Use of Java Binary Support

  In order to use the Java binary support, the following steps must be
  taken with compiled Java code.

  o  Compile your java source file as you normally would.

  o  Set the execution bit on the generated class file with chmod.

  o  Execute the class file as if it were any other executable.

  3.3.  Further Reading

  Release notes pertaining to Java binary format support in the Linux
  kernel can be found in
  <file:///usr/src/linux/Documentation/java.txt>.

  4.  Netscape and Java

  4.1.  Netscape 3.0

  The fundamental problem with Netscape 3.0, java, and linux machines is
  the use of a Standard C Library compiled with dl-malloc. Using a
  wrapper script and the older gnumalloc, java will for the most part
  cease to crash the browser.

  The script also sets a very simple CLASSPATH. Be careful, certain
  CLASSPATH entries can confuse netscape and cause it to crash, as can
  the presence of outdated Netscape class libraries.

  ______________________________________________________________________
  #!/bin/sh
  export CLASSPATH="/usr/local/netscape/java/classes/java_301:."
  export LD_PRELOAD="/lib/gnumalloc.so"
  exec /opt/netscape/bin/netscape "$@"  # NOTE! This must be the path to the
                                          real netscape executable, not this
                                          script.
  ______________________________________________________________________

  To make this all work, follow these steps:

  o  Install netscape

  o  Copy the java_30 or java_301 file included with the netscape
     archive to /usr/local/netscape/java/classes/

  o  Copy gnumalloc.so to /lib

  o  Edit the shell script to match your setup

  You can find gnumalloc.so at http://www.blackdown.org/java-
  linux/downloads/gnumalloc.tar.gz <http://www.blackdown.org/java-
  linux/downloads/gnumalloc.tar.gz>. Thanks to Doug Ridgway
  (ridgway@routh.UCSD.EDU) for this tip.

  Recently, it has been reported that netscape will also crash with Java
  applets if using versions of libXext.so higher than libXext.so.6.0.
  The solution, is to copy libXext.so.6.0 into a directory such as
  /lib/509/, making the appropriate symbolic links and setting the
  LD_LIBRARY_PATH to look in that directory first.

  Geoffrey Dairiki (dairiki@apl.washington.edu) has created a workaround
  for playing sound with Java under Netscape 3.0, which can be found at
  http://irving.apl.washington.edu/~dairiki/libmmoss/libmmoss.html
  <http://irving.apl.washington.edu/~dairiki/libmmoss/libmmoss.html>.
  4.2.  Netscape 4.0

  Prior to Netscape 4.0b3 <ftp://ftp.netscape.com/pub/communicator/4.0>,
  no combination of libraries and modules could curb Netscape's desire
  to crash. Version beta3 of Netscape 4.0, however, when used in
  conjunction with libc 5.4.23 and higher, has been verified to work
  without the need for any of the previous workarounds that Netscape 3.0
  necessitated.

  5.  Marimba's Tuner, Transmitter, and Bongo

  Marimba, Inc. has not yet released versions of the Tuner, Transmitter,
  and Bongo that are compatible with the JDK 1.1.1.