Java-Linux HOWTO Karl Asha, karl@blackdown.org v1.6.2, 21 April 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. Netscape and Java 4.1. Netscape 3.0 4.2. Netscape 4.0 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 . Both Redhat Software and Slackware 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 . The naming convention for this package is libc-5.x.y.bin.tar.gz. The ld.so package can be found at . Again, the naming convention for this package is ld.so-1.x.y.tar.gz. The XFree86 package can be found at . 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 . 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 . 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 . A wealth of Java information is available directly from JavaSoft . 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 . 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. 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. ______________________________________________________________________ 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. 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 . 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. 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 5.1. Installation Instructions The official Linux versions of Marimba's Tuner, Transmitter, and Bongo can be found at . 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 . 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 . 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 , 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 page. You must be running the JDK 1.0.2 pl2 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.