README.linux for Java 2 SDK Version 1.2.2 RC4 for Linux
Juergen Kreileder
2000/01/27

This is the Blackdown Java-Linux port of the Java 2 SDK Version 1.2.2
Release Candidate 4.

Note that this is not the final version of the Java 2 SDK Version
1.2.2.  A final version will be released when we've verified
compatibility with the JCK testsuite and fixed the problems you
possibly report against this release candidate.

Also note that this version needs at least a glibc-2.1.2 based system
with a recent 2.2.xx kernel.  This build will not run with glibc-2.0
or glibc-2.1[.1].

Changes from 1.2.2 RC3:
=======================

* The incompabtible raster problem that kept Swing from running on some
  Xservers has been fixed.

* Remote display on Xservers with non-native byte order now is supported
  with depth 15 and 16 too.

* JPDA has been backported from the JDK 1.3:
        - javadt is small graphical debugger
        - jdb now uses JPDA
        - the older jdb had been renamed to oldjdb

* Native threads VM:
        - Fixed interruption of the primordial thread
        - Fixed the 'bad file descriptor' errors
        - Fixed Thread.interrupted()

* Green threads VM:
        - No longer limited to 1024 file descriptors
        - Fixed 'Interrupted system call' errors

* Reverted font.properties change


Changes from 1.2 pre v2:
========================

There have been a lot of changes from the since the 1.2 releases.  The
following list highlights some of the more important ones:

* The default max heap size is 64M again.  If want to have the reduced
  max heap size (as in 1.2pre2), set _JVM_LOWMEM to a nonempty value
  (e.g. 'export _JVM_LOWMEM=1').

* The JIT has been improved, though there are still a few know
  problems.

* Complete rewrite of the native threads VM using the latest
  LinuxThreads version to create a much improved stable native threads
  port.

* The "Error: can't find libjava.so." problem has been fixed.

* Problems with thread interrupts, condvar waiting are fixed.

* Problems with socket interrupts, socket closing, etc. are fixed.

* Fixed some awt problems under some window managers
  (although some still exist)

* Numerous problem fixes directly from Sun in Swing 1.1.1

* Some bug fixes have been backported from Sun's 1.3

* Swing finally should work with all color depths.

* Included a sample font.properties.tt file.

Known Problems
==============

* The sunwjit JIT compiler does still not work entirely correctly.

* There may be some problems with Frames and Dialogs under some window
  managers.  The best tested environment currently is KDE's kwm as
  that's what I use daily.

* Drag-and-Drop fails if there's a Window around.  This is a serious
  bug as Swing uses Windows for popups. (This bug is not Linux
  specific, it occurs with the Solaris JDK too).  See JDC bugs:
  4185644, 4248661.

* JSlider.getValueIsAdjusting() always returns true.  This is a
  platform independent Swing bug in 1.2.2.  The bug is fixed in 1.3.
  See JDC bugs: 4246117, 4246270, 4233024

* 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, or
  upgrade to a 2.3.xx kernel.
  [Though it's typically bad design to use hundreds of threads]
  Another limit is in LinuxThreads library, by default it supports
  1024 threads per process.  Volano's Linux support page at
  http://www.volano.com/linux.html shows how you can work around
  this limitation.

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.

* Native code using JNI should NOT modify the signal processing state.
  The VM uses signals and any change to the signal handling may result
  in VM failures.

Fonts:

* Dingbats/Symbol fonts: You can get these fonts from
  http://www.gimp.org/fonts.html

* We have included a second font properties file
  (jre/lib/font.properties.tt).  If you have the TrueType Fonts
  listed in this file (Times New Roman, Arial, Courier New) you can
  get a much better display as with the original font.properties file.


Build environment:
==================

This release was built on a Debian potato system.  It was built using
gcc-2.95.2 (20000116), using glibc 2.1.2.


Credits
=======

The following people have helped with the porting of Java 2 to Linux:

Juergen Kreileder, Kevin Hendricks, Steve Byrne, Johan Vos, Anand
Palaniswamy, Eddie Dost, David Connelly, Karl Asha, Kars de Jong,
Scott Hutinger, Calvin Austin, Nigel Gamble, Michael Sinz, Brad
Crochet, and Jeffery Gaylan.


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
underestimating 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 of 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.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.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 (depending the tar version):

       tar xvIf jdk1.2.2.tar.bz2   # whatever the file is called
   or
       tar xvyf jdk1.2.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.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.2
                                  # directory to be "fred"

   If you see messages like 'CLASSPATH not set' or 'No library path
   set.', then your PATH is not set correctly.  These messages come
   from Kaffe and not from the JDK.

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=
or
   -Djava.compiler=NONE

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=
or
   -J-Djava.compiler=NONE

To run with native threads, you can use

   java -native  ...

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.
The also can set the default virtual machine you want to use by
setting the THREADS_FLAG environment variable to 'green' or 'native'.

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.
