@c This is necessary due to Sun's restrictions on the use of
@c the word ``Java'.
+@c When this manual is copyrighted.
+@set copyrights-gcj 2001, 2002
+
+@c Versions
+@set version-gcc 3.1
+@set which-gcj GCC-@value{version-gcc}
+
+@macro gcctabopt{body}
+@code{\body\}
+@end macro
@ifinfo
@format
* jcf-dump: (gcj)Invoking jcf-dump.
Print information about Java class files
* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
+* jv-convert: (gcj)Invoking jv-convert.
+ Convert file from one encoding to another
@end direntry
@end format
+
+@c man begin COPYRIGHT
+Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', the Front-Cover
+texts being (a) (see below), and with the Back-Cover Texts being (b)
+(see below). A copy of the license is included in the
+@c man end
+section entitled
+``GNU Free Documentation License''.
+@ignore
+@c man begin COPYRIGHT
+man page gfdl(7).
+@c man end
+@end ignore
+
+(a) The FSF's Front-Cover Text is:
+
+ A GNU Manual
+
+(b) The FSF's Back-Cover Text is:
+
+ You have freedom to copy and modify this GNU Manual, like GNU
+ software. Copies published by the Free Software Foundation raise
+ funds for GNU development.
@end ifinfo
@titlepage
@title GNU gcj
@author Tom Tromey
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
+@sp 2
+For the @value{which-gcj} Version*
+@sp 1
+Published by the Free Software Foundation @*
+59 Temple Place - Suite 330@*
+Boston, MA 02111-1307, USA@*
+@sp 1
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', the Front-Cover
+texts being (a) (see below), and with the Back-Cover Texts being (b)
+(see below). A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+
+(a) The FSF's Front-Cover Text is:
+
+ A GNU Manual
+
+(b) The FSF's Back-Cover Text is:
+
+ You have freedom to copy and modify this GNU Manual, like GNU
+ software. Copies published by the Free Software Foundation raise
+ funds for GNU development.
@end titlepage
+@contents
+@page
+
@node Top
@top Introduction
@file{.class} files.
@menu
+* Copying:: The GNU General Public License
+* GNU Free Documentation License::
+ How you can share and copy this manual
* Invoking gcj:: Compiler options supported by @code{gcj}
* Compatibility:: Compatibility between gcj and other tools for Java
* Invoking gcjh:: Generate header files from class files
* Invoking jv-scan:: Print information about source files
* Invoking jcf-dump:: Print information about class files
* Invoking gij:: Interpreting Java bytecodes
+* Invoking jv-convert:: Converting from one encoding to another
* Resources:: Where to look for more information
@end menu
+@include gpl.texi
+
+@include fdl.texi
+
+
@node Invoking gcj
@chapter Invoking gcj
+@c man title gcj Ahead-of-time compiler for the Java language
+
+@ignore
+@c man begin SYNOPSIS gcj
+gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
+ [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
+ [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
+ [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
+ [@option{-C}] [@option{-R} @var{resource-name}] [@option{-d} @var{directory}]
+ [@option{-W}@var{warn}@dots{}]
+ @var{sourcefile}@dots{}
+@c man end
+@c man begin SEEALSO gcj
+gcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gcj
+
As @code{gcj} is just another front end to @code{gcc}, it supports many
of the same options as gcc. @xref{Option Summary, , Option Summary,
-gcc, Using the GNU Compiler Collection}. This manual only documents the
+gcc, Using the GNU Compiler Collection (GCC)}. This manual only documents the
options specific to @code{gcj}.
+@c man end
+
@menu
+* Input and output files::
* Input Options:: How gcj finds files
* Encodings:: Options controlling source file encoding
* Warnings:: Options controlling warnings specific to gcj
* Configure-time Options:: Options you won't use
@end menu
+@c man begin OPTIONS gcj
+
+@node Input and output files
+@section Input and output files
+
+A @code{gcj} command is like a @code{gcc} command, in that it
+consists of a number of options and file names. The following kinds
+of input file names are supported:
+
+@table @gcctabopt
+@item @var{file}.java
+Java source files.
+@item @var{file}.class
+Java bytecode files.
+@item @var{file}.zip
+@itemx @var{file}.jar
+An archive containing one or more @code{.class} files, all of
+which are compiled. The archive may be compressed.
+@item @@@var{file}
+A file containing a whitespace-separated list of input file names.
+(Currently, these must all be @code{.java} source files, but that
+may change.)
+Each named file is compiled, just as if it had been on the command line.
+@item @var{library}.a
+@itemx @var{library}.so
+@itemx -l@var{libname}
+Libraries to use when linking. See the @code{gcc} manual.
+@end table
+
+You can specify more than one input file on the @code{gcj} command line,
+in which case they will all be compiled. If you specify a
+@code{-o @var{FILENAME}}
+option, all the input files will be compiled together, producing a
+single output file, named @var{FILENAME}.
+This is allowed even when using @code{-S} or @code{-c},
+but not when using @code{-C} or @code{-R}.
+(This is an extension beyond the what plain @code{gcc} allows.)
+(If more than one input file is specified, all must currently
+be @code{.java} files, though we hope to fix this.)
@node Input Options
@section Input Options
actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
file, which @code{gcj} will search as if it is a directory.
-@table @code
+@table @gcctabopt
@item -I@var{dir}
All directories specified by @code{-I} are kept in order and prepended
to the class path constructed from all the other options. Unless
Finally, the built-in system directory, @file{libgcj.jar}, is appended.
@end itemize
+The classfile built by @code{gcj} for the class @code{java.lang.Object}
+(and placed in @code{libgcj.jar}) contains a special zero length
+attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
+attribute when loading @code{java.lang.Object} and will report an error
+if it isn't found, unless it compiles to bytecode (the option
+@code{-fforce-classes-archive-check} can be used to override this
+behavior in this particular case.)
+
+@table @gcctabopt
+@item -fforce-classes-archive-check
+This forces the compiler to always check for the special zero length
+attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
+issue an error if it isn't found.
+@end table
@node Encodings
@section Encodings
document the form of the warning which will have an effect -- the
default being the opposite of what is listed.
-@table @code
+@table @gcctabopt
@item -Wredundant-modifiers
With this flag, @code{gcj} will warn about redundant modifiers. For
instance, it will warn if an interface method is declared @code{public}.
In addition to the many @code{gcc} options controlling code generation,
@code{gcj} has several options specific to itself.
-@table @code
+@table @gcctabopt
@item --main=@var{CLASSNAME}
This option is used when linking to specify the name of the class whose
@code{main} method should be invoked when the resulting executable is
This option is used to tell @code{gcj} to generate bytecode
(@file{.class} files) rather than object code.
+@item -R @var{resource-name}
+This option is used to tell @code{gcj} to compile the contents of a
+given file to object code so it may be accessed at runtime with the core
+protocol handler as @var{core:/resource-name}.
+
@item -d @var{directory}
When used with @code{-C}, this causes all generated @file{.class} files
to be put in the appropriate subdirectory of @var{directory}. By
using JNI, then you must use @code{-fjni}. This option causes
@code{gcj} to generate stubs which will invoke the underlying JNI
methods.
+
+@item -fno-optimize-static-class-initialization
+When the optimization level is greather or equal to @code{-O2},
+@code{gcj} will try to optimize the way calls into the runtime are made
+to initialize static classes upon their first use (this optimization
+isn't carried out if @code{-C} was specified.) When compiling to native
+code, @code{-fno-optimize-static-class-initialization} will turn this
+optimization off, regardless of the optimization level in use.
@end table
options are listed here for completeness; if you are using @code{libgcj}
then you won't want to touch these options.
-@table @code
+@table @gcctabopt
@item -fuse-boehm-gc
This enables the use of the Boehm GC bitmap marking code. In particular
this causes @code{gcj} to put an object marking descriptor into each
On some systems, a library routine is called to perform integer
division. This is required to get exception handling correct when
dividing by zero.
+
+@item -fcheck-references
+On some systems it's necessary to insert inline checks whenever
+accessing an object via a reference. On other systems you won't need
+this because null pointer accesses are caught automatically by the
+processor.
@end table
+@c man end
@node Compatibility
@chapter Compatibility with the Java Platform
@node Invoking gcjh
@chapter Invoking gcjh
+@c man title gcjh generate header files from Java class files
+
+@c man begin DESCRIPTION gcjh
+
The @code{gcjh} program is used to generate header files from class
files. It can generate both CNI and JNI header files, as well as stub
implementation files which can be used as a basis for implementing the
required native methods.
-@table @code
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gcjh
+gcjh [@option{-stubs}] [@option{-jni}]
+ [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
+ [@option{-preprend} @var{text}]
+ [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
+ [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
+ [@option{-o} @var{file}] [@option{-td} @var{dir}]
+ [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
+ [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
+ @var{classname}@dots{}
+@c man end
+@c man begin SEEALSO gcjh
+gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin OPTIONS gcjh
+
+@table @gcctabopt
@item -stubs
This causes @code{gcjh} to generate stub files instead of header files.
By default the stub file will be named after the class, with a suffix of
@item -td @var{directory}
Sets the name of the directory to use for temporary files.
+@item -M
+Print all dependencies to stdout; suppress ordinary output.
+
+@item -MM
+Print non-system dependencies to stdout; suppress ordinary output.
+
+@item -MD
+Print all dependencies to stdout.
+
+@item -MMD
+Print non-system dependencies to stdout.
+
@item --help
Print help about @code{gcjh} and exit. No further processing is done.
@item --version
Print version information for @code{gcjh} and exit. No further
processing is done.
+
+@item -v, --verbose
+Print extra information while running.
@end table
All remaining options are considered to be names of classes.
+@c man end
@node Invoking jv-scan
@chapter Invoking jv-scan
+@c man title jv-scan print information about Java source file
+
+@c man begin DESCRIPTION jv-scan
+
The @code{jv-scan} program can be used to print information about a Java
source file (@file{.java} file).
-@table @code
+@c man end
+
+@ignore
+@c man begin SYNOPSIS jv-scan
+jv-scan [@option{--complexity}] [@option{--encoding}=@var{name}]
+ [@option{--print-main}] [@option{--list-class}] [@option{--list-filename}]
+ [@option{--version}] [@option{--help}]
+ [@option{-o} @var{file}] @var{inputfile}@dots{}
+@c man end
+@c man begin SEEALSO jv-scan
+gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin OPTIONS jv-scan
+
+@table @gcctabopt
@item --complexity
This prints a complexity measure, related to cyclomatic complexity, for
each input file.
@item -o @var{file}
Print output to the named file.
+
+@item --help
+Print help, then exit.
+
+@item --version
+Print version number, then exit.
@end table
+@c man end
@node Invoking jcf-dump
@chapter Invoking jcf-dump
+@c man title jcf-dump print information about Java class files
+
+@ignore
+@c man begin SYNOPSIS jcf-dump
+jcf-dump [@option{-c}] [@option{--javap}]
+ [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
+ [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
+ [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
+ @var{classname}@dots{}
+@c man end
+@c man begin SEEALSO jcf-dump
+gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION jcf-dump
+
This is a class file examiner, similar to @code{javap}. It will print
information about a number of classes, which are specifed by class name
or file name.
-@table @code
+@c man end
+
+@c man begin OPTIONS jcf-dump
+
+@table @gcctabopt
@item -c
Disassemble method bodies. By default method bodies are not printed.
@itemx -I@var{directory}
@itemx -o @var{file}
These options as the same as the corresponding @code{gcj} options.
+
+@item --help
+Print help, then exit.
+
+@item --version
+Print version number, then exit.
+
+@item -v, --verbose
+Print extra information while running.
@end table
+@c man end
@node Invoking gij
@chapter Invoking gij
+@c man title gij GNU interpreter for Java bytecode
+
+@ignore
+@c man begin SYNOPSIS gij
+gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
+
+gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
+ [@option{-D}@var{name}[=@var{value}]@dots{}]
+ [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
+ [@option{--version}] [@option{--help}]
+@c man end
+@c man begin SEEALSO gij
+gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gij
+
@code{gij} is a Java bytecode interpreter included with @code{libgcj}.
@code{gij} is not available on every platform; porting it requires a
small amount of assembly programming which has not been done for all the
objects, it is possible to give @code{gij} the name of a class which has
been compiled and put into a shared library on the class path.
-@table @code
+@c man end
+
+@c man begin OPTIONS gij
+
+@table @gcctabopt
@item -D@var{name}[=@var{value}]
This defines a system property named @var{name} with value @var{value}.
If @var{value} is not specified then it defaults to the empty string.
method.
@item -ms=@var{number}
-This sets the initial heap size
+This sets the initial heap size.
@item -mx=@var{number}
This sets the maximum heap size.
@item -jar
This indicates that the name passed to @code{gij} should be interpreted
as the name of a jar file, not a class.
+
+@item --help
+Print help, then exit.
+
+@item --version
+Print version number, then exit.
@end table
+@c man end
+
+@node Invoking jv-convert
+@chapter Invoking jv-convert
+
+@c man title jv-convert Convert file from one encoding to another
+
+@c man begin synopsis jv-convert
+@command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
+@ignore
+
+ [@option{--encoding} @var{name}]
+ [@option{--from} @var{name}]
+ [@option{--to} @var{name}]
+ [@option{-i} @var{file}] [@option{-o} @var{file}]
+ [@option{--reverse}] [@option{--help}] [@option{--version}]
+@end ignore
+@c man end
+
+@c man begin DESCRIPTION jv-convert
+
+@command{jv-convert} is a utility included with @code{libgcj} which
+converts a file from one encoding to another. It is similar to the Unix
+@command{iconv} utility.
+
+The encodings supported by @command{jv-convert} are platform-dependent.
+Currently there is no way to get a list of all supported encodings.
+
+@c man end
+
+@c man begin OPTIONS jv-convert
+
+@table @gcctabopt
+@item --encoding @var{name}
+@itemx --from @var{name}
+Use @var{name} as the input encoding. The default is the current
+locale's encoding.
+
+@item --to @var{name}
+Use @var{name} as the output encoding. The default is the
+@code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
+non-ASCII characters.
+
+@item -i @var{file}
+Read from @var{file}. The default is to read from standard input.
+
+@item -o @var{file}
+Write to @var{file}. The default is to write to standard output.
+
+@item --reverse
+Swap the input and output encodings.
+
+@item --help
+Print a help message, then exit.
+
+@item --version
+Print version information, then exit.
+@end table
+
+@c man end
@node Resources
@chapter Resources
at @uref{http://java.sun.com/}.
The current @code{gcj} home page is
-@uref{http://sources.redhat.com/java/}. This is likely to change in the
-near future.
+@uref{http://gcc.gnu.org/java/}.
For more information on gcc, see @uref{http://gcc.gnu.org/}.
because the JCK is not free. See
@uref{http://sources.redhat.com/mauve/} for more information.
-@contents
@bye