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.