@node    Tools,    Index,  Install, Top
@chapter Tools

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

@section 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...]


@section dump-class    

@code{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.

@subsection usage:
@code{dump-class [OPTIONS] ClassName1 ClassName2 ...}

@table @samp

@item --ascii
Output the files as plain ascii text. (default)

@item --html
Output the files using HTML.

@end table


@section japhar        
The VM runtime. 

@subsection usage: 
@code{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.

@table @samp

@item --classpath=PATH  
use PATH to lookup classes

@item --help
display this help and exit

@item --version
output version information and exit

@end table


@section japharh       
Generates C header files and stubs for a java class.

@subsection usage:  
@code{javah [--d directory] [--stubs|--header] [--classpath classpath]+ classes...}


@section 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 @code{tar}, so watch out.

@subsection usage: 
@code{jar @{ctx@}[vfm0M] [jar-file] [manifest-file] files ...}

@table @samp    

@item -c  
create new archive

@item -t  
list table of contents for archive

@item -x  
extract named (or all) files from archive

@item -v  
generate verbose output on standard error

@item -f  
specify archive file name

@item -m  
include manifest information from specified manifest file

@item -0  
store only; use no ZIP compression

@item -M  
Do not create a manifest file for the entries

@end table

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

@section javac         
The java compiler.

@subsection usage: 
@code{javac [-g][-O][-debug][-depend][-nowarn][-verbose][-classpath path][-nowrite][-deprecation][-d dir][-J<runtime flag>] file.java...}

@table @samp
@item -g
Compile with debugging information.
@item -O
Optimize generated bytecodes.
@item -debug
[duh... I dunno.]
@item -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.
@item -nowarn
Turns off nagging for those who know better than the compiler.
@item -verbose
Spews out reams of stuff, including when each class is found, loaded, compiled, etc.
@item -classpath <path>
Lets you specify the classpath explicitly.
@item -nowrite
[I have no idea]
@item -deprecation
Nags you more vigorously about deprecated methods.
@item -d <dir>
Compiles the classes to the directory tree rooted at dir.
@item -J<runtime flag>
Lets you raise some runtime flags.
@end table

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

@subsection usage: 
@code{javadoc flags* [class | package]*}
@table @samp
@item -sourcepath <path>  
Colon-separated list of source-file directories
@item -classpath <path>   
Synonym for -sourcepath
@item -d <directory>
Destination directory for output files
@item -version
Include @@version paragraphs
@item -nodeprecated
Exclude @@deprecated paragraphs
@item -author             
Include @@author paragraphs
@item -noindex
Do not generate method and field index
@item -notree
Do not generate class hierarchy
@item -public
show only public classes and members
@item -protected
show protected/public classes and members (default)
@item -package
show package/protected/public classes and members
@item -private
show all classes and members
@item -J<flag>
Pass <flag> directly to the runtime system
@item -encoding <name>
Source file encoding name
@item -docencoding <name>
Output encoding name
@end table

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

@subsection usage:
javakey
@table @samp
 
@item l 
list of the identities in the database.

@item c
create an new identity.

@item r
remove an identity from the database.

@item i
import a public key, a key pair, etc.

@item g 
generate a key pair, a certificate, etc.

@item d 
display a certficate.
@end table


@section javap         
A bytecode dissassembler.

@subsection usage: 
javap <options> <classes>...

where options include:
@table @samp

@item -b
Backward compatibility with javap in JDK 1.1

@item -c
Disassemble the code

@item -classpath <directories separated by colons>
List directories in which to look for classes

@item -l
Print line number and local variable tables

@item -public 
Show only public classes and members

@item -protected 
Show protected/public classes and members

@item -package
Show package/protected/public classes
and members (default)

@item -private
Show all classes and members

@item -s
Print internal type signatures

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

@item -version
Print the javap version string

@item -verify 
Run the verifier

@end table


@section 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...]


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

@subsection usage:
@code{rmiregistry [port]}


@section 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...]

@subsection usage:
@code{native2ascii [sourcefile] [destinationfile]}


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

@subsection usage:
@code{serialver [-show] [classname...]}

@table @samp
@item -show
Pops up a little GUI [I think; it certainly doesn't now].
@end table


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

@subsection usage: 
@code{rmic [-g][-O][-debug][-depend][-nowarn][-verbose][-classpath path][-nowrite][-d dir][-dstub dir][-dskel dir][-show][-keepgenerated] classname...}

