This is Info file japhar.info, produced by Makeinfo version 1.68 from
the input file japhar.texi.

INFO-DIR-SECTION Java Tools
START-INFO-DIR-ENTRY
* japhar::                           Japhar Java Virtual Machine
END-INFO-DIR-ENTRY

   This is the info documentation for Japhar.


File: japhar.info,  Node: Top,  Next: About Japhar,  Up: (dir)

* Menu:

* About Japhar::        Overview of the Japhar VM.
* FAQ::                 Frequently Asked Questions about Japhar.
* Install::             Installing Japhar.
* Tools::               The Japhar command set.
* Index::               The index, or course.


File: japhar.info,  Node: About Japhar,  Next: FAQ,  Prev: Top,  Up: Top

About Japhar
************

What is it?
===========

   Japhar is the Hungry Programer's Java VM. It has been built from the
ground up without consulting Sun's sources.

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 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.

   Downloads of the distribution are available at:
ftp://ftp.hungry.com/pub/hungry/japhar.

Mailing List : Want to Help?
============================

   We've set up a mailing list for discussion about japhar. The address
is japhar@hungry.com.  To subscribe, send a message with subscribe in
the Subject: line to japhar-request@hungry.com.

Regression Testing
==================

   We have made a DejaGNU testsuite for Java which we use to assure
that no new bugs sneak into the distribution. We recommend that you run
the tests and check for new bugs before you send patches. You will need
the DejaGNU distribution to get 'runtest'. It can be found at
ftp://ftp.cygnus.com/pub/dejagnu.  To actually run the tests, cd to the
'testsuite' directory and do 'make check'.


File: japhar.info,  Node: FAQ,  Next: Install,  Prev: About Japhar,  Up: Top

FAQ
***

   Here is the beginnings of an FAQ for Japhar.

Basic Clues
===========

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.

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.

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 <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.

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
<http://www.javasoft.com> if you need more.

Who are the Hungry Programmers?
-------------------------------

   The Hungry Programmers live at `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
`http://www.oryxsoft.com'.

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

Who am I? Where am I?
---------------------

   This is a tricky one. Sources of information include:
   * address on mailbox or outside of house

   * purse or wallet

   * other humans in area

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

Meta Data
=========

Who's responsible for this stupid FAQ?
--------------------------------------

   That would be <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.

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
`http://www.mindspring.com/~tumu/japhar/'.

The Japhar Project
==================

Where can I find information about Japhar?
------------------------------------------

   The official www site is `http://www.hungry.com/products/japhar/'.
There is also a developer's mailing list.

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.

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.

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.

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
`http://www.oryxsoft.com/projects/jcl'.

Inside Japhar
=============

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.

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...).

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.

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.

How do I run the testsuite?
---------------------------

  1. You will need the DejaGNU package.

  2. Be sure your classpath includes Japhar's classes.jar and the
     current directory.

  3. Sun's javac should be in your path.

  4. From the testsuite directory run 'make check'.

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:

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

Troubles and Troubleshooting
============================

Nothing works, and I'm seeing "`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.

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,
<pere@games.no>.

     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


File: japhar.info,  Node: Install,  Next: Tools,  Prev: FAQ,  Up: Top

Install
*******

   Here lies some documentation about Japhar documentation. It is a
supplement to the INSTALL file in the top-level directory of the
distribution.

Failure modes
=============

   Here are some common failure modes and their causes. If you were
stumped by something that isn't in here, send it to me, please, so no
one else has to be.

Trouble with aclocal
--------------------

Macro `AM_DISABLE_STATIC' not found in library
..............................................

     bash-2.01$ aclocal
     aclocal: configure.in: 16: macro `AM_DISABLE_STATIC' not found in library

   You need to have libtool-1.2 installed.

Trouble with class library
--------------------------

NullPointerException
....................

     java/lang/NullPointerException
     (objectref == null in call to virtual method
     'get Property' from java/lang/System.getProperty())
              in java/lang/System.getProperty(pc = 20)
              in sun/tools/javac/Main.main(pc = 9)
   This is the error you get when you use a pre-1.1.5 classes.zip file.
Snag a 1.1.5 classes.zip file and try again.

Archive has a truncated file name
.................................

   This is a problem with Solaris tar.  It seem to be incompatible with
GNU tar on long filenames. (Win95 GNU tar has also been reported to
have problems.)

There is no classes.zip in ./japhar-0.04/classes
................................................

   You will need to fetch it from a preinstalled JDK.  You must give
-with-sun-jdk=<path> to configure.

General ailments
----------------

This release does not seem ready for public consumption.
........................................................

   Japhar is currently in development, and, yes, is not ready for
prime-time. More like late-night on Tuesday.

This thing sucks!
.................

   Yes, japhar sucks. We suck too. Even the documentation says so. :-b


File: japhar.info,  Node: Tools,  Next: Index,  Prev: Install,  Up: Top

Tools
*****

   Japhar provides a set of command-line tools to run Java programs in
the VM.

appletviewer
============

   The appletviewer opens a frame for each applet in an html file. It
is handy for testing those pesky applet things before you unleash them
on your neighbors.

   [currently not working for me...]

dump-class
==========

   `dump-class' disassembles the bytecodes for a class and saves them in
human-readable format, either as a simple text file or as HTML. The
output contains all the method signatures and variable types, formatted
as if they were declaring the class in a java source file. Instead of
java code, however, the method bodies consist of bytecodes and
mnemonics.

usage:
------

   `dump-class [OPTIONS] ClassName1 ClassName2 ...'

`--ascii'
     Output the files as plain ascii text. (default)

`--html'
     Output the files using HTML.

japhar
======

   The VM runtime.

usage:
------

   `japhar [OPTION]... CLASS [ARG]...'

   Execute Java bytecode in CLASS, starting with the method "static
public void main(String[])".  Each ARG is passed into "main" via the
String array.

   Note that, regardless of the value of the CLASSPATH environment
variable or parameters set via the -classpath=PATH option, all .zip and
.jar files in the ../japhar/share directory are added to the classpath
at startup.

`--classpath=PATH'
     use PATH to lookup classes

`--help'
     display this help and exit

`--version'
     output version information and exit

japharh
=======

   Generates C header files and stubs for a java class.

usage:
------

   `javah [--d directory] [--stubs|--header] [--classpath classpath]+
classes...'

jar
===

   Short for Java ARchive, isn't that clever?

   Conglomerates all yer stuff (class files, images, resources, bits of
dirt from floor, etc.)  into one nice file that can be placed in your
classpath or whatever. Basically a zip file with some special
conventions. But the utility works more like `tar', so watch out.

usage:
------

   `jar {ctx}[vfm0M] [jar-file] [manifest-file] files ...'

`-c'
     create new archive

`-t'
     list table of contents for archive

`-x'
     extract named (or all) files from archive

`-v'
     generate verbose output on standard error

`-f'
     specify archive file name

`-m'
     include manifest information from specified manifest file

`-0'
     store only; use no ZIP compression

`-M'
     Do not create a manifest file for the entries

   If any file is a directory then it is processed recursively.
Example: to archive two class files into an archive called classes.jar:
 `jar cvf classes.jar Foo.class Bar.class' Note: use the `0' option to
create a jar file that can be put in your CLASSPATH

javac
=====

   The java compiler.

usage:
------

   `javac [-g][-O][-debug][-depend][-nowarn][-verbose][-classpath
path][-nowrite][-deprecation][-d dir][-J<runtime flag>] file.java...'

`-g'
     Compile with debugging information.

`-O'
     Optimize generated bytecodes.

`-debug'
     [duh... I dunno.]

`-depend'
     Tries to find and compile any classes that the given .java files
     depend on. Recompiles them if the source is more recent,
     make-style.

`-nowarn'
     Turns off nagging for those who know better than the compiler.

`-verbose'
     Spews out reams of stuff, including when each class is found,
     loaded, compiled, etc.

`-classpath <path>'
     Lets you specify the classpath explicitly.

`-nowrite'
     [I have no idea]

`-deprecation'
     Nags you more vigorously about deprecated methods.

`-d <dir>'
     Compiles the classes to the directory tree rooted at dir.

`-J<runtime flag>'
     Lets you raise some runtime flags.

javadoc
=======

   Generates handy html documentation directly from your
oh-so-well-documented source code. Soon to be replaced by japhardoc [or
so I hear?].

usage:
------

   `javadoc flags* [class | package]*'
`-sourcepath <path>'
     Colon-separated list of source-file directories

`-classpath <path>'
     Synonym for -sourcepath

`-d <directory>'
     Destination directory for output files

`-version'
     Include @version paragraphs

`-nodeprecated'
     Exclude @deprecated paragraphs

`-author'
     Include @author paragraphs

`-noindex'
     Do not generate method and field index

`-notree'
     Do not generate class hierarchy

`-public'
     show only public classes and members

`-protected'
     show protected/public classes and members (default)

`-package'
     show package/protected/public classes and members

`-private'
     show all classes and members

`-J<flag>'
     Pass <flag> directly to the runtime system

`-encoding <name>'
     Source file encoding name

`-docencoding <name>'
     Output encoding name

javakey
=======

   Generates digital signatures for archive files. Manages the database
of crypto-stuff.

usage:
------

   javakey
`l'
     list of the identities in the database.

`c'
     create an new identity.

`r'
     remove an identity from the database.

`i'
     import a public key, a key pair, etc.

`g'
     generate a key pair, a certificate, etc.

`d'
     display a certficate.

javap
=====

   A bytecode dissassembler.

usage:
------

   javap <options> <classes>...

   where options include:
`-b'
     Backward compatibility with javap in JDK 1.1

`-c'
     Disassemble the code

`-classpath <directories separated by colons>'
     List directories in which to look for classes

`-l'
     Print line number and local variable tables

`-public'
     Show only public classes and members

`-protected'
     Show protected/public classes and members

`-package'
     Show package/protected/public classes and members (default)

`-private'
     Show all classes and members

`-s'
     Print internal type signatures

`-verbose'
     Print stack size, number of locals and args for methods If
     verifying, print reasons for failure

`-version'
     Print the javap version string

`-verify'
     Run the verifier

jdb
===

   The Japhar debugger. I hear that people who write buggy code
sometimes have to use this; I wouldn't know, myself.

   [currently not working for me...]

rmiregistry
===========

   An rmi naming service thingie.

   Starts a remote object registry on a specified port. The remote
object registry is a bootstrap naming service which is used by RMI
servers.

usage:
------

   `rmiregistry [port]'

native2ascii
============

   Converts non-Unicode Latin-1 (source code or property) files to
Unicode Latin-1.  [I know what this did under MSWindows, never used it
otherwise...]

usage:
------

   `native2ascii [sourcefile] [destinationfile]'

serialver
=========

   Makes up strange numbers for the serialVersionID of your classes.
Check out the docs on java serialization for more info.

usage:
------

   `serialver [-show] [classname...]'

`-show'
     Pops up a little GUI [I think; it certainly doesn't now].

rmic
====

   Generates stub and skeleton class files for Java objects
implementing the java.rmi.Remote interface.

usage:
------

   `rmic [-g][-O][-debug][-depend][-nowarn][-verbose][-classpath
path][-nowrite][-d dir][-dstub dir][-dskel dir][-show][-keepgenerated]
classname...'


File: japhar.info,  Node: Index,  Prev: Tools,  Up: Top

Index
*****

* Menu:


Tag Table:
Node: Top280
Node: About Japhar609
Node: FAQ2519
Node: Install12930
Node: Tools14908
Node: Index22147

End Tag Table
