@node    FAQ,    Install,  About Japhar, Top
@chapter FAQ

Here is the beginnings of an FAQ for Japhar.

@section Basic Clues

@subsection What is Japhar?
Japhar is the Hungry Programer's Java VM. It has been built from the
ground up without consulting Sun's sources.  It is licensed under the
GNU LGPL, so you are free to distribute it and use it with your own
programs.

@subsection What is a Java VM?
A Java Virtual Machine (VM) is a program which runs compiled Java
classes, in bytecode format. To be fully compliant with Sun's reference
implementation, the VM must provide a core API as well as correct
bytecode execution, so that Java programs and applets can run in Japhar
just as they would in any other Java-compatible virtual machine.

Japhar will also include a complete set of development tools, including
a Java compiler, automated API documentation generator, and others.

@section Why another Java VM?
Japhar is different because it was designed from the beginning to
conform to the JNI Spec published by Sun. So, it's easy to actually
embed Japhar in your own programs (you can even create more than one
Japhar VM in the same process.)

Performance is important to us, but it is secondary to our primary goal,
which is to very quickly follow specifications as they are published. We
have, for example, begun work on following the Java VM Debugger
Interface (JVMDI).  The goal is to hook up GDB to this interface to
provide a consistent debugging environment.

That being said, there are plans to work on a JIT for japhar. Please
contact @email{japhar@@hungry.com} for more info, or if you'd like to
help out (or write the entire thing :)

Also, japhar uses thread libraries that are native to the machine. Both
pthreads and cthreads are supported.

Oh yeah, Japhar is also open-source, free software, and has far fewer
restrictions than the Sun JDK.

@subsection What is Java?
What rock have you been hiding under? Java is an object-oriented
general-purpose language. It is also a virtual machine specification
that can be implemented on most computers without much pain. It is also
a general platform for network and GUI programming. Check out
@email{http://www.javasoft.com} if you need more.

@subsection Who are the Hungry Programmers?
The Hungry Programmers live at @url{http://www.hungry.com} and have
brought much open source software to the world.  The LessTif project, an
OSF/Motif replacement, is one of theirs.

Japhar is also being worked on by members of oryxsoft. They live at
@url{http://www.oryxsoft.com}.

And, of course, there are plenty of volunteers who are neither hungry
nor antelope. Me, I'm a musk ox.

@subsection Who am I? Where am I?
This is a tricky one. Sources of information include: 
@itemize @bullet
@item 
address on mailbox or outside of house
@item 
purse or wallet
@item 
other humans in area
@end itemize

You can also try sending email to yourself; most user mail agents send
along some sort of "name" with the To: email address.

@section Meta Data

@subsection Who's responsible for this stupid FAQ?
That would be @email{tumu@@worldofbeverage.net}. There are those who
call me Paul Reavis. 

I am new to this texinfo stuff, so be gentle. 

This thing is in CVS along with all the source, though, so the other
developers also contribute to the doc.

@subsection Where can I get a fresher, less smelly, copy?
Try the japhar www site. The latest source distribution should have the
latest docs.  Recent HTML version should be at
@url{http://www.mindspring.com/~tumu/japhar/}.

@section The Japhar Project

@subsection Where can I find information about Japhar?
The official www site is @url{http://www.hungry.com/products/japhar/}.
There is also a developer's mailing list.

@subsection How can I help?
Grab the source. Play with it. Join the mailing list. Lurk awhile. Read
the HACKING file in the source for things to do. Volunteer to do
them. Repeat as necessary.

@subsection What version of Java will Japhar be compatible with?
Compatibility with Sun's Java 1.1 specification is the immediate goal,
though code is already being written for 1.2 compliance as well.

@subsection Will japhar be incorporated into Mozilla?
Japhar is now released under the GNU LGPL, rather than the more
restrictive GPL. This should allow linking into Mozilla and other
non-GPL projects.

@subsection What about the core libraries?
The core classes are a separate project from japhar, but of course the
two projects are highly interconnected.  The project is entitled
JCL, for Java Core Library, and is a GNU project located at
@url{http://www.oryxsoft.com/projects/jcl}.

@section Inside Japhar

@subsection Does Japhar use the patented Sun "_quick" instruction rewriting optimization or anything like it?

No! One of the obvious principles of open source software is that it
shouldn't contain blatant patent infringement.

@subsection What about HotSpot? Are any of its optimizations (synchronization, GC, profiling JIT, etc.) planned for Japhar?

All these things would be great. Want to write them? Sun did not invent
these things out of whole cloth; there is considerable literature
available from academic and other circles. So it is certainly possible
that we could incorporate similar advances to the VM without violating
intellectual property rights.

In any case, getting a reasonably fast but fully-compliant open-source
JVM is the first mission of Japhar. Optimization can come later (unless,
of course, you've got some time on your hands...).

@subsection What garbage collection algorithm does Japhar plan to use?

Whichever one you decide to write. :-) I don't think Japhar currently
has GC, so which algorithm it uses will most likely be determined by
whomever sits down and actually writes the code for one. Several people
have expressed interest, so check with the japhar mailing list to what
the current status is.

@section The Japhar Testsuite
As quality-minded and dedicated software professionals, the japhar
developers have set up a regression testsuite to make sure that the code
doesn't, well, regress.  The testsuite can be copied freely, much like
everything else, and is maintained as part of the source distribution.

@subsection How do I run the testsuite?

@enumerate
@item
You will need the DejaGNU package. 
@item
Be sure your classpath includes Japhar's classes.jar and the current
directory.
@item
Sun's javac should be in your path.
@item
From the testsuite directory run 'make check'.
@end enumerate

@subsection How do I make a new test?

Decide which subdir to place the test. If you want your own subdir, copy
java.lang/execute.exp into the new subdir.  The subdir must start with
"java." to be tested automatically along with all the others.

Make new Java class with its own main. The filename and the classname
must match. It _MUST_ print "PASSED: " if the test went OK, and "FAILED:
" if it didn't.

The simplest test looks like this:

@example
    public class SimpleTest @{
        public static void main(String args[])
        @{
            System.out.println("PASSED: All ok.");
        @}
    @}
@end example

@section Troubles and Troubleshooting

@subsection Nothing works, and I'm seeing "@code{objectref == null in call to virtual method <blah>}" when I run japhar

This is what happens when you've got a pre 1.1.5 (1.1.3, most probably)
classes.zip file.  japhar only works with the JDK1.1.5 classes.zip.

@subsection Hey, japhar is failing some of the tests. What's up?

Japhar can be expected to fail some of the tests at the moment.

Here is the current status, submitted by Petter Reinholdtsen, @email{pere@@games.no}.

@example
I just ran all the tests in the testsuite.  70 passes and 9 failures.
Currently the following fails on i386/Linux RedHat 5.0.  I've added
comments as to why it fails.

  FAIL: ./java.lang/OutOfMemoryErrorTest.java 
        child killed: 
        bus error java frame: java/util/Vector.(null) (pc = 4) 
        java frame: java/util/Vector.(null) (pc = 10) 
        java frame: OutOfMemoryErrorTest.main (pc = 29)
   
  - We don't throw exceptions where we should

  FAIL: ./java.lang/SyncronizedTest.java   
        timer triggered run object = 0x8345180
        run object = 0x8366a40 child process exited abnormally
   
  - This one beats me...
 
  FAIL: ./java.net/DatagramSocketSendReceiveTest.java   
        timer triggered run object = 0x83aceb8 
        run object = 0x8395718 
        child process exited abnormally

  FAIL: ./java.net/SocketSendReceiveTest.java   
        timer triggered run object = 0x83ad190 
        run object = 0x83959f0 
        child process exited abnormally

  - Not sure where these hang either

  FAIL: ./java.opstack/LeftBehind.j  
        Exception 'java/lang/ClassNotFoundException 
        (LeftBehind)' reached the toplevel.

  - I'm missing the java assembler

  FAIL: ./java.sun.awt/FrameMenuTest.java  
        child killed: bus error
  FAIL: ./java.sun.awt/FrameTest.java  
        child killed: bus error
  
  - AWT has newer worked.  I think it goes in an endless loop...

  FAIL: ./java.sun.tools/JavacTest.java  
        /tmp/japhar/bin/japhar: error in loading shared libraries 
        /tmp/japhar/lib/libjaphar_zip.so: undefined symbol: inflateInit_

   - libtool fail to link -lz with libjaphar_zip.so

  FAIL: ./java.util/ResourceBundleTest.java   
        java.util.MissingResourceException:
        can't find resource for sun.tools.javac.resources.javac_en

   - No idea

@end example
