Subversion Repositories openrisc

\input texinfo @c -*-texinfo-*-

@setfilename gcj.info

@settitle Guide to GNU gcj

@c Merge the standard indexes into a single one.

@syncodeindex fn cp

@syncodeindex vr cp

@syncodeindex ky cp

@syncodeindex pg cp

@syncodeindex tp cp

@include gcc-common.texi

@c Note: When reading this manual you'll find lots of strange

@c circumlocutions like ``compiler for the Java language''.

@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, 2003, 2004, 2005, 2006, 2007, 2008, 2010

@copying

@c man begin COPYRIGHT

Copyright @copyright{} @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.3 or

any later version published by the Free Software Foundation; with no

Invariant Sections, 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

@c man begin COPYRIGHT

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

@c man end

@end copying

@ifinfo

@format

@dircategory Software development

@direntry

* Gcj: (gcj).               Ahead-of-time compiler for the Java language

@end direntry

@dircategory Individual utilities

@direntry

* jcf-dump: (gcj)Invoking jcf-dump.

                            Print information about Java class files

* gij: (gcj)Invoking gij.   GNU interpreter for Java bytecode

* gcj-dbtool: (gcj)Invoking gcj-dbtool.

                            Tool for manipulating class file databases.

* jv-convert: (gcj)Invoking jv-convert.

                            Convert file from one encoding to another

* grmic: (gcj)Invoking grmic.

                            Generate stubs for Remote Method Invocation.

* gc-analyze: (gcj)Invoking gc-analyze.

                            Analyze Garbage Collector (GC) memory dumps.

* aot-compile: (gcj)Invoking aot-compile.

                            Compile bytecode to native and generate databases.

* rebuild-gcj-db: (gcj)Invoking rebuild-gcj-db.

                            Merge the per-solib databases made by aot-compile

                            into one system-wide database.

@end direntry

@end format

@insertcopying

@end ifinfo

@titlepage

@title GNU gcj

@versionsubtitle

@author Tom Tromey

@page

@vskip 0pt plus 1filll

Published by the Free Software Foundation @*

51 Franklin Street, Fifth Floor@*

Boston, MA 02110-1301, USA@*

@sp 1

@insertcopying

@end titlepage

@contents

@page

@node Top

@top Introduction

This manual describes how to use @command{gcj}, the GNU compiler for the

Java programming language.  @command{gcj} can generate both @file{.class}

files and object files, and it can read both Java source code and

@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 @command{gcj}

* Compatibility::       Compatibility between gcj and other tools for Java

* Invoking jcf-dump::   Print information about class files

* Invoking gij::        Interpreting Java bytecodes

* Invoking gcj-dbtool:: Tool for manipulating class file databases.

* Invoking jv-convert:: Converting from one encoding to another

* Invoking grmic::      Generate stubs for Remote Method Invocation.

* Invoking gc-analyze:: Analyze Garbage Collector (GC) memory dumps.

* Invoking aot-compile:: Compile bytecode to native and generate databases.

* Invoking rebuild-gcj-db:: Merge the per-solib databases made by aot-compile

                            into one system-wide database.

* About CNI::           Description of the Compiled Native Interface

* System properties::   Modifying runtime behavior of the libgcj library

* Resources::           Where to look for more information

* Index::               Index.

@end menu

@include gpl_v3.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{--resource} @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), gjnih(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 gcj

As @command{gcj} is just another front end to @command{gcc}, it supports many

of the same options as gcc.  @xref{Option Summary, , Option Summary,

gcc, Using the GNU Compiler Collection (GCC)}.  This manual only documents the

options specific to @command{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

* Linking::                     Options for making an executable

* Code Generation::             Options controlling the output of 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 @command{gcj} command is like a @command{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.  Files in

an archive which don't end with @samp{.class} are treated as

resource files; they are compiled into the resulting object file

as @samp{core:} URLs.

@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 @command{gcc} manual.

@end table

You can specify more than one input file on the @command{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{--resource}.

(This is an extension beyond the what plain @command{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

@cindex class path

@command{gcj} has options to control where it looks to find files it needs.

For instance, @command{gcj} might need to load a class that is referenced

by the file it has been asked to compile.  Like other compilers for the

Java language, @command{gcj} has a notion of a @dfn{class path}.  There are

several options and environment variables which can be used to

manipulate the class path.  When @command{gcj} looks for a given class, it

searches the class path looking for matching @file{.class} or

@file{.java} file.  @command{gcj} comes with a built-in class path which

points at the installed @file{libgcj.jar}, a file which contains all the

standard classes.

In the text below, a directory or path component can refer either to an

actual directory on the filesystem, or to a @file{.zip} or @file{.jar}

file, which @command{gcj} will search as if it is a directory.

@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

compatibility with tools like @code{javac} is important, we recommend

always using @code{-I} instead of the other options for manipulating the

class path.

@item --classpath=@var{path}

This sets the class path to @var{path}, a colon-separated list of paths

(on Windows-based systems, a semicolon-separate list of paths).

This does not override the builtin (``boot'') search path.

@item --CLASSPATH=@var{path}

Deprecated synonym for @code{--classpath}.

@item --bootclasspath=@var{path}

Where to find the standard builtin classes, such as @code{java.lang.String}.

@item --extdirs=@var{path}

For each directory in the @var{path}, place the contents of that

directory at the end of the class path.

@item CLASSPATH

This is an environment variable which holds a list of paths.

@end table

The final class path is constructed like so:

@itemize @bullet

@item

First come all directories specified via @code{-I}.

@item

If @option{--classpath} is specified, its value is appended.

Otherwise, if the @code{CLASSPATH} environment variable is specified,

then its value is appended.

Otherwise, the current directory (@code{"."}) is appended.

@item

If @code{--bootclasspath} was specified, append its value.

Otherwise, append the built-in system directory, @file{libgcj.jar}.

@item

Finally, if @code{--extdirs} was specified, append the contents of the

specified directories at the end of the class path.  Otherwise, append

the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.

@end itemize

The classfile built by @command{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.

@item -fsource=@var{VERSION}

This option is used to choose the source version accepted by

@command{gcj}.  The default is @samp{1.5}.

@end table

@node Encodings

@section Encodings

The Java programming language uses Unicode throughout.  In an effort to

integrate well with other locales, @command{gcj} allows @file{.java} files

to be written using almost any encoding.  @command{gcj} knows how to

convert these encodings into its internal encoding at compile time.

You can use the @code{--encoding=@var{NAME}} option to specify an

encoding (of a particular character set) to use for source files.  If

this is not specified, the default encoding comes from your current

locale.  If your host system has insufficient locale support, then

@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding

of Unicode.

To implement @code{--encoding}, @command{gcj} simply uses the host

platform's @code{iconv} conversion routine.  This means that in practice

@command{gcj} is limited by the capabilities of the host platform.

The names allowed for the argument @code{--encoding} vary from platform

to platform (since they are not standardized anywhere).  However,

@command{gcj} implements the encoding named @samp{UTF-8} internally, so if

you choose to use this for your source files you can be assured that it

will work on every host.

@node Warnings

@section Warnings

@command{gcj} implements several warnings.  As with other generic

@command{gcc} warnings, if an option of the form @code{-Wfoo} enables a

warning, then @code{-Wno-foo} will disable it.  Here we've chosen to

document the form of the warning which will have an effect -- the

default being the opposite of what is listed.

@table @gcctabopt

@item -Wredundant-modifiers

With this flag, @command{gcj} will warn about redundant modifiers.  For

instance, it will warn if an interface method is declared @code{public}.

@item -Wextraneous-semicolon

This causes @command{gcj} to warn about empty statements.  Empty statements

have been deprecated.

@item -Wno-out-of-date

This option will cause @command{gcj} not to warn when a source file is

newer than its matching class file.  By default @command{gcj} will warn

about this.

@item -Wno-deprecated

Warn if a deprecated class, method, or field is referred to.

@item -Wunused

This is the same as @command{gcc}'s @code{-Wunused}.

@item -Wall

This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon

-Wunused}.

@end table

@node Linking

@section Linking

To turn a Java application into an executable program,

you need to link it with the needed libraries, just as for C or C++.

The linker by default looks for a global function named @code{main}.

Since Java does not have global functions, and a

collection of Java classes may have more than one class with a

@code{main} method, you need to let the linker know which of those

@code{main} methods it should invoke when starting the application.

You can do that in any of these ways:

@itemize @bullet

@item

Specify the class containing the desired @code{main} method

when you link the application, using the @code{--main} flag,

described below.

@item

Link the Java package(s) into a shared library (dll) rather than an

executable.  Then invoke the application using the @code{gij} program,

making sure that @code{gij} can find the libraries it needs.

@item

Link the Java packages(s) with the flag @code{-lgij}, which links

in the @code{main} routine from the @code{gij} command.

This allows you to select the class whose @code{main} method you

want to run when you run the application.  You can also use

other @code{gij} flags, such as @code{-D} flags to set properties.

Using the @code{-lgij} library (rather than the @code{gij} program

of the previous mechanism) has some advantages: it is compatible with

static linking, and does not require configuring or installing libraries.

@end itemize

These @code{gij} options relate to linking an executable:

@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

run.

@item -D@var{name}[=@var{value}]

This option can only be used with @code{--main}.  It defines a system

property named @var{name} with value @var{value}.  If @var{value} is not

specified then it defaults to the empty string.  These system properties

are initialized at the program's startup and can be retrieved at runtime

using the @code{java.lang.System.getProperty} method.

@item -lgij

Create an application whose command-line processing is that

of the @code{gij} command.

This option is an alternative to using @code{--main}; you cannot use both.

@item -static-libgcj

This option causes linking to be done against a static version of the

libgcj runtime library.  This option is only available if

corresponding linker support exists.

@strong{Caution:} Static linking of libgcj may cause essential parts

of libgcj to be omitted.  Some parts of libgcj use reflection to load

classes at runtime.  Since the linker does not see these references at

link time, it can omit the referred to classes.  The result is usually

(but not always) a @code{ClassNotFoundException} being thrown at

runtime. Caution must be used when using this option.  For more

details see:

@w{@uref{http://gcc.gnu.org/wiki/Statically%20linking%20libgcj}}

@end table

@node Code Generation

@section Code Generation

In addition to the many @command{gcc} options controlling code generation,

@command{gcj} has several options specific to itself.

@table @gcctabopt

@item -C

This option is used to tell @command{gcj} to generate bytecode

(@file{.class} files) rather than object code.

@item --resource @var{resource-name}

This option is used to tell @command{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 @samp{core:/@var{resource-name}}.  Note that

@var{resource-name} is the name of the resource as found at runtime; for

instance, it could be used in a call to @code{ResourceBundle.getBundle}.

The actual file name to be compiled this way must be specified

separately.

@item -ftarget=@var{VERSION}

This can be used with @option{-C} to choose the version of bytecode

emitted by @command{gcj}.  The default is @samp{1.5}.  When not

generating bytecode, this option has no effect.

@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

default they will be put in subdirectories of the current working

directory.

@item -fno-bounds-check

By default, @command{gcj} generates code which checks the bounds of all

array indexing operations.  With this option, these checks are omitted, which

can improve performance for code that uses arrays extensively.  Note that this

can result in unpredictable behavior if the code in question actually does

violate array bounds constraints.  It is safe to use this option if you are

sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.

@item -fno-store-check

Don't generate array store checks.  When storing objects into arrays, a runtime

check is normally generated in order to ensure that the object is assignment

compatible with the component type of the array (which may not be known

at compile-time).  With this option, these checks are omitted.  This can

improve performance for code which stores objects into arrays frequently.

It is safe to use this option if you are sure your code will never throw an

@code{ArrayStoreException}.

@item -fjni

With @command{gcj} there are two options for writing native methods: CNI

and JNI@.  By default @command{gcj} assumes you are using CNI@.  If you are

compiling a class with native methods, and these methods are implemented

using JNI, then you must use @code{-fjni}.  This option causes

@command{gcj} to generate stubs which will invoke the underlying JNI

methods.

@item -fno-assert

Don't recognize the @code{assert} keyword.  This is for compatibility

with older versions of the language specification.

@item -fno-optimize-static-class-initialization

When the optimization level is greater or equal to @code{-O2},

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

@item --disable-assertions[=@var{class-or-package}]

Don't include code for checking assertions in the compiled code.

If @code{=@var{class-or-package}} is missing disables assertion code

generation for all classes, unless overridden by a more

specific @code{--enable-assertions} flag.

If @var{class-or-package} is a class name, only disables generating

assertion checks within the named class or its inner classes.

If @var{class-or-package} is a package name, disables generating

assertion checks within the named package or a subpackage.

By default, assertions are enabled when generating class files

or when not optimizing, and disabled when generating optimized binaries.

@item --enable-assertions[=@var{class-or-package}]

Generates code to check assertions.  The option is perhaps misnamed,

as you still need to turn on assertion checking at run-time,

and we don't support any easy way to do that.

So this flag isn't very useful yet, except to partially override

@code{--disable-assertions}.

@item -findirect-dispatch

@command{gcj} has a special binary compatibility ABI, which is enabled

by the @code{-findirect-dispatch} option.  In this mode, the code

generated by @command{gcj} honors the binary compatibility guarantees

in the Java Language Specification, and the resulting object files do

not need to be directly linked against their dependencies.  Instead,

all dependencies are looked up at runtime.  This allows free mixing of

interpreted and compiled code.

Note that, at present, @code{-findirect-dispatch} can only be used

when compiling @file{.class} files.  It will not work when compiling

from source.  CNI also does not yet work with the binary compatibility

ABI.  These restrictions will be lifted in some future release.

However, if you compile CNI code with the standard ABI, you can call

it from code built with the binary compatibility ABI.

@item -fbootstrap-classes

This option can be use to tell @code{libgcj} that the compiled classes

should be loaded by the bootstrap loader, not the system class loader.

By default, if you compile a class and link it into an executable, it

will be treated as if it was loaded using the system class loader.

This is convenient, as it means that things like

@code{Class.forName()} will search @samp{CLASSPATH} to find the

desired class.

@item -freduced-reflection

This option causes the code generated by @command{gcj} to contain a

reduced amount of the class meta-data used to support runtime

reflection. The cost of this savings is the loss of

the ability to use certain reflection capabilities of the standard

Java runtime environment. When set all meta-data except for that

which is needed to obtain correct runtime semantics is eliminated.

For code that does not use reflection (i.e. serialization, RMI, CORBA

or call methods in the @code{java.lang.reflect} package),

@code{-freduced-reflection} will result in proper operation with a

savings in executable code size.

JNI (@code{-fjni}) and the binary compatibility ABI

(@code{-findirect-dispatch}) do not work properly without full

reflection meta-data.  Because of this, it is an error to use these options

with @code{-freduced-reflection}.

@strong{Caution:} If there is no reflection meta-data, code that uses

a @code{SecurityManager} may not work properly.  Also calling

@code{Class.forName()} may fail if the calling method has no

reflection meta-data.

@end table

@node Configure-time Options

@section Configure-time Options

Some @command{gcj} code generations options affect the resulting ABI, and

so can only be meaningfully given when @code{libgcj}, the runtime

package, is configured.  @code{libgcj} puts the appropriate options from

this group into a @samp{spec} file which is read by @command{gcj}.  These

options are listed here for completeness; if you are using @code{libgcj}

then you won't want to touch these options.

@table @gcctabopt

@item -fuse-boehm-gc

This enables the use of the Boehm GC bitmap marking code.  In particular

this causes @command{gcj} to put an object marking descriptor into each

vtable.

@item -fhash-synchronization

By default, synchronization data (the data used for @code{synchronize},

@code{wait}, and @code{notify}) is pointed to by a word in each object.

With this option @command{gcj} assumes that this information is stored in a

hash table and not in the object itself.

@item -fuse-divide-subroutine

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.

@item -fuse-atomic-builtins

On some systems, gcc can generate code for built-in atomic operations.

Use this option to force gcj to use these builtins when compiling Java

code.  Where this capability is present it should be automatically

detected, so you won't usually need to use this option.

@end table

@c man end

@node Compatibility

@chapter Compatibility with the Java Platform

As we believe it is important that the Java platform not be fragmented,

@command{gcj} and @code{libgcj} try to conform to the relevant Java

specifications.  However, limited manpower and incomplete and unclear

documentation work against us.  So, there are caveats to using

@command{gcj}.

@menu

* Limitations::

* Extensions::

@end menu

@node Limitations

@section Standard features not yet supported

This list of compatibility issues is by no means complete.

@itemize @bullet

@item

@command{gcj} implements the JDK 1.2 language.  It supports inner classes

and the new 1.4 @code{assert} keyword.  It does not yet support the Java 2

@code{strictfp} keyword (it recognizes the keyword but ignores it).

@item

@code{libgcj} is largely compatible with the JDK 1.2 libraries.

However, @code{libgcj} is missing many packages, most notably

@code{java.awt}.  There are also individual missing classes and methods.

We currently do not have a list showing differences between

@code{libgcj} and the Java 2 platform.

@item

Sometimes the @code{libgcj} implementation of a method or class differs

from the JDK implementation.  This is not always a bug.  Still, if it

affects you, it probably makes sense to report it so that we can discuss

the appropriate response.

@item

@command{gcj} does not currently allow for piecemeal replacement of

components within @code{libgcj}. Unfortunately, programmers often want

to use newer versions of certain packages, such as those provided by

the Apache Software Foundation's Jakarta project.  This has forced us

to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into

their own libraries, separate from @code{libgcj}.  If you intend to

use these classes, you must link them explicitly with

@code{-l-org-w3c-dom} and @code{-l-org-xml-sax}.  Future versions of

@command{gcj} may not have this restriction.

@end itemize

@node Extensions

@section Extra features unique to gcj

The main feature of @command{gcj} is that it can compile programs written in

the Java programming language to native code.  Most extensions that have been

added are to facilitate this functionality.

@itemize @bullet

@item

@command{gcj} makes it easy and efficient to mix code written in Java and C++.

@xref{About CNI}, for more info on how to use this in your programs.

@item

When you compile your classes into a shared library using

@code{-findirect-dispatch} then add them to the system-wide

classmap.db file using @code{gcj-dbtool}, they will be automatically

loaded by the @code{libgcj} system classloader.  This is the new,

preferred classname-to-library resolution mechanism.  @xref{Invoking

gcj-dbtool}, for more information on using the classmap database.

@item

The old classname-to-library lookup mechanism is still supported

through the @code{gnu.gcj.runtime.VMClassLoader.library_control}

property, but it is deprecated and will likely be removed in some

future release.  When trying to load a class @code{gnu.pkg.SomeClass}

the system classloader will first try to load the shared library

@file{lib-gnu-pkg-SomeClass.so}, if that fails to load the class then

it will try to load @file{lib-gnu-pkg.so} and finally when the class

is still not loaded it will try to load @file{lib-gnu.so}.  Note that

all @samp{.}s will be transformed into @samp{-}s and that searching

for inner classes starts with their outermost outer class.  If the

class cannot be found this way the system classloader tries to use the

@code{libgcj} bytecode interpreter to load the class from the standard

classpath.  This process can be controlled to some degree via the

@code{gnu.gcj.runtime.VMClassLoader.library_control} property;

@xref{libgcj Runtime Properties}.

@item

@code{libgcj} includes a special @samp{gcjlib} URL type.  A URL of

this form is like a @code{jar} URL, and looks like

@samp{gcjlib:/path/to/shared/library.so!/path/to/resource}.  An access

to one of these URLs causes the shared library to be @code{dlopen()}d,

and then the resource is looked for in that library.  These URLs are

most useful when used in conjunction with @code{java.net.URLClassLoader}.

Note that, due to implementation limitations, currently any such URL

can be accessed by only one class loader, and libraries are never

unloaded.  This means some care must be exercised to make sure that

a @code{gcjlib} URL is not accessed by more than one class loader at once.

In a future release this limitation will be lifted, and such

libraries will be mapped privately.

@item

A program compiled by @command{gcj} will examine the

@env{GCJ_PROPERTIES} environment variable and change its behavior in

some ways.  In particular @env{GCJ_PROPERTIES} holds a list of

assignments to global properties, such as would be set with the

@option{-D} option to @command{java}.  For instance,

@samp{java.compiler=gcj} is a valid (but currently meaningless)

setting.

@cindex GCJ_PROPERTIES

@vindex GCJ_PROPERTIES

@end itemize

@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 specified by class name

or file name.

@c man end

@c man begin OPTIONS jcf-dump

@table @gcctabopt

@item -c

Disassemble method bodies.  By default method bodies are not printed.

@item --print-constants

Print the constant pool.  When printing a reference to a constant

also print its index in the constant pool.

@item --javap

Generate output in @code{javap} format.  The implementation of this

feature is very incomplete.

@item --classpath=@var{path}

@itemx --CLASSPATH=@var{path}

@itemx -I@var{directory}

@itemx -o @var{file}

These options as the same as the corresponding @command{gcj} options.

@item --help

Print help, then exit.

@item --version

Print version number, then exit.

@item -v, --verbose

Print extra information while running.

Implies @code{--print-constants}.

@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{-cp} @var{path}] [@option{-classpath} @var{path}]

  [@option{-D}@var{name}[=@var{value}]@dots{}]

  [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]

  [@option{-X@var{argument}}] [@option{-verbose}] [@option{-verbose:class}]

  [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]

@c man end

@c man begin SEEALSO gij

gcc(1), gcj(1), gcjh(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

targets supported by @command{gcj}.

The primary argument to @code{gij} is the name of a class or, with

@code{-jar}, a jar file.  Options before this argument are interpreted

by @code{gij}; remaining options are passed to the interpreted program.

If a class name is specified and this class does not have a @code{main}

method with the appropriate signature (a @code{static void} method with

a @code{String[]} as its sole argument), then @code{gij} will print an

error and exit.

If a jar file is specified then @code{gij} will use information in it to

determine which class' @code{main} method will be invoked.

@code{gij} will invoke the @code{main} method with all the remaining

command-line options.

Note that @code{gij} is not limited to interpreting code.  Because

@code{libgcj} includes a class loader which can dynamically load shared

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.

@c man end

@c man begin OPTIONS gij

@table @gcctabopt

@item -cp @var{path}

@itemx -classpath @var{path}

Set the initial class path.  The class path is used for finding

class and resource files.  If specified, this option overrides the

@code{CLASSPATH} environment variable.  Note that this option is

ignored if @code{-jar} is used.

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

These system properties are initialized at the program's startup and can

be retrieved at runtime using the @code{java.lang.System.getProperty}

method.

@item -ms=@var{number}

Equivalent to @code{-Xms}.

@item -mx=@var{number}

Equivalent to @code{-Xmx}.

@item -noverify

Do not verify compliance of bytecode with the VM specification. In addition,

this option disables type verification which is otherwise performed on BC-ABI

compiled code.

@item -X

@itemx -X@var{argument}

Supplying @code{-X} by itself will cause @code{gij} to list all the

supported @code{-X} options.  Currently these options are supported:

@table @gcctabopt

@item -Xms@var{size}

Set the initial heap size.

@item -Xmx@var{size}

Set the maximum heap size.

@item -Xss@var{size}

Set the thread stack size.

@end table

Unrecognized @code{-X} options are ignored, for compatibility with

other runtimes.

@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

@itemx -?

Print help, then exit.

@item --showversion

Print version number and continue.

@item --fullversion

Print detailed version information, then exit.

@item --version

Print version number, then exit.

@item -verbose

@itemx -verbose:class

Each time a class is initialized, print a short message on standard error.

@end table

@code{gij} also recognizes and ignores the following options, for

compatibility with existing application launch scripts:

@code{-client}, @code{-server}, @code{-hotspot}, @code{-jrockit},

@code{-agentlib}, @code{-agentpath}, @code{-debug}, @code{-d32},

@code{-d64}, @code{-javaagent}, @code{-noclassgc}, @code{-verify},

and @code{-verifyremote}.

@c man end

@node Invoking gcj-dbtool

@chapter Invoking gcj-dbtool.

@c man title gcj-dbtool Manipulate class file mapping databases for libgcj

@ignore

@c man begin SYNOPSIS gcj-dbtool

gcj-dbtool @option{OPTION} @var{DBFILE} [@option{MORE}] @dots{}

gcj-dbtool [@option{-0}] [@option{-}] [@option{-n}] [@option{-a}] [@option{-f}]

  [@option{-t}] [@option{-l}] [@option{-p} [@var{LIBDIR}]]

  [@option{-v}] [@option{-m}] [@option{--version}] [@option{--help}]

@c man end

@c man begin SEEALSO gcj-dbtool