1 This is doc/gcj.info, produced by makeinfo version 4.7 from
2 /scratch/mitchell/gcc-releases/gcc-4.0.0/gcc-4.0.0/gcc/java/gcj.texi.
4 Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation,
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being "GNU General Public License", the Front-Cover
11 texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the section entitled
13 "GNU Free Documentation License".
15 (a) The FSF's Front-Cover Text is:
19 (b) The FSF's Back-Cover Text is:
21 You have freedom to copy and modify this GNU Manual, like GNU
22 software. Copies published by the Free Software Foundation raise
23 funds for GNU development. man end
25 INFO-DIR-SECTION Programming
27 * Gcj: (gcj). Ahead-of-time compiler for the Java language
30 INFO-DIR-SECTION Individual utilities
32 * gcjh: (gcj)Invoking gcjh.
33 Generate header files from Java class files
34 * jv-scan: (gcj)Invoking jv-scan.
35 Print information about Java source files
36 * jcf-dump: (gcj)Invoking jcf-dump.
37 Print information about Java class files
38 * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
39 * gcj-dbtool: (gcj)Invoking gcj-dbtool.
40 Tool for manipulating class file databases.
41 * jv-convert: (gcj)Invoking jv-convert.
42 Convert file from one encoding to another
43 * grmic: (gcj)Invoking grmic.
44 Generate stubs for Remote Method Invocation.
45 * grmiregistry: (gcj)Invoking grmiregistry.
46 The remote object registry.
49 Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation,
52 Permission is granted to copy, distribute and/or modify this document
53 under the terms of the GNU Free Documentation License, Version 1.2 or
54 any later version published by the Free Software Foundation; with the
55 Invariant Sections being "GNU General Public License", the Front-Cover
56 texts being (a) (see below), and with the Back-Cover Texts being (b)
57 (see below). A copy of the license is included in the section entitled
58 "GNU Free Documentation License".
60 (a) The FSF's Front-Cover Text is:
64 (b) The FSF's Back-Cover Text is:
66 You have freedom to copy and modify this GNU Manual, like GNU
67 software. Copies published by the Free Software Foundation raise
68 funds for GNU development. man end
71 File: gcj.info, Node: Top, Next: Copying, Up: (dir)
76 This manual describes how to use `gcj', the GNU compiler for the Java
77 programming language. `gcj' can generate both `.class' files and
78 object files, and it can read both Java source code and `.class' files.
82 * Copying:: The GNU General Public License
83 * GNU Free Documentation License::
84 How you can share and copy this manual
85 * Invoking gcj:: Compiler options supported by `gcj'
86 * Compatibility:: Compatibility between gcj and other tools for Java
87 * Invoking gcjh:: Generate header files from class files
88 * Invoking jv-scan:: Print information about source files
89 * Invoking jcf-dump:: Print information about class files
90 * Invoking gij:: Interpreting Java bytecodes
91 * Invoking gcj-dbtool:: Tool for manipulating class file databases.
92 * Invoking jv-convert:: Converting from one encoding to another
93 * Invoking grmic:: Generate stubs for Remote Method Invocation.
94 * Invoking grmiregistry:: The remote object registry.
95 * About CNI:: Description of the Compiled Native Interface
96 * System properties:: Modifying runtime behavior of the libgcj library
97 * Resources:: Where to look for more information
100 File: gcj.info, Node: Copying, Next: GNU Free Documentation License, Prev: Top, Up: Top
102 GNU GENERAL PUBLIC LICENSE
103 **************************
107 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
108 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
110 Everyone is permitted to copy and distribute verbatim copies
111 of this license document, but changing it is not allowed.
116 The licenses for most software are designed to take away your freedom
117 to share and change it. By contrast, the GNU General Public License is
118 intended to guarantee your freedom to share and change free
119 software--to make sure the software is free for all its users. This
120 General Public License applies to most of the Free Software
121 Foundation's software and to any other program whose authors commit to
122 using it. (Some other Free Software Foundation software is covered by
123 the GNU Library General Public License instead.) You can apply it to
126 When we speak of free software, we are referring to freedom, not
127 price. Our General Public Licenses are designed to make sure that you
128 have the freedom to distribute copies of free software (and charge for
129 this service if you wish), that you receive source code or can get it
130 if you want it, that you can change the software or use pieces of it in
131 new free programs; and that you know you can do these things.
133 To protect your rights, we need to make restrictions that forbid
134 anyone to deny you these rights or to ask you to surrender the rights.
135 These restrictions translate to certain responsibilities for you if you
136 distribute copies of the software, or if you modify it.
138 For example, if you distribute copies of such a program, whether
139 gratis or for a fee, you must give the recipients all the rights that
140 you have. You must make sure that they, too, receive or can get the
141 source code. And you must show them these terms so they know their
144 We protect your rights with two steps: (1) copyright the software,
145 and (2) offer you this license which gives you legal permission to copy,
146 distribute and/or modify the software.
148 Also, for each author's protection and ours, we want to make certain
149 that everyone understands that there is no warranty for this free
150 software. If the software is modified by someone else and passed on, we
151 want its recipients to know that what they have is not the original, so
152 that any problems introduced by others will not reflect on the original
153 authors' reputations.
155 Finally, any free program is threatened constantly by software
156 patents. We wish to avoid the danger that redistributors of a free
157 program will individually obtain patent licenses, in effect making the
158 program proprietary. To prevent this, we have made it clear that any
159 patent must be licensed for everyone's free use or not licensed at all.
161 The precise terms and conditions for copying, distribution and
164 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
165 0. This License applies to any program or other work which contains a
166 notice placed by the copyright holder saying it may be distributed
167 under the terms of this General Public License. The "Program",
168 below, refers to any such program or work, and a "work based on
169 the Program" means either the Program or any derivative work under
170 copyright law: that is to say, a work containing the Program or a
171 portion of it, either verbatim or with modifications and/or
172 translated into another language. (Hereinafter, translation is
173 included without limitation in the term "modification".) Each
174 licensee is addressed as "you".
176 Activities other than copying, distribution and modification are
177 not covered by this License; they are outside its scope. The act
178 of running the Program is not restricted, and the output from the
179 Program is covered only if its contents constitute a work based on
180 the Program (independent of having been made by running the
181 Program). Whether that is true depends on what the Program does.
183 1. You may copy and distribute verbatim copies of the Program's
184 source code as you receive it, in any medium, provided that you
185 conspicuously and appropriately publish on each copy an appropriate
186 copyright notice and disclaimer of warranty; keep intact all the
187 notices that refer to this License and to the absence of any
188 warranty; and give any other recipients of the Program a copy of
189 this License along with the Program.
191 You may charge a fee for the physical act of transferring a copy,
192 and you may at your option offer warranty protection in exchange
195 2. You may modify your copy or copies of the Program or any portion
196 of it, thus forming a work based on the Program, and copy and
197 distribute such modifications or work under the terms of Section 1
198 above, provided that you also meet all of these conditions:
200 a. You must cause the modified files to carry prominent notices
201 stating that you changed the files and the date of any change.
203 b. You must cause any work that you distribute or publish, that
204 in whole or in part contains or is derived from the Program
205 or any part thereof, to be licensed as a whole at no charge
206 to all third parties under the terms of this License.
208 c. If the modified program normally reads commands interactively
209 when run, you must cause it, when started running for such
210 interactive use in the most ordinary way, to print or display
211 an announcement including an appropriate copyright notice and
212 a notice that there is no warranty (or else, saying that you
213 provide a warranty) and that users may redistribute the
214 program under these conditions, and telling the user how to
215 view a copy of this License. (Exception: if the Program
216 itself is interactive but does not normally print such an
217 announcement, your work based on the Program is not required
218 to print an announcement.)
220 These requirements apply to the modified work as a whole. If
221 identifiable sections of that work are not derived from the
222 Program, and can be reasonably considered independent and separate
223 works in themselves, then this License, and its terms, do not
224 apply to those sections when you distribute them as separate
225 works. But when you distribute the same sections as part of a
226 whole which is a work based on the Program, the distribution of
227 the whole must be on the terms of this License, whose permissions
228 for other licensees extend to the entire whole, and thus to each
229 and every part regardless of who wrote it.
231 Thus, it is not the intent of this section to claim rights or
232 contest your rights to work written entirely by you; rather, the
233 intent is to exercise the right to control the distribution of
234 derivative or collective works based on the Program.
236 In addition, mere aggregation of another work not based on the
237 Program with the Program (or with a work based on the Program) on
238 a volume of a storage or distribution medium does not bring the
239 other work under the scope of this License.
241 3. You may copy and distribute the Program (or a work based on it,
242 under Section 2) in object code or executable form under the terms
243 of Sections 1 and 2 above provided that you also do one of the
246 a. Accompany it with the complete corresponding machine-readable
247 source code, which must be distributed under the terms of
248 Sections 1 and 2 above on a medium customarily used for
249 software interchange; or,
251 b. Accompany it with a written offer, valid for at least three
252 years, to give any third party, for a charge no more than your
253 cost of physically performing source distribution, a complete
254 machine-readable copy of the corresponding source code, to be
255 distributed under the terms of Sections 1 and 2 above on a
256 medium customarily used for software interchange; or,
258 c. Accompany it with the information you received as to the offer
259 to distribute corresponding source code. (This alternative is
260 allowed only for noncommercial distribution and only if you
261 received the program in object code or executable form with
262 such an offer, in accord with Subsection b above.)
264 The source code for a work means the preferred form of the work for
265 making modifications to it. For an executable work, complete
266 source code means all the source code for all modules it contains,
267 plus any associated interface definition files, plus the scripts
268 used to control compilation and installation of the executable.
269 However, as a special exception, the source code distributed need
270 not include anything that is normally distributed (in either
271 source or binary form) with the major components (compiler,
272 kernel, and so on) of the operating system on which the executable
273 runs, unless that component itself accompanies the executable.
275 If distribution of executable or object code is made by offering
276 access to copy from a designated place, then offering equivalent
277 access to copy the source code from the same place counts as
278 distribution of the source code, even though third parties are not
279 compelled to copy the source along with the object code.
281 4. You may not copy, modify, sublicense, or distribute the Program
282 except as expressly provided under this License. Any attempt
283 otherwise to copy, modify, sublicense or distribute the Program is
284 void, and will automatically terminate your rights under this
285 License. However, parties who have received copies, or rights,
286 from you under this License will not have their licenses
287 terminated so long as such parties remain in full compliance.
289 5. You are not required to accept this License, since you have not
290 signed it. However, nothing else grants you permission to modify
291 or distribute the Program or its derivative works. These actions
292 are prohibited by law if you do not accept this License.
293 Therefore, by modifying or distributing the Program (or any work
294 based on the Program), you indicate your acceptance of this
295 License to do so, and all its terms and conditions for copying,
296 distributing or modifying the Program or works based on it.
298 6. Each time you redistribute the Program (or any work based on the
299 Program), the recipient automatically receives a license from the
300 original licensor to copy, distribute or modify the Program
301 subject to these terms and conditions. You may not impose any
302 further restrictions on the recipients' exercise of the rights
303 granted herein. You are not responsible for enforcing compliance
304 by third parties to this License.
306 7. If, as a consequence of a court judgment or allegation of patent
307 infringement or for any other reason (not limited to patent
308 issues), conditions are imposed on you (whether by court order,
309 agreement or otherwise) that contradict the conditions of this
310 License, they do not excuse you from the conditions of this
311 License. If you cannot distribute so as to satisfy simultaneously
312 your obligations under this License and any other pertinent
313 obligations, then as a consequence you may not distribute the
314 Program at all. For example, if a patent license would not permit
315 royalty-free redistribution of the Program by all those who
316 receive copies directly or indirectly through you, then the only
317 way you could satisfy both it and this License would be to refrain
318 entirely from distribution of the Program.
320 If any portion of this section is held invalid or unenforceable
321 under any particular circumstance, the balance of the section is
322 intended to apply and the section as a whole is intended to apply
323 in other circumstances.
325 It is not the purpose of this section to induce you to infringe any
326 patents or other property right claims or to contest validity of
327 any such claims; this section has the sole purpose of protecting
328 the integrity of the free software distribution system, which is
329 implemented by public license practices. Many people have made
330 generous contributions to the wide range of software distributed
331 through that system in reliance on consistent application of that
332 system; it is up to the author/donor to decide if he or she is
333 willing to distribute software through any other system and a
334 licensee cannot impose that choice.
336 This section is intended to make thoroughly clear what is believed
337 to be a consequence of the rest of this License.
339 8. If the distribution and/or use of the Program is restricted in
340 certain countries either by patents or by copyrighted interfaces,
341 the original copyright holder who places the Program under this
342 License may add an explicit geographical distribution limitation
343 excluding those countries, so that distribution is permitted only
344 in or among countries not thus excluded. In such case, this
345 License incorporates the limitation as if written in the body of
348 9. The Free Software Foundation may publish revised and/or new
349 versions of the General Public License from time to time. Such
350 new versions will be similar in spirit to the present version, but
351 may differ in detail to address new problems or concerns.
353 Each version is given a distinguishing version number. If the
354 Program specifies a version number of this License which applies
355 to it and "any later version", you have the option of following
356 the terms and conditions either of that version or of any later
357 version published by the Free Software Foundation. If the Program
358 does not specify a version number of this License, you may choose
359 any version ever published by the Free Software Foundation.
361 10. If you wish to incorporate parts of the Program into other free
362 programs whose distribution conditions are different, write to the
363 author to ask for permission. For software which is copyrighted
364 by the Free Software Foundation, write to the Free Software
365 Foundation; we sometimes make exceptions for this. Our decision
366 will be guided by the two goals of preserving the free status of
367 all derivatives of our free software and of promoting the sharing
368 and reuse of software generally.
371 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
372 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
373 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
374 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
375 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
376 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
377 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
378 QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
379 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
380 SERVICING, REPAIR OR CORRECTION.
382 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
383 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
384 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
385 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
386 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
387 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
388 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
389 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
390 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
391 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
393 END OF TERMS AND CONDITIONS
394 How to Apply These Terms to Your New Programs
395 =============================================
397 If you develop a new program, and you want it to be of the greatest
398 possible use to the public, the best way to achieve this is to make it
399 free software which everyone can redistribute and change under these
402 To do so, attach the following notices to the program. It is safest
403 to attach them to the start of each source file to most effectively
404 convey the exclusion of warranty; and each file should have at least
405 the "copyright" line and a pointer to where the full notice is found.
407 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
408 Copyright (C) YEAR NAME OF AUTHOR
410 This program is free software; you can redistribute it and/or modify
411 it under the terms of the GNU General Public License as published by
412 the Free Software Foundation; either version 2 of the License, or
413 (at your option) any later version.
415 This program is distributed in the hope that it will be useful,
416 but WITHOUT ANY WARRANTY; without even the implied warranty of
417 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
418 GNU General Public License for more details.
420 You should have received a copy of the GNU General Public License
421 along with this program; if not, write to the Free Software Foundation,
422 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
424 Also add information on how to contact you by electronic and paper
427 If the program is interactive, make it output a short notice like
428 this when it starts in an interactive mode:
430 Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
431 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
433 This is free software, and you are welcome to redistribute it
434 under certain conditions; type `show c' for details.
436 The hypothetical commands `show w' and `show c' should show the
437 appropriate parts of the General Public License. Of course, the
438 commands you use may be called something other than `show w' and `show
439 c'; they could even be mouse-clicks or menu items--whatever suits your
442 You should also get your employer (if you work as a programmer) or
443 your school, if any, to sign a "copyright disclaimer" for the program,
444 if necessary. Here is a sample; alter the names:
446 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
447 `Gnomovision' (which makes passes at compilers) written by James Hacker.
449 SIGNATURE OF TY COON, 1 April 1989
450 Ty Coon, President of Vice
452 This General Public License does not permit incorporating your
453 program into proprietary programs. If your program is a subroutine
454 library, you may consider it more useful to permit linking proprietary
455 applications with the library. If this is what you want to do, use the
456 GNU Library General Public License instead of this License.
459 File: gcj.info, Node: GNU Free Documentation License, Next: Invoking gcj, Prev: Copying, Up: Top
461 GNU Free Documentation License
462 ******************************
464 Version 1.2, November 2002
466 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
467 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
469 Everyone is permitted to copy and distribute verbatim copies
470 of this license document, but changing it is not allowed.
474 The purpose of this License is to make a manual, textbook, or other
475 functional and useful document "free" in the sense of freedom: to
476 assure everyone the effective freedom to copy and redistribute it,
477 with or without modifying it, either commercially or
478 noncommercially. Secondarily, this License preserves for the
479 author and publisher a way to get credit for their work, while not
480 being considered responsible for modifications made by others.
482 This License is a kind of "copyleft", which means that derivative
483 works of the document must themselves be free in the same sense.
484 It complements the GNU General Public License, which is a copyleft
485 license designed for free software.
487 We have designed this License in order to use it for manuals for
488 free software, because free software needs free documentation: a
489 free program should come with manuals providing the same freedoms
490 that the software does. But this License is not limited to
491 software manuals; it can be used for any textual work, regardless
492 of subject matter or whether it is published as a printed book.
493 We recommend this License principally for works whose purpose is
494 instruction or reference.
496 1. APPLICABILITY AND DEFINITIONS
498 This License applies to any manual or other work, in any medium,
499 that contains a notice placed by the copyright holder saying it
500 can be distributed under the terms of this License. Such a notice
501 grants a world-wide, royalty-free license, unlimited in duration,
502 to use that work under the conditions stated herein. The
503 "Document", below, refers to any such manual or work. Any member
504 of the public is a licensee, and is addressed as "you". You
505 accept the license if you copy, modify or distribute the work in a
506 way requiring permission under copyright law.
508 A "Modified Version" of the Document means any work containing the
509 Document or a portion of it, either copied verbatim, or with
510 modifications and/or translated into another language.
512 A "Secondary Section" is a named appendix or a front-matter section
513 of the Document that deals exclusively with the relationship of the
514 publishers or authors of the Document to the Document's overall
515 subject (or to related matters) and contains nothing that could
516 fall directly within that overall subject. (Thus, if the Document
517 is in part a textbook of mathematics, a Secondary Section may not
518 explain any mathematics.) The relationship could be a matter of
519 historical connection with the subject or with related matters, or
520 of legal, commercial, philosophical, ethical or political position
523 The "Invariant Sections" are certain Secondary Sections whose
524 titles are designated, as being those of Invariant Sections, in
525 the notice that says that the Document is released under this
526 License. If a section does not fit the above definition of
527 Secondary then it is not allowed to be designated as Invariant.
528 The Document may contain zero Invariant Sections. If the Document
529 does not identify any Invariant Sections then there are none.
531 The "Cover Texts" are certain short passages of text that are
532 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
533 that says that the Document is released under this License. A
534 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
537 A "Transparent" copy of the Document means a machine-readable copy,
538 represented in a format whose specification is available to the
539 general public, that is suitable for revising the document
540 straightforwardly with generic text editors or (for images
541 composed of pixels) generic paint programs or (for drawings) some
542 widely available drawing editor, and that is suitable for input to
543 text formatters or for automatic translation to a variety of
544 formats suitable for input to text formatters. A copy made in an
545 otherwise Transparent file format whose markup, or absence of
546 markup, has been arranged to thwart or discourage subsequent
547 modification by readers is not Transparent. An image format is
548 not Transparent if used for any substantial amount of text. A
549 copy that is not "Transparent" is called "Opaque".
551 Examples of suitable formats for Transparent copies include plain
552 ASCII without markup, Texinfo input format, LaTeX input format,
553 SGML or XML using a publicly available DTD, and
554 standard-conforming simple HTML, PostScript or PDF designed for
555 human modification. Examples of transparent image formats include
556 PNG, XCF and JPG. Opaque formats include proprietary formats that
557 can be read and edited only by proprietary word processors, SGML or
558 XML for which the DTD and/or processing tools are not generally
559 available, and the machine-generated HTML, PostScript or PDF
560 produced by some word processors for output purposes only.
562 The "Title Page" means, for a printed book, the title page itself,
563 plus such following pages as are needed to hold, legibly, the
564 material this License requires to appear in the title page. For
565 works in formats which do not have any title page as such, "Title
566 Page" means the text near the most prominent appearance of the
567 work's title, preceding the beginning of the body of the text.
569 A section "Entitled XYZ" means a named subunit of the Document
570 whose title either is precisely XYZ or contains XYZ in parentheses
571 following text that translates XYZ in another language. (Here XYZ
572 stands for a specific section name mentioned below, such as
573 "Acknowledgements", "Dedications", "Endorsements", or "History".)
574 To "Preserve the Title" of such a section when you modify the
575 Document means that it remains a section "Entitled XYZ" according
578 The Document may include Warranty Disclaimers next to the notice
579 which states that this License applies to the Document. These
580 Warranty Disclaimers are considered to be included by reference in
581 this License, but only as regards disclaiming warranties: any other
582 implication that these Warranty Disclaimers may have is void and
583 has no effect on the meaning of this License.
587 You may copy and distribute the Document in any medium, either
588 commercially or noncommercially, provided that this License, the
589 copyright notices, and the license notice saying this License
590 applies to the Document are reproduced in all copies, and that you
591 add no other conditions whatsoever to those of this License. You
592 may not use technical measures to obstruct or control the reading
593 or further copying of the copies you make or distribute. However,
594 you may accept compensation in exchange for copies. If you
595 distribute a large enough number of copies you must also follow
596 the conditions in section 3.
598 You may also lend copies, under the same conditions stated above,
599 and you may publicly display copies.
601 3. COPYING IN QUANTITY
603 If you publish printed copies (or copies in media that commonly
604 have printed covers) of the Document, numbering more than 100, and
605 the Document's license notice requires Cover Texts, you must
606 enclose the copies in covers that carry, clearly and legibly, all
607 these Cover Texts: Front-Cover Texts on the front cover, and
608 Back-Cover Texts on the back cover. Both covers must also clearly
609 and legibly identify you as the publisher of these copies. The
610 front cover must present the full title with all words of the
611 title equally prominent and visible. You may add other material
612 on the covers in addition. Copying with changes limited to the
613 covers, as long as they preserve the title of the Document and
614 satisfy these conditions, can be treated as verbatim copying in
617 If the required texts for either cover are too voluminous to fit
618 legibly, you should put the first ones listed (as many as fit
619 reasonably) on the actual cover, and continue the rest onto
622 If you publish or distribute Opaque copies of the Document
623 numbering more than 100, you must either include a
624 machine-readable Transparent copy along with each Opaque copy, or
625 state in or with each Opaque copy a computer-network location from
626 which the general network-using public has access to download
627 using public-standard network protocols a complete Transparent
628 copy of the Document, free of added material. If you use the
629 latter option, you must take reasonably prudent steps, when you
630 begin distribution of Opaque copies in quantity, to ensure that
631 this Transparent copy will remain thus accessible at the stated
632 location until at least one year after the last time you
633 distribute an Opaque copy (directly or through your agents or
634 retailers) of that edition to the public.
636 It is requested, but not required, that you contact the authors of
637 the Document well before redistributing any large number of
638 copies, to give them a chance to provide you with an updated
639 version of the Document.
643 You may copy and distribute a Modified Version of the Document
644 under the conditions of sections 2 and 3 above, provided that you
645 release the Modified Version under precisely this License, with
646 the Modified Version filling the role of the Document, thus
647 licensing distribution and modification of the Modified Version to
648 whoever possesses a copy of it. In addition, you must do these
649 things in the Modified Version:
651 A. Use in the Title Page (and on the covers, if any) a title
652 distinct from that of the Document, and from those of
653 previous versions (which should, if there were any, be listed
654 in the History section of the Document). You may use the
655 same title as a previous version if the original publisher of
656 that version gives permission.
658 B. List on the Title Page, as authors, one or more persons or
659 entities responsible for authorship of the modifications in
660 the Modified Version, together with at least five of the
661 principal authors of the Document (all of its principal
662 authors, if it has fewer than five), unless they release you
663 from this requirement.
665 C. State on the Title page the name of the publisher of the
666 Modified Version, as the publisher.
668 D. Preserve all the copyright notices of the Document.
670 E. Add an appropriate copyright notice for your modifications
671 adjacent to the other copyright notices.
673 F. Include, immediately after the copyright notices, a license
674 notice giving the public permission to use the Modified
675 Version under the terms of this License, in the form shown in
678 G. Preserve in that license notice the full lists of Invariant
679 Sections and required Cover Texts given in the Document's
682 H. Include an unaltered copy of this License.
684 I. Preserve the section Entitled "History", Preserve its Title,
685 and add to it an item stating at least the title, year, new
686 authors, and publisher of the Modified Version as given on
687 the Title Page. If there is no section Entitled "History" in
688 the Document, create one stating the title, year, authors,
689 and publisher of the Document as given on its Title Page,
690 then add an item describing the Modified Version as stated in
691 the previous sentence.
693 J. Preserve the network location, if any, given in the Document
694 for public access to a Transparent copy of the Document, and
695 likewise the network locations given in the Document for
696 previous versions it was based on. These may be placed in
697 the "History" section. You may omit a network location for a
698 work that was published at least four years before the
699 Document itself, or if the original publisher of the version
700 it refers to gives permission.
702 K. For any section Entitled "Acknowledgements" or "Dedications",
703 Preserve the Title of the section, and preserve in the
704 section all the substance and tone of each of the contributor
705 acknowledgements and/or dedications given therein.
707 L. Preserve all the Invariant Sections of the Document,
708 unaltered in their text and in their titles. Section numbers
709 or the equivalent are not considered part of the section
712 M. Delete any section Entitled "Endorsements". Such a section
713 may not be included in the Modified Version.
715 N. Do not retitle any existing section to be Entitled
716 "Endorsements" or to conflict in title with any Invariant
719 O. Preserve any Warranty Disclaimers.
721 If the Modified Version includes new front-matter sections or
722 appendices that qualify as Secondary Sections and contain no
723 material copied from the Document, you may at your option
724 designate some or all of these sections as invariant. To do this,
725 add their titles to the list of Invariant Sections in the Modified
726 Version's license notice. These titles must be distinct from any
727 other section titles.
729 You may add a section Entitled "Endorsements", provided it contains
730 nothing but endorsements of your Modified Version by various
731 parties--for example, statements of peer review or that the text
732 has been approved by an organization as the authoritative
733 definition of a standard.
735 You may add a passage of up to five words as a Front-Cover Text,
736 and a passage of up to 25 words as a Back-Cover Text, to the end
737 of the list of Cover Texts in the Modified Version. Only one
738 passage of Front-Cover Text and one of Back-Cover Text may be
739 added by (or through arrangements made by) any one entity. If the
740 Document already includes a cover text for the same cover,
741 previously added by you or by arrangement made by the same entity
742 you are acting on behalf of, you may not add another; but you may
743 replace the old one, on explicit permission from the previous
744 publisher that added the old one.
746 The author(s) and publisher(s) of the Document do not by this
747 License give permission to use their names for publicity for or to
748 assert or imply endorsement of any Modified Version.
750 5. COMBINING DOCUMENTS
752 You may combine the Document with other documents released under
753 this License, under the terms defined in section 4 above for
754 modified versions, provided that you include in the combination
755 all of the Invariant Sections of all of the original documents,
756 unmodified, and list them all as Invariant Sections of your
757 combined work in its license notice, and that you preserve all
758 their Warranty Disclaimers.
760 The combined work need only contain one copy of this License, and
761 multiple identical Invariant Sections may be replaced with a single
762 copy. If there are multiple Invariant Sections with the same name
763 but different contents, make the title of each such section unique
764 by adding at the end of it, in parentheses, the name of the
765 original author or publisher of that section if known, or else a
766 unique number. Make the same adjustment to the section titles in
767 the list of Invariant Sections in the license notice of the
770 In the combination, you must combine any sections Entitled
771 "History" in the various original documents, forming one section
772 Entitled "History"; likewise combine any sections Entitled
773 "Acknowledgements", and any sections Entitled "Dedications". You
774 must delete all sections Entitled "Endorsements."
776 6. COLLECTIONS OF DOCUMENTS
778 You may make a collection consisting of the Document and other
779 documents released under this License, and replace the individual
780 copies of this License in the various documents with a single copy
781 that is included in the collection, provided that you follow the
782 rules of this License for verbatim copying of each of the
783 documents in all other respects.
785 You may extract a single document from such a collection, and
786 distribute it individually under this License, provided you insert
787 a copy of this License into the extracted document, and follow
788 this License in all other respects regarding verbatim copying of
791 7. AGGREGATION WITH INDEPENDENT WORKS
793 A compilation of the Document or its derivatives with other
794 separate and independent documents or works, in or on a volume of
795 a storage or distribution medium, is called an "aggregate" if the
796 copyright resulting from the compilation is not used to limit the
797 legal rights of the compilation's users beyond what the individual
798 works permit. When the Document is included an aggregate, this
799 License does not apply to the other works in the aggregate which
800 are not themselves derivative works of the Document.
802 If the Cover Text requirement of section 3 is applicable to these
803 copies of the Document, then if the Document is less than one half
804 of the entire aggregate, the Document's Cover Texts may be placed
805 on covers that bracket the Document within the aggregate, or the
806 electronic equivalent of covers if the Document is in electronic
807 form. Otherwise they must appear on printed covers that bracket
812 Translation is considered a kind of modification, so you may
813 distribute translations of the Document under the terms of section
814 4. Replacing Invariant Sections with translations requires special
815 permission from their copyright holders, but you may include
816 translations of some or all Invariant Sections in addition to the
817 original versions of these Invariant Sections. You may include a
818 translation of this License, and all the license notices in the
819 Document, and any Warrany Disclaimers, provided that you also
820 include the original English version of this License and the
821 original versions of those notices and disclaimers. In case of a
822 disagreement between the translation and the original version of
823 this License or a notice or disclaimer, the original version will
826 If a section in the Document is Entitled "Acknowledgements",
827 "Dedications", or "History", the requirement (section 4) to
828 Preserve its Title (section 1) will typically require changing the
833 You may not copy, modify, sublicense, or distribute the Document
834 except as expressly provided for under this License. Any other
835 attempt to copy, modify, sublicense or distribute the Document is
836 void, and will automatically terminate your rights under this
837 License. However, parties who have received copies, or rights,
838 from you under this License will not have their licenses
839 terminated so long as such parties remain in full compliance.
841 10. FUTURE REVISIONS OF THIS LICENSE
843 The Free Software Foundation may publish new, revised versions of
844 the GNU Free Documentation License from time to time. Such new
845 versions will be similar in spirit to the present version, but may
846 differ in detail to address new problems or concerns. See
847 `http://www.gnu.org/copyleft/'.
849 Each version of the License is given a distinguishing version
850 number. If the Document specifies that a particular numbered
851 version of this License "or any later version" applies to it, you
852 have the option of following the terms and conditions either of
853 that specified version or of any later version that has been
854 published (not as a draft) by the Free Software Foundation. If
855 the Document does not specify a version number of this License,
856 you may choose any version ever published (not as a draft) by the
857 Free Software Foundation.
859 ADDENDUM: How to use this License for your documents
860 ====================================================
862 To use this License in a document you have written, include a copy of
863 the License in the document and put the following copyright and license
864 notices just after the title page:
866 Copyright (C) YEAR YOUR NAME.
867 Permission is granted to copy, distribute and/or modify this document
868 under the terms of the GNU Free Documentation License, Version 1.2
869 or any later version published by the Free Software Foundation;
870 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
871 A copy of the license is included in the section entitled ``GNU
872 Free Documentation License''.
874 If you have Invariant Sections, Front-Cover Texts and Back-Cover
875 Texts, replace the "with...Texts." line with this:
877 with the Invariant Sections being LIST THEIR TITLES, with
878 the Front-Cover Texts being LIST, and with the Back-Cover Texts
881 If you have Invariant Sections without Cover Texts, or some other
882 combination of the three, merge those two alternatives to suit the
885 If your document contains nontrivial examples of program code, we
886 recommend releasing these examples in parallel under your choice of
887 free software license, such as the GNU General Public License, to
888 permit their use in free software.
891 File: gcj.info, Node: Invoking gcj, Next: Compatibility, Prev: GNU Free Documentation License, Up: Top
896 As `gcj' is just another front end to `gcc', it supports many of the
897 same options as gcc. *Note Option Summary: (gcc)Option Summary. This
898 manual only documents the options specific to `gcj'.
902 * Input and output files::
903 * Input Options:: How gcj finds files
904 * Encodings:: Options controlling source file encoding
905 * Warnings:: Options controlling warnings specific to gcj
906 * Linking:: Options for making an executable
907 * Code Generation:: Options controlling the output of gcj
908 * Configure-time Options:: Options you won't use
911 File: gcj.info, Node: Input and output files, Next: Input Options, Up: Invoking gcj
913 1.1 Input and output files
914 ==========================
916 A `gcj' command is like a `gcc' command, in that it consists of a
917 number of options and file names. The following kinds of input file
928 An archive containing one or more `.class' files, all of which are
929 compiled. The archive may be compressed. Files in an archive
930 which don't end with `.class' are treated as resource files; they
931 are compiled into the resulting object file as `core:' URLs.
934 A file containing a whitespace-separated list of input file names.
935 (Currently, these must all be `.java' source files, but that may
936 change.) Each named file is compiled, just as if it had been on
942 Libraries to use when linking. See the `gcc' manual.
944 You can specify more than one input file on the `gcj' command line,
945 in which case they will all be compiled. If you specify a `-o FILENAME'
946 option, all the input files will be compiled together, producing a
947 single output file, named FILENAME. This is allowed even when using
948 `-S' or `-c', but not when using `-C' or `--resource'. (This is an
949 extension beyond the what plain `gcc' allows.) (If more than one input
950 file is specified, all must currently be `.java' files, though we hope
954 File: gcj.info, Node: Input Options, Next: Encodings, Prev: Input and output files, Up: Invoking gcj
959 `gcj' has options to control where it looks to find files it needs.
960 For instance, `gcj' might need to load a class that is referenced by
961 the file it has been asked to compile. Like other compilers for the
962 Java language, `gcj' has a notion of a "class path". There are several
963 options and environment variables which can be used to manipulate the
964 class path. When `gcj' looks for a given class, it searches the class
965 path looking for matching `.class' or `.java' file. `gcj' comes with a
966 built-in class path which points at the installed `libgcj.jar', a file
967 which contains all the standard classes.
969 In the below, a directory or path component can refer either to an
970 actual directory on the filesystem, or to a `.zip' or `.jar' file,
971 which `gcj' will search as if it is a directory.
974 All directories specified by `-I' are kept in order and prepended
975 to the class path constructed from all the other options. Unless
976 compatibility with tools like `javac' is important, we recommend
977 always using `-I' instead of the other options for manipulating the
981 This sets the class path to PATH, a colon-separated list of paths
982 (on Windows-based systems, a semicolon-separate list of paths).
983 This does not override the builtin ("boot") search path.
986 Deprecated synonym for `--classpath'.
988 `--bootclasspath=PATH'
989 Where to find the standard builtin classes, such as
993 For each directory in the PATH, place the contents of that
994 directory at the end of the class path.
997 This is an environment variable which holds a list of paths.
999 The final class path is constructed like so:
1001 * First come all directories specified via `-I'.
1003 * If `--classpath' is specified, its value is appended. Otherwise,
1004 if the `CLASSPATH' environment variable is specified, then its
1005 value is appended. Otherwise, the current directory (`"."') is
1008 * If `--bootclasspath' was specified, append its value. Otherwise,
1009 append the built-in system directory, `libgcj.jar'.
1011 * Finally, if `--extdirs' was specified, append the contents of the
1012 specified directories at the end of the class path. Otherwise,
1013 append the contents of the built-in extdirs at
1014 `$(prefix)/share/java/ext'.
1016 The classfile built by `gcj' for the class `java.lang.Object' (and
1017 placed in `libgcj.jar') contains a special zero length attribute
1018 `gnu.gcj.gcj-compiled'. The compiler looks for this attribute when
1019 loading `java.lang.Object' and will report an error if it isn't found,
1020 unless it compiles to bytecode (the option
1021 `-fforce-classes-archive-check' can be used to override this behavior
1022 in this particular case.)
1024 `-fforce-classes-archive-check'
1025 This forces the compiler to always check for the special zero
1026 length attribute `gnu.gcj.gcj-compiled' in `java.lang.Object' and
1027 issue an error if it isn't found.
1030 File: gcj.info, Node: Encodings, Next: Warnings, Prev: Input Options, Up: Invoking gcj
1035 The Java programming language uses Unicode throughout. In an effort to
1036 integrate well with other locales, `gcj' allows `.java' files to be
1037 written using almost any encoding. `gcj' knows how to convert these
1038 encodings into its internal encoding at compile time.
1040 You can use the `--encoding=NAME' option to specify an encoding (of
1041 a particular character set) to use for source files. If this is not
1042 specified, the default encoding comes from your current locale. If
1043 your host system has insufficient locale support, then `gcj' assumes
1044 the default encoding to be the `UTF-8' encoding of Unicode.
1046 To implement `--encoding', `gcj' simply uses the host platform's
1047 `iconv' conversion routine. This means that in practice `gcj' is
1048 limited by the capabilities of the host platform.
1050 The names allowed for the argument `--encoding' vary from platform
1051 to platform (since they are not standardized anywhere). However, `gcj'
1052 implements the encoding named `UTF-8' internally, so if you choose to
1053 use this for your source files you can be assured that it will work on
1057 File: gcj.info, Node: Warnings, Next: Linking, Prev: Encodings, Up: Invoking gcj
1062 `gcj' implements several warnings. As with other generic `gcc'
1063 warnings, if an option of the form `-Wfoo' enables a warning, then
1064 `-Wno-foo' will disable it. Here we've chosen to document the form of
1065 the warning which will have an effect - the default being the opposite
1068 `-Wredundant-modifiers'
1069 With this flag, `gcj' will warn about redundant modifiers. For
1070 instance, it will warn if an interface method is declared `public'.
1072 `-Wextraneous-semicolon'
1073 This causes `gcj' to warn about empty statements. Empty statements
1074 have been deprecated.
1077 This option will cause `gcj' not to warn when a source file is
1078 newer than its matching class file. By default `gcj' will warn
1082 Warn if a deprecated class, method, or field is referred to.
1085 This is the same as `gcc''s `-Wunused'.
1088 This is the same as `-Wredundant-modifiers -Wextraneous-semicolon
1092 File: gcj.info, Node: Linking, Next: Code Generation, Prev: Warnings, Up: Invoking gcj
1097 To turn a Java application into an executable program, you need to link
1098 it with the needed libraries, just as for C or C++. The linker by
1099 default looks for a global function named `main'. Since Java does not
1100 have global functions, and a collection of Java classes may have more
1101 than one class with a `main' method, you need to let the linker know
1102 which of those `main' methods it should invoke when starting the
1103 application. You can do that in any of these ways:
1105 * Specify the class containing the desired `main' method when you
1106 link the application, using the `--main' flag, described below.
1108 * Link the Java package(s) into a shared library (dll) rather than an
1109 executable. Then invoke the application using the `gij' program,
1110 making sure that `gij' can find the libraries it needs.
1112 * Link the Java packages(s) with the flag `-lgij', which links in
1113 the `main' routine from the `gij' command. This allows you to
1114 select the class whose `main' method you want to run when you run
1115 the application. You can also use other `gij' flags, such as `-D'
1116 flags to set properties. Using the `-lgij' library (rather than
1117 the `gij' program of the previous mechanism) has some advantages:
1118 it is compatible with static linking, and does not require
1119 configuring or installing libraries.
1121 These `gij' options relate to linking an executable:
1124 This option is used when linking to specify the name of the class
1125 whose `main' method should be invoked when the resulting
1129 This option can only be used with `--main'. It defines a system
1130 property named NAME with value VALUE. If VALUE is not specified
1131 then it defaults to the empty string. These system properties are
1132 initialized at the program's startup and can be retrieved at
1133 runtime using the `java.lang.System.getProperty' method.
1136 Create an application whose command-line processing is that of the
1139 This option is an alternative to using `--main'; you cannot use
1143 File: gcj.info, Node: Code Generation, Next: Configure-time Options, Prev: Linking, Up: Invoking gcj
1148 In addition to the many `gcc' options controlling code generation,
1149 `gcj' has several options specific to itself.
1152 This option is used to tell `gcj' to generate bytecode (`.class'
1153 files) rather than object code.
1155 `--resource RESOURCE-NAME'
1156 This option is used to tell `gcj' to compile the contents of a
1157 given file to object code so it may be accessed at runtime with
1158 the core protocol handler as `core:/RESOURCE-NAME'. Note that
1159 RESOURCE-NAME is the name of the resource as found at runtime; for
1160 instance, it could be used in a call to `ResourceBundle.getBundle'.
1161 The actual file name to be compiled this way must be specified
1165 When used with `-C', this causes all generated `.class' files to
1166 be put in the appropriate subdirectory of DIRECTORY. By default
1167 they will be put in subdirectories of the current working
1171 By default, `gcj' generates code which checks the bounds of all
1172 array indexing operations. With this option, these checks are
1173 omitted, which can improve performance for code that uses arrays
1174 extensively. Note that this can result in unpredictable behavior
1175 if the code in question actually does violate array bounds
1176 constraints. It is safe to use this option if you are sure that
1177 your code will never throw an `ArrayIndexOutOfBoundsException'.
1180 Don't generate array store checks. When storing objects into
1181 arrays, a runtime check is normally generated in order to ensure
1182 that the object is assignment compatible with the component type
1183 of the array (which may not be known at compile-time). With this
1184 option, these checks are omitted. This can improve performance
1185 for code which stores objects into arrays frequently. It is safe
1186 to use this option if you are sure your code will never throw an
1187 `ArrayStoreException'.
1190 With `gcj' there are two options for writing native methods: CNI
1191 and JNI. By default `gcj' assumes you are using CNI. If you are
1192 compiling a class with native methods, and these methods are
1193 implemented using JNI, then you must use `-fjni'. This option
1194 causes `gcj' to generate stubs which will invoke the underlying JNI
1198 Don't recognize the `assert' keyword. This is for compatibility
1199 with older versions of the language specification.
1201 `-fno-optimize-static-class-initialization'
1202 When the optimization level is greater or equal to `-O2', `gcj'
1203 will try to optimize the way calls into the runtime are made to
1204 initialize static classes upon their first use (this optimization
1205 isn't carried out if `-C' was specified.) When compiling to native
1206 code, `-fno-optimize-static-class-initialization' will turn this
1207 optimization off, regardless of the optimization level in use.
1209 `--disable-assertions[=CLASS-OR-PACKAGE]'
1210 Don't include code for checking assertions in the compiled code.
1211 If `=CLASS-OR-PACKAGE' is missing disables assertion code
1212 generation for all classes, unless overridden by a more specific
1213 `--enable-assertions' flag. If CLASS-OR-PACKAGE is a class name,
1214 only disables generating assertion checks within the named class
1215 or its inner classes. If CLASS-OR-PACKAGE is a package name,
1216 disables generating assertion checks within the named package or a
1219 By default, assertions are enabled when generating class files or
1220 when not optimizing, and disabled when generating optimized
1223 `--enable-assertions[=CLASS-OR-PACKAGE]'
1224 Generates code to check assertions. The option is perhaps
1225 misnamed, as you still need to turn on assertion checking at
1226 run-time, and we don't support any easy way to do that. So this
1227 flag isn't very useful yet, except to partially override
1228 `--disable-assertions'.
1230 `-findirect-dispatch'
1231 `gcj' has a special binary compatibility ABI, which is enabled by
1232 the `-findirect-dispatch' option. In this mode, the code
1233 generated by `gcj' honors the binary compatibility guarantees in
1234 the Java Language Specification, and the resulting object files do
1235 not need to be directly linked against their dependencies.
1236 Instead, all dependencies are looked up at runtime. This allows
1237 free mixing of interpreted and compiled code.
1239 Note that, at present, `-findirect-dispatch' can only be used when
1240 compiling `.class' files. It will not work when compiling from
1241 source. CNI also does not yet work with the binary compatibility
1242 ABI. These restrictions will be lifted in some future release.
1244 However, if you compile CNI code with the standard ABI, you can
1245 call it from code built with the binary compatibility ABI.
1249 File: gcj.info, Node: Configure-time Options, Prev: Code Generation, Up: Invoking gcj
1251 1.7 Configure-time Options
1252 ==========================
1254 Some `gcj' code generations options affect the resulting ABI, and so
1255 can only be meaningfully given when `libgcj', the runtime package, is
1256 configured. `libgcj' puts the appropriate options from this group into
1257 a `spec' file which is read by `gcj'. These options are listed here
1258 for completeness; if you are using `libgcj' then you won't want to
1259 touch these options.
1262 This enables the use of the Boehm GC bitmap marking code. In
1263 particular this causes `gcj' to put an object marking descriptor
1266 `-fhash-synchronization'
1267 By default, synchronization data (the data used for `synchronize',
1268 `wait', and `notify') is pointed to by a word in each object.
1269 With this option `gcj' assumes that this information is stored in a
1270 hash table and not in the object itself.
1272 `-fuse-divide-subroutine'
1273 On some systems, a library routine is called to perform integer
1274 division. This is required to get exception handling correct when
1277 `-fcheck-references'
1278 On some systems it's necessary to insert inline checks whenever
1279 accessing an object via a reference. On other systems you won't
1280 need this because null pointer accesses are caught automatically
1284 File: gcj.info, Node: Compatibility, Next: Invoking gcjh, Prev: Invoking gcj, Up: Top
1286 2 Compatibility with the Java Platform
1287 **************************************
1289 As we believe it is important that the Java platform not be fragmented,
1290 `gcj' and `libgcj' try to conform to the relevant Java specifications.
1291 However, limited manpower and incomplete and unclear documentation work
1292 against us. So, there are caveats to using `gcj'.
1300 File: gcj.info, Node: Limitations, Next: Extensions, Up: Compatibility
1302 2.1 Standard features not yet supported
1303 =======================================
1305 This list of compatibility issues is by no means complete.
1307 * `gcj' implements the JDK 1.2 language. It supports inner classes
1308 and the new 1.4 `assert' keyword. It does not yet support the
1309 Java 2 `strictfp' keyword (it recognizes the keyword but ignores
1312 * `libgcj' is largely compatible with the JDK 1.2 libraries.
1313 However, `libgcj' is missing many packages, most notably
1314 `java.awt'. There are also individual missing classes and methods.
1315 We currently do not have a list showing differences between
1316 `libgcj' and the Java 2 platform.
1318 * Sometimes the `libgcj' implementation of a method or class differs
1319 from the JDK implementation. This is not always a bug. Still, if
1320 it affects you, it probably makes sense to report it so that we
1321 can discuss the appropriate response.
1323 * `gcj' does not currently allow for piecemeal replacement of
1324 components within `libgcj'. Unfortunately, programmers often want
1325 to use newer versions of certain packages, such as those provided
1326 by the Apache Software Foundation's Jakarta project. This has
1327 forced us to place the `org.w3c.dom' and `org.xml.sax' packages
1328 into their own libraries, separate from `libgcj'. If you intend to
1329 use these classes, you must link them explicitly with
1330 `-l-org-w3c-dom' and `-l-org-xml-sax'. Future versions of `gcj'
1331 may not have this restriction.
1334 File: gcj.info, Node: Extensions, Prev: Limitations, Up: Compatibility
1336 2.2 Extra features unique to gcj
1337 ================================
1339 The main feature of `gcj' is that it can compile programs written in
1340 the Java programming language to native code. Most extensions that
1341 have been added are to facilitate this functionality.
1343 * `gcj' makes it easy and efficient to mix code written in Java and
1344 C++. *Note About CNI::, for more info on how to use this in your
1347 * When you compile your classes into a shared library they can be
1348 automatically loaded by the `libgcj' system classloader. When
1349 trying to load a class `gnu.pkg.SomeClass' the system classloader
1350 will first try to load the shared library
1351 `lib-gnu-pkg-SomeClass.so', if that fails to load the class then
1352 it will try to load `lib-gnu-pkg.so' and finally when the class is
1353 still not loaded it will try to load `lib-gnu.so'. Note that all
1354 `.'s will be transformed into `-'s and that searching for inner
1355 classes starts with their outermost outer class. If the class
1356 cannot be found this way the system classloader tries to use the
1357 `libgcj' bytecode interpreter to load the class from the standard
1358 classpath. This process can be controlled to some degree via the
1359 `gnu.gcj.runtime.VMClassLoader.library_control' property; *Note
1360 libgcj Runtime Properties::.
1362 * `libgcj' includes a special `gcjlib' URL type. A URL of this form
1363 is like a `jar' URL, and looks like
1364 `gcjlib:/path/to/shared/library.so!/path/to/resource'. An access
1365 to one of these URLs causes the shared library to be `dlopen()'d,
1366 and then the resource is looked for in that library. These URLs
1367 are most useful when used in conjunction with
1368 `java.net.URLClassLoader'. Note that, due to implementation
1369 limitations, currently any such URL can be accessed by only one
1370 class loader, and libraries are never unloaded. This means some
1371 care must be exercised to make sure that a `gcjlib' URL is not
1372 accessed by more than one class loader at once. In a future
1373 release this limitation will be lifted, and such libraries will be
1376 * A program compiled by `gcj' will examine the `GCJ_PROPERTIES'
1377 environment variable and change its behavior in some ways. In
1378 particular `GCJ_PROPERTIES' holds a list of assignments to global
1379 properties, such as would be set with the `-D' option to `java'.
1380 For instance, `java.compiler=gcj' is a valid (but currently
1381 meaningless) setting.
1385 File: gcj.info, Node: Invoking gcjh, Next: Invoking jv-scan, Prev: Compatibility, Up: Top
1390 The `gcjh' program is used to generate header files from class files.
1391 It can generate both CNI and JNI header files, as well as stub
1392 implementation files which can be used as a basis for implementing the
1393 required native methods.
1396 This causes `gcjh' to generate stub files instead of header files.
1397 By default the stub file will be named after the class, with a
1398 suffix of `.cc'. In JNI mode, the default output file will have
1402 This tells `gcjh' to generate a JNI header or stub. By default,
1403 CNI headers are generated.
1406 Inserts TEXT into the class body. This is ignored in JNI mode.
1409 Inserts TEXT into the header file after the class declaration.
1410 This is ignored in JNI mode.
1413 Inserts TEXT into the class as a `friend' declaration. This is
1414 ignored in JNI mode.
1417 Inserts TEXT into the header file before the class declaration.
1418 This is ignored in JNI mode.
1425 These options are all identical to the corresponding `gcj' options.
1428 Sets the output file name. This cannot be used if there is more
1429 than one class on the command line.
1432 Sets the name of the directory to use for temporary files.
1435 Print all dependencies to stdout; suppress ordinary output.
1438 Print non-system dependencies to stdout; suppress ordinary output.
1441 Print all dependencies to stdout.
1444 Print non-system dependencies to stdout.
1447 Print help about `gcjh' and exit. No further processing is done.
1450 Print version information for `gcjh' and exit. No further
1454 Print extra information while running.
1456 All remaining options are considered to be names of classes.
1459 File: gcj.info, Node: Invoking jv-scan, Next: Invoking jcf-dump, Prev: Invoking gcjh, Up: Top
1464 The `jv-scan' program can be used to print information about a Java
1465 source file (`.java' file).
1468 Don't recognize the `assert' keyword, for backwards compatibility
1469 with older versions of the language specification.
1472 This prints a complexity measure, related to cyclomatic
1473 complexity, for each input file.
1476 This works like the corresponding `gcj' option.
1479 This prints the name of the class in this file containing a `main'
1483 This lists the names of all classes defined in the input files.
1486 If `--list-class' is given, this option causes `jv-scan' to also
1487 print the name of the file in which each class was found.
1490 Print output to the named file.
1493 Print help, then exit.
1496 Print version number, then exit.
1499 File: gcj.info, Node: Invoking jcf-dump, Next: Invoking gij, Prev: Invoking jv-scan, Up: Top
1504 This is a class file examiner, similar to `javap'. It will print
1505 information about a number of classes, which are specified by class name
1509 Disassemble method bodies. By default method bodies are not
1513 Print the constant pool. When printing a reference to a constant
1514 also print its index in the constant pool.
1517 Generate output in `javap' format. The implementation of this
1518 feature is very incomplete.
1524 These options as the same as the corresponding `gcj' options.
1527 Print help, then exit.
1530 Print version number, then exit.
1533 Print extra information while running. Implies
1534 `--print-constants'.
1537 File: gcj.info, Node: Invoking gij, Next: Invoking gcj-dbtool, Prev: Invoking jcf-dump, Up: Top
1542 `gij' is a Java bytecode interpreter included with `libgcj'. `gij' is
1543 not available on every platform; porting it requires a small amount of
1544 assembly programming which has not been done for all the targets
1547 The primary argument to `gij' is the name of a class or, with
1548 `-jar', a jar file. Options before this argument are interpreted by
1549 `gij'; remaining options are passed to the interpreted program.
1551 If a class name is specified and this class does not have a `main'
1552 method with the appropriate signature (a `static void' method with a
1553 `String[]' as its sole argument), then `gij' will print an error and
1556 If a jar file is specified then `gij' will use information in it to
1557 determine which class' `main' method will be invoked.
1559 `gij' will invoke the `main' method with all the remaining
1560 command-line options.
1562 Note that `gij' is not limited to interpreting code. Because
1563 `libgcj' includes a class loader which can dynamically load shared
1564 objects, it is possible to give `gij' the name of a class which has
1565 been compiled and put into a shared library on the class path.
1569 Set the initial class path. The class path is used for finding
1570 class and resource files. If specified, this option overrides the
1571 `CLASSPATH' environment variable. Note that this option is
1572 ignored if `-jar' is used.
1575 This defines a system property named NAME with value VALUE. If
1576 VALUE is not specified then it defaults to the empty string.
1577 These system properties are initialized at the program's startup
1578 and can be retrieved at runtime using the
1579 `java.lang.System.getProperty' method.
1582 Equivalent to `-Xms'.
1585 Equivalent to `-Xmx'.
1589 Supplying `-X' by itself will cause `gij' to list all the
1590 supported `-X' options. Currently these options are supported:
1593 Set the initial heap size.
1596 Set the maximum heap size.
1598 Unrecognized `-X' options are ignored, for compatibility with
1602 This indicates that the name passed to `gij' should be interpreted
1603 as the name of a jar file, not a class.
1607 Print help, then exit.
1610 Print version number and continue.
1613 Print detailed version information, then exit.
1616 Print version number, then exit.
1620 Each time a class is initialized, print a short message on
1623 `gij' also recognizes and ignores the following options, for
1624 compatibility with existing application launch scripts: `-client',
1625 `-server', `-hotspot', `-jrockit', `-agentlib', `-agentpath', `-debug',
1626 `-d32', `-d64', `-javaagent' and `-noclassgc'.
1629 File: gcj.info, Node: Invoking gcj-dbtool, Next: Invoking jv-convert, Prev: Invoking gij, Up: Top
1631 7 Invoking gcj-dbtool.
1632 **********************
1634 `gcj-dbtool' is a tool for creating and manipulating class file mapping
1635 databases. `libgcj' can use these databases to find a shared library
1636 corresponding to the bytecode representation of a class. This
1637 functionality is useful for ahead-of-time compilation of a program that
1638 has no knowledge of `gcj'.
1640 `gcj-dbtool' works best if all the jar files added to it are
1641 compiled using `-findirect-dispatch'.
1643 Note that `gcj-dbtool' is currently available as "preview
1644 technology". We believe it is a reasonable way to allow
1645 application-transparent ahead-of-time compilation, but this is an
1646 unexplored area. We welcome your comments.
1649 This creates a new database. Currently, databases cannot be
1650 resized; you can choose a larger initial size if desired. The
1651 default size is 32,749.
1653 `-a DBFILE JARFILE LIB'
1654 `-f DBFILE JARFILE LIB'
1655 This adds a jar file to the database. For each class file in the
1656 jar, a cryptographic signature of the bytecode representation of
1657 the class is recorded in the database. At runtime, a class is
1658 looked up by its signature and the compiled form of the class is
1659 looked for in the corresponding shared library. The `-a' option
1660 will verify that LIB exists before adding it to the database; `-f'
1663 `[`-'][`-0'] -m DBFILE DBFILE,[DBFILE]'
1664 Merge a number of databases. The output database overwrites any
1665 existing database. To add databases into an existing database,
1666 include the destination in the list of sources.
1668 If `-' or `-0' are used, the list of files to read is taken from
1669 standard input instead of the command line. For `-0', Input
1670 filenames are terminated by a null character instead of by
1671 whitespace. Useful when arguments might contain white space. The
1672 GNU find -print0 option produces input suitable for this mode.
1678 List the contents of a database.
1681 Print the name of the default database. If there is no default
1682 database, this prints a blank line. If LIBDIR is specified, use
1683 it instead of the default library directory component of the
1687 Print a help message, then exit.
1691 Print version information, then exit.
1695 File: gcj.info, Node: Invoking jv-convert, Next: Invoking grmic, Prev: Invoking gcj-dbtool, Up: Top
1697 8 Invoking jv-convert
1698 *********************
1700 `jv-convert' [`OPTION'] ... [INPUTFILE [OUTPUTFILE]]
1702 `jv-convert' is a utility included with `libgcj' which converts a
1703 file from one encoding to another. It is similar to the Unix `iconv'
1706 The encodings supported by `jv-convert' are platform-dependent.
1707 Currently there is no way to get a list of all supported encodings.
1711 Use NAME as the input encoding. The default is the current
1715 Use NAME as the output encoding. The default is the `JavaSrc'
1716 encoding; this is ASCII with `\u' escapes for non-ASCII characters.
1719 Read from FILE. The default is to read from standard input.
1722 Write to FILE. The default is to write to standard output.
1725 Swap the input and output encodings.
1728 Print a help message, then exit.
1731 Print version information, then exit.
1734 File: gcj.info, Node: Invoking grmic, Next: Invoking grmiregistry, Prev: Invoking jv-convert, Up: Top
1739 `grmic' [`OPTION'] ... CLASS ...
1741 `grmic' is a utility included with `libgcj' which generates stubs
1744 Note that this program isn't yet fully compatible with the JDK
1745 `grmic'. Some options, such as `-classpath', are recognized but
1746 currently ignored. We have left these options undocumented for now.
1748 Long options can also be given with a GNU-style leading `--'. For
1749 instance, `--help' is accepted.
1753 By default, `grmic' deletes intermediate files. Either of these
1754 options causes it not to delete such files.
1757 Cause `grmic' to create stubs and skeletons for the 1.1 protocol
1761 Cause `grmic' to create stubs and skeletons compatible with both
1762 the 1.1 and 1.2 protocol versions. This is the default.
1765 Cause `grmic' to create stubs and skeletons for the 1.2 protocol
1769 Don't compile the generated files.
1772 Print information about what `grmic' is doing.
1775 Put output files in DIRECTORY. By default the files are put in
1776 the current working directory.
1779 Print a help message, then exit.
1782 Print version information, then exit.
1785 File: gcj.info, Node: Invoking grmiregistry, Next: About CNI, Prev: Invoking grmic, Up: Top
1787 10 Invoking grmiregistry
1788 ************************
1790 `grmic' [`OPTION'] ... [PORT]
1792 `grmiregistry' starts a remote object registry on the current host.
1793 If no port number is specified, then port 1099 is used.
1796 Print a help message, then exit.
1799 Print version information, then exit.
1802 File: gcj.info, Node: About CNI, Next: System properties, Prev: Invoking grmiregistry, Up: Top
1807 This documents CNI, the Compiled Native Interface, which is is a
1808 convenient way to write Java native methods using C++. This is a more
1809 efficient, more convenient, but less portable alternative to the
1810 standard JNI (Java Native Interface).
1814 * Basic concepts:: Introduction to using CNI.
1815 * Packages:: How packages are mapped to C++.
1816 * Primitive types:: Handling Java types in C++.
1817 * Interfaces:: How Java interfaces map to C++.
1818 * Objects and Classes:: C++ and Java classes.
1819 * Class Initialization:: How objects are initialized.
1820 * Object allocation:: How to create Java objects in C++.
1821 * Memory allocation:: How to allocate and free memory.
1822 * Arrays:: Dealing with Java arrays in C++.
1823 * Methods:: Java methods in C++.
1824 * Strings:: Information about Java Strings.
1825 * Mixing with C++:: How CNI can interoperate with C++.
1826 * Exception Handling:: How exceptions are handled.
1827 * Synchronization:: Synchronizing between Java and C++.
1828 * Invocation:: Starting the Java runtime from C++.
1829 * Reflection:: Using reflection from C++.
1832 File: gcj.info, Node: Basic concepts, Next: Packages, Up: About CNI
1837 In terms of languages features, Java is mostly a subset of C++. Java
1838 has a few important extensions, plus a powerful standard class library,
1839 but on the whole that does not change the basic similarity. Java is a
1840 hybrid object-oriented language, with a few native types, in addition
1841 to class types. It is class-based, where a class may have static as
1842 well as per-object fields, and static as well as instance methods.
1843 Non-static methods may be virtual, and may be overloaded. Overloading
1844 is resolved at compile time by matching the actual argument types
1845 against the parameter types. Virtual methods are implemented using
1846 indirect calls through a dispatch table (virtual function table).
1847 Objects are allocated on the heap, and initialized using a constructor
1848 method. Classes are organized in a package hierarchy.
1850 All of the listed attributes are also true of C++, though C++ has
1851 extra features (for example in C++ objects may be allocated not just on
1852 the heap, but also statically or in a local stack frame). Because
1853 `gcj' uses the same compiler technology as G++ (the GNU C++ compiler),
1854 it is possible to make the intersection of the two languages use the
1855 same ABI (object representation and calling conventions). The key idea
1856 in CNI is that Java objects are C++ objects, and all Java classes are
1857 C++ classes (but not the other way around). So the most important task
1858 in integrating Java and C++ is to remove gratuitous incompatibilities.
1860 You write CNI code as a regular C++ source file. (You do have to use
1861 a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
1863 A CNI C++ source file must have:
1865 #include <gcj/cni.h>
1867 and then must include one header file for each Java class it uses, e.g.:
1869 #include <java/lang/Character.h>
1870 #include <java/util/Date.h>
1871 #include <java/lang/IndexOutOfBoundsException.h>
1873 These header files are automatically generated by `gcjh'.
1875 CNI provides some functions and macros to make using Java objects and
1876 primitive types from C++ easier. In general, these CNI functions and
1877 macros start with the `Jv' prefix, for example the function
1878 `JvNewObjectArray'. This convention is used to avoid conflicts with
1879 other libraries. Internal functions in CNI start with the prefix
1880 `_Jv_'. You should not call these; if you find a need to, let us know
1881 and we will try to come up with an alternate solution.
1886 Whilst a Java class is just a C++ class that doesn't mean that you are
1887 freed from the shackles of Java, a CNI C++ class must adhere to the
1888 rules of the Java programming language.
1890 For example: it is not possible to declare a method in a CNI class
1891 that will take a C string (`char*') as an argument, or to declare a
1892 member variable of some non-Java datatype.
1895 File: gcj.info, Node: Packages, Next: Primitive types, Prev: Basic concepts, Up: About CNI
1900 The only global names in Java are class names, and packages. A
1901 "package" can contain zero or more classes, and also zero or more
1902 sub-packages. Every class belongs to either an unnamed package or a
1903 package that has a hierarchical and globally unique name.
1905 A Java package is mapped to a C++ "namespace". The Java class
1906 `java.lang.String' is in the package `java.lang', which is a
1907 sub-package of `java'. The C++ equivalent is the class
1908 `java::lang::String', which is in the namespace `java::lang' which is
1909 in the namespace `java'.
1911 Here is how you could express this:
1913 (// Declare the class(es), possibly in a header file:
1922 class java::lang::String : public java::lang::Object
1927 The `gcjh' tool automatically generates the necessary namespace
1930 11.2.1 Leaving out package names
1931 --------------------------------
1933 Always using the fully-qualified name of a java class can be tiresomely
1934 verbose. Using the full qualified name also ties the code to a single
1935 package making code changes necessary should the class move from one
1936 package to another. The Java `package' declaration specifies that the
1937 following class declarations are in the named package, without having
1938 to explicitly name the full package qualifiers. The `package'
1939 declaration can be followed by zero or more `import' declarations, which
1940 allows either a single class or all the classes in a package to be
1941 named by a simple identifier. C++ provides something similar with the
1942 `using' declaration and directive.
1946 import PACKAGE-NAME.CLASS-NAME;
1948 allows the program text to refer to CLASS-NAME as a shorthand for the
1949 fully qualified name: `PACKAGE-NAME.CLASS-NAME'.
1951 To achieve the same effect C++, you have to do this:
1953 using PACKAGE-NAME::CLASS-NAME;
1955 Java can also cause imports on demand, like this:
1957 import PACKAGE-NAME.*;
1959 Doing this allows any class from the package PACKAGE-NAME to be
1960 referred to only by its class-name within the program text.
1962 The same effect can be achieved in C++ like this:
1964 using namespace PACKAGE-NAME;
1967 File: gcj.info, Node: Primitive types, Next: Interfaces, Prev: Packages, Up: About CNI
1969 11.3 Primitive types
1970 ====================
1972 Java provides 8 "primitives" types which represent integers, floats,
1973 characters and booleans (and also the void type). C++ has its own very
1974 similar concrete types. Such types in C++ however are not always
1975 implemented in the same way (an int might be 16, 32 or 64 bits for
1976 example) so CNI provides a special C++ type for each primitive Java
1979 *Java type* *C/C++ typename* *Description*
1980 `char' `jchar' 16 bit Unicode character
1981 `boolean' `jboolean' logical (true or false) values
1982 `byte' `jbyte' 8-bit signed integer
1983 `short' `jshort' 16 bit signed integer
1984 `int' `jint' 32 bit signed integer
1985 `long' `jlong' 64 bit signed integer
1986 `float' `jfloat' 32 bit IEEE floating point number
1987 `double' `jdouble' 64 bit IEEE floating point number
1988 `void' `void' no value
1990 When referring to a Java type You should always use these C++
1991 typenames (e.g.: `jint') to avoid disappointment.
1993 11.3.1 Reference types associated with primitive types
1994 ------------------------------------------------------
1996 In Java each primitive type has an associated reference type, e.g.:
1997 `boolean' has an associated `java.lang.Boolean' class. In order to
1998 make working with such classes easier GCJ provides the macro
2001 -- macro: JvPrimClass type
2002 Return a pointer to the `Class' object corresponding to the type
2005 JvPrimClass(void) => java.lang.Void.TYPE
2009 File: gcj.info, Node: Interfaces, Next: Objects and Classes, Prev: Primitive types, Up: About CNI
2014 A Java class can "implement" zero or more "interfaces", in addition to
2015 inheriting from a single base class.
2017 CNI allows CNI code to implement methods of interfaces. You can
2018 also call methods through interface references, with some limitations.
2020 CNI doesn't understand interface inheritance at all yet. So, you
2021 can only call an interface method when the declared type of the field
2022 being called matches the interface which declares that method. The
2023 workaround is to cast the interface reference to the right
2026 For example if you have:
2033 interface B extends A
2038 and declare a variable of type `B' in C++, you can't call `a()'
2039 unless you cast it to an `A' first.
2042 File: gcj.info, Node: Objects and Classes, Next: Class Initialization, Prev: Interfaces, Up: About CNI
2044 11.5 Objects and Classes
2045 ========================
2050 All Java classes are derived from `java.lang.Object'. C++ does not
2051 have a unique root class, but we use the C++ class `java::lang::Object'
2052 as the C++ version of the `java.lang.Object' Java class. All other
2053 Java classes are mapped into corresponding C++ classes derived from
2054 `java::lang::Object'.
2056 Interface inheritance (the `implements' keyword) is currently not
2057 reflected in the C++ mapping.
2059 11.5.2 Object fields
2060 --------------------
2062 Each object contains an object header, followed by the instance fields
2063 of the class, in order. The object header consists of a single pointer
2064 to a dispatch or virtual function table. (There may be extra fields
2065 _in front of_ the object, for example for memory management, but this
2066 is invisible to the application, and the reference to the object points
2067 to the dispatch table pointer.)
2069 The fields are laid out in the same order, alignment, and size as in
2070 C++. Specifically, 8-bite and 16-bit native types (`byte', `short',
2071 `char', and `boolean') are _not_ widened to 32 bits. Note that the
2072 Java VM does extend 8-bit and 16-bit types to 32 bits when on the VM
2073 stack or temporary registers.
2075 If you include the `gcjh'-generated header for a class, you can
2076 access fields of Java classes in the _natural_ way. For example, given
2077 the following Java class:
2082 public Integer (int i) { this.i = i; }
2083 public static zero = new Integer(0);
2088 #include <gcj/cni.h>;
2092 mult (Int *p, jint k)
2095 return Int::zero; // Static member access.
2096 return new Int(p->i * k);
2099 11.5.3 Access specifiers
2100 ------------------------
2102 CNI does not strictly enforce the Java access specifiers, because Java
2103 permissions cannot be directly mapped into C++ permission. Private
2104 Java fields and methods are mapped to private C++ fields and methods,
2105 but other fields and methods are mapped to public fields and methods.
2108 File: gcj.info, Node: Class Initialization, Next: Object allocation, Prev: Objects and Classes, Up: About CNI
2110 11.6 Class Initialization
2111 =========================
2113 Java requires that each class be automatically initialized at the time
2114 of the first active use. Initializing a class involves initializing
2115 the static fields, running code in class initializer methods, and
2116 initializing base classes. There may also be some implementation
2117 specific actions, such as allocating `String' objects corresponding to
2118 string literals in the code.
2120 The GCJ compiler inserts calls to `JvInitClass' at appropriate
2121 places to ensure that a class is initialized when required. The C++
2122 compiler does not insert these calls automatically--it is the
2123 programmer's responsibility to make sure classes are initialized.
2124 However, this is fairly painless because of the conventions assumed by
2127 First, `libgcj' will make sure a class is initialized before an
2128 instance of that object is created. This is one of the
2129 responsibilities of the `new' operation. This is taken care of both in
2130 Java code, and in C++ code. When G++ sees a `new' of a Java class, it
2131 will call a routine in `libgcj' to allocate the object, and that
2132 routine will take care of initializing the class. Note however that
2133 this does not happen for Java arrays; you must allocate those using the
2134 appropriate CNI function. It follows that you can access an instance
2135 field, or call an instance (non-static) method and be safe in the
2136 knowledge that the class and all of its base classes have been
2139 Invoking a static method is also safe. This is because the Java
2140 compiler adds code to the start of a static method to make sure the
2141 class is initialized. However, the C++ compiler does not add this
2142 extra code. Hence, if you write a native static method using CNI, you
2143 are responsible for calling `JvInitClass' before doing anything else in
2144 the method (unless you are sure it is safe to leave it out).
2146 Accessing a static field also requires the class of the field to be
2147 initialized. The Java compiler will generate code to call
2148 `Jv_InitClass' before getting or setting the field. However, the C++
2149 compiler will not generate this extra code, so it is your
2150 responsibility to make sure the class is initialized before you access
2151 a static field from C++.
2154 File: gcj.info, Node: Object allocation, Next: Memory allocation, Prev: Class Initialization, Up: About CNI
2156 11.7 Object allocation
2157 ======================
2159 New Java objects are allocated using a "class instance creation
2164 The same syntax is used in C++. The main difference is that C++
2165 objects have to be explicitly deleted; in Java they are automatically
2166 deleted by the garbage collector. Using CNI, you can allocate a new
2167 Java object using standard C++ syntax and the C++ compiler will allocate
2168 memory from the garbage collector. If you have overloaded
2169 constructors, the compiler will choose the correct one using standard
2170 C++ overload resolution rules.
2174 java::util::Hashtable *ht = new java::util::Hashtable(120);
2177 File: gcj.info, Node: Memory allocation, Next: Arrays, Prev: Object allocation, Up: About CNI
2179 11.8 Memory allocation
2180 ======================
2182 When allocting memory in CNI methods it is best to handle out-of-memory
2183 conditions by throwing a Java exception. These functions are provided
2186 -- Function: void* JvMalloc (jsize SIZE)
2187 Calls malloc. Throws `java.lang.OutOfMemoryError' if allocation
2190 -- Function: void* JvRealloc (void* PTR, jsize SIZE)
2191 Calls realloc. Throws `java.lang.OutOfMemoryError' if
2194 -- Function: void JvFree (void* PTR)
2198 File: gcj.info, Node: Arrays, Next: Methods, Prev: Memory allocation, Up: About CNI
2203 While in many ways Java is similar to C and C++, it is quite different
2204 in its treatment of arrays. C arrays are based on the idea of pointer
2205 arithmetic, which would be incompatible with Java's security
2206 requirements. Java arrays are true objects (array types inherit from
2207 `java.lang.Object'). An array-valued variable is one that contains a
2208 reference (pointer) to an array object.
2210 Referencing a Java array in C++ code is done using the `JArray'
2211 template, which as defined as follows:
2213 class __JArray : public java::lang::Object
2220 class JArray : public __JArray
2224 T& operator[](jint i) { return data[i]; }
2227 There are a number of `typedef's which correspond to `typedef's from
2228 the JNI. Each is the type of an array holding objects of the relevant
2231 typedef __JArray *jarray;
2232 typedef JArray<jobject> *jobjectArray;
2233 typedef JArray<jboolean> *jbooleanArray;
2234 typedef JArray<jbyte> *jbyteArray;
2235 typedef JArray<jchar> *jcharArray;
2236 typedef JArray<jshort> *jshortArray;
2237 typedef JArray<jint> *jintArray;
2238 typedef JArray<jlong> *jlongArray;
2239 typedef JArray<jfloat> *jfloatArray;
2240 typedef JArray<jdouble> *jdoubleArray;
2242 -- Method on template<class T>: T* elements (JArray<T> ARRAY)
2243 This template function can be used to get a pointer to the
2244 elements of the `array'. For instance, you can fetch a pointer to
2245 the integers that make up an `int[]' like so:
2247 extern jintArray foo;
2248 jint *intp = elements (foo);
2250 The name of this function may change in the future.
2252 -- Function: jobjectArray JvNewObjectArray (jsize LENGTH, jclass
2253 KLASS, jobject INIT)
2254 Here `klass' is the type of elements of the array and `init' is
2255 the initial value put into every slot in the array.
2257 11.9.1 Creating arrays
2258 ----------------------
2260 For each primitive type there is a function which can be used to create
2261 a new array of that type. The name of the function is of the form:
2269 can be used to create an array of Java primitive boolean types.
2271 The following function definition is the template for all such
2274 -- Function: jbooleanArray JvNewBooleanArray (jint LENGTH)
2275 Create's an array LENGTH indices long.
2277 -- Function: jsize JvGetArrayLength (jarray ARRAY)
2278 Returns the length of the ARRAY.
2281 File: gcj.info, Node: Methods, Next: Strings, Prev: Arrays, Up: About CNI
2286 Java methods are mapped directly into C++ methods. The header files
2287 generated by `gcjh' include the appropriate method definitions.
2288 Basically, the generated methods have the same names and
2289 _corresponding_ types as the Java methods, and are called in the
2295 Both Java and C++ provide method overloading, where multiple methods in
2296 a class have the same name, and the correct one is chosen (at compile
2297 time) depending on the argument types. The rules for choosing the
2298 correct method are (as expected) more complicated in C++ than in Java,
2299 but given a set of overloaded methods generated by `gcjh' the C++
2300 compiler will choose the expected one.
2302 Common assemblers and linkers are not aware of C++ overloading, so
2303 the standard implementation strategy is to encode the parameter types
2304 of a method into its assembly-level name. This encoding is called
2305 "mangling", and the encoded name is the "mangled name". The same
2306 mechanism is used to implement Java overloading. For C++/Java
2307 interoperability, it is important that both the Java and C++ compilers
2308 use the _same_ encoding scheme.
2310 11.10.2 Static methods
2311 ----------------------
2313 Static Java methods are invoked in CNI using the standard C++ syntax,
2314 using the `::' operator rather than the `.' operator.
2318 jint i = java::lang::Math::round((jfloat) 2.3);
2320 C++ method definition syntax is used to define a static native method.
2323 #include <java/lang/Integer>
2324 java::lang::Integer*
2325 java::lang::Integer::getInteger(jstring str)
2330 11.10.3 Object Constructors
2331 ---------------------------
2333 Constructors are called implicitly as part of object allocation using
2338 java::lang::Integer *x = new java::lang::Integer(234);
2340 Java does not allow a constructor to be a native method. This
2341 limitation can be coded round however because a constructor can _call_
2344 11.10.4 Instance methods
2345 ------------------------
2347 Calling a Java instance method from a C++ CNI method is done using the
2348 standard C++ syntax, e.g.:
2350 // First create the Java object.
2351 java::lang::Integer *x = new java::lang::Integer(234);
2352 // Now call a method.
2353 jint prim_value = x->intValue();
2354 if (x->longValue == 0)
2357 Defining a Java native instance method is also done the natural way:
2359 #include <java/lang/Integer.h>
2362 java::lang:Integer::doubleValue()
2364 return (jdouble) value;
2367 11.10.5 Interface methods
2368 -------------------------
2370 In Java you can call a method using an interface reference. This is
2371 supported, but not completely. *Note Interfaces::.
2374 File: gcj.info, Node: Strings, Next: Mixing with C++, Prev: Methods, Up: About CNI
2379 CNI provides a number of utility functions for working with Java Java
2380 `String' objects. The names and interfaces are analogous to those of
2383 -- Function: jstring JvNewString (const char* CHARS, jsize LEN)
2384 Returns a Java `String' object with characters from the C string
2385 CHARS up to the index LEN in that array.
2387 -- Function: jstring JvNewStringLatin1 (const char* BYTES, jsize LEN)
2388 Returns a Java `String' made up of LEN bytes from BYTES.
2390 -- Function: jstring JvNewStringLatin1 (const char* BYTES)
2391 As above but the length of the `String' is `strlen(BYTES)'.
2393 -- Function: jstring JvNewStringUTF (const char* BYTES)
2394 Returns a `String' which is made up of the UTF encoded characters
2395 present in the C string BYTES.
2397 -- Function: jchar* JvGetStringChars (jstring STR)
2398 Returns a pointer to an array of characters making up the `String'
2401 -- Function: int JvGetStringUTFLength (jstring STR)
2402 Returns the number of bytes required to encode the contents of the
2403 `String' STR in UTF-8.
2405 -- Function: jsize JvGetStringUTFRegion (jstring STR, jsize START,
2406 jsize LEN, char* BUF)
2407 Puts the UTF-8 encoding of a region of the `String' STR into the
2408 buffer `buf'. The region to fetch is marked by START and LEN.
2410 Note that BUF is a buffer, not a C string. It is _not_ null
2414 File: gcj.info, Node: Mixing with C++, Next: Exception Handling, Prev: Strings, Up: About CNI
2416 11.12 Interoperating with C/C++
2417 ===============================
2419 Because CNI is designed to represent Java classes and methods it cannot
2420 be mixed readily with C/C++ types.
2422 One important restriction is that Java classes cannot have non-Java
2423 type instance or static variables and cannot have methods which take
2424 non-Java types as arguments or return non-Java types.
2426 None of the following is possible with CNI:
2429 class ::MyClass : public java::lang::Object
2431 char* variable; // char* is not a valid Java type.
2436 ::SomeClass::someMethod (char *arg)
2441 } // `uint' is not a valid Java type, neither is `char*'
2443 Of course, it is ok to use C/C++ types within the scope of a method:
2446 ::SomeClass::otherMethod (jstring str)
2457 The above restriction can be problematic, so CNI includes the
2458 `gnu.gcj.RawData' class. The `RawData' class is a "non-scanned
2459 reference" type. In other words variables declared of type `RawData'
2460 can contain any data and are not checked by the compiler or memory
2463 This means that you can put C/C++ data structures (including classes)
2464 in your CNI classes, as long as you use the appropriate cast.
2466 Here are some examples:
2469 class ::MyClass : public java::lang::Object
2471 gnu.gcj.RawData string;
2474 gnu.gcj.RawData getText ();
2478 ::MyClass::MyClass ()
2485 ::MyClass::getText ()
2491 ::MyClass::printText ()
2493 printf("%s\n", (char*) string);
2496 11.12.2 RawDataManaged
2497 ----------------------
2499 `gnu.gcj.RawDataManaged' is another type used to indicate special data
2500 used by native code. Unlike the `RawData' type, fields declared as
2501 `RawDataManaged' will be "marked" by the memory manager and considered
2502 for garbage collection.
2504 Native data which is allocated using CNI's `JvAllocBytes()' function
2505 and stored in a `RawDataManaged' will be automatically freed when the
2506 Java object it is associated with becomes unreachable.
2508 11.12.3 Native memory allocation
2509 --------------------------------
2511 -- Function: void* JvAllocBytes (jsize SIZE)
2512 Allocates SIZE bytes from the heap. The memory returned is zeroed.
2513 This memory is not scanned for pointers by the garbage collector,
2514 but will be freed if no references to it are discovered.
2516 This function can be useful if you need to associate some native
2517 data with a Java object. Using a CNI's special `RawDataManaged'
2518 type, native data allocated with `JvAllocBytes' will be
2519 automatically freed when the Java object itself becomes
2522 11.12.4 Posix signals
2523 ---------------------
2525 On Posix based systems the `libgcj' library uses several signals
2526 internally. CNI code should not attempt to use the same signals as
2527 doing so may cause `libgcj' and/or the CNI code to fail.
2529 SIGSEGV is used on many systems to generate `NullPointerExceptions'.
2530 SIGCHLD is used internally by `Runtime.exec()'. Several other signals
2531 (that vary from platform to platform) can be used by the memory manager
2532 and by `Thread.interrupt()'.
2535 File: gcj.info, Node: Exception Handling, Next: Synchronization, Prev: Mixing with C++, Up: About CNI
2537 11.13 Exception Handling
2538 ========================
2540 While C++ and Java share a common exception handling framework, things
2541 are not yet perfectly integrated. The main issue is that the run-time
2542 type information facilities of the two languages are not integrated.
2544 Still, things work fairly well. You can throw a Java exception from
2545 C++ using the ordinary `throw' construct, and this exception can be
2546 caught by Java code. Similarly, you can catch an exception thrown from
2547 Java using the C++ `catch' construct.
2552 throw new java::lang::IndexOutOfBoundsException();
2554 Normally, G++ will automatically detect when you are writing C++
2555 code that uses Java exceptions, and handle them appropriately.
2556 However, if C++ code only needs to execute destructors when Java
2557 exceptions are thrown through it, GCC will guess incorrectly. Sample
2562 extern void bar(); // Is implemented in Java and may throw exceptions.
2570 The usual effect of an incorrect guess is a link failure,
2571 complaining of a missing routine called `__gxx_personality_v0'.
2573 You can inform the compiler that Java exceptions are to be used in a
2574 translation unit, irrespective of what it might think, by writing
2575 `#pragma GCC java_exceptions' at the head of the file. This `#pragma'
2576 must appear before any functions that throw or catch exceptions, or run
2577 destructors when exceptions are thrown through them.
2580 File: gcj.info, Node: Synchronization, Next: Invocation, Prev: Exception Handling, Up: About CNI
2582 11.14 Synchronization
2583 =====================
2585 Each Java object has an implicit monitor. The Java VM uses the
2586 instruction `monitorenter' to acquire and lock a monitor, and
2587 `monitorexit' to release it.
2589 The corresponding CNI macros are `JvMonitorEnter' and
2590 `JvMonitorExit' (JNI has similar methods `MonitorEnter' and
2593 The Java source language does not provide direct access to these
2594 primitives. Instead, there is a `synchronized' statement that does an
2595 implicit `monitorenter' before entry to the block, and does a
2596 `monitorexit' on exit from the block. Note that the lock has to be
2597 released even when the block is abnormally terminated by an exception,
2598 which means there is an implicit `try finally' surrounding
2599 synchronization locks.
2601 From C++, it makes sense to use a destructor to release a lock. CNI
2602 defines the following utility class:
2604 class JvSynchronize() {
2606 JvSynchronize(jobject o) { obj = o; JvMonitorEnter(o); }
2607 ~JvSynchronize() { JvMonitorExit(obj); }
2617 might become this C++ code:
2620 JvSynchronize dummy (OBJ);
2624 Java also has methods with the `synchronized' attribute. This is
2625 equivalent to wrapping the entire method body in a `synchronized'
2626 statement. (Alternatively, an implementation could require the caller
2627 to do the synchronization. This is not practical for a compiler,
2628 because each virtual method call would have to test at run-time if
2629 synchronization is needed.) Since in `gcj' the `synchronized'
2630 attribute is handled by the method implementation, it is up to the
2631 programmer of a synchronized native method to handle the synchronization
2632 (in the C++ implementation of the method). In other words, you need to
2633 manually add `JvSynchronize' in a `native synchronized' method.
2636 File: gcj.info, Node: Invocation, Next: Reflection, Prev: Synchronization, Up: About CNI
2641 CNI permits C++ applications to make calls into Java classes, in
2642 addition to allowing Java code to call into C++. Several functions,
2643 known as the "invocation API", are provided to support this.
2645 -- Function: jint JvCreateJavaVM (JvVMInitArgs* VM_ARGS)
2646 Initializes the Java runtime. This function performs essential
2647 initialization of the threads interface, garbage collector,
2648 exception handling and other key aspects of the runtime. It must
2649 be called once by an application with a non-Java `main()'
2650 function, before any other Java or CNI calls are made. It is
2651 safe, but not recommended, to call `JvCreateJavaVM()' more than
2652 once provided it is only called from a single thread. The VMARGS
2653 parameter can be used to specify initialization parameters for the
2654 Java runtime. It may be `NULL'.
2656 JvVMInitArgs represents a list of virtual machine initialization
2657 arguments. `JvCreateJavaVM()' ignores the version field.
2659 typedef struct JvVMOption
2661 // a VM initialization option
2663 // extra information associated with this option
2667 typedef struct JvVMInitArgs
2669 // for compatibility with JavaVMInitArgs
2672 // number of VM initialization options
2675 // an array of VM initialization options
2676 JvVMOption* options;
2678 // true if the option parser should ignore unrecognized options
2679 jboolean ignoreUnrecognized;
2682 `JvCreateJavaVM()' returns `0' upon success, or `-1' if the
2683 runtime is already initialized.
2685 _Note:_ In GCJ 3.1, the `vm_args' parameter is ignored. It is
2686 recognized and used as of release 4.0.
2688 -- Function: java::lang::Thread* JvAttachCurrentThread (jstring NAME,
2689 java::lang::ThreadGroup* GROUP)
2690 Registers an existing thread with the Java runtime. This must be
2691 called once from each thread, before that thread makes any other
2692 Java or CNI calls. It must be called after `JvCreateJavaVM'. NAME
2693 specifies a name for the thread. It may be `NULL', in which case a
2694 name will be generated. GROUP is the ThreadGroup in which this
2695 thread will be a member. If it is `NULL', the thread will be a
2696 member of the main thread group. The return value is the Java
2697 `Thread' object that represents the thread. It is safe to call
2698 `JvAttachCurrentThread()' more than once from the same thread. If
2699 the thread is already attached, the call is ignored and the current
2700 thread object is returned.
2702 -- Function: jint JvDetachCurrentThread ()
2703 Unregisters a thread from the Java runtime. This should be called
2704 by threads that were attached using `JvAttachCurrentThread()',
2705 after they have finished making calls to Java code. This ensures
2706 that any resources associated with the thread become eligible for
2707 garbage collection. This function returns `0' upon success, or
2708 `-1' if the current thread is not attached.
2710 11.15.1 Handling uncaught exceptions
2711 ------------------------------------
2713 If an exception is thrown from Java code called using the invocation
2714 API, and no handler for the exception can be found, the runtime will
2715 abort the application. In order to make the application more robust, it
2716 is recommended that code which uses the invocation API be wrapped by a
2717 top-level try/catch block that catches all Java exceptions.
2722 The following code demonstrates the use of the invocation API. In this
2723 example, the C++ application initializes the Java runtime and attaches
2724 itself. The `java.lang.System' class is initialized in order to access
2725 its `out' field, and a Java string is printed. Finally, the thread is
2726 detached from the runtime once it has finished making Java calls.
2727 Everything is wrapped with a try/catch block to provide a default
2728 handler for any uncaught exceptions.
2730 The example can be compiled with `c++ test.cc -lgcj'.
2733 #include <gcj/cni.h>
2734 #include <java/lang/System.h>
2735 #include <java/io/PrintStream.h>
2736 #include <java/lang/Throwable.h>
2738 int main(int argc, char *argv)
2740 using namespace java::lang;
2744 JvCreateJavaVM(NULL);
2745 JvAttachCurrentThread(NULL, NULL);
2747 String *message = JvNewStringLatin1("Hello from C++");
2748 JvInitClass(&System::class$);
2749 System::out->println(message);
2751 JvDetachCurrentThread();
2753 catch (Throwable *t)
2755 System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
2756 t->printStackTrace();
2761 File: gcj.info, Node: Reflection, Prev: Invocation, Up: About CNI
2766 Reflection is possible with CNI code, it functions similarly to how it
2769 The types `jfieldID' and `jmethodID' are as in JNI.
2773 * `JvFromReflectedField',
2775 * `JvFromReflectedMethod',
2777 * `JvToReflectedField'
2779 * `JvToFromReflectedMethod'
2781 will be added shortly, as will other functions corresponding to JNI.
2784 File: gcj.info, Node: System properties, Next: Resources, Prev: About CNI, Up: Top
2786 12 System properties
2787 ********************
2789 The runtime behavior of the `libgcj' library can be modified by setting
2790 certain system properties. These properties can be compiled into the
2791 program using the `-DNAME[=VALUE]' option to `gcj' or by setting them
2792 explicitly in the program by calling the
2793 `java.lang.System.setProperty()' method. Some system properties are
2794 only used for informational purposes (like giving a version number or a
2795 user name). A program can inspect the current value of a property by
2796 calling the `java.lang.System.getProperty()' method.
2800 * Standard Properties:: Standard properties supported by `libgcj'
2801 * GNU Classpath Properties:: Properties found in Classpath based libraries
2802 * libgcj Runtime Properties:: Properties specific to `libgcj'
2805 File: gcj.info, Node: Standard Properties, Next: GNU Classpath Properties, Up: System properties
2807 12.1 Standard Properties
2808 ========================
2810 The following properties are normally found in all implementations of
2811 the core libraries for the Java language.
2814 The `libgcj' version number.
2817 Set to `The Free Software Foundation, Inc.'
2820 Set to `http://gcc.gnu.org/java/'.
2823 The directory where `gcj' was installed. Taken from the `--prefix'
2824 option given to `configure'.
2826 `java.class.version'
2827 The class format version number supported by the libgcj byte code
2828 interpreter. (Currently `46.0')
2830 `java.vm.specification.version'
2831 The Virtual Machine Specification version implemented by `libgcj'.
2834 `java.vm.specification.vendor'
2835 The name of the Virtual Machine specification designer.
2837 `java.vm.specification.name'
2838 The name of the Virtual Machine specification (Set to `Java
2839 Virtual Machine Specification').
2842 The `gcj' version number.
2845 Set to `The Free Software Foundation, Inc.'
2848 Set to `GNU libgcj'.
2850 `java.specification.version'
2851 The Runtime Environment specification version implemented by
2852 `libgcj'. (Currently set to `1.3')
2854 `java.specification.vendor'
2855 The Runtime Environment specification designer.
2857 `java.specification.name'
2858 The name of the Runtime Environment specification (Set to `Java
2859 Platform API Specification').
2862 The paths (jar files, zip files and directories) used for finding
2866 Directory path used for finding native libraries.
2869 The directory used to put temporary files in.
2872 Name of the Just In Time compiler to use by the byte code
2873 interpreter. Currently not used in `libgcj'.
2876 Directories containing jar files with extra libraries. Will be
2877 used when resolving classes.
2879 `java.protocol.handler.pkgs'
2880 A `|' separated list of package names that is used to find classes
2881 that implement handlers for `java.net.URL'.
2883 `java.rmi.server.codebase'
2884 A list of URLs that is used by the `java.rmi.server.RMIClassLoader'
2885 to load classes from.
2888 A list of class names that will be loaded by the
2889 `java.sql.DriverManager' when it starts up.
2892 The separator used in when directories are included in a filename
2893 (normally `/' or `\' ).
2896 The default character encoding used when converting platform
2897 native files to Unicode (usually set to `8859_1').
2900 The standard separator used when a string contains multiple paths
2901 (normally `:' or `;'), the string is usually not a valid character
2902 to use in normal directory names.)
2905 The default line separator used on the platform (normally `\n',
2906 `\r' or a combination of those two characters).
2909 The class name used for the default policy provider returned by
2910 `java.security.Policy.getPolicy'.
2913 The name of the user running the program. Can be the full name,
2914 the login name or empty if unknown.
2917 The default directory to put user specific files in.
2920 The current working directory from which the program was started.
2923 The default language as used by the `java.util.Locale' class.
2926 The default region as used by the `java.util.Local' class.
2929 The default variant of the language and region local used.
2932 The default timezone as used by the `java.util.TimeZone' class.
2935 The operating system/kernel name that the program runs on.
2938 The hardware that we are running on.
2941 The version number of the operating system/kernel.
2944 The string to display when an untrusted applet is displayed.
2945 Returned by `java.awt.Window.getWarningString()' when the window is
2949 The class name used for initializing the default
2950 `java.awt.Toolkit'. Defaults to `gnu.awt.gtk.GtkToolkit'.
2953 Name of proxy host for http connections.
2956 Port number to use when a proxy host is in use.
2960 File: gcj.info, Node: GNU Classpath Properties, Next: libgcj Runtime Properties, Prev: Standard Properties, Up: System properties
2962 12.2 GNU Classpath Properties
2963 =============================
2965 `libgcj' is based on the GNU Classpath (Essential Libraries for Java) a
2966 GNU project to create free core class libraries for use with virtual
2967 machines and compilers for the Java language. The following properties
2968 are common to libraries based on GNU Classpath.
2971 Enables printing serialization debugging by the
2972 `java.io.ObjectInput' and `java.io.ObjectOutput' classes when set
2973 to something else then the empty string. Only used when running a
2974 debug build of the library.
2976 `gnu.classpath.vm.shortname'
2977 This is a succint name of the virtual machine. For `libgcj', this
2978 will always be `libgcj'.
2980 `gnu.classpath.home.url'
2981 A base URL used for finding system property files (e.g.,
2982 `classpath.security'). By default this is a `file:' URL pointing
2983 to the `lib' directory under `java.home'.
2987 File: gcj.info, Node: libgcj Runtime Properties, Prev: GNU Classpath Properties, Up: System properties
2989 12.3 libgcj Runtime Properties
2990 ==============================
2992 The following properties are specific to the `libgcj' runtime and will
2993 normally not be found in other core libraries for the java language.
2996 The combination of `java.vm.name' and `java.vm.version'.
2999 Same as `java.fullversion'.
3002 Used by the `java.net.DatagramSocket' class when set to something
3003 else then the empty string. When set all newly created
3004 `DatagramSocket's will try to load a class
3005 `java.net.[impl.prefix]DatagramSocketImpl' instead of the normal
3006 `java.net.PlainDatagramSocketImpl'.
3009 The name that was used to invoked the program.
3011 `gnu.gcj.runtime.NameFinder.demangle'
3012 Whether names in a stack trace should be demangled. Defaults to
3015 `gnu.gcj.runtime.NameFinder.sanitize'
3016 Whether calls to initialize exceptions and starting the runtime
3017 system should be removed from the stack trace. Only done when
3018 names are demangled. Defaults to `true'.
3020 `gnu.gcj.runtime.NameFinder.remove_unknown'
3021 Whether calls to unknown functions (class and method names are
3022 unknown) should be removed from the stack trace. Only done when
3023 the stack is sanitized. Ignored if this means no stack trace
3024 information would be available anymore. Defaults to `true'.
3026 `gnu.gcj.runtime.NameFinder.remove_interpreter'
3027 Whether runtime interpreter calls (methods in the
3028 `_Jv_InterpMethod' class and functions starting with `ffi_')
3029 should be removed from the stack trace. Only done when the stack
3030 is sanitized. Defaults to `true'.
3032 `gnu.gcj.runtime.NameFinder.use_addr2line'
3033 Whether an external process (`addr2line' or `addr2name.awk')
3034 should be used as fallback to convert the addresses to function
3035 names when the runtime is unable to do it through `dladdr'.
3037 `gnu.gcj.runtime.VMClassLoader.library_control'
3038 This controls how shared libraries are automatically loaded by the
3039 built-in class loader. If this property is set to `full', a full
3040 search is done for each requested class. If this property is set
3041 to `cache' (the default), then any failed lookups are cached and
3042 not tried again. If this property is set to `never', then lookups
3043 are never done. For more information, *Note Extensions::.
3045 `gnu.gcj.runtime.endorsed.dirs'
3046 This is like the standard `java.endorsed.dirs', property, but
3047 specifies some extra directories which are searched after the
3048 standard endorsed directories. This is primarily useful for
3049 telling `libgcj' about additional libraries which are ordinarily
3050 incorporated into the JDK, and which should be loaded by the
3051 bootstrap class loader, but which are not yet part of `libgcj'
3052 itself for some reason.
3054 `gnu.gcj.jit.compiler'
3055 This is the full path to `gcj' executable which should be used to
3056 compile classes just-in-time when `ClassLoader.defineClass' is
3057 called. If not set, `gcj' will not be invoked by the runtime;
3058 this can also be controlled via `Compiler.disable'.
3060 `gnu.gcj.jit.options'
3061 This is a space-separated string of options which should be passed
3062 to `gcj' when in JIT mode. If not set, a sensible default is
3065 `gnu.gcj.jit.cachedir'
3066 This is the directory where cached shared library files are
3067 stored. If not set, JIT compilation is disabled. This should
3068 never be set to a directory that is writable by any other user.
3070 `gnu.gcj.precompiled.db.path'
3071 This is a sequence of file names, each referring to a file created
3072 by `gcj-dbtool'. These files will be used by `libgcj' to find
3073 shared libraries corresponding to classes that are loaded from
3074 bytecode. `libgcj' often has a built-in default database; it can
3075 be queried using `gcj-dbtool -p'.
3079 File: gcj.info, Node: Resources, Prev: System properties, Up: Top
3084 While writing `gcj' and `libgcj' we have, of course, relied heavily on
3085 documentation from Sun Microsystems. In particular we have used The
3086 Java Language Specification (both first and second editions), the Java
3087 Class Libraries (volumes one and two), and the Java Virtual Machine
3088 Specification. In addition we've used the online documentation at
3089 `http://java.sun.com/'.
3091 The current `gcj' home page is `http://gcc.gnu.org/java/'.
3093 For more information on gcc, see `http://gcc.gnu.org/'.
3095 Some `libgcj' testing is done using the Mauve test suite. This is a
3096 free software Java class library test suite which is being written
3097 because the JCK is not free. See `http://sources.redhat.com/mauve/'
3098 for more information.
3104 Node: Copying
\7f3973
3105 Node: GNU Free Documentation License
\7f23141
3106 Node: Invoking gcj
\7f45543
3107 Node: Input and output files
\7f46242
3108 Node: Input Options
\7f47768
3109 Node: Encodings
\7f50916
3110 Node: Warnings
\7f52122
3111 Node: Linking
\7f53235
3112 Node: Code Generation
\7f55468
3113 Node: Configure-time Options
\7f60485
3114 Node: Compatibility
\7f61908
3115 Node: Limitations
\7f62388
3116 Node: Extensions
\7f63970
3117 Node: Invoking gcjh
\7f66568
3118 Node: Invoking jv-scan
\7f68624
3119 Node: Invoking jcf-dump
\7f69665
3120 Node: Invoking gij
\7f70613
3121 Node: Invoking gcj-dbtool
\7f73584
3122 Node: Invoking jv-convert
\7f76050
3123 Node: Invoking grmic
\7f77129
3124 Node: Invoking grmiregistry
\7f78517
3125 Node: About CNI
\7f78930
3126 Node: Basic concepts
\7f80292
3127 Node: Packages
\7f83188
3128 Node: Primitive types
\7f85516
3129 Node: Interfaces
\7f87184
3130 Node: Objects and Classes
\7f88095
3131 Node: Class Initialization
\7f90295
3132 Node: Object allocation
\7f92638
3133 Node: Memory allocation
\7f93428
3134 Node: Arrays
\7f94059
3135 Node: Methods
\7f96663
3136 Node: Strings
\7f99484
3137 Node: Mixing with C++
\7f100968
3138 Node: Exception Handling
\7f104439
3139 Node: Synchronization
\7f106073
3140 Node: Invocation
\7f108063
3141 Node: Reflection
\7f112988
3142 Node: System properties
\7f113449
3143 Node: Standard Properties
\7f114326
3144 Node: GNU Classpath Properties
\7f118758
3145 Node: libgcj Runtime Properties
\7f119804
3146 Node: Resources
\7f123786