| @\input texinfo @c -*-texinfo-*- |
| @setfilename gcj.info |
| @settitle Guide to GNU gcj |
| |
| @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 |
| |
| @c Versions |
| @set version-gcc 3.1 |
| @set which-gcj GCC-@value{version-gcc} |
| |
| @ifinfo |
| @format |
| @dircategory Programming |
| @direntry |
| * Gcj: (gcj). Ahead-of-time compiler for the Java language |
| @end direntry |
| |
| @dircategory Individual utilities |
| @direntry |
| * gcjh: (gcj)Invoking gcjh. |
| Generate header files from Java class files |
| * jv-scan: (gcj)Invoking jv-scan. |
| Print information about Java source files |
| * jcf-dump: (gcj)Invoking jcf-dump. |
| Print information about Java class files |
| * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode |
| @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. |
| @end ifinfo |
| |
| @titlepage |
| @title GNU gcj |
| @author Tom Tromey |
| |
| @page |
| @vskip 0pt plus 1filll |
| Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc. |
| @sp 2 |
| For the @value{which-gcj} Version* |
| @sp 1 |
| Published by the Free Software Foundation @* |
| 59 Temple Place - Suite 330@* |
| Boston, MA 02111-1307, USA@* |
| @sp 1 |
| Permission is granted to 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. |
| @end titlepage |
| @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} |
| 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} |
| * Compatibility:: Compatibility between gcj and other tools for Java |
| * Invoking gcjh:: Generate header files from class files |
| * Invoking jv-scan:: Print information about source files |
| * Invoking jcf-dump:: Print information about class files |
| * Invoking gij:: Interpreting Java bytecodes |
| * 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. |
| |
| @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 |
| |
| @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 |
| |
| @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. |
| |
| |
| @node Invoking gcj |
| @chapter Invoking gcj |
| |
| As @code{gcj} is just another front end to @code{gcc}, it supports many |
| of the same options as gcc. @xref{Option Summary, , Option Summary, |
| gcc, Using the GNU Compiler Collection}. This manual only documents the |
| options specific to @code{gcj}. |
| |
| @menu |
| * Input and output files:: |
| * Input Options:: How gcj finds files |
| * Encodings:: Options controlling source file encoding |
| * Warnings:: Options controlling warnings specific to gcj |
| * Code Generation:: Options controlling the output of gcj |
| * Configure-time Options:: Options you won't use |
| @end menu |
| |
| @node Input and output files |
| @section Input and output files |
| |
| A @code{gcj} command is like a @code{gcc} command, in that it |
| consists of a number of options and file names. The following kinds |
| of input file names are supported: |
| |
| @table @code |
| @item @var{file}.java |
| Java source files. |
| @item @var{file}.class |
| Java bytecode files. |
| @item @var{file}.zip |
| @itemx @var{file}.jar |
| An archive containing one or more @code{.class} files, all of |
| which are compiled. The archive may be compressed. |
| @item @@@var{file} |
| A file containing a whitespace-separated list of input file names. |
| (Currently, these must all be @code{.java} source files, but that |
| may change.) |
| Each named file is compiled, just as if it had been on the command line. |
| @item @var{library}.a |
| @itemx @var{library}.so |
| @itemx -l@var{libname} |
| Libraries to use when linking. See the @code{gcc} manual. |
| @end table |
| |
| You can specify more than one input file on the @code{gcj} command line, |
| in which case they will all be compiled. If you specify a |
| @code{-o @var{FILENAME}} |
| option, all the input files will be compiled together, producing a |
| single output file, named @var{FILENAME}. |
| This is allowed even when using @code{-S} or @code{-c}, |
| but not when using @code{-C}. |
| (This is an extension beyond the what plain @code{gcc} allows.) |
| (If more than one input file is specified, all must currently |
| be @code{.java} files, though we hope to fix this.) |
| |
| @node Input Options |
| @section Input Options |
| |
| @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 |
| 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 |
| several options and environment variables which can be used to |
| manipulate the class path. When @code{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 |
| 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. |
| |
| @table @code |
| @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 |
| 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). |
| |
| @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. |
| |
| @item CLASSPATH |
| This is an environment variable which holds a list of paths. |
| @end table |
| |
| The final class path is constructed like so: |
| |
| @itemize @bullet |
| @item |
| First come all directories specified via @code{-I}. |
| |
| @item |
| If @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. |
| |
| @item |
| If the @code{CLASSPATH} environment variable is specified (and was not |
| suppressed by @code{--CLASSPATH}), then its value is appended. |
| |
| @item |
| Finally, the built-in system directory, @file{libgcj.jar}, is appended. |
| @end itemize |
| |
| The classfile built by @code{gcj} for the class @code{java.lang.Object} |
| (and placed in @code{libgcj.jar}) contains a special zero length |
| attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this |
| attribute when loading @code{java.lang.Object} and will report an error |
| if it isn't found, unless it compiles to bytecode (the option |
| @code{-fforce-classes-archive-check} can be used to overide this |
| behavior in this particular case.) |
| |
| @table @code |
| @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 |
| 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 |
| of Unicode. |
| |
| To implement @code{--encoding}, @code{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. |
| |
| 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 |
| 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 |
| 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 |
| @item -Wredundant-modifiers |
| With this flag, @code{gcj} will warn about redundant modifiers. For |
| instance, it will warn if an interface method is declared @code{public}. |
| |
| @item -Wextraneous-semicolon |
| This causes @code{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 |
| about this. |
| |
| @item -Wunused |
| This is the same as @code{gcc}'s @code{-Wunused}. |
| |
| @item -Wall |
| This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon |
| -Wunused}. |
| @end table |
| |
| |
| @node Code Generation |
| @section Code Generation |
| |
| In addition to the many @code{gcc} options controlling code generation, |
| @code{gcj} has several options specific to itself. |
| |
| @table @code |
| @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.} |
| |
| @item -D@var{name}[=@var{value}] |
| This option can only be used with @code{--main}. It defines a system |
| property named @var{name} with value @var{value}. If @var{value} is not |
| specified then it defaults to the empty string. These system properties |
| are initialized at the program's startup and can be retrieved at runtime |
| using the @code{java.lang.System.getProperty} method. |
| |
| @item -C |
| This option is used to tell @code{gcj} to generate bytecode |
| (@file{.class} files) rather than object code. |
| |
| @item -d @var{directory} |
| When used with @code{-C}, this causes all generated @file{.class} files |
| to be put in the appropriate subdirectory of @var{directory}. By |
| default they will be put in subdirectories of the current working |
| directory. |
| |
| @item -fno-bounds-check |
| By default, @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. |
| |
| @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 |
| 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 |
| methods. |
| @end table |
| |
| |
| @node Configure-time Options |
| @section Configure-time Options |
| |
| Some @code{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 |
| options are listed here for completeness; if you are using @code{libgcj} |
| then you won't want to touch these options. |
| |
| @table @code |
| @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 |
| 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 |
| 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 |
| |
| |
| @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 |
| specifications. However, limited manpower and incomplete and unclear |
| documentation work against us. So, there are caveats to using |
| @code{gcj}. |
| |
| 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). |
| |
| @item |
| @code{libgcj} is largely compatible with the JDK 1.2 libraries. |
| However, @code{libgcj} is missing many packages, most notably |
| @code{java.awt}. There are also individual missing classes and methods. |
| We currently do not have a list showing differences between |
| @code{libgcj} and the Java 2 platform. |
| |
| @item |
| Sometimes the @code{libgcj} implementation of a method or class differs |
| from the JDK implementation. This is not always a bug. Still, if it |
| affects you, it probably makes sense to report it so that we can discuss |
| the appropriate response. |
| @end itemize |
| |
| |
| @node Invoking gcjh |
| @chapter Invoking 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 |
| @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 |
| @samp{.cc}. In JNI mode, the default output file will have the suffix |
| @samp{.c}. |
| |
| @item -jni |
| This tells @code{gcjh} to generate a JNI header or stub. By default, |
| CNI headers are generated. |
| |
| @item -add @var{text} |
| Inserts @var{text} into the class body. This is ignored in JNI mode. |
| |
| @item -append @var{text} |
| Inserts @var{text} into the header file after the class declaration. |
| This is ignored in JNI mode. |
| |
| @item -friend @var{text} |
| Inserts @var{text} into the class as a @code{friend} declaration. |
| This is ignored in JNI mode. |
| |
| @item -prepend @var{text} |
| Inserts @var{text} into the header file before the class declaration. |
| This is ignored in JNI mode. |
| |
| @item --classpath=@var{path} |
| @itemx --CLASSPATH=@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. |
| |
| @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 --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. |
| @end table |
| |
| All remaining options are considered to be names of classes. |
| |
| |
| @node Invoking jv-scan |
| @chapter Invoking jv-scan |
| |
| The @code{jv-scan} program can be used to print information about a Java |
| source file (@file{.java} file). |
| |
| @table @code |
| @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. |
| |
| @item --print-main |
| This prints the name of the class in this file containing a @code{main} |
| method. |
| |
| @item --list-class |
| This lists the names of all classes defined in the input files. |
| |
| @item --list-filename |
| If @code{--list-class} is given, this option causes @code{jv-scan} to |
| also print the name of the file in which each class was found. |
| |
| @item -o @var{file} |
| Print output to the named file. |
| @end table |
| |
| |
| @node Invoking jcf-dump |
| @chapter Invoking jcf-dump |
| |
| This is a class file examiner, similar to @code{javap}. It will print |
| information about a number of classes, which are specifed by class name |
| or file name. |
| |
| @table @code |
| @item -c |
| Disassemble method bodies. By default method bodies are not printed. |
| |
| @item --javap |
| Generate output in @code{javap} format. The implementation of this |
| feature is very incomplete. |
| |
| @item --classpath=@var{path} |
| @itemx --CLASSPATH=@var{path} |
| @itemx -I@var{directory} |
| @itemx -o @var{file} |
| These options as the same as the corresponding @code{gcj} options. |
| @end table |
| |
| |
| @node Invoking gij |
| @chapter Invoking 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}. |
| |
| The primary argument to @code{gij} is the name of a class or, with |
| @code{-jar}, a jar file. Options before this argument are interpreted |
| by @code{gij}; remaining options are passed to the interpreted program. |
| |
| If a class name is specified and this class does not have a @code{main} |
| method with the appropriate signature (a @code{static void} method with |
| a @code{String[]} as its sole argument), then @code{gij} will print an |
| error and exit. |
| |
| If a jar file is specified then @code{gij} will use information in it to |
| determine which class' @code{main} method will be invoked. |
| |
| @code{gij} will invoke the @code{main} method with all the remaining |
| command-line options. |
| |
| Note that @code{gij} is not limited to interpreting code. Because |
| @code{libgcj} includes a class loader which can dynamically load shared |
| objects, it is possible to give @code{gij} the name of a class which has |
| been compiled and put into a shared library on the class path. |
| |
| @table @code |
| @item -D@var{name}[=@var{value}] |
| This defines a system property named @var{name} with value @var{value}. |
| If @var{value} is not specified then it defaults to the empty string. |
| These system properties are initialized at the program's startup and can |
| be retrieved at runtime using the @code{java.lang.System.getProperty} |
| method. |
| |
| @item -ms=@var{number} |
| This sets the initial heap size |
| |
| @item -mx=@var{number} |
| This sets the maximum heap size. |
| |
| @item -jar |
| This indicates that the name passed to @code{gij} should be interpreted |
| as the name of a jar file, not a class. |
| @end table |
| |
| |
| @node Resources |
| @chapter Resources |
| |
| 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/}. |
| |
| The current @code{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 |