Java-Linux HOWTO Karl Asha, karl@blackdown.org v1.6.0, 1 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. Problems and Bug Reporting 1.7. 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 ______________________________________________________________________ 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. 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.7. 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. 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 . 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_30:." export LD_PRELOAD="/lib/gnumalloc.so" /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 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. 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)