-@\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@setfilename gcj.info
@settitle Guide to GNU gcj
+@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
@set copyrights-gcj 2001, 2002
@c Versions
-@set version-gcc 3.3
-@set which-gcj GCC-@value{version-gcc}
-
-@macro gcctabopt{body}
-@code{\body\}
-@end macro
-
-@ifinfo
-@format
-@dircategory Programming
-@direntry
-* Gcj: (gcj). Ahead-of-time compiler for the Java language
-@end direntry
-
-@dircategory Individual utilities
-@direntry
-* gcjh: (gcj)Invoking gcjh.
- Generate header files from Java class files
-* jv-scan: (gcj)Invoking jv-scan.
- Print information about Java source files
-* 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
-* rmic: (gcj)Invoking rmic.
- Generate stubs for Remote Method Invocation.
-* rmiregistry: (gcj)Invoking rmiregistry.
- The remote object registry.
-@end direntry
-@end format
+@set which-gcj GCC-@value{version-GCC}
+@copying
@c man begin COPYRIGHT
-Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
+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.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 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)
@c man end
@end ignore
+@c man begin COPYRIGHT
+
(a) The FSF's Front-Cover Text is:
A GNU Manual
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 Programming
+@direntry
+* Gcj: (gcj). Ahead-of-time compiler for the Java language
+@end direntry
+
+@dircategory Individual utilities
+@direntry
+* gcjh: (gcj)Invoking gcjh.
+ Generate header files from Java class files
+* jv-scan: (gcj)Invoking jv-scan.
+ Print information about Java source files
+* 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
+* grmic: (gcj)Invoking grmic.
+ Generate stubs for Remote Method Invocation.
+* grmiregistry: (gcj)Invoking grmiregistry.
+ The remote object registry.
+@end direntry
+@end format
+
+@insertcopying
@end ifinfo
@titlepage
@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.
+@insertcopying
@end titlepage
@contents
@page
* Invoking jcf-dump:: Print information about class files
* Invoking gij:: Interpreting Java bytecodes
* Invoking jv-convert:: Converting from one encoding to another
-* Invoking rmic:: Generate stubs for Remote Method Invocation.
-* Invoking rmiregistry:: The remote object registry.
-* About CNI:: Description of the Cygnus Native Interface
+* Invoking grmic:: Generate stubs for Remote Method Invocation.
+* Invoking grmiregistry:: The remote object registry.
+* About CNI:: Description of the Compiled Native Interface
* System properties:: Modifying runtime behavior of the libgcj library
* Resources:: Where to look for more information
@end menu
* 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
@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.
+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
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}.
@end table
-@node Code Generation
-@section Code Generation
+@node Linking
+@section Linking
-In addition to the many @command{gcc} options controlling code generation,
-@command{gcj} has several options specific to itself.
+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. @footnote{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.}
+run.
@item -D@var{name}[=@var{value}]
This option can only be used with @code{--main}. It defines a system
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.
+@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.
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}.
+
@end table
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
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.
+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 gcjh
@chapter Invoking gcjh
@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 -v, --verbose
Print extra information while running.
+Implies @code{--print-constants}.
@end table
@c man end
[@option{-cp} @var{path}] [@option{-classpath} @var{path}]
[@option{-D}@var{name}[=@var{value}]@dots{}]
[@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
- [@option{--version}] [@option{--help}]
+ [@option{-X@var{argument}]
+ [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
@c man end
@c man begin SEEALSO gij
gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
@item -mx=@var{number}
This sets the maximum heap size.
+@item -X
+@itemx -X@var{argument}
+Supplying @code{-X} by itself will cause @code{gij} to list all the
+supported @code{-X} options. Currently there are none. 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 --version
Print version number, then exit.
+
+@item -verbose:class
+Each time a class is initialized, print a short message on standard error.
@end table
@c man end
@c man end
-@node Invoking rmic
-@chapter Invoking rmic
+@node Invoking grmic
+@chapter Invoking grmic
-@c man title rmic Generate stubs for Remote Method Invocation
+@c man title grmic Generate stubs for Remote Method Invocation
-@c man begin SYNOPSIS rmic
-@command{rmic} [@option{OPTION}] @dots{} @var{class} @dots{}
+@c man begin SYNOPSIS grmic
+@command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
@ignore
[@option{-keep}]
[@option{-keepgenerated}]
@end ignore
@c man end
-@c man begin DESCRIPTION rmic
+@c man begin DESCRIPTION grmic
-@command{rmic} is a utility included with @code{libgcj} which generates
+@command{grmic} is a utility included with @code{libgcj} which generates
stubs for remote objects.
@c FIXME: Add real information here.
@c This really isn't much more than the --help output.
Note that this program isn't yet fully compatible with the JDK
-@command{rmic}. Some options, such as @option{-classpath}, are
+@command{grmic}. Some options, such as @option{-classpath}, are
recognized but currently ignored. We have left these options
undocumented for now.
@c man end
-@c man begin OPTIONS rmic
+@c man begin OPTIONS grmic
@table @gcctabopt
@item -keep
@itemx -keepgenerated
-By default, @command{rmic} deletes intermediate files. Either of these
+By default, @command{grmic} deletes intermediate files. Either of these
options causes it not to delete such files.
@item -v1.1
-Cause @command{rmic} to create stubs and skeletons for the 1.1
+Cause @command{grmic} to create stubs and skeletons for the 1.1
protocol version.
@item -vcompat
-Cause @command{rmic} to create stubs and skeletons compatible with both
+Cause @command{grmic} to create stubs and skeletons compatible with both
the 1.1 and 1.2 protocol versions. This is the default.
@item -v1.2
-Cause @command{rmic} to create stubs and skeletons for the 1.2
+Cause @command{grmic} to create stubs and skeletons for the 1.2
protocol version.
@item -nocompile
Don't compile the generated files.
@item -verbose
-Print information about what @command{rmic} is doing.
+Print information about what @command{grmic} is doing.
@item -d @var{directory}
Put output files in @var{directory}. By default the files are put in
@c man end
-@node Invoking rmiregistry
-@chapter Invoking rmiregistry
+@node Invoking grmiregistry
+@chapter Invoking grmiregistry
-@c man title rmiregistry Remote object registry
+@c man title grmiregistry Remote object registry
-@c man begin SYNOPSIS rmiregistry
-@command{rmic} [@option{OPTION}] @dots{} [@var{port}]
+@c man begin SYNOPSIS grmiregistry
+@command{grmic} [@option{OPTION}] @dots{} [@var{port}]
@ignore
[@option{--help}]
[@option{--version}]
@end ignore
@c man end
-@c man begin DESCRIPTION rmiregistry
+@c man begin DESCRIPTION grmiregistry
-@command{rmiregistry} starts a remote object registry on the current
+@command{grmiregistry} starts a remote object registry on the current
host. If no port number is specified, then port 1099 is used.
@c FIXME: Add real information here.
@c man end
-@c man begin OPTIONS rmiregistry
+@c man begin OPTIONS grmiregistry
@table @gcctabopt
@item --help
@node About CNI
@chapter About CNI
-This documents CNI, the Cygnus Native Interface,
+This documents CNI, the Compiled Native Interface,
which is is a convenient way to write Java native methods using C++.
This is a more efficient, more convenient, but less portable
alternative to the standard JNI (Java Native Interface).
@code{JvNewObjectArray}. This convention is used to avoid conflicts
with other libraries. Internal functions in CNI start with the prefix
@code{_Jv_}. You should not call these; if you find a need to, let us
-know and we will try to come up with an alternate solution. (This
-manual lists @code{_Jv_AllocBytes} as an example; CNI should instead
-provide a @code{JvAllocBytes} function.)
+know and we will try to come up with an alternate solution.
@subsection Limitations
java::util::Hashtable *ht = new java::util::Hashtable(120);
@end example
-@deftypefun void* _Jv_AllocBytes (jsize @var{size})
-Allocates @var{size} bytes from the heap. The memory is not scanned
-by the garbage collector but it freed if no references to it are discovered.
-@end deftypefun
-
@node Arrays
@section Arrays
@}
@end example
-But this restriction can cause a problem so @acronym{CNI} includes the
+@subsection RawData
+
+The above restriction can be problematic, so @acronym{CNI} includes the
@code{gnu.gcj.RawData} class. The @code{RawData} class is a
@dfn{non-scanned reference} type. In other words variables declared
of type @code{RawData} can contain any data and are not checked by the
-compiler in any way.
+compiler or memory manager in any way.
This means that you can put C/C++ data structures (including classes)
in your @acronym{CNI} classes, as long as you use the appropriate cast.
@end example
+@subsection RawDataManaged
+
+@code{gnu.gcj.RawDataManaged} is another type used to indicate special data used
+by native code. Unlike the @code{RawData} type, fields declared as
+@code{RawDataManaged} will be "marked" by the memory manager and
+considered for garbage collection.
+
+Native data which is allocated using CNI's @code{JvAllocBytes()}
+function and stored in a @code{RawDataManaged} will be automatically
+freed when the Java object it is associated with becomes unreachable.
+
+@subsection Native memory allocation
+
+@deftypefun void* JvAllocBytes (jsize @var{size})
+Allocates @var{size} bytes from the heap. The memory returned is zeroed.
+This memory is not scanned for pointers by the garbage collector, but will
+be freed if no references to it are discovered.
+
+This function can be useful if you need to associate some native data with a
+Java object. Using a CNI's special @code{RawDataManaged} type, native data
+allocated with @code{JvAllocBytes} will be automatically freed when the Java
+object itself becomes unreachable.
+@end deftypefun
+
+@subsection Posix signals
+
+On Posix based systems the @code{libgcj} library uses several signals
+internally. @acronym{CNI} code should not attempt to use the same
+signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
+code to fail.
+
+SIGSEGV is used on many systems to generate
+@code{NullPointerExceptions}. SIGCHLD is used internally by
+@code{Runtime.exec()}. Several other signals (that vary from platform to
+platform) can be used by the memory manager and by
+@code{Thread.interrupt()}.
+
@node Exception Handling
@section Exception Handling
The paths (jar files, zip files and directories) used for finding class files.
@item java.library.path
-Directory path used for finding native libraries. Currently not set.
+Directory path used for finding native libraries.
@item java.io.tmpdir
The directory used to put temporary files in.
The class name used for initializing the default @code{java.awt.Toolkit}.
Defaults to @code{gnu.awt.gtk.GtkToolkit}.
+@item http.proxyHost
+Name of proxy host for http connections.
+
+@item http.proxyPort
+Port number to use when a proxy host is in use.
+
@end table
@node GNU Classpath Properties
@code{java.io.ObjectOutput} classes when set to something else then the empty
string. Only used when running a debug build of the library.
+@item gnu.classpath.vm.shortname
+This is a succint name of the virtual machine. For @code{libgcj},
+this will always be @samp{libgcj}.
+
+@item gnu.classpath.home.url
+A base URL used for finding system property files (e.g.,
+@file{classpath.security}). By default this is a @samp{file:} URL
+pointing to the @file{lib} directory under @samp{java.home}.
+
@end table
@node libgcj Runtime Properties
should be used as fallback to convert the addresses to function names when
the runtime is unable to do it through @code{dladdr}.
+@item gnu.gcj.runtime.VMClassLoader.library_control
+This controls how shared libraries are automatically loaded by the
+built-in class loader. By default, or if this property is set to
+@samp{full}, a full search is done for each requested class. If this
+property is set to @samp{cache}, then any failed lookups are cached
+and not tried again. If this property is set to @samp{never}, then
+lookups are never done. For more information, @xref{Extensions}.
+
@end table
OSDN Git Service
