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 . 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 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 . 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 . 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 . 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 . 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 . 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 . 4.2. Netscape 4.0 Prior to Netscape 4.0b3 , 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.