README.linux for Java 2 SDK (aka JDK 1.2) for Linux, version pre-release 1 Steve Byrne 03/03/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. Known Problems ============== * AWT/Motif will always be used. This version only has Motif statically linked in. We are working on providing the functionality that the 1.1.x series of Blackdown releases had to have the JVM be runnable without loading AWT. * 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. * Green threads and JIT. The just in time compiler is on by default, but it doesn't play nice with green threads yet, so you need to disable it when running with green threads. See "Execution options" below for details. * Sound is garbled. Playing .wav files may result in broken up sounds or no sounds. We're working on fixing this; please bear with us. * There may be issues with running debug versions of java, i.e. using java_g. Most likely, you will get runtime linker errors which manifest themselves as inabilities to load specific libraries. 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 almost 2.1 system. It was built using egcc-2.91.61, and associated g++, libstdc++ shared libraries. As such, you may find that the release will not work on your system if your libraries are too different from these. One problem that you may encounter is a missing definition of the symbol __register_frame_info or __deregister_frame_info. If you encounter this problem, we suggest trying two things; 1) making sure that you have a recent enought libstdc++ (2.8 or greater) which contains a definition for this symbol, and 2) adding it to LD_PRELOAD. Step 1 may be sufficient; it may be sufficient just to have the library present on your system. If your package installation system doesn't update the runtime linker cache when you install libstdc++, you can run ldconfig (as root) to update things. If step 1 didn't work, try setting the environment variable LD_PRELOAD to be the full path name of whereever you have libstdc++ installed, such as /usr/lib/libstdc++-libc6.0-1.so.2. Please be aware that this problem with the undefined symbol is one that we are working hard on eliminating; your clear bug reports about what environments you've had to take additional steps to get java to run in (and where it runs "out of the box") will help us in this effort. 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, and Brad Crochet. Reporting bugs ============== Please, *Please*, report all bugs to the Java-Linux jitterbug bug database at http://www.blackdown.org/java-linux.html. 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 architecture you downloaded (x86 glibc 2.0, powerpc, sparc, etc.) 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. I (and others) 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 doesn't 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, and you have bunzip2 installed on your system, the equivalent tar command is: tar xvIf jdk1.2.tar.gz # 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 need to disable both the JIT and specify an additional flag (the requirement for disabling the JIT is transient; we don't expect you to have to disable it to run green threads in future releases). So, for right now, you need to say java -green -Djava.compiler= ... but eventually you can say just: java -green ... We've tested the green threads version using the Java Compatibility Kit pretty thoroughly, and, except for the kernel multicast related failures described above, green threads works very well.