-@\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
@c the word ``Java'.
@c When this manual is copyrighted.
-@set copyrights-gcj 2001
+@set copyrights-gcj 2001, 2002, 2003, 2004, 2005
+
+@c Versions
+@set which-gcj GCC-@value{version-GCC}
+
+@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.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)
+(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
@direntry
* gcjh: (gcj)Invoking gcjh.
Generate header files from Java class files
+* gjnih: (gcj)Invoking gjnih.
+ Generate JNI 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
+* 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.
+* grmiregistry: (gcj)Invoking grmiregistry.
+ The remote object registry.
@end direntry
@end format
-Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through Tex and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-sections entitled ``GNU General Public License'' and ``Funding for Free
-Software'' are included exactly as in the original, and provided that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the sections entitled ``GNU General Public License'', and
-this permission notice, may be included in translations approved by the
-Free Software Foundation instead of in the original English.
+@insertcopying
@end ifinfo
@titlepage
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
-@sp 2
-For the @value{which-g77} Version*
+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 make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-sections entitled ``GNU General Public License,'' ``Funding for Free
-Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are
-included exactly as in the original, and provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License,'' and
-this permission notice, may be included in translations approved by the
-Free Software Foundation instead of in the original English.
+@insertcopying
@end titlepage
+@contents
@page
@node Top
@top Introduction
-This manual describes how to use @code{gcj}, the GNU compiler for the
-Java programming language. @code{gcj} can generate both @file{.class}
+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
-* Invoking gcj:: Compiler options supported by @code{gcj}
+* 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 gcjh:: Generate header files from class files
+* Invoking gjnih:: Generate JNI 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 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 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
-@node Copying
-@unnumbered GNU GENERAL PUBLIC LICENSE
-@center Version 2, June 1991
-
-@display
-Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
-
-@unnumberedsec Preamble
-
- The licenses for most software are designed to take away your
-freedom to share and change it. By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software---to make sure the software is free for all its users. This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it. (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.) You can apply it to
-your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have. You must make sure that they, too, receive or can get the
-source code. And you must show them these terms so they know their
-rights.
-
- We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software. If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
- Finally, any free program is threatened constantly by software
-patents. We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary. To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-
-@iftex
-@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-@end iftex
-@ifinfo
-@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-@end ifinfo
-
-@enumerate 0
-@item
-This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License. The ``Program'', below,
-refers to any such program or work, and a ``work based on the Program''
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language. (Hereinafter, translation is included without limitation in
-the term ``modification''.) Each licensee is addressed as ``you''.
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope. The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
-@item
-You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
-@item
-You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
-@enumerate a
-@item
-You must cause the modified files to carry prominent notices
-stating that you changed the files and the date of any change.
-
-@item
-You must cause any work that you distribute or publish, that in
-whole or in part contains or is derived from the Program or any
-part thereof, to be licensed as a whole at no charge to all third
-parties under the terms of this License.
-
-@item
-If the modified program normally reads commands interactively
-when run, you must cause it, when started running for such
-interactive use in the most ordinary way, to print or display an
-announcement including an appropriate copyright notice and a
-notice that there is no warranty (or else, saying that you provide
-a warranty) and that users may redistribute the program under
-these conditions, and telling the user how to view a copy of this
-License. (Exception: if the Program itself is interactive but
-does not normally print such an announcement, your work based on
-the Program is not required to print an announcement.)
-@end enumerate
-
-These requirements apply to the modified work as a whole. If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works. But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
-@item
-You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
-@enumerate a
-@item
-Accompany it with the complete corresponding machine-readable
-source code, which must be distributed under the terms of Sections
-1 and 2 above on a medium customarily used for software interchange; or,
-
-@item
-Accompany it with a written offer, valid for at least three
-years, to give any third party, for a charge no more than your
-cost of physically performing source distribution, a complete
-machine-readable copy of the corresponding source code, to be
-distributed under the terms of Sections 1 and 2 above on a medium
-customarily used for software interchange; or,
-
-@item
-Accompany it with the information you received as to the offer
-to distribute corresponding source code. (This alternative is
-allowed only for noncommercial distribution and only if you
-received the program in object code or executable form with such
-an offer, in accord with Subsection b above.)
-@end enumerate
-
-The source code for a work means the preferred form of the work for
-making modifications to it. For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable. However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
-@item
-You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-@item
-You are not required to accept this License, since you have not
-signed it. However, nothing else grants you permission to modify or
-distribute the Program or its derivative works. These actions are
-prohibited by law if you do not accept this License. Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
-@item
-Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions. You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
-@item
-If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all. For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices. Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
-@item
-If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded. In such case, this License incorporates
-the limitation as if written in the body of this License.
-
-@item
-The Free Software Foundation may publish revised and/or new versions
-of the General Public License from time to time. Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Program
-specifies a version number of this License which applies to it and ``any
-later version'', you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation. If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
+@include gpl.texi
-@item
-If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission. For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this. Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
-@iftex
-@heading NO WARRANTY
-@end iftex
-@ifinfo
-@center NO WARRANTY
-@end ifinfo
+@include fdl.texi
-@item
-BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-@item
-IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-@end enumerate
-
-@iftex
-@heading END OF TERMS AND CONDITIONS
-@end iftex
-@ifinfo
-@center END OF TERMS AND CONDITIONS
-@end ifinfo
+@node Invoking gcj
+@chapter Invoking gcj
-@page
-@unnumberedsec How to Apply These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
- To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the ``copyright'' line and a pointer to where the full notice is found.
-
-@smallexample
-@var{one line to give the program's name and a brief idea of what it does.}
-Copyright (C) @var{year} @var{name of author}
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-@end smallexample
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
-@smallexample
-Gnomovision version 69, Copyright (C) @var{year} @var{name of author}
-Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
-type `show w'.
-This is free software, and you are welcome to redistribute it
-under certain conditions; type `show c' for details.
-@end smallexample
-
-The hypothetical commands @samp{show w} and @samp{show c} should show
-the appropriate parts of the General Public License. Of course, the
-commands you use may be called something other than @samp{show w} and
-@samp{show c}; they could even be mouse-clicks or menu items---whatever
-suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a ``copyright disclaimer'' for the program, if
-necessary. Here is a sample; alter the names:
-
-@smallexample
-Yoyodyne, Inc., hereby disclaims all copyright interest in the program
-`Gnomovision' (which makes passes at compilers) written by James Hacker.
-
-@var{signature of Ty Coon}, 1 April 1989
-Ty Coon, President of Vice
-@end smallexample
-
-This General Public License does not permit incorporating your program into
-proprietary programs. If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library. If this is what you want to do, use the GNU Library General
-Public License instead of this License.
+@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), jv-scan(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
-@node Invoking gcj
-@chapter Invoking gcj
+@c man begin DESCRIPTION gcj
-As @code{gcj} is just another front end to @code{gcc}, it supports many
+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}. This manual only documents the
-options specific to @code{gcj}.
+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
-@code{gcj} has options to control where it looks to find files it needs.
-For instance, @code{gcj} might need to load a class that is referenced
+@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, @code{gcj} has a notion of a @dfn{class path}. There are
+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 @code{gcj} looks for a given class, it
+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. @code{gcj} comes with a built-in class path which
+@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 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 @code{gcj} will search as if it is a directory.
+file, which @command{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
-compatibility with tools like @code{javac} is imported, we recommend
+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}
-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
-differs from the @code{--classpath} option in that it also suppresses
-the built-in system 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.
First come all directories specified via @code{-I}.
@item
-If @code{--classpath} is specified, its value is appended and processing
-stops. That is, @code{--classpath} suppresses all the options mentioned
-later in this list.
-
-@item
-If @code{--CLASSPATH} is specified, its value is appended and the
-@code{CLASSPATH} environment variable is suppressed.
+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 the @code{CLASSPATH} environment variable is specified (and was not
-suppressed by @code{--CLASSPATH}), then its value is appended.
+If @code{--bootclasspath} was specified, append its value.
+Otherwise, append the built-in system directory, @file{libgcj.jar}.
@item
-Finally, the built-in system directory, @file{libgcj.jar}, is appended.
+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.
+@end table
@node Encodings
@section Encodings
The Java programming language uses Unicode throughout. In an effort to
-integrate well with other locales, @code{gcj} allows @file{.java} files
-to be written using almost any encoding. @code{gcj} knows how 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
-@code{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
+@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
of Unicode.
-To implement @code{--encoding}, @code{gcj} simply uses the host
+To implement @code{--encoding}, @command{gcj} simply uses the host
platform's @code{iconv} conversion routine. This means that in practice
-@code{gcj} is limited by the capabilities of the host platform.
+@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,
-@code{gcj} implements the encoding named @samp{UTF-8} internally, so if
+@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
-@code{gcj} implements several warnings. As with other generic
-@code{gcc} warnings, if an option of the form @code{-Wfoo} enables a
+@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 @code
+@table @gcctabopt
@item -Wredundant-modifiers
-With this flag, @code{gcj} will warn about redundant modifiers. For
+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 @code{gcj} to warn about empty statements. Empty statements
+This causes @command{gcj} to warn about empty statements. Empty statements
have been deprecated.
@item -Wno-out-of-date
-This option will cause @code{gcj} not to warn when a source file is
-newer than its matching class file. By default @code{gcj} will warn
+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 @code{gcc}'s @code{-Wunused}.
+This is the same as @command{gcc}'s @code{-Wunused}.
@item -Wall
This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
@end table
-@node Code Generation
-@section Code Generation
+@node Linking
+@section Linking
-In addition to the many @code{gcc} options controlling code generation,
-@code{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
-@table @code
+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 @code{gcj} to generate bytecode
+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 -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
directory.
@item -fno-bounds-check
-By default, @code{gcj} generates code which checks the bounds of all
-array indexing operations. With this option, these checks are omitted.
-Note that this can result in unpredictable behavior if the code in
-question actually does violate array bounds constraints.
+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 @code{gcj} there are two options for writing native methods: CNI
-and JNI. By default @code{gcj} assumes you are using CNI. If you are
+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
-@code{gcj} to generate stubs which will invoke the underlying JNI
+@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.
+
@end table
@node Configure-time Options
@section Configure-time Options
-Some @code{gcj} code generations options affect the resulting ABI, and
+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 @code{gcj}. These
+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 @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
+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 @code{gcj} assumes that this information is stored in a
+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,
-@code{gcj} and @code{libgcj} try to conform to the relevant Java
+@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
-@code{gcj}.
+@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
-@code{gcj} implements the JDK 1.1 language. It supports inner classes,
-though these are known to still be buggy. It does not yet support the
-Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores
-it).
+@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.
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 they can be automatically
+loaded by the @code{libgcj} system classloader. 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 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{-force}] [@option{-old}] [@option{-trace}] [@option{-J} @var{option}]
+ [@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{--bootclasspath}=@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
This tells @code{gcjh} to generate a JNI header or stub. By default,
CNI headers are generated.
+@item -force
+This option forces @code{gcjh} to write the output file.
+
+@item -old
+This option is accepted but ignored for compatibility.
+
+@item -trace
+This option is accepted but ignored for compatibility.
+
+@item -J @var{option}
+This option is accepted but ignored for compatibility.
+
@item -add @var{text}
Inserts @var{text} into the class body. This is ignored in JNI mode.
@item --classpath=@var{path}
@itemx --CLASSPATH=@var{path}
+@itemx --bootclasspath=@var{path}
@itemx -I@var{directory}
@itemx -d @var{directory}
@itemx -o @var{file}
-These options are all identical to the corresponding @code{gcj} options.
+These options are all identical to the corresponding @command{gcj} options.
@item -o @var{file}
Sets the output file name. This cannot be used if there is more than
@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 gjnih
+@chapter Invoking gjnih
+
+@c man title gjnih generate JNI header files from Java class files
+
+@c man begin DESCRIPTION gjnih
+
+The @code{gjnih} program is used to generate JNI header files from class
+files. Running it is equivalent to running @code{gcjh -jni}.
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gjnih
+gjnih [@option{-stubs}] [@option{-jni}]
+ [@option{-force}] [@option{-old}] [@option{-trace}] [@option{-J} @var{option}]
+ [@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{--bootclasspath}=@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 gjnih
+gcc(1), gcj(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 OPTIONS gjnih
+
+@table @gcctabopt
+@item -stubs
+This causes @code{gjnih} to generate stub files instead of header files.
+By default the stub file will be named after the class, with a suffix of
+@samp{.c}.
+
+@item -jni
+This option specifies the default behavior which is to generate a JNI
+header or stub.
+
+@item -force
+This option forces @code{gjnih} to write the output file.
+
+@item -old
+This option is accepted but ignored for compatibility.
+
+@item -trace
+This option is accepted but ignored for compatibility.
+
+@item -J @var{option}
+This option is accepted but ignored for compatibility.
+
+@item -add @var{text}
+Inserts @var{text} into the class body. This is ignored in by
+@code{gjnih}.
+
+@item -append @var{text}
+Inserts @var{text} into the header file after the class declaration.
+This is ignored in by @code{gjnih}.
+
+@item -friend @var{text}
+Inserts @var{text} into the class as a @code{friend} declaration.
+This is ignored by @code{gjnih}.
+
+@item -prepend @var{text}
+Inserts @var{text} into the header file before the class declaration.
+This is ignored in by @code{gjnih}.
+
+@item --classpath=@var{path}
+@itemx --CLASSPATH=@var{path}
+@itemx --bootclasspath=@var{path}
+@itemx -I@var{directory}
+@itemx -d @var{directory}
+@itemx -o @var{file}
+These options are all identical to the corresponding @command{gcj} options.
+
+@item -o @var{file}
+Sets the output file name. This cannot be used if there is more than
+one class on the command line.
+
+@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{gjnih} and exit. No further processing is done.
+
+@item --version
+Print version information for @code{gjnih} 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{--no-assert}] [@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 --no-assert
+Don't recognize the @code{assert} keyword, for backwards compatibility
+with older versions of the language specification.
+
@item --complexity
This prints a complexity measure, related to cyclomatic complexity, for
each input file.
@item --encoding=@var{name}
-This works like the corresponding @code{gcj} option.
+This works like the corresponding @command{gcj} option.
@item --print-main
This prints the name of the class in this file containing a @code{main}
@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
+information about a number of classes, which are specified 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.
+@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.
@itemx --CLASSPATH=@var{path}
@itemx -I@var{directory}
@itemx -o @var{file}
-These options as the same as the corresponding @code{gcj} options.
+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), 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
-targets supported by @code{gcj}.
+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
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 -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.
method.
@item -ms=@var{number}
-This sets the initial heap size
+Equivalent to @code{-Xms}.
@item -mx=@var{number}
-This sets the maximum heap size.
+Equivalent to @code{-Xmx}.
+
+@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.
+@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} and @code{-noclassgc}.
-@node Resources
-@chapter Resources
+@c man end
-While writing @code{gcj} and @code{libgcj} we have, of course, relied
-heavily on documentation from Sun Microsystems. In particular we have
-used The Java Language Specification (both first and second editions),
-the Java Class Libraries (volumes one and two), and the Java Virtual
-Machine Specification. In addition we've used the online documentation
-at @uref{http://java.sun.com/}.
+@node Invoking gcj-dbtool
+@chapter Invoking gcj-dbtool.
-The current @code{gcj} home page is
-@uref{http://sources.redhat.com/java/}. This is likely to change in the
-near future.
+@c man title gcj-dbtool Manipulate class file mapping databases for libgcj
-For more information on gcc, see @uref{http://gcc.gnu.org/}.
+@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 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
-Some @code{libgcj} testing is done using the Mauve test suite. This is
-a free software Java class library test suite which is being written
-because the JCK is not free. See
-@uref{http://sources.redhat.com/mauve/} for more information.
+@c man begin DESCRIPTION gcj-dbtool
+
+@code{gcj-dbtool} is a tool for creating and manipulating class file
+mapping databases. @code{libgcj} can use these databases to find a
+shared library corresponding to the bytecode representation of a
+class. This functionality is useful for ahead-of-time compilation of
+a program that has no knowledge of @code{gcj}.
+
+@code{gcj-dbtool} works best if all the jar files added to it are
+compiled using @code{-findirect-dispatch}.
+
+Note that @code{gcj-dbtool} is currently available as ``preview
+technology''. We believe it is a reasonable way to allow
+application-transparent ahead-of-time compilation, but this is an
+unexplored area. We welcome your comments.
+
+@c man end
+
+@c man begin OPTIONS gcj-dbtool
+
+@table @gcctabopt
+@item -n @var{DBFILE} [@var{SIZE}]
+This creates a new database. Currently, databases cannot be resized;
+you can choose a larger initial size if desired. The default size is
+32,749.
+
+@item -a @var{DBFILE} @var{JARFILE} @var{LIB}
+@itemx -f @var{DBFILE} @var{JARFILE} @var{LIB}
+This adds a jar file to the database. For each class file in the jar,
+a cryptographic signature of the bytecode representation of the class
+is recorded in the database. At runtime, a class is looked up by its
+signature and the compiled form of the class is looked for in the
+corresponding shared library. The @option{-a} option will verify
+that @var{LIB} exists before adding it to the database; @option{-f}
+skips this check.
+
+@item [@option{-}][@option{-0}] -m @var{DBFILE} @var{DBFILE},[@var{DBFILE}]
+Merge a number of databases. The output database overwrites any
+existing database. To add databases into an existing database,
+include the destination in the list of sources.
+
+If @option{-} or @option{-0} are used, the list of files to read is
+taken from standard input instead of the command line. For
+@option{-0}, Input filenames are terminated by a null character
+instead of by whitespace. Useful when arguments might contain white
+space. The GNU find -print0 option produces input suitable for this
+mode.
+
+@item -t @var{DBFILE}
+Test a database.
+
+@item -l @var{DBFILE}
+List the contents of a database.
+
+@item -p
+Print the name of the default database. If there is no default
+database, this prints a blank line. If @var{LIBDIR} is specified, use
+it instead of the default library directory component of the database
+name.
+
+@item --help
+Print a help message, then exit.
+
+@item --version
+@itemx -v
+Print version information, 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 Invoking grmic
+@chapter Invoking grmic
+
+@c man title grmic Generate stubs for Remote Method Invocation
+
+@c man begin SYNOPSIS grmic
+@command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
+@ignore
+ [@option{-keep}]
+ [@option{-keepgenerated}]
+ [@option{-v1.1}]
+ [@option{-vcompat}]
+ [@option{-v1.2}]
+ [@option{-nocompile}]
+ [@option{-verbose}]
+ [@option{-d} @var{directory}]
+ [@option{-help}]
+ [@option{-version}]
+@end ignore
+@c man end
+
+@c man begin DESCRIPTION grmic
+
+@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{grmic}. Some options, such as @option{-classpath}, are
+recognized but currently ignored. We have left these options
+undocumented for now.
+
+Long options can also be given with a GNU-style leading @samp{--}. For
+instance, @option{--help} is accepted.
+
+@c man end
+
+@c man begin OPTIONS grmic
+
+@table @gcctabopt
+@item -keep
+@itemx -keepgenerated
+By default, @command{grmic} deletes intermediate files. Either of these
+options causes it not to delete such files.
+
+@item -v1.1
+Cause @command{grmic} to create stubs and skeletons for the 1.1
+protocol version.
+
+@item -vcompat
+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{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{grmic} is doing.
+
+@item -d @var{directory}
+Put output files in @var{directory}. By default the files are put in
+the current working directory.
+
+@item -help
+Print a help message, then exit.
+
+@item -version
+Print version information, then exit.
+@end table
+
+@c man end
+
+
+@node Invoking grmiregistry
+@chapter Invoking grmiregistry
+
+@c man title grmiregistry Remote object registry
+
+@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 grmiregistry
+
+@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 This really isn't much more than the --help output.
+
+@c man end
+
+@c man begin OPTIONS grmiregistry
+
+@table @gcctabopt
+@item --help
+Print a help message, then exit.
+
+@item --version
+Print version information, then exit.
+@end table
+
+@c man end
+
+
+@node About CNI
+@chapter About CNI
+
+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).
+
+@menu
+* Basic concepts:: Introduction to using CNI@.
+* Packages:: How packages are mapped to C++.
+* Primitive types:: Handling Java types in C++.
+* Interfaces:: How Java interfaces map to C++.
+* Objects and Classes:: C++ and Java classes.
+* Class Initialization:: How objects are initialized.
+* Object allocation:: How to create Java objects in C++.
+* Memory allocation:: How to allocate and free memory.
+* Arrays:: Dealing with Java arrays in C++.
+* Methods:: Java methods in C++.
+* Strings:: Information about Java Strings.
+* Mixing with C++:: How CNI can interoperate with C++.
+* Exception Handling:: How exceptions are handled.
+* Synchronization:: Synchronizing between Java and C++.
+* Invocation:: Starting the Java runtime from C++.
+* Reflection:: Using reflection from C++.
+@end menu
+
+
+@node Basic concepts
+@section Basic concepts
+
+In terms of languages features, Java is mostly a subset
+of C++. Java has a few important extensions, plus a powerful standard
+class library, but on the whole that does not change the basic similarity.
+Java is a hybrid object-oriented language, with a few native types,
+in addition to class types. It is class-based, where a class may have
+static as well as per-object fields, and static as well as instance methods.
+Non-static methods may be virtual, and may be overloaded. Overloading is
+resolved at compile time by matching the actual argument types against
+the parameter types. Virtual methods are implemented using indirect calls
+through a dispatch table (virtual function table). Objects are
+allocated on the heap, and initialized using a constructor method.
+Classes are organized in a package hierarchy.
+
+All of the listed attributes are also true of C++, though C++ has
+extra features (for example in C++ objects may be allocated not just
+on the heap, but also statically or in a local stack frame). Because
+@command{gcj} uses the same compiler technology as G++ (the GNU
+C++ compiler), it is possible to make the intersection of the two
+languages use the same ABI (object representation and calling
+conventions). The key idea in CNI is that Java objects are C++
+objects, and all Java classes are C++ classes (but not the other way
+around). So the most important task in integrating Java and C++ is to
+remove gratuitous incompatibilities.
+
+You write CNI code as a regular C++ source file. (You do have to use
+a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
+
+@noindent A CNI C++ source file must have:
+
+@example
+#include <gcj/cni.h>
+@end example
+
+@noindent and then must include one header file for each Java class it uses, e.g.:
+
+@example
+#include <java/lang/Character.h>
+#include <java/util/Date.h>
+#include <java/lang/IndexOutOfBoundsException.h>
+@end example
+
+@noindent These header files are automatically generated by @code{gcjh}.
+
+
+CNI provides some functions and macros to make using Java objects and
+primitive types from C++ easier. In general, these CNI functions and
+macros start with the @code{Jv} prefix, for example the function
+@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.
+
+
+@subsection Limitations
+
+Whilst a Java class is just a C++ class that doesn't mean that you are
+freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
+rules of the Java programming language.
+
+For example: it is not possible to declare a method in a CNI class
+that will take a C string (@code{char*}) as an argument, or to declare a
+member variable of some non-Java datatype.
+
+
+@node Packages
+@section Packages
+
+The only global names in Java are class names, and packages. A
+@dfn{package} can contain zero or more classes, and also zero or more
+sub-packages. Every class belongs to either an unnamed package or a
+package that has a hierarchical and globally unique name.
+
+A Java package is mapped to a C++ @dfn{namespace}. The Java class
+@code{java.lang.String} is in the package @code{java.lang}, which is a
+sub-package of @code{java}. The C++ equivalent is the class
+@code{java::lang::String}, which is in the namespace @code{java::lang}
+which is in the namespace @code{java}.
+
+@noindent Here is how you could express this:
+
+@example
+(// @r{Declare the class(es), possibly in a header file:}
+namespace java @{
+ namespace lang @{
+ class Object;
+ class String;
+ ...
+ @}
+@}
+
+class java::lang::String : public java::lang::Object
+@{
+ ...
+@};
+@end example
+
+@noindent The @code{gcjh} tool automatically generates the necessary namespace
+declarations.
+
+
+@subsection Leaving out package names
+
+Always using the fully-qualified name of a java class can be
+tiresomely verbose. Using the full qualified name also ties the code
+to a single package making code changes necessary should the class
+move from one package to another. The Java @code{package} declaration
+specifies that the following class declarations are in the named
+package, without having to explicitly name the full package
+qualifiers. The @code{package} declaration can be
+followed by zero or more @code{import} declarations, which
+allows either a single class or all the classes in a package to be
+named by a simple identifier. C++ provides something similar with the
+@code{using} declaration and directive.
+
+@noindent In Java:
+
+@example
+import @var{package-name}.@var{class-name};
+@end example
+
+@noindent allows the program text to refer to @var{class-name} as a shorthand for
+the fully qualified name: @code{@var{package-name}.@var{class-name}}.
+
+
+@noindent To achieve the same effect C++, you have to do this:
+
+@example
+using @var{package-name}::@var{class-name};
+@end example
+
+
+@noindent Java can also cause imports on demand, like this:
+
+@example
+import @var{package-name}.*;
+@end example
+
+@noindent Doing this allows any class from the package @var{package-name} to be
+referred to only by its class-name within the program text.
+
+
+@noindent The same effect can be achieved in C++ like this:
+
+@example
+using namespace @var{package-name};
+@end example
+
+
+@node Primitive types
+@section Primitive types
+
+Java provides 8 @dfn{primitives} types which represent integers, floats,
+characters and booleans (and also the void type). C++ has its own
+very similar concrete types. Such types in C++ however are not always
+implemented in the same way (an int might be 16, 32 or 64 bits for example)
+so CNI provides a special C++ type for each primitive Java type:
+
+@multitable @columnfractions .20 .25 .60
+@item @strong{Java type} @tab @strong{C/C++ typename} @tab @strong{Description}
+@item @code{char} @tab @code{jchar} @tab 16 bit Unicode character
+@item @code{boolean} @tab @code{jboolean} @tab logical (true or false) values
+@item @code{byte} @tab @code{jbyte} @tab 8-bit signed integer
+@item @code{short} @tab @code{jshort} @tab 16 bit signed integer
+@item @code{int} @tab @code{jint} @tab 32 bit signed integer
+@item @code{long} @tab @code{jlong} @tab 64 bit signed integer
+@item @code{float} @tab @code{jfloat} @tab 32 bit IEEE floating point number
+@item @code{double} @tab @code{jdouble} @tab 64 bit IEEE floating point number
+@item @code{void} @tab @code{void} @tab no value
+@end multitable
+
+When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
+to avoid disappointment.
+
+
+@subsection Reference types associated with primitive types
+
+In Java each primitive type has an associated reference type,
+e.g.: @code{boolean} has an associated @code{java.lang.Boolean} class.
+In order to make working with such classes easier GCJ provides the macro
+@code{JvPrimClass}:
+
+@deffn macro JvPrimClass type
+Return a pointer to the @code{Class} object corresponding to the type supplied.
+
+@example
+JvPrimClass(void) @result{} java.lang.Void.TYPE
+@end example
+
+@end deffn
+
+
+@node Interfaces
+@section Interfaces
+
+A Java class can @dfn{implement} zero or more
+@dfn{interfaces}, in addition to inheriting from
+a single base class.
+
+@acronym{CNI} allows CNI code to implement methods of interfaces.
+You can also call methods through interface references, with some
+limitations.
+
+@acronym{CNI} doesn't understand interface inheritance at all yet. So,
+you can only call an interface method when the declared type of the
+field being called matches the interface which declares that
+method. The workaround is to cast the interface reference to the right
+superinterface.
+
+For example if you have:
+
+@example
+interface A
+@{
+ void a();
+@}
+
+interface B extends A
+@{
+ void b();
+@}
+@end example
+
+and declare a variable of type @code{B} in C++, you can't call
+@code{a()} unless you cast it to an @code{A} first.
+
+@node Objects and Classes
+@section Objects and Classes
+
+@subsection Classes
+
+All Java classes are derived from @code{java.lang.Object}. C++ does
+not have a unique root class, but we use the C++ class
+@code{java::lang::Object} as the C++ version of the
+@code{java.lang.Object} Java class. All other Java classes are mapped
+into corresponding C++ classes derived from @code{java::lang::Object}.
+
+Interface inheritance (the @code{implements} keyword) is currently not
+reflected in the C++ mapping.
+
+
+@subsection Object fields
+
+Each object contains an object header, followed by the instance fields
+of the class, in order. The object header consists of a single
+pointer to a dispatch or virtual function table. (There may be extra
+fields @emph{in front of} the object, for example for memory
+management, but this is invisible to the application, and the
+reference to the object points to the dispatch table pointer.)
+
+The fields are laid out in the same order, alignment, and size as in
+C++. Specifically, 8-bit and 16-bit native types (@code{byte},
+@code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
+to 32 bits. Note that the Java VM does extend 8-bit and 16-bit types
+to 32 bits when on the VM stack or temporary registers.
+
+If you include the @code{gcjh}-generated header for a
+class, you can access fields of Java classes in the @emph{natural}
+way. For example, given the following Java class:
+
+@example
+public class Int
+@{
+ public int i;
+ public Int (int i) @{ this.i = i; @}
+ public static Int zero = new Int(0);
+@}
+@end example
+
+you can write:
+
+@example
+#include <gcj/cni.h>;
+#include <Int>;
+
+Int*
+mult (Int *p, jint k)
+@{
+ if (k == 0)
+ return Int::zero; // @r{Static member access.}
+ return new Int(p->i * k);
+@}
+@end example
+
+
+@subsection Access specifiers
+
+CNI does not strictly enforce the Java access
+specifiers, because Java permissions cannot be directly mapped
+into C++ permission. Private Java fields and methods are mapped
+to private C++ fields and methods, but other fields and methods
+are mapped to public fields and methods.
+
+
+
+@node Class Initialization
+@section Class Initialization
+
+Java requires that each class be automatically initialized at the time
+of the first active use. Initializing a class involves
+initializing the static fields, running code in class initializer
+methods, and initializing base classes. There may also be
+some implementation specific actions, such as allocating
+@code{String} objects corresponding to string literals in
+the code.
+
+The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
+places to ensure that a class is initialized when required. The C++
+compiler does not insert these calls automatically---it is the
+programmer's responsibility to make sure classes are initialized.
+However, this is fairly painless because of the conventions assumed by
+the Java system.
+
+First, @code{libgcj} will make sure a class is initialized before an
+instance of that object is created. This is one of the
+responsibilities of the @code{new} operation. This is taken care of
+both in Java code, and in C++ code. When G++ sees a @code{new} of a
+Java class, it will call a routine in @code{libgcj} to allocate the
+object, and that routine will take care of initializing the class.
+Note however that this does not happen for Java arrays; you must
+allocate those using the appropriate CNI function. It follows that
+you can access an instance field, or call an instance (non-static)
+method and be safe in the knowledge that the class and all of its base
+classes have been initialized.
+
+Invoking a static method is also safe. This is because the
+Java compiler adds code to the start of a static method to make sure
+the class is initialized. However, the C++ compiler does not
+add this extra code. Hence, if you write a native static method
+using CNI, you are responsible for calling @code{JvInitClass}
+before doing anything else in the method (unless you are sure
+it is safe to leave it out).
+
+Accessing a static field also requires the class of the
+field to be initialized. The Java compiler will generate code
+to call @code{JvInitClass} before getting or setting the field.
+However, the C++ compiler will not generate this extra code,
+so it is your responsibility to make sure the class is
+initialized before you access a static field from C++.
+
+
+@node Object allocation
+@section Object allocation
+
+New Java objects are allocated using a
+@dfn{class instance creation expression}, e.g.:
+
+@example
+new @var{Type} ( ... )
+@end example
+
+The same syntax is used in C++. The main difference is that
+C++ objects have to be explicitly deleted; in Java they are
+automatically deleted by the garbage collector.
+Using @acronym{CNI}, you can allocate a new Java object
+using standard C++ syntax and the C++ compiler will allocate
+memory from the garbage collector. If you have overloaded
+constructors, the compiler will choose the correct one
+using standard C++ overload resolution rules.
+
+@noindent For example:
+
+@example
+java::util::Hashtable *ht = new java::util::Hashtable(120);
+@end example
+
+
+@node Memory allocation
+@section Memory allocation
+
+When allocating memory in @acronym{CNI} methods it is best to handle
+out-of-memory conditions by throwing a Java exception. These
+functions are provided for that purpose:
+
+@deftypefun void* JvMalloc (jsize @var{size})
+Calls malloc. Throws @code{java.lang.OutOfMemoryError} if allocation
+fails.
+@end deftypefun
+
+@deftypefun void* JvRealloc (void* @var{ptr}, jsize @var{size})
+Calls realloc. Throws @code{java.lang.OutOfMemoryError} if
+reallocation fails.
+@end deftypefun
+
+@deftypefun void JvFree (void* @var{ptr})
+Calls free.
+@end deftypefun
+
+@node Arrays
+@section Arrays
+
+While in many ways Java is similar to C and C++, it is quite different
+in its treatment of arrays. C arrays are based on the idea of pointer
+arithmetic, which would be incompatible with Java's security
+requirements. Java arrays are true objects (array types inherit from
+@code{java.lang.Object}). An array-valued variable is one that
+contains a reference (pointer) to an array object.
+
+Referencing a Java array in C++ code is done using the
+@code{JArray} template, which as defined as follows:
+
+@example
+class __JArray : public java::lang::Object
+@{
+public:
+ int length;
+@};
+
+template<class T>
+class JArray : public __JArray
+@{
+ T data[0];
+public:
+ T& operator[](jint i) @{ return data[i]; @}
+@};
+@end example
+
+
+There are a number of @code{typedef}s which correspond to @code{typedef}s
+from the @acronym{JNI}. Each is the type of an array holding objects
+of the relevant type:
+
+@example
+typedef __JArray *jarray;
+typedef JArray<jobject> *jobjectArray;
+typedef JArray<jboolean> *jbooleanArray;
+typedef JArray<jbyte> *jbyteArray;
+typedef JArray<jchar> *jcharArray;
+typedef JArray<jshort> *jshortArray;
+typedef JArray<jint> *jintArray;
+typedef JArray<jlong> *jlongArray;
+typedef JArray<jfloat> *jfloatArray;
+typedef JArray<jdouble> *jdoubleArray;
+@end example
+
+
+@deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
+This template function can be used to get a pointer to the elements of
+the @code{array}. For instance, you can fetch a pointer to the
+integers that make up an @code{int[]} like so:
+
+@example
+extern jintArray foo;
+jint *intp = elements (foo);
+@end example
+
+The name of this function may change in the future.
+@end deftypemethod
+
+
+@deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
+Here @code{klass} is the type of elements of the array and
+@code{init} is the initial value put into every slot in the array.
+@end deftypefun
+
+
+@subsection Creating arrays
+
+For each primitive type there is a function which can be used to
+create a new array of that type. The name of the function is of the
+form:
+
+@example
+JvNew@var{Type}Array
+@end example
+
+@noindent For example:
+
+@example
+JvNewBooleanArray
+@end example
+
+@noindent can be used to create an array of Java primitive boolean types.
+
+@noindent The following function definition is the template for all such functions:
+
+@deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
+Create's an array @var{length} indices long.
+@end deftypefun
+
+@deftypefun jsize JvGetArrayLength (jarray @var{array})
+Returns the length of the @var{array}.
+@end deftypefun
+
+
+@node Methods
+@section Methods
+
+Java methods are mapped directly into C++ methods.
+The header files generated by @code{gcjh}
+include the appropriate method definitions.
+Basically, the generated methods have the same names and
+@emph{corresponding} types as the Java methods,
+and are called in the natural manner.
+
+@subsection Overloading
+
+Both Java and C++ provide method overloading, where multiple
+methods in a class have the same name, and the correct one is chosen
+(at compile time) depending on the argument types.
+The rules for choosing the correct method are (as expected) more complicated
+in C++ than in Java, but given a set of overloaded methods
+generated by @code{gcjh} the C++ compiler will choose
+the expected one.
+
+Common assemblers and linkers are not aware of C++ overloading,
+so the standard implementation strategy is to encode the
+parameter types of a method into its assembly-level name.
+This encoding is called @dfn{mangling},
+and the encoded name is the @dfn{mangled name}.
+The same mechanism is used to implement Java overloading.
+For C++/Java interoperability, it is important that both the Java
+and C++ compilers use the @emph{same} encoding scheme.
+
+@subsection Static methods
+
+Static Java methods are invoked in @acronym{CNI} using the standard
+C++ syntax, using the @code{::} operator rather
+than the @code{.} operator.
+
+@noindent For example:
+
+@example
+jint i = java::lang::Math::round((jfloat) 2.3);
+@end example
+
+@noindent C++ method definition syntax is used to define a static native method.
+For example:
+
+@example
+#include <java/lang/Integer>
+java::lang::Integer*
+java::lang::Integer::getInteger(jstring str)
+@{
+ ...
+@}
+@end example
+
+
+@subsection Object Constructors
+
+Constructors are called implicitly as part of object allocation
+using the @code{new} operator.
+
+@noindent For example:
+
+@example
+java::lang::Integer *x = new java::lang::Integer(234);
+@end example
+
+Java does not allow a constructor to be a native method.
+This limitation can be coded round however because a constructor
+can @emph{call} a native method.
+
+
+@subsection Instance methods
+
+Calling a Java instance method from a C++ @acronym{CNI} method is done
+using the standard C++ syntax, e.g.:
+
+@example
+// @r{First create the Java object.}
+java::lang::Integer *x = new java::lang::Integer(234);
+// @r{Now call a method.}
+jint prim_value = x->intValue();
+if (x->longValue == 0)
+ ...
+@end example
+
+@noindent Defining a Java native instance method is also done the natural way:
+
+@example
+#include <java/lang/Integer.h>
+
+jdouble
+java::lang:Integer::doubleValue()
+@{
+ return (jdouble) value;
+@}
+@end example
+
+
+@subsection Interface methods
+
+In Java you can call a method using an interface reference. This is
+supported, but not completely. @xref{Interfaces}.
+
+
+
+
+@node Strings
+@section Strings
+
+@acronym{CNI} provides a number of utility functions for
+working with Java Java @code{String} objects.
+The names and interfaces are analogous to those of @acronym{JNI}.
+
+
+@deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len})
+Returns a Java @code{String} object with characters from the C string
+@var{chars} up to the index @var{len} in that array.
+@end deftypefun
+
+@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
+Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
+@end deftypefun
+
+
+@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
+As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
+@end deftypefun
+
+@deftypefun jstring JvNewStringUTF (const char* @var{bytes})
+Returns a @code{String} which is made up of the UTF encoded characters
+present in the C string @var{bytes}.
+@end deftypefun
+
+@deftypefun jchar* JvGetStringChars (jstring @var{str})
+Returns a pointer to an array of characters making up the @code{String} @var{str}.
+@end deftypefun
+
+@deftypefun int JvGetStringUTFLength (jstring @var{str})
+Returns the number of bytes required to encode the contents of the
+@code{String} @var{str} in UTF-8.
+@end deftypefun
+
+@deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
+Puts the UTF-8 encoding of a region of the @code{String} @var{str} into
+the buffer @code{buf}. The region to fetch is marked by @var{start} and @var{len}.
+
+Note that @var{buf} is a buffer, not a C string. It is @emph{not}
+null terminated.
+@end deftypefun
+
+
+@node Mixing with C++
+@section Interoperating with C/C++
+
+Because @acronym{CNI} is designed to represent Java classes and methods it
+cannot be mixed readily with C/C++ types.
+
+One important restriction is that Java classes cannot have non-Java
+type instance or static variables and cannot have methods which take
+non-Java types as arguments or return non-Java types.
+
+@noindent None of the following is possible with CNI:
+
+@example
+
+class ::MyClass : public java::lang::Object
+@{
+ char* variable; // @r{char* is not a valid Java type.}
+@}
+
+
+uint
+::SomeClass::someMethod (char *arg)
+@{
+ .
+ .
+ .
+@} // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
+@end example
+
+@noindent Of course, it is ok to use C/C++ types within the scope of a method:
+
+
+@example
+jint
+::SomeClass::otherMethod (jstring str)
+@{
+ char *arg = ...
+ .
+ .
+ .
+@}
+@end example
+
+@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 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.
+
+@noindent Here are some examples:
+
+@example
+
+class ::MyClass : public java::lang::Object
+@{
+ gnu.gcj.RawData string;
+
+ MyClass ();
+ gnu.gcj.RawData getText ();
+ void printText ();
+@}
+
+::MyClass::MyClass ()
+@{
+ char* text = ...
+ string = text;
+@}
+
+gnu.gcj.RawData
+::MyClass::getText ()
+@{
+ return string;
+@}
+
+void
+::MyClass::printText ()
+@{
+ printf("%s\n", (char*) string);
+@}
+@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
+
+While C++ and Java share a common exception handling framework,
+things are not yet perfectly integrated. The main issue is that the
+run-time type information facilities of the two
+languages are not integrated.
+
+Still, things work fairly well. You can throw a Java exception from
+C++ using the ordinary @code{throw} construct, and this
+exception can be caught by Java code. Similarly, you can catch an
+exception thrown from Java using the C++ @code{catch}
+construct.
+
+@noindent Here is an example:
+
+@example
+if (i >= count)
+ throw new java::lang::IndexOutOfBoundsException();
+@end example
+
+Normally, G++ will automatically detect when you are writing C++
+code that uses Java exceptions, and handle them appropriately.
+However, if C++ code only needs to execute destructors when Java
+exceptions are thrown through it, GCC will guess incorrectly. Sample
+problematic code:
+
+@example
+struct S @{ ~S(); @};
+
+extern void bar(); // @r{Is implemented in Java and may throw exceptions.}
+
+void foo()
+@{
+ S s;
+ bar();
+@}
+@end example
+
+The usual effect of an incorrect guess is a link failure, complaining of
+a missing routine called @code{__gxx_personality_v0}.
+
+You can inform the compiler that Java exceptions are to be used in a
+translation unit, irrespective of what it might think, by writing
+@code{#pragma GCC java_exceptions} at the head of the
+file. This @code{#pragma} must appear before any
+functions that throw or catch exceptions, or run destructors when
+exceptions are thrown through them.
+
+@node Synchronization
+@section Synchronization
+
+Each Java object has an implicit monitor.
+The Java VM uses the instruction @code{monitorenter} to acquire
+and lock a monitor, and @code{monitorexit} to release it.
+
+The corresponding CNI macros are @code{JvMonitorEnter} and
+@code{JvMonitorExit} (JNI has similar methods @code{MonitorEnter}
+and @code{MonitorExit}).
+
+
+The Java source language does not provide direct access to these primitives.
+Instead, there is a @code{synchronized} statement that does an
+implicit @code{monitorenter} before entry to the block,
+and does a @code{monitorexit} on exit from the block.
+Note that the lock has to be released even when the block is abnormally
+terminated by an exception, which means there is an implicit
+@code{try finally} surrounding synchronization locks.
+
+From C++, it makes sense to use a destructor to release a lock.
+@acronym{CNI} defines the following utility class:
+
+@example
+class JvSynchronize() @{
+ jobject obj;
+ JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
+ ~JvSynchronize() @{ JvMonitorExit(obj); @}
+@};
+@end example
+
+So this Java code:
+
+@example
+synchronized (OBJ)
+@{
+ CODE
+@}
+@end example
+
+@noindent might become this C++ code:
+
+@example
+@{
+ JvSynchronize dummy (OBJ);
+ CODE;
+@}
+@end example
+
+Java also has methods with the @code{synchronized} attribute.
+This is equivalent to wrapping the entire method body in a
+@code{synchronized} statement.
+(Alternatively, an implementation could require the caller to do
+the synchronization. This is not practical for a compiler, because
+each virtual method call would have to test at run-time if
+synchronization is needed.) Since in @command{gcj}
+the @code{synchronized} attribute is handled by the
+method implementation, it is up to the programmer
+of a synchronized native method to handle the synchronization
+(in the C++ implementation of the method).
+In other words, you need to manually add @code{JvSynchronize}
+in a @code{native synchronized} method.
+
+@node Invocation
+@section Invocation
+
+CNI permits C++ applications to make calls into Java classes, in addition to
+allowing Java code to call into C++. Several functions, known as the
+@dfn{invocation API}, are provided to support this.
+
+@deftypefun jint JvCreateJavaVM (JvVMInitArgs* @var{vm_args})
+
+Initializes the Java runtime. This function performs essential initialization
+of the threads interface, garbage collector, exception handling and other key
+aspects of the runtime. It must be called once by an application with
+a non-Java @code{main()} function, before any other Java or CNI calls are made.
+It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
+once provided it is only called from a single thread.
+The @var{vmargs} parameter can be used to specify initialization parameters
+for the Java runtime. It may be @code{NULL}.
+
+JvVMInitArgs represents a list of virtual machine initialization
+arguments. @code{JvCreateJavaVM()} ignores the version field.
+
+@example
+typedef struct JvVMOption
+@{
+ // a VM initialization option
+ char* optionString;
+ // extra information associated with this option
+ void* extraInfo;
+@} JvVMOption;
+
+typedef struct JvVMInitArgs
+@{
+ // for compatibility with JavaVMInitArgs
+ jint version;
+
+ // number of VM initialization options
+ jint nOptions;
+
+ // an array of VM initialization options
+ JvVMOption* options;
+
+ // true if the option parser should ignore unrecognized options
+ jboolean ignoreUnrecognized;
+@} JvVMInitArgs;
+@end example
+
+@code{JvCreateJavaVM()} returns @code{0} upon success, or @code{-1} if
+the runtime is already initialized.
+
+@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It
+is recognized and used as of release 4.0.
+@end deftypefun
+
+@deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
+Registers an existing thread with the Java runtime. This must be called once
+from each thread, before that thread makes any other Java or CNI calls. It
+must be called after @code{JvCreateJavaVM}.
+@var{name} specifies a name for the thread. It may be @code{NULL}, in which
+case a name will be generated.
+@var{group} is the ThreadGroup in which this thread will be a member. If it
+is @code{NULL}, the thread will be a member of the main thread group.
+The return value is the Java @code{Thread} object that represents the thread.
+It is safe to call @code{JvAttachCurrentThread()} more than once from the same
+thread. If the thread is already attached, the call is ignored and the current
+thread object is returned.
+@end deftypefun
+
+@deftypefun jint JvDetachCurrentThread ()
+Unregisters a thread from the Java runtime. This should be called by threads
+that were attached using @code{JvAttachCurrentThread()}, after they have
+finished making calls to Java code. This ensures that any resources associated
+with the thread become eligible for garbage collection.
+This function returns @code{0} upon success, or @code{-1} if the current thread
+is not attached.
+@end deftypefun
+
+@subsection Handling uncaught exceptions
+
+If an exception is thrown from Java code called using the invocation API, and
+no handler for the exception can be found, the runtime will abort the
+application. In order to make the application more robust, it is recommended
+that code which uses the invocation API be wrapped by a top-level try/catch
+block that catches all Java exceptions.
+
+@subsection Example
+
+The following code demonstrates the use of the invocation API. In this
+example, the C++ application initializes the Java runtime and attaches
+itself. The @code{java.lang.System} class is initialized in order to
+access its @code{out} field, and a Java string is printed. Finally, the thread
+is detached from the runtime once it has finished making Java calls. Everything
+is wrapped with a try/catch block to provide a default handler for any uncaught
+exceptions.
+
+The example can be compiled with @command{c++ test.cc -lgcj}.
+
+@example
+// test.cc
+#include <gcj/cni.h>
+#include <java/lang/System.h>
+#include <java/io/PrintStream.h>
+#include <java/lang/Throwable.h>
+
+int main(int argc, char *argv)
+@{
+ using namespace java::lang;
+
+ try
+ @{
+ JvCreateJavaVM(NULL);
+ JvAttachCurrentThread(NULL, NULL);
+
+ String *message = JvNewStringLatin1("Hello from C++");
+ JvInitClass(&System::class$);
+ System::out->println(message);
+
+ JvDetachCurrentThread();
+ @}
+ catch (Throwable *t)
+ @{
+ System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
+ t->printStackTrace();
+ @}
+@}
+@end example
+
+@node Reflection
+@section Reflection
+
+Reflection is possible with CNI code, it functions similarly to how it
+functions with JNI@.
+
+@c clean this up... I mean, what are the types jfieldID and jmethodID in JNI?
+The types @code{jfieldID} and @code{jmethodID}
+are as in JNI@.
+
+@noindent The functions:
+
+@itemize
+@item @code{JvFromReflectedField},
+@item @code{JvFromReflectedMethod},
+@item @code{JvToReflectedField}
+@item @code{JvToFromReflectedMethod}
+@end itemize
+
+@noindent will be added shortly, as will other functions corresponding to JNI@.
+
+
+@node System properties
+@chapter System properties
+
+The runtime behavior of the @code{libgcj} library can be modified by setting
+certain system properties. These properties can be compiled into the program
+using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
+setting them explicitly in the program by calling the
+@code{java.lang.System.setProperty()} method. Some system properties are only
+used for informational purposes (like giving a version number or a user name).
+A program can inspect the current value of a property by calling the
+@code{java.lang.System.getProperty()} method.
+
+@menu
+* Standard Properties:: Standard properties supported by @code{libgcj}
+* GNU Classpath Properties:: Properties found in Classpath based libraries
+* libgcj Runtime Properties:: Properties specific to @code{libgcj}
+@end menu
+
+@node Standard Properties
+@section Standard Properties
+
+The following properties are normally found in all implementations of the core
+libraries for the Java language.
+
+@table @gcctabopt
+
+@item java.version
+The @code{libgcj} version number.
+
+@item java.vendor
+Set to @samp{The Free Software Foundation, Inc.}
+
+@item java.vendor.url
+Set to @uref{http://gcc.gnu.org/java/}.
+
+@item java.home
+The directory where @code{gcj} was installed. Taken from the @code{--prefix}
+option given to @command{configure}.
+
+@item java.class.version
+The class format version number supported by the libgcj byte code interpreter.
+(Currently @samp{46.0})
+
+@item java.vm.specification.version
+The Virtual Machine Specification version implemented by @code{libgcj}.
+(Currently @samp{1.0})
+
+@item java.vm.specification.vendor
+The name of the Virtual Machine specification designer.
+
+@item java.vm.specification.name
+The name of the Virtual Machine specification
+(Set to @samp{Java Virtual Machine Specification}).
+
+@item java.vm.version
+The @command{gcj} version number.
+
+@item java.vm.vendor
+Set to @samp{The Free Software Foundation, Inc.}
+
+@item java.vm.name
+Set to @samp{GNU libgcj}.
+
+@item java.specification.version
+The Runtime Environment specification version implemented by @code{libgcj}.
+(Currently set to @samp{1.3})
+
+@item java.specification.vendor
+The Runtime Environment specification designer.
+
+@item java.specification.name
+The name of the Runtime Environment specification
+(Set to @samp{Java Platform API Specification}).
+
+@item java.class.path
+The paths (jar files, zip files and directories) used for finding class files.
+
+@item java.library.path
+Directory path used for finding native libraries.
+
+@item java.io.tmpdir
+The directory used to put temporary files in.
+
+@item java.compiler
+Name of the Just In Time compiler to use by the byte code interpreter.
+Currently not used in @code{libgcj}.
+
+@item java.ext.dirs
+Directories containing jar files with extra libraries. Will be used when
+resolving classes.
+
+@item java.protocol.handler.pkgs
+A @samp{|} separated list of package names that is used to find classes that
+implement handlers for @code{java.net.URL}.
+
+@item java.rmi.server.codebase
+A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
+to load classes from.
+
+@item jdbc.drivers
+A list of class names that will be loaded by the @code{java.sql.DriverManager}
+when it starts up.
+
+@item file.separator
+The separator used in when directories are included in a filename
+(normally @samp{/} or @samp{\} ).
+
+@item file.encoding
+The default character encoding used when converting platform native files to
+Unicode (usually set to @samp{8859_1}).
+
+@item path.separator
+The standard separator used when a string contains multiple paths
+(normally @samp{:} or @samp{;}), the string is usually not a valid character
+to use in normal directory names.)
+
+@item line.separator
+The default line separator used on the platform (normally @samp{\n}, @samp{\r}
+or a combination of those two characters).
+
+@item policy.provider
+The class name used for the default policy provider returned by
+@code{java.security.Policy.getPolicy}.
+
+@item user.name
+The name of the user running the program. Can be the full name, the login name
+or empty if unknown.
+
+@item user.home
+The default directory to put user specific files in.
+
+@item user.dir
+The current working directory from which the program was started.
+
+@item user.language
+The default language as used by the @code{java.util.Locale} class.
+
+@item user.region
+The default region as used by the @code{java.util.Local} class.
+
+@item user.variant
+The default variant of the language and region local used.
+
+@item user.timezone
+The default timezone as used by the @code{java.util.TimeZone} class.
+
+@item os.name
+The operating system/kernel name that the program runs on.
+
+@item os.arch
+The hardware that we are running on.
+
+@item os.version
+The version number of the operating system/kernel.
+
+@item awt.appletWarning
+The string to display when an untrusted applet is displayed.
+Returned by @code{java.awt.Window.getWarningString()} when the window is
+``insecure''.
+
+@item awt.toolkit
+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
+@section GNU Classpath Properties
+
+@code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
+GNU project to create free core class libraries for use with virtual machines
+and compilers for the Java language. The following properties are common to
+libraries based on GNU Classpath.
+
+@table @gcctabopt
+
+@item gcj.dumpobject
+Enables printing serialization debugging by the @code{java.io.ObjectInput} and
+@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
+@section libgcj Runtime Properties
+
+The following properties are specific to the @code{libgcj} runtime and will
+normally not be found in other core libraries for the java language.
+
+@table @gcctabopt
+
+@item java.fullversion
+The combination of @code{java.vm.name} and @code{java.vm.version}.
+
+@item java.vm.info
+Same as @code{java.fullversion}.
+
+@item impl.prefix
+Used by the @code{java.net.DatagramSocket} class when set to something else
+then the empty string. When set all newly created @code{DatagramSocket}s will
+try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
+the normal @code{java.net.PlainDatagramSocketImpl}.
+
+@item gnu.gcj.progname
+The class or binary name that was used to invoke the program. This will be
+the name of the "main" class in the case where the @code{gij} front end is
+used, or the program binary name in the case where an application is compiled
+to a native binary.
+
+@item gnu.gcj.runtime.NameFinder.use_addr2line
+Whether an external process, @command{addr2line}, should be used to determine
+line number information when tracing the stack. Setting this to @code{false}
+may suppress line numbers when printing stack traces and when using
+the java.util.logging infrastructure. However, performance may improve
+significantly for applications that print stack traces or make logging calls
+frequently.
+
+@item gnu.gcj.runtime.VMClassLoader.library_control
+This controls how shared libraries are automatically loaded by the
+built-in class loader. 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} (the default), 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}.
+
+@item gnu.gcj.runtime.endorsed.dirs
+This is like the standard @code{java.endorsed.dirs}, property, but
+specifies some extra directories which are searched after the standard
+endorsed directories. This is primarily useful for telling
+@code{libgcj} about additional libraries which are ordinarily
+incorporated into the JDK, and which should be loaded by the bootstrap
+class loader, but which are not yet part of @code{libgcj} itself for
+some reason.
+
+@item gnu.gcj.jit.compiler
+@c FIXME we should probably have a whole node on this...
+This is the full path to @command{gcj} executable which should be
+used to compile classes just-in-time when
+@code{ClassLoader.defineClass} is called. If not set, @command{gcj}
+will not be invoked by the runtime; this can also be controlled via
+@code{Compiler.disable}.
+
+@item gnu.gcj.jit.options
+This is a space-separated string of options which should be passed to
+@command{gcj} when in JIT mode. If not set, a sensible default is
+chosen.
+
+@item gnu.gcj.jit.cachedir
+This is the directory where cached shared library files are
+stored. If not set, JIT compilation is disabled. This should never
+be set to a directory that is writable by any other user.
+
+@item gnu.gcj.precompiled.db.path
+This is a sequence of file names, each referring to a file created by
+@command{gcj-dbtool}. These files will be used by @code{libgcj} to
+find shared libraries corresponding to classes that are loaded from
+bytecode. @code{libgcj} often has a built-in default database; it
+can be queried using @code{gcj-dbtool -p}.
+
+@end table
+
+
+@node Resources
+@chapter Resources
+
+While writing @command{gcj} and @code{libgcj} we have, of course, relied
+heavily on documentation from Sun Microsystems. In particular we have
+used The Java Language Specification (both first and second editions),
+the Java Class Libraries (volumes one and two), and the Java Virtual
+Machine Specification. In addition we've used the online documentation
+at @uref{http://java.sun.com/}.
+
+The current @command{gcj} home page is
+@uref{http://gcc.gnu.org/java/}.
+
+For more information on gcc, see @uref{http://gcc.gnu.org/}.
+
+Some @code{libgcj} testing is done using the Mauve test suite. This is
+a free software Java class library test suite which is being written
+because the JCK is not free. See
+@uref{http://sources.redhat.com/mauve/} for more information.
-@contents
@bye
projects / platform / upstream / gcc.git / blobdiff