  Java-Linux HOWTO
  Karl Asha, karl@blackdown.org
  v1.6.1, 14 January 1997

  This document provides a rundown of what setup and external libraries
  are required to use the JDK 1.0.2 for Linux.
  ______________________________________________________________________

  Table of Contents:

  1.      Installing the JDK 1.0.2

  1.1.    Overview

  1.2.    Information on ELF

  1.3.    Required ELF Libraries

  1.4.    Retrieving the JDK for Linux

  1.5.    Required System Settings

  1.6.    Performance Issues

  1.7.    Problems and Bug Reporting

  1.8.    Further Reading

  2.      JDK-1.0.2 Release Notes

  2.1.    XFree86 and libXt.so.6.0

  2.2.    Motif Distributions

  2.3.    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.      How to make Netscape 3.0 and Java work

  4.1.    Getting the Environment Right

  5.      Marimba's Tuner, Transmitter, and Bongo

  5.1.    Installation Instructions

  5.2.    Installation Problems

  6.      Working with the SunSoft Java Workshop (JWS)

  6.1.    Installation

  6.2.    The JWS and Linux

  6.3.    Problems with the JWS
  ______________________________________________________________________

  1.  Installing the JDK 1.0.2

  1.1.  Overview

  Depending on your Linux installation, using the Java Developer's Kit
  for Linux may require a number of system-wide changes.

  Recent developments in the Linux world brought forth a new binary
  format called ``ELF'', which made features such as dynamic loading and
  painless shared library generation possible. The JDK for Linux relies
  on these features and, as a result, your system must have both kernel
  support for ELF binaries and a number of support libraries installed.

  Unfortunately, Linux is plagued with an ever changing environment, and
  sometimes, these changes have adverse effects on the programs you may
  run. The remainder of this document will help provide you with the
  ideal configuration for working with, and developing Java based
  applications.

  1.2.  Information on ELF

  The JDK for Linux relies on a Linux kernel that has been configured to
  support ELF executables, as well as a number of ELF ``support
  libraries''.

  Detailed information on ELF is available through Daniel Barlow's
  HOWTO, located at  <http://www.blackdown.org/elf/elf.html>.

  Both Redhat Software <http://www.redhat.com> and Slackware
  <http://www.cdrom.com/titles/os/slack96.htm> provide elf based
  distributions of Linux.

  1.3.  Required ELF Libraries

  There are three major packages requied to use the JDK for Linux, each
  containing a number of ELF shared libraries.

     Required Packages

     o  The Standard C Library ("libc")

     o  The Linux Dynamic Loader Library ("ld.so")

     o  The XFree86 Libraries ("XFree86")

     Required Package Revisions

     o  libc version 5.2.18 or greater

     o  ld.so version 1.7.14 or greater (excluding 1.8.2)

     o  XFree86 version 3.1.2 or greater

  The libc package can be found at <ftp://tsx-11.mit.edu/pub/linux/pack-
  ages/GCC/>. The naming convention for this package is
  libc-5.x.y.bin.tar.gz.

  The ld.so package can be found at
  <ftp://tsx-11.mit.edu/pub/linux/packages/GCC/>. Again, the naming
  convention for this package is ld.so-1.x.y.tar.gz.

  The XFree86 package 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.  XFree86
  is required for working with graphical user interface based Java
  applications. For text/console based applications, the JDK shared-
  motif can be used without this package. (See ``Retrieving the JDK for
  Linux'').

  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.4.  Retrieving the JDK for Linux

  The Java Developer's Kit for Linux can only be found on mirror sites.

  The current list of recognized mirrors is available at
  <http://www.blackdown.org/java-linux/Mirrors.html>.  These sites
  provide both standard archive and RPM format packages.

  The JDK for Linux relies on the Motif library for much of its user GUI
  based functionality. Due to the commercial nature of the Motif
  library, the JDK is distributed in both 'static' and 'shared'
  flavours. If you have purchased motif libraries from a 3rd party
  vendor, using the shared version of the JDK will allow you to make use
  of your ELF Motif shared libraries (version 2.0 only).

  Note: The shared archive will also allow you to use the JDK for
  text/console based applications without installing the XFree86
  distribution.

  If you have not purchased Motif, and wish to work with GUI based
  applications, then you must use the static version of the JDK.

     Choosing the Right Files

        Standard Archive Format
           The standard archive format packages come in two parts. You
           will need the common archive and either a shared or static
           archive, depending on your situation with regards to Motif.

        RPM Format
           The RPM format packages are self contained archives. You will
           only need to select either the shared or static package.

  The RPM packages will install themselves in /usr/local/java/.  For
  consistency, it is suggested that unarchive the common and program
  archives that you have selected in /usr/local/.

  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.

  1.6.  Performance Issues

  Richard Long (rlong@cerebrum.ucd.ie) made the following suggestion to
  improve JDK performance on slower machines.

  Unzipping the classes.zip in a driectory and setting the CLASSPATH to
  point at it, along with modifying the appletviewer to avoid it loading
  classes.zip, will reveal a significant performance gain in both
  compilation and execution times.

  1.7.  Problems and Bug Reporting

  If you discover a what might be a bug while working with the JDK for
  Linux, please send email to chapman@wilbursoft.com or
  karl@blackdown.org.

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

  The current list of known problems is documented at
  <http://www.blackdown.org/java-linux/bugs.html>.

  1.8.  Further Reading

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

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

  2.  JDK-1.0.2 Release Notes

  2.1.  XFree86 and libXt.so.6.0

  It has been reported that the libXt.so.6.0 distributed with some
  XFree86-3.1.2 distributions may cause problems with certain Java based
  applications under linux. You can find a replacement at
  <http://www.blackdown.org/java-linux/downloads/libXt.tar.gz>.

  2.2.  Motif Distributions

  Two 3rd party distributions of Motif have been found to work
  incorrectly when used with the JDK shared package. These are Moteeth
  and UIUC Motif.

  Redhat Motif, Mootif, and Xinside Motif hava been found to work
  correctly.

  2.3.  jdb

  The debugger ("jdb") packaged with the JDK requires an active network
  interface to function. One solution to the problem is to change the
  hostname of your machine to localhost. A more sensible solution is to
  use a dummy device that corresponds to the name and address you have
  specified for your machine in /etc/hosts.

  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.  How to make Netscape 3.0 and Java work

  4.1.  Getting the Environment Right

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

  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.

  Steven Adler (adler@bnlku5.phy.bnl.gov) has provided an extremely
  useful RPM to automate the process described above. The archive can be
  found at  <ftp://ftp.phy.bnl.gov/pub/linux/redhat/bnl-RPMS-i386/>.

  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.

  5.  Marimba's Tuner, Transmitter, and Bongo

  5.1.  Installation Instructions

  The official Linux versions of Marimba's Tuner, Transmitter, and Bongo
  can be found at  <http://www.blackdown.org/java-linux/Products.html>.
  Installation simply involves unpacking these archives in a directory
  of your choice and executing the scripts in the bin subdirectory.

  JDK-1.0.2-pl2 or greater is required to use these applications. It is
  distributed separately from  <http://www.blackdown.org/java-
  linux/Mirrors.cgi>.

  5.2.  Installation Problems

  prio    2c) If you find that running the Tuner results in the
  following error, then you need to update your libXt.so.6.0. A
  replacement version can be found at http://www.blackdown.org/java-
  linux/downloads/libXt.tar.gz <http://www.blackdown.org/java-
  linux/downloads/libXt.tar.gz>.

  SIGSEGV   11*  segmentation violation

  Full thread dump:
      "AWT-Motif" (TID:0x404b8c68, sys_thread_t:0x41=5
          java.lang.Thread.run(Thread.java)
      "AWT-Input" (TID:0x404b8c40, sys_thread_t:0x412c3f2c) prio=5
      "Finalizer thread" (TID:0x404b8368, sys_thread_t:0x4129ff2c) prio=1
      "Idle thread" (TID:0x404b8320, sys_thread_t:0x4127df2c) prio=0
      "clock handler" (TID:0x404b81f8, sys_thread_t:0x4125bf2c) prio=11
      "main" (TID:0x404b80a0, sys_thread_t:0x817dd30) prio=5 *current thread*
          sun.awt.motif.MComponentPeer.dispose(MComponentPeer.java:175)
          sun.awt.motif.MFramePeer.dispose(MFramePeer.java:82)

  6.  Working with the SunSoft Java Workshop (JWS)

  6.1.  Installation

  The Java Workshop can be found at  <http://www.sun.com/developer-
  products/java/>, and is availble for a 30 day evaulation period.

  6.2.  The JWS and Linux

  In order to use the JWS under Linux, you must retreive the Solaris x86
  version of the JWS, along with replacement 'jws' script from the Java-
  Linux Products <http://www.blackdown.org/java-linux/Products.html>
  page. You must be running the JDK 1.0.2 pl2
  <http://www.blackdown.org/java-linux/Mirrors.html> in order to use
  this package under Linux.

  6.3.  Problems with the JWS

  If the JWS editor has a problem with freezing, try disabling version
  control.

  If the JWS claims that it is unable to find 'javac', it is an
  indication that you are not running the JDK 1.0.2 pl2 for Linux.

