gcj.texi

来自「理解和实践操作系统的一本好书」· TEXI 代码 · 共 1,908 行 · 第 1/5 页

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