README.linux for Java 2 SDK (aka JDK 1.2) for Linux, version pre-release 2 Steve Byrne 06/1/1999 This is the Blackdown Java-Linux port of the Java 2 SDK to Linux. Pre-release =========== Please understand that this is definitely a PRE-RELEASE version. There are bugs. It may encounter a variety of problems depending on what versions of various libraries (libc, libdl, ld-linux, libpthreads) that you have installed on your system. We're making available this release for you to download and test out, and report back to us problems that you encounter so that we can have a nice, high quality first release of the JDK. Changes from Previous Release ============================= There have been a lot of changes from the previous release, almost entirely bug fixing. The following list highlights some of the more important ones: * Base memory footprint has been reduced. The default max heap size is now 16 meg (it was 64). This may mean that if you get OutOfMemory errors when running particular applications, you'll need to use -mxNNm to increase the maximum heap size. * Motif is no longer statically linked in to the executables. This means that the disk footprint is smaller, and start times, especially for non-GUI applications, should be better. * Green threads works with the JIT. * The JIT has been improved. * Drag and drop works. * Fonts aren't overly tall. * Sound works properly now. Known Problems ============== * Native threads & exec. We've experienced some very infrequent problems with doing Runtime.exec from java and then waitiing for the child thread to finish executing. The problems are typically that the waiting Java thread doesn't get notified of the child processes termination. Additionally, (as a related side effect), signals aren't always delivered reliably when using native threads. * Problems with AWT * For additional, up to date known bugs, please visit: http://www.blackdown.org/java-linux/jdk1.2-status/known-bugs.html Words of wisdom =============== Native threads: * If you get OutOfMemory errors when you try create more than xxx threads you'll have to increase the number of tasks supported by kernel (the default is 256 per user). Change NR_TASKS in /usr/src/linux/include/linux/tasks.h and recompile the kernel. [Though it's typically bad design to use hundreds of threads] JNI: * We strongly recommend using the native threads vm in conjunction with JNI. An absolute no-no is using pthread code with with the green threads vm. * Don't forget to specify '-D_REENTRANT' when compiling for the native threads vm. * The glibc 2.0 dynamic linker isn't thread safe. If you want to use the Invocation API you'll have to set LD_BIND_NOW=true. If you want to use dlopen, you should use RTLD_NOW. The dynamic linker in glibc 2.1 is thread safe. Build environment: This release was built on a Debian 2.1 system. It was built using egcc-2.91.61, using glibc 2.0, and a separate release was built using glibc 2.1. You need to be sure to download the version of the JDK that matches your glibc version. Credits ======= The following people have helped with the porting of Java 2 to Linux: Steve Byrne, Juergen Kreileder, Kevin Hendricks, Johan Vos, Anand Palaniswamy, David Connelly, Karl Asha, Kars de Jong, Scott Hutinger, Michael Sinz, Brad Crochet and Eddie Dost. Checking status =============== The porting team has set up a set of web pages which cover all manner of status information related to the port. Please check these pages before posting a question about whether a bug is fixed or when will thus-and-such part of the port be done. Please remember that the porting team consists of volunteers who are working hard in their spare time, and that often the availability of spare time is an unpredictable commodity. Generally, we simply *can't* predict when a release will be out, and even if we do, chances are that we're understimating the release date by a bit. (Ok, enough of the sermon) The URL to check status of the Java 2 port for Linux is: http://www.blackdown.org/java-linux/jdk1.2-status We try to keep this as up to date as we can, so please feel free to check there often. Reporting bugs ============== Please, *Please*, report all bugs to the Java-Linux jitterbug bug database at http://www.blackdown.org/java-linux.html. Please check that your bug isn't already a well known bug; you'll save yourself the time it take to create a bug report, and we'll appreciate not getting lots of reports which basically say the same thing. If you do report a bug, it helps to have the following information: * What Linux distribution (with version) you have (RedHat 5.2, Debian 2.1, etc.) * Which version of the JDK you downloaded (including the "v" number, i.e. 1.2v1 or whatever) * Which hardware architecture you downloaded (x86, powerpc, sparc, etc.) * Which library version you are using (glibc 2.0, glibc 2.1), and which version your system has (i.e. before you report a bug that may be related to library version skew, we'd like you to make sure that you have downloaded the proper version of the JDK). NOTE: This cannot be said enough: Sending (or making available via web or ftp) a small program that demonstrates the bug increases its chance of being diagnosed and fixed by two orders of magnitude. We can zoom right in on what the problem is right away, and that's often more than 1/2 the battle to getting things fixed. If the JDK crashes on startup, it's quite helpful to send the output of ldconfig -D as this tells us a lot about what libraries you have on your system, and variations in library versions are often the cause of crashes on startup. If you have weird AWT behavior, it helps to know what window manager you are using, and what version of X. Typically it DOES NOT help to know what display adapter you have. Sanity testing of your code on Solaris (to see if it breaks there) is always encouraged, as this often rules out generic JDK bugs (and, heaven forbid, bugs in your code that you didn't realize you had :-). Win32 sanity checking is also good, but since the Linux JDK is derived by modifying the Solaris version, Win32 is not nearly as representative in most cases. If you can't come up with a small program that reproduces the bug, but it occurs in some standard application that's downloadable off the web, please include the URL to get to the application -- this saves us the effort (and possibly differing results) of finding the program ourselves. Having exact instructions about how to reproduce the problem ("Start ICQ via 'java icq'. Select the destroy->empire menu. Click the ok button and then click on the Bill Gates icon. ..." helps a lot). If you get out of memory errors, having information about how much RAM and swap space you have is quite useful. It is essential that you verify that you have as much swap as you think by using the 'top' program. I've had cases where I was sure that I had enough swap and was getting out of memory errors, only to find that I'd forgotten to turn a particular swap file back on. Also, if you're invoking the java interpreter with any parameters which affect memory size (like mx), we need to know that too. Missing libXp -------------- The JDK now depends on having the X printing library, libXp installed with the rest of your X files. This is part of the most recent X11 distributions, so you'll need to upgrade (or, if you are daring, you can just extract the libXp.so* file from the upgrade package for your Linux distribution and install it by hand w/o upgrading everything else, although this is unlikely to work if your X libraries are substantially out oof date) Installation ============ Installation of the Linux JDK is trivial. (If you are not on an x86 based Linux system, skip to the bottom of this section). For the x86 processor family, there currently only one flavor, that's based on glibc 2.0 (we will be soon making available a version for glibc 2.1) Note that you must have glibc 2.0 available on your system in order to run all of the JDK properly (you may be able to run some things if you have a glibc 2.1 system, but there are known problems that may prevent you from doing much of anything). You should try to make sure that your glibc 2.0 version is a late version of 2.0.7, like "t" or 20 (depending on how your Linux distribution numbers its package versions). win). Now that that's out of the way, you're asking "Yes, Steve, that's all fine and dandy, but how do I INSTALL the darn thing???". It's *real* easy: 1) decide where you want the directory to live. It can be anywhere in your filesystem that supports symbolic links (i.e. not on certain mounted Windows filesystems). 2) unzip and untar into your chosen directory (the system untars itself into a subdirectory called "jdk1.2"; you can call it whatever you like after you untar it -- I call mine "fred"). Want to know a secret? GNU tar, like all winning GNU software, has a cool feature (ok, ok, it has more than just one) that few folks seem to know about: you can unzip and untar with one tar command! Just do: tar xvzf jdk1.2.tar.gz # whatever the file is called the "z" flag says "gunzip before untarring". The same flag works in reverse when tarring. It's handy, and I think more people ought to know about it. If you have downloaded the .bz2 version of the file (since that's the only way we package it right now), *and* you have bunzip2 installed on your system (it's available with most modern distributions, probably in a package called bzip or bzip2) , the equivalent tar command is: tar xvIf jdk1.2.tar.bz2 # whatever the file is called 3) [optional] Put the bin directory of the JDK into your PATH environment variable so you can just say "java" instead of "/foo/bar/jdk1.2/bin/java" when you want to run the interpreter. For my setup, I'd do (bash shell, I'm sure you are bright enough to figure out the csh equivalent): export PATH=/fred/bin:$PATH # remember, I changed my jdk1.2 directory # to be "fred" That's it! No CLASSPATH, no JAVA_HOME, or other environment variables to set to get the basic system running. It can be installed anywhere on your machine, and it figures out whatever information it needs about where it was installed automatically when it runs. Execution options ================= This release comes with support for both green threads and native threads. Native threads is the default choice. This version also includes a "just in time" byte code compiler (JIT) that's based on the Solaris x86 JIT, and that's turned on by default. To disable the JIT, add: -Djava.compiler= to the java command line. Some of the other java tools (e.g. javac) need you to prefix arguments that are to be passed directly to java with a -J, so for those tools, you'd use: -J-Djava.compiler= To run with green threads, you can use: java -green ... And you can similarly disable the JIT using the -java.compiler= construct for green threads. You can also set the JIT to use (including none) via the JAVA_COMPILER environment variable; that way you won't have to remember to set it on the command line each time. To run with no JIT, you can set the value of JAVA_COMPILER to NONE. We've tested the green threads version using the Java Compatibility Kit pretty thoroughly (without the JIT), and, except for the kernel multicast related failures described above (which are fixed in kernels 2.0.37ac9 and above), green threads works very well.