Basic Installation
==================

  You need to download Sun's JDK1.1.x or JDK1.2 distribution (or
  a port to another OS.. it doesn't matter.)

  you need to point the configure script at your jdk installation
  directory with the --with-jdk configure option.

  for example:

  ./configure --with-jdk=/usr/local/jdk1.1.5 --with-nspr=/path/to/nspr/dist
  gmake  (gnu make, thanks to the use of automake, is required).
  gmake install

NSPR Installation
=================

Japhar 0.09 and on depends on NSPR (Netscape Portable Runtime) from
mozilla.org.

There is a (pretty old) downloadable tar file at:

ftp://ftp.mozilla.org/pub/mozilla/libraries/source/nspr-pthreads-3.1-199903171926.tar.gz

Getting NSPR from CVS is pretty easy too.  set things up as per the
mozilla cvs instructions, and

$ cvs co mozilla/nsprpub

cd into that directory and type:

$ make NSDISTMODE=copy DIST=/usr/local/nspr

This will install nspr into /usr/local/nspr (make the path whatever
you'd like).  Use this same path on the configure line to japhar:

$ configure --with-nspr=/usr/local/nspr

and you're all set.


Avoiding name conflicts with JDK
================================

If you add --program-suffix=-japhar to configure, all programs are
installed with -japhar appended.  This will avoid name collitions with
JDK.  The only problem is that japhar itself is installed as
japhar-japhar.  :-(

Building a debug or profiling version
=====================================

configure accepts the following japhar specific flags:

  --enable-debugging
  --enable-logging
  --enable-profiling

--enable-debugging enables certain debugging code throughout the
source.  If you're planning to hack on the code in any way, you
should use this option.

--enable-logging enables specific logging constructs sprinkled
throughout the code.  A more detailed explanation follows.  You
should only enable logging if you want to track down specific problems
and running a debugger just isn't enough, as it has a serious effect
on performance.

--enable-profiling causes the -pg flag to be added to CFLAGS, and
turns off dynamic loading of native methods.

Logging
=======

Logging in the java runtime is configurable at runtime, via the
NSPR_LOG_MODULES environment variable.  It has the following form:

<moduleName>:<value>[, <moduleName>:<value>]*

For example:

  export JAPHAR_LOG=gizmo:2

The following logging modules are available:

ArrayClass       "Fake" classes for arrays, created on demand.
Array          
AWT            
Exception        Exception throwing (and catching) code.
DLL              Dynamic loading of shared libraries.
GC             
Interp           Generic interpreter logging.
Inflate        
JNI            
JVMDI          
Method         
NativeGlue       Glue used is java->C calls, as well as C->java
                 calls.
Object           Spew dealing with the runtime representation
                 of objects.
ParseClass       The code used to parse a .class file into a
                 ClazzFile structure.
PrimitiveClass 
Sig              Parsing java signatures into the Signature
                 structure.
Native           Generic log dealing with native methods.

... there may be more...

for more information about the format and options for the
NSPR_LOG_MODULES environment variable, consult prlog.h in
$(nspr_installdir)/include.

Which JDK to slurp classes.zip from?
====================================

The following are known to work:
  - JDK 1.1.5v7 for Linux glibc from Blackdown
  - ftp://ftp.freebsd.org/pub/FreeBSD/packages/All/jdk1.1.6.V98-8-14.tar.gz
  - JDK 1.2fcs for Solaris

The following _do not_ work:
  - JDK 1.1.5 for Solaris
  - JDK 1.1.6 for Solaris
  - JDK 1.1.6v2 for Linux glibc from Blackdown
