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. 
