<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0077)ftp://ftp.uk.linux.org/pub/linux/java/JDK-1.2/i386/pre-v1/jdk1.2-README.linux -->
<HTML><HEAD>
<META content="text/html; charset=windows-1252" http-equiv=Content-Type>
<META content="MSHTML 5.00.2314.1000" name=GENERATOR></HEAD>
<BODY><XMP>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.
</XMP></BODY></HTML>
