1 @\input texinfo @c -*-texinfo-*-
3 @settitle Guide to GNU gcj
5 @c Note: When reading this manual you'll find lots of strange
6 @c circumlocutions like ``compiler for the Java language''.
7 @c This is necessary due to Sun's restrictions on the use of
10 @c When this manual is copyrighted.
11 @set copyrights-gcj 2001
15 @dircategory Programming
17 * Gcj: (gcj). Ahead-of-time compiler for the Java language
20 @dircategory Individual utilities
22 * gcjh: (gcj)Invoking gcjh.
23 Generate header files from Java class files
24 * jv-scan: (gcj)Invoking jv-scan.
25 Print information about Java source files
26 * jcf-dump: (gcj)Invoking jcf-dump.
27 Print information about Java class files
28 * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
32 Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
34 Permission is granted to make and distribute verbatim copies of
35 this manual provided the copyright notice and this permission notice
36 are preserved on all copies.
39 Permission is granted to process this file through Tex and print the
40 results, provided the printed document carries copying permission
41 notice identical to this one except for the removal of this paragraph
42 (this paragraph not being relevant to the printed manual).
45 Permission is granted to copy and distribute modified versions of this
46 manual under the conditions for verbatim copying, provided also that the
47 sections entitled ``GNU General Public License'' and ``Funding for Free
48 Software'' are included exactly as in the original, and provided that
49 the entire resulting derived work is distributed under the terms of a
50 permission notice identical to this one.
52 Permission is granted to copy and distribute translations of this manual
53 into another language, under the above conditions for modified versions,
54 except that the sections entitled ``GNU General Public License'', and
55 this permission notice, may be included in translations approved by the
56 Free Software Foundation instead of in the original English.
64 @vskip 0pt plus 1filll
65 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
67 For the @value{which-g77} Version*
69 Published by the Free Software Foundation @*
70 59 Temple Place - Suite 330@*
71 Boston, MA 02111-1307, USA@*
73 Permission is granted to make and distribute verbatim copies of
74 this manual provided the copyright notice and this permission notice
75 are preserved on all copies.
77 Permission is granted to copy and distribute modified versions of this
78 manual under the conditions for verbatim copying, provided also that the
79 sections entitled ``GNU General Public License,'' ``Funding for Free
80 Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are
81 included exactly as in the original, and provided that the entire
82 resulting derived work is distributed under the terms of a permission
83 notice identical to this one.
85 Permission is granted to copy and distribute translations of this manual
86 into another language, under the above conditions for modified versions,
87 except that the section entitled ``GNU General Public License,'' and
88 this permission notice, may be included in translations approved by the
89 Free Software Foundation instead of in the original English.
97 This manual describes how to use @code{gcj}, the GNU compiler for the
98 Java programming language. @code{gcj} can generate both @file{.class}
99 files and object files, and it can read both Java source code and
103 * Copying:: The GNU General Public License
104 * Invoking gcj:: Compiler options supported by @code{gcj}
105 * Compatibility:: Compatibility between gcj and other tools for Java
106 * Invoking gcjh:: Generate header files from class files
107 * Invoking jv-scan:: Print information about source files
108 * Invoking jcf-dump:: Print information about class files
109 * Invoking gij:: Interpreting Java bytecodes
110 * Resources:: Where to look for more information
115 @unnumbered GNU GENERAL PUBLIC LICENSE
116 @center Version 2, June 1991
119 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
120 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
122 Everyone is permitted to copy and distribute verbatim copies
123 of this license document, but changing it is not allowed.
126 @unnumberedsec Preamble
128 The licenses for most software are designed to take away your
129 freedom to share and change it. By contrast, the GNU General Public
130 License is intended to guarantee your freedom to share and change free
131 software---to make sure the software is free for all its users. This
132 General Public License applies to most of the Free Software
133 Foundation's software and to any other program whose authors commit to
134 using it. (Some other Free Software Foundation software is covered by
135 the GNU Library General Public License instead.) You can apply it to
138 When we speak of free software, we are referring to freedom, not
139 price. Our General Public Licenses are designed to make sure that you
140 have the freedom to distribute copies of free software (and charge for
141 this service if you wish), that you receive source code or can get it
142 if you want it, that you can change the software or use pieces of it
143 in new free programs; and that you know you can do these things.
145 To protect your rights, we need to make restrictions that forbid
146 anyone to deny you these rights or to ask you to surrender the rights.
147 These restrictions translate to certain responsibilities for you if you
148 distribute copies of the software, or if you modify it.
150 For example, if you distribute copies of such a program, whether
151 gratis or for a fee, you must give the recipients all the rights that
152 you have. You must make sure that they, too, receive or can get the
153 source code. And you must show them these terms so they know their
156 We protect your rights with two steps: (1) copyright the software, and
157 (2) offer you this license which gives you legal permission to copy,
158 distribute and/or modify the software.
160 Also, for each author's protection and ours, we want to make certain
161 that everyone understands that there is no warranty for this free
162 software. If the software is modified by someone else and passed on, we
163 want its recipients to know that what they have is not the original, so
164 that any problems introduced by others will not reflect on the original
165 authors' reputations.
167 Finally, any free program is threatened constantly by software
168 patents. We wish to avoid the danger that redistributors of a free
169 program will individually obtain patent licenses, in effect making the
170 program proprietary. To prevent this, we have made it clear that any
171 patent must be licensed for everyone's free use or not licensed at all.
173 The precise terms and conditions for copying, distribution and
177 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
180 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
185 This License applies to any program or other work which contains
186 a notice placed by the copyright holder saying it may be distributed
187 under the terms of this General Public License. The ``Program'', below,
188 refers to any such program or work, and a ``work based on the Program''
189 means either the Program or any derivative work under copyright law:
190 that is to say, a work containing the Program or a portion of it,
191 either verbatim or with modifications and/or translated into another
192 language. (Hereinafter, translation is included without limitation in
193 the term ``modification''.) Each licensee is addressed as ``you''.
195 Activities other than copying, distribution and modification are not
196 covered by this License; they are outside its scope. The act of
197 running the Program is not restricted, and the output from the Program
198 is covered only if its contents constitute a work based on the
199 Program (independent of having been made by running the Program).
200 Whether that is true depends on what the Program does.
203 You may copy and distribute verbatim copies of the Program's
204 source code as you receive it, in any medium, provided that you
205 conspicuously and appropriately publish on each copy an appropriate
206 copyright notice and disclaimer of warranty; keep intact all the
207 notices that refer to this License and to the absence of any warranty;
208 and give any other recipients of the Program a copy of this License
209 along with the Program.
211 You may charge a fee for the physical act of transferring a copy, and
212 you may at your option offer warranty protection in exchange for a fee.
215 You may modify your copy or copies of the Program or any portion
216 of it, thus forming a work based on the Program, and copy and
217 distribute such modifications or work under the terms of Section 1
218 above, provided that you also meet all of these conditions:
222 You must cause the modified files to carry prominent notices
223 stating that you changed the files and the date of any change.
226 You must cause any work that you distribute or publish, that in
227 whole or in part contains or is derived from the Program or any
228 part thereof, to be licensed as a whole at no charge to all third
229 parties under the terms of this License.
232 If the modified program normally reads commands interactively
233 when run, you must cause it, when started running for such
234 interactive use in the most ordinary way, to print or display an
235 announcement including an appropriate copyright notice and a
236 notice that there is no warranty (or else, saying that you provide
237 a warranty) and that users may redistribute the program under
238 these conditions, and telling the user how to view a copy of this
239 License. (Exception: if the Program itself is interactive but
240 does not normally print such an announcement, your work based on
241 the Program is not required to print an announcement.)
244 These requirements apply to the modified work as a whole. If
245 identifiable sections of that work are not derived from the Program,
246 and can be reasonably considered independent and separate works in
247 themselves, then this License, and its terms, do not apply to those
248 sections when you distribute them as separate works. But when you
249 distribute the same sections as part of a whole which is a work based
250 on the Program, the distribution of the whole must be on the terms of
251 this License, whose permissions for other licensees extend to the
252 entire whole, and thus to each and every part regardless of who wrote it.
254 Thus, it is not the intent of this section to claim rights or contest
255 your rights to work written entirely by you; rather, the intent is to
256 exercise the right to control the distribution of derivative or
257 collective works based on the Program.
259 In addition, mere aggregation of another work not based on the Program
260 with the Program (or with a work based on the Program) on a volume of
261 a storage or distribution medium does not bring the other work under
262 the scope of this License.
265 You may copy and distribute the Program (or a work based on it,
266 under Section 2) in object code or executable form under the terms of
267 Sections 1 and 2 above provided that you also do one of the following:
271 Accompany it with the complete corresponding machine-readable
272 source code, which must be distributed under the terms of Sections
273 1 and 2 above on a medium customarily used for software interchange; or,
276 Accompany it with a written offer, valid for at least three
277 years, to give any third party, for a charge no more than your
278 cost of physically performing source distribution, a complete
279 machine-readable copy of the corresponding source code, to be
280 distributed under the terms of Sections 1 and 2 above on a medium
281 customarily used for software interchange; or,
284 Accompany it with the information you received as to the offer
285 to distribute corresponding source code. (This alternative is
286 allowed only for noncommercial distribution and only if you
287 received the program in object code or executable form with such
288 an offer, in accord with Subsection b above.)
291 The source code for a work means the preferred form of the work for
292 making modifications to it. For an executable work, complete source
293 code means all the source code for all modules it contains, plus any
294 associated interface definition files, plus the scripts used to
295 control compilation and installation of the executable. However, as a
296 special exception, the source code distributed need not include
297 anything that is normally distributed (in either source or binary
298 form) with the major components (compiler, kernel, and so on) of the
299 operating system on which the executable runs, unless that component
300 itself accompanies the executable.
302 If distribution of executable or object code is made by offering
303 access to copy from a designated place, then offering equivalent
304 access to copy the source code from the same place counts as
305 distribution of the source code, even though third parties are not
306 compelled to copy the source along with the object code.
309 You may not copy, modify, sublicense, or distribute the Program
310 except as expressly provided under this License. Any attempt
311 otherwise to copy, modify, sublicense or distribute the Program is
312 void, and will automatically terminate your rights under this License.
313 However, parties who have received copies, or rights, from you under
314 this License will not have their licenses terminated so long as such
315 parties remain in full compliance.
318 You are not required to accept this License, since you have not
319 signed it. However, nothing else grants you permission to modify or
320 distribute the Program or its derivative works. These actions are
321 prohibited by law if you do not accept this License. Therefore, by
322 modifying or distributing the Program (or any work based on the
323 Program), you indicate your acceptance of this License to do so, and
324 all its terms and conditions for copying, distributing or modifying
325 the Program or works based on it.
328 Each time you redistribute the Program (or any work based on the
329 Program), the recipient automatically receives a license from the
330 original licensor to copy, distribute or modify the Program subject to
331 these terms and conditions. You may not impose any further
332 restrictions on the recipients' exercise of the rights granted herein.
333 You are not responsible for enforcing compliance by third parties to
337 If, as a consequence of a court judgment or allegation of patent
338 infringement or for any other reason (not limited to patent issues),
339 conditions are imposed on you (whether by court order, agreement or
340 otherwise) that contradict the conditions of this License, they do not
341 excuse you from the conditions of this License. If you cannot
342 distribute so as to satisfy simultaneously your obligations under this
343 License and any other pertinent obligations, then as a consequence you
344 may not distribute the Program at all. For example, if a patent
345 license would not permit royalty-free redistribution of the Program by
346 all those who receive copies directly or indirectly through you, then
347 the only way you could satisfy both it and this License would be to
348 refrain entirely from distribution of the Program.
350 If any portion of this section is held invalid or unenforceable under
351 any particular circumstance, the balance of the section is intended to
352 apply and the section as a whole is intended to apply in other
355 It is not the purpose of this section to induce you to infringe any
356 patents or other property right claims or to contest validity of any
357 such claims; this section has the sole purpose of protecting the
358 integrity of the free software distribution system, which is
359 implemented by public license practices. Many people have made
360 generous contributions to the wide range of software distributed
361 through that system in reliance on consistent application of that
362 system; it is up to the author/donor to decide if he or she is willing
363 to distribute software through any other system and a licensee cannot
366 This section is intended to make thoroughly clear what is believed to
367 be a consequence of the rest of this License.
370 If the distribution and/or use of the Program is restricted in
371 certain countries either by patents or by copyrighted interfaces, the
372 original copyright holder who places the Program under this License
373 may add an explicit geographical distribution limitation excluding
374 those countries, so that distribution is permitted only in or among
375 countries not thus excluded. In such case, this License incorporates
376 the limitation as if written in the body of this License.
379 The Free Software Foundation may publish revised and/or new versions
380 of the General Public License from time to time. Such new versions will
381 be similar in spirit to the present version, but may differ in detail to
382 address new problems or concerns.
384 Each version is given a distinguishing version number. If the Program
385 specifies a version number of this License which applies to it and ``any
386 later version'', you have the option of following the terms and conditions
387 either of that version or of any later version published by the Free
388 Software Foundation. If the Program does not specify a version number of
389 this License, you may choose any version ever published by the Free Software
393 If you wish to incorporate parts of the Program into other free
394 programs whose distribution conditions are different, write to the author
395 to ask for permission. For software which is copyrighted by the Free
396 Software Foundation, write to the Free Software Foundation; we sometimes
397 make exceptions for this. Our decision will be guided by the two goals
398 of preserving the free status of all derivatives of our free software and
399 of promoting the sharing and reuse of software generally.
409 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
410 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
411 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
412 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
413 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
414 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
415 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
416 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
417 REPAIR OR CORRECTION.
420 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
421 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
422 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
423 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
424 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
425 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
426 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
427 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
428 POSSIBILITY OF SUCH DAMAGES.
432 @heading END OF TERMS AND CONDITIONS
435 @center END OF TERMS AND CONDITIONS
439 @unnumberedsec How to Apply These Terms to Your New Programs
441 If you develop a new program, and you want it to be of the greatest
442 possible use to the public, the best way to achieve this is to make it
443 free software which everyone can redistribute and change under these terms.
445 To do so, attach the following notices to the program. It is safest
446 to attach them to the start of each source file to most effectively
447 convey the exclusion of warranty; and each file should have at least
448 the ``copyright'' line and a pointer to where the full notice is found.
451 @var{one line to give the program's name and a brief idea of what it does.}
452 Copyright (C) @var{year} @var{name of author}
454 This program is free software; you can redistribute it and/or modify
455 it under the terms of the GNU General Public License as published by
456 the Free Software Foundation; either version 2 of the License, or
457 (at your option) any later version.
459 This program is distributed in the hope that it will be useful,
460 but WITHOUT ANY WARRANTY; without even the implied warranty of
461 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
462 GNU General Public License for more details.
464 You should have received a copy of the GNU General Public License
465 along with this program; if not, write to the Free Software
466 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
469 Also add information on how to contact you by electronic and paper mail.
471 If the program is interactive, make it output a short notice like this
472 when it starts in an interactive mode:
475 Gnomovision version 69, Copyright (C) @var{year} @var{name of author}
476 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
478 This is free software, and you are welcome to redistribute it
479 under certain conditions; type `show c' for details.
482 The hypothetical commands @samp{show w} and @samp{show c} should show
483 the appropriate parts of the General Public License. Of course, the
484 commands you use may be called something other than @samp{show w} and
485 @samp{show c}; they could even be mouse-clicks or menu items---whatever
488 You should also get your employer (if you work as a programmer) or your
489 school, if any, to sign a ``copyright disclaimer'' for the program, if
490 necessary. Here is a sample; alter the names:
493 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
494 `Gnomovision' (which makes passes at compilers) written by James Hacker.
496 @var{signature of Ty Coon}, 1 April 1989
497 Ty Coon, President of Vice
500 This General Public License does not permit incorporating your program into
501 proprietary programs. If your program is a subroutine library, you may
502 consider it more useful to permit linking proprietary applications with the
503 library. If this is what you want to do, use the GNU Library General
504 Public License instead of this License.
508 @chapter Invoking gcj
510 As @code{gcj} is just another front end to @code{gcc}, it supports many
511 of the same options as gcc. @xref{Option Summary, , Option Summary,
512 gcc, Using the GNU Compiler Collection}. This manual only documents the
513 options specific to @code{gcj}.
516 * Input Options:: How gcj finds files
517 * Encodings:: Options controlling source file encoding
518 * Warnings:: Options controlling warnings specific to gcj
519 * Code Generation:: Options controlling the output of gcj
520 * Configure-time Options:: Options you won't use
525 @section Input Options
529 @code{gcj} has options to control where it looks to find files it needs.
530 For instance, @code{gcj} might need to load a class that is referenced
531 by the file it has been asked to compile. Like other compilers for the
532 Java language, @code{gcj} has a notion of a @dfn{class path}. There are
533 several options and environment variables which can be used to
534 manipulate the class path. When @code{gcj} looks for a given class, it
535 searches the class path looking for matching @file{.class} or
536 @file{.java} file. @code{gcj} comes with a built-in class path which
537 points at the installed @file{libgcj.jar}, a file which contains all the
540 In the below, a directory or path component can refer either to an
541 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
542 file, which @code{gcj} will search as if it is a directory.
546 All directories specified by @code{-I} are kept in order and prepended
547 to the class path constructed from all the other options. Unless
548 compatibility with tools like @code{javac} is imported, we recommend
549 always using @code{-I} instead of the other options for manipulating the
552 @item --classpath=@var{path}
553 This sets the class path to @var{path}, a colon-separated list of paths
554 (on Windows-based systems, a semicolon-separate list of paths).
556 @item --CLASSPATH=@var{path}
557 This sets the class path to @var{path}, a colon-separated list of paths
558 (on Windows-based systems, a semicolon-separate list of paths). This
559 differs from the @code{--classpath} option in that it also suppresses
560 the built-in system path.
563 This is an environment variable which holds a list of paths.
566 The final class path is constructed like so:
570 First come all directories specified via @code{-I}.
573 If @code{--classpath} is specified, its value is appended and processing
574 stops. That is, @code{--classpath} suppresses all the options mentioned
578 If @code{--CLASSPATH} is specified, its value is appended and the
579 @code{CLASSPATH} environment variable is suppressed.
582 If the @code{CLASSPATH} environment variable is specified (and was not
583 suppressed by @code{--CLASSPATH}), then its value is appended.
586 Finally, the built-in system directory, @file{libgcj.jar}, is appended.
593 The Java programming language uses Unicode throughout. In an effort to
594 integrate well with other locales, @code{gcj} allows @file{.java} files
595 to be written using almost any encoding. @code{gcj} knows how to
596 convert these encodings into its internal encoding at compile time.
598 You can use the @code{--encoding=@var{NAME}} option to specify an
599 encoding (of a particular character set) to use for source files. If
600 this is not specified, the default encoding comes from your current
601 locale. If your host system has insufficient locale support, then
602 @code{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
605 To implement @code{--encoding}, @code{gcj} simply uses the host
606 platform's @code{iconv} conversion routine. This means that in practice
607 @code{gcj} is limited by the capabilities of the host platform.
609 The names allowed for the argument @code{--encoding} vary from platform
610 to platform (since they are not standardized anywhere). However,
611 @code{gcj} implements the encoding named @samp{UTF-8} internally, so if
612 you choose to use this for your source files you can be assured that it
613 will work on every host.
619 @code{gcj} implements several warnings. As with other generic
620 @code{gcc} warnings, if an option of the form @code{-Wfoo} enables a
621 warning, then @code{-Wno-foo} will disable it. Here we've chosen to
622 document the form of the warning which will have an effect -- the
623 default being the opposite of what is listed.
626 @item -Wredundant-modifiers
627 With this flag, @code{gcj} will warn about redundant modifiers. For
628 instance, it will warn if an interface method is declared @code{public}.
630 @item -Wextraneous-semicolon
631 This causes @code{gcj} to warn about empty statements. Empty statements
632 have been deprecated.
634 @item -Wno-out-of-date
635 This option will cause @code{gcj} not to warn when a source file is
636 newer than its matching class file. By default @code{gcj} will warn
640 This is the same as @code{gcc}'s @code{-Wunused}.
643 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
648 @node Code Generation
649 @section Code Generation
651 In addition to the many @code{gcc} options controlling code generation,
652 @code{gcj} has several options specific to itself.
655 @item --main=@var{CLASSNAME}
656 This option is used when linking to specify the name of the class whose
657 @code{main} method should be invoked when the resulting executable is
658 run. @footnote{The linker by default looks for a global function named
659 @code{main}. Since Java does not have global functions, and a
660 collection of Java classes may have more than one class with a
661 @code{main} method, you need to let the linker know which of those
662 @code{main} methods it should invoke when starting the application.}
664 @item -D@var{name}[=@var{value}]
665 This option can only be used with @code{--main}. It defines a system
666 property named @var{name} with value @var{value}. If @var{value} is not
667 specified then it defaults to the empty string. These system properties
668 are initialized at the program's startup and can be retrieved at runtime
669 using the @code{java.lang.System.getProperty} method.
672 This option is used to tell @code{gcj} to generate bytecode
673 (@file{.class} files) rather than object code.
675 @item -d @var{directory}
676 When used with @code{-C}, this causes all generated @file{.class} files
677 to be put in the appropriate subdirectory of @var{directory}. By
678 default they will be put in subdirectories of the current working
681 @item -fno-bounds-check
682 By default, @code{gcj} generates code which checks the bounds of all
683 array indexing operations. With this option, these checks are omitted.
684 Note that this can result in unpredictable behavior if the code in
685 question actually does violate array bounds constraints.
688 With @code{gcj} there are two options for writing native methods: CNI
689 and JNI. By default @code{gcj} assumes you are using CNI. If you are
690 compiling a class with native methods, and these methods are implemented
691 using JNI, then you must use @code{-fjni}. This option causes
692 @code{gcj} to generate stubs which will invoke the underlying JNI
697 @node Configure-time Options
698 @section Configure-time Options
700 Some @code{gcj} code generations options affect the resulting ABI, and
701 so can only be meaningfully given when @code{libgcj}, the runtime
702 package, is configured. @code{libgcj} puts the appropriate options from
703 this group into a @samp{spec} file which is read by @code{gcj}. These
704 options are listed here for completeness; if you are using @code{libgcj}
705 then you won't want to touch these options.
709 This enables the use of the Boehm GC bitmap marking code. In particular
710 this causes @code{gcj} to put an object marking descriptor into each
713 @item -fhash-synchronization
714 By default, synchronization data (the data used for @code{synchronize},
715 @code{wait}, and @code{notify}) is pointed to by a word in each object.
716 With this option @code{gcj} assumes that this information is stored in a
717 hash table and not in the object itself.
719 @item -fuse-divide-subroutine
720 On some systems, a library routine is called to perform integer
721 division. This is required to get exception handling correct when
727 @chapter Compatibility with the Java Platform
729 As we believe it is important that the Java platform not be fragmented,
730 @code{gcj} and @code{libgcj} try to conform to the relevant Java
731 specifications. However, limited manpower and incomplete and unclear
732 documentation work against us. So, there are caveats to using
735 This list of compatibility issues is by no means complete.
739 @code{gcj} implements the JDK 1.1 language. It supports inner classes,
740 though these are known to still be buggy. It does not yet support the
741 Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores
745 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
746 However, @code{libgcj} is missing many packages, most notably
747 @code{java.awt}. There are also individual missing classes and methods.
748 We currently do not have a list showing differences between
749 @code{libgcj} and the Java 2 platform.
752 Sometimes the @code{libgcj} implementation of a method or class differs
753 from the JDK implementation. This is not always a bug. Still, if it
754 affects you, it probably makes sense to report it so that we can discuss
755 the appropriate response.
760 @chapter Invoking gcjh
762 The @code{gcjh} program is used to generate header files from class
763 files. It can generate both CNI and JNI header files, as well as stub
764 implementation files which can be used as a basis for implementing the
765 required native methods.
769 This causes @code{gcjh} to generate stub files instead of header files.
770 By default the stub file will be named after the class, with a suffix of
771 @samp{.cc}. In JNI mode, the default output file will have the suffix
775 This tells @code{gcjh} to generate a JNI header or stub. By default,
776 CNI headers are generated.
778 @item -add @var{text}
779 Inserts @var{text} into the class body. This is ignored in JNI mode.
781 @item -append @var{text}
782 Inserts @var{text} into the header file after the class declaration.
783 This is ignored in JNI mode.
785 @item -friend @var{text}
786 Inserts @var{text} into the class as a @code{friend} declaration.
787 This is ignored in JNI mode.
789 @item -prepend @var{text}
790 Inserts @var{text} into the header file before the class declaration.
791 This is ignored in JNI mode.
793 @item --classpath=@var{path}
794 @itemx --CLASSPATH=@var{path}
795 @itemx -I@var{directory}
796 @itemx -d @var{directory}
798 These options are all identical to the corresponding @code{gcj} options.
801 Sets the output file name. This cannot be used if there is more than
802 one class on the command line.
804 @item -td @var{directory}
805 Sets the name of the directory to use for temporary files.
808 Print help about @code{gcjh} and exit. No further processing is done.
811 Print version information for @code{gcjh} and exit. No further
815 All remaining options are considered to be names of classes.
818 @node Invoking jv-scan
819 @chapter Invoking jv-scan
821 The @code{jv-scan} program can be used to print information about a Java
822 source file (@file{.java} file).
826 This prints a complexity measure, related to cyclomatic complexity, for
829 @item --encoding=@var{name}
830 This works like the corresponding @code{gcj} option.
833 This prints the name of the class in this file containing a @code{main}
837 This lists the names of all classes defined in the input files.
839 @item --list-filename
840 If @code{--list-class} is given, this option causes @code{jv-scan} to
841 also print the name of the file in which each class was found.
844 Print output to the named file.
848 @node Invoking jcf-dump
849 @chapter Invoking jcf-dump
851 This is a class file examiner, similar to @code{javap}. It will print
852 information about a number of classes, which are specifed by class name
857 Disassemble method bodies. By default method bodies are not printed.
860 Generate output in @code{javap} format. The implementation of this
861 feature is very incomplete.
863 @item --classpath=@var{path}
864 @itemx --CLASSPATH=@var{path}
865 @itemx -I@var{directory}
867 These options as the same as the corresponding @code{gcj} options.
872 @chapter Invoking gij
874 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
875 @code{gij} is not available on every platform; porting it requires a
876 small amount of assembly programming which has not been done for all the
877 targets supported by @code{gcj}.
879 The primary argument to @code{gij} is the name of a class or, with
880 @code{-jar}, a jar file. Options before this argument are interpreted
881 by @code{gij}; remaining options are passed to the interpreted program.
883 If a class name is specified and this class does not have a @code{main}
884 method with the appropriate signature (a @code{static void} method with
885 a @code{String[]} as its sole argument), then @code{gij} will print an
888 If a jar file is specified then @code{gij} will use information in it to
889 determine which class' @code{main} method will be invoked.
891 @code{gij} will invoke the @code{main} method with all the remaining
892 command-line options.
894 Note that @code{gij} is not limited to interpreting code. Because
895 @code{libgcj} includes a class loader which can dynamically load shared
896 objects, it is possible to give @code{gij} the name of a class which has
897 been compiled and put into a shared library on the class path.
900 @item -D@var{name}[=@var{value}]
901 This defines a system property named @var{name} with value @var{value}.
902 If @var{value} is not specified then it defaults to the empty string.
903 These system properties are initialized at the program's startup and can
904 be retrieved at runtime using the @code{java.lang.System.getProperty}
907 @item -ms=@var{number}
908 This sets the initial heap size
910 @item -mx=@var{number}
911 This sets the maximum heap size.
914 This indicates that the name passed to @code{gij} should be interpreted
915 as the name of a jar file, not a class.
922 While writing @code{gcj} and @code{libgcj} we have, of course, relied
923 heavily on documentation from Sun Microsystems. In particular we have
924 used The Java Language Specification (both first and second editions),
925 the Java Class Libraries (volumes one and two), and the Java Virtual
926 Machine Specification. In addition we've used the online documentation
927 at @uref{http://java.sun.com/}.
929 The current @code{gcj} home page is
930 @uref{http://gcc.gnu.org/java/}.
932 For more information on gcc, see @uref{http://gcc.gnu.org/}.
934 Some @code{libgcj} testing is done using the Mauve test suite. This is
935 a free software Java class library test suite which is being written
936 because the JCK is not free. See
937 @uref{http://sources.redhat.com/mauve/} for more information.