1 @\input texinfo @c -*-texinfo-*-
3 @settitle Guide to GNU gcj
5 @c Note: When reading this manual you'll find lots of strange
6 @c circumlocutions like ``compiler for the Java language''.
7 @c This is necessary due to Sun's restrictions on the use of
10 @c When this manual is copyrighted.
11 @set copyrights-gcj 2001
15 @set which-gcj GCC-@value{version-gcc}
17 @macro gcctabopt{body}
23 @dircategory Programming
25 * Gcj: (gcj). Ahead-of-time compiler for the Java language
28 @dircategory Individual utilities
30 * gcjh: (gcj)Invoking gcjh.
31 Generate header files from Java class files
32 * jv-scan: (gcj)Invoking jv-scan.
33 Print information about Java source files
34 * jcf-dump: (gcj)Invoking jcf-dump.
35 Print information about Java class files
36 * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
40 @c man begin COPYRIGHT
41 Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
43 Permission is granted to copy, distribute and/or modify this document
44 under the terms of the GNU Free Documentation License, Version 1.1 or
45 any later version published by the Free Software Foundation; with the
46 Invariant Sections being ``GNU General Public License'', the Front-Cover
47 texts being (a) (see below), and with the Back-Cover Texts being (b)
48 (see below). A copy of the license is included in the
51 ``GNU Free Documentation License''.
53 @c man begin COPYRIGHT
58 (a) The FSF's Front-Cover Text is:
62 (b) The FSF's Back-Cover Text is:
64 You have freedom to copy and modify this GNU Manual, like GNU
65 software. Copies published by the Free Software Foundation raise
66 funds for GNU development.
74 @vskip 0pt plus 1filll
75 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
77 For the @value{which-gcj} Version*
79 Published by the Free Software Foundation @*
80 59 Temple Place - Suite 330@*
81 Boston, MA 02111-1307, USA@*
83 Permission is granted to copy, distribute and/or modify this document
84 under the terms of the GNU Free Documentation License, Version 1.1 or
85 any later version published by the Free Software Foundation; with the
86 Invariant Sections being ``GNU General Public License'', the Front-Cover
87 texts being (a) (see below), and with the Back-Cover Texts being (b)
88 (see below). A copy of the license is included in the section entitled
89 ``GNU Free Documentation License''.
91 (a) The FSF's Front-Cover Text is:
95 (b) The FSF's Back-Cover Text is:
97 You have freedom to copy and modify this GNU Manual, like GNU
98 software. Copies published by the Free Software Foundation raise
99 funds for GNU development.
108 This manual describes how to use @code{gcj}, the GNU compiler for the
109 Java programming language. @code{gcj} can generate both @file{.class}
110 files and object files, and it can read both Java source code and
114 * Copying:: The GNU General Public License
115 * GNU Free Documentation License::
116 How you can share and copy this manual
117 * Invoking gcj:: Compiler options supported by @code{gcj}
118 * Compatibility:: Compatibility between gcj and other tools for Java
119 * Invoking gcjh:: Generate header files from class files
120 * Invoking jv-scan:: Print information about source files
121 * Invoking jcf-dump:: Print information about class files
122 * Invoking gij:: Interpreting Java bytecodes
123 * Resources:: Where to look for more information
133 @chapter Invoking gcj
135 @c man title gcj Ahead-of-time compiler for the Java language
138 @c man begin SYNOPSIS gcj
139 gcj [@option{-I}@var{dir}@dots{}] [@option{-d}@var{dir}@dots{}]
140 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
141 [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
142 [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
143 [@option{-C}] [@option{-R} @var{resource-name}] [@option{-d} @var{directory}]
144 [@option{-W}@var{warn}@dots{}]
145 @var{sourcefile}@dots{}
147 @c man begin SEEALSO gcj
148 gcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
149 and the Info entries for @file{gcj} and @file{gcc}.
153 @c man begin DESCRIPTION gcj
155 As @code{gcj} is just another front end to @code{gcc}, it supports many
156 of the same options as gcc. @xref{Option Summary, , Option Summary,
157 gcc, Using the GNU Compiler Collection}. This manual only documents the
158 options specific to @code{gcj}.
163 * Input and output files::
164 * Input Options:: How gcj finds files
165 * Encodings:: Options controlling source file encoding
166 * Warnings:: Options controlling warnings specific to gcj
167 * Code Generation:: Options controlling the output of gcj
168 * Configure-time Options:: Options you won't use
171 @c man begin OPTIONS gcj
173 @node Input and output files
174 @section Input and output files
176 A @code{gcj} command is like a @code{gcc} command, in that it
177 consists of a number of options and file names. The following kinds
178 of input file names are supported:
181 @item @var{file}.java
183 @item @var{file}.class
186 @itemx @var{file}.jar
187 An archive containing one or more @code{.class} files, all of
188 which are compiled. The archive may be compressed.
190 A file containing a whitespace-separated list of input file names.
191 (Currently, these must all be @code{.java} source files, but that
193 Each named file is compiled, just as if it had been on the command line.
194 @item @var{library}.a
195 @itemx @var{library}.so
196 @itemx -l@var{libname}
197 Libraries to use when linking. See the @code{gcc} manual.
200 You can specify more than one input file on the @code{gcj} command line,
201 in which case they will all be compiled. If you specify a
202 @code{-o @var{FILENAME}}
203 option, all the input files will be compiled together, producing a
204 single output file, named @var{FILENAME}.
205 This is allowed even when using @code{-S} or @code{-c},
206 but not when using @code{-C} or @code{-R}.
207 (This is an extension beyond the what plain @code{gcc} allows.)
208 (If more than one input file is specified, all must currently
209 be @code{.java} files, though we hope to fix this.)
212 @section Input Options
216 @code{gcj} has options to control where it looks to find files it needs.
217 For instance, @code{gcj} might need to load a class that is referenced
218 by the file it has been asked to compile. Like other compilers for the
219 Java language, @code{gcj} has a notion of a @dfn{class path}. There are
220 several options and environment variables which can be used to
221 manipulate the class path. When @code{gcj} looks for a given class, it
222 searches the class path looking for matching @file{.class} or
223 @file{.java} file. @code{gcj} comes with a built-in class path which
224 points at the installed @file{libgcj.jar}, a file which contains all the
227 In the below, a directory or path component can refer either to an
228 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
229 file, which @code{gcj} will search as if it is a directory.
233 All directories specified by @code{-I} are kept in order and prepended
234 to the class path constructed from all the other options. Unless
235 compatibility with tools like @code{javac} is imported, we recommend
236 always using @code{-I} instead of the other options for manipulating the
239 @item --classpath=@var{path}
240 This sets the class path to @var{path}, a colon-separated list of paths
241 (on Windows-based systems, a semicolon-separate list of paths).
243 @item --CLASSPATH=@var{path}
244 This sets the class path to @var{path}, a colon-separated list of paths
245 (on Windows-based systems, a semicolon-separate list of paths). This
246 differs from the @code{--classpath} option in that it also suppresses
247 the built-in system path.
250 This is an environment variable which holds a list of paths.
253 The final class path is constructed like so:
257 First come all directories specified via @code{-I}.
260 If @code{--classpath} is specified, its value is appended and processing
261 stops. That is, @code{--classpath} suppresses all the options mentioned
265 If @code{--CLASSPATH} is specified, its value is appended and the
266 @code{CLASSPATH} environment variable is suppressed.
269 If the @code{CLASSPATH} environment variable is specified (and was not
270 suppressed by @code{--CLASSPATH}), then its value is appended.
273 Finally, the built-in system directory, @file{libgcj.jar}, is appended.
276 The classfile built by @code{gcj} for the class @code{java.lang.Object}
277 (and placed in @code{libgcj.jar}) contains a special zero length
278 attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
279 attribute when loading @code{java.lang.Object} and will report an error
280 if it isn't found, unless it compiles to bytecode (the option
281 @code{-fforce-classes-archive-check} can be used to overide this
282 behavior in this particular case.)
285 @item -fforce-classes-archive-check
286 This forces the compiler to always check for the special zero length
287 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
288 issue an error if it isn't found.
294 The Java programming language uses Unicode throughout. In an effort to
295 integrate well with other locales, @code{gcj} allows @file{.java} files
296 to be written using almost any encoding. @code{gcj} knows how to
297 convert these encodings into its internal encoding at compile time.
299 You can use the @code{--encoding=@var{NAME}} option to specify an
300 encoding (of a particular character set) to use for source files. If
301 this is not specified, the default encoding comes from your current
302 locale. If your host system has insufficient locale support, then
303 @code{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
306 To implement @code{--encoding}, @code{gcj} simply uses the host
307 platform's @code{iconv} conversion routine. This means that in practice
308 @code{gcj} is limited by the capabilities of the host platform.
310 The names allowed for the argument @code{--encoding} vary from platform
311 to platform (since they are not standardized anywhere). However,
312 @code{gcj} implements the encoding named @samp{UTF-8} internally, so if
313 you choose to use this for your source files you can be assured that it
314 will work on every host.
320 @code{gcj} implements several warnings. As with other generic
321 @code{gcc} warnings, if an option of the form @code{-Wfoo} enables a
322 warning, then @code{-Wno-foo} will disable it. Here we've chosen to
323 document the form of the warning which will have an effect -- the
324 default being the opposite of what is listed.
327 @item -Wredundant-modifiers
328 With this flag, @code{gcj} will warn about redundant modifiers. For
329 instance, it will warn if an interface method is declared @code{public}.
331 @item -Wextraneous-semicolon
332 This causes @code{gcj} to warn about empty statements. Empty statements
333 have been deprecated.
335 @item -Wno-out-of-date
336 This option will cause @code{gcj} not to warn when a source file is
337 newer than its matching class file. By default @code{gcj} will warn
341 This is the same as @code{gcc}'s @code{-Wunused}.
344 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
349 @node Code Generation
350 @section Code Generation
352 In addition to the many @code{gcc} options controlling code generation,
353 @code{gcj} has several options specific to itself.
356 @item --main=@var{CLASSNAME}
357 This option is used when linking to specify the name of the class whose
358 @code{main} method should be invoked when the resulting executable is
359 run. @footnote{The linker by default looks for a global function named
360 @code{main}. Since Java does not have global functions, and a
361 collection of Java classes may have more than one class with a
362 @code{main} method, you need to let the linker know which of those
363 @code{main} methods it should invoke when starting the application.}
365 @item -D@var{name}[=@var{value}]
366 This option can only be used with @code{--main}. It defines a system
367 property named @var{name} with value @var{value}. If @var{value} is not
368 specified then it defaults to the empty string. These system properties
369 are initialized at the program's startup and can be retrieved at runtime
370 using the @code{java.lang.System.getProperty} method.
373 This option is used to tell @code{gcj} to generate bytecode
374 (@file{.class} files) rather than object code.
376 @item -R @var{resource-name}
377 This option is used to tell @code{gcj} to compile the contents of a
378 given file to object code so it may be accessed at runtime with the core
379 protocol handler as @var{core:/resource-name}.
381 @item -d @var{directory}
382 When used with @code{-C}, this causes all generated @file{.class} files
383 to be put in the appropriate subdirectory of @var{directory}. By
384 default they will be put in subdirectories of the current working
387 @item -fno-bounds-check
388 By default, @code{gcj} generates code which checks the bounds of all
389 array indexing operations. With this option, these checks are omitted.
390 Note that this can result in unpredictable behavior if the code in
391 question actually does violate array bounds constraints.
394 With @code{gcj} there are two options for writing native methods: CNI
395 and JNI. By default @code{gcj} assumes you are using CNI. If you are
396 compiling a class with native methods, and these methods are implemented
397 using JNI, then you must use @code{-fjni}. This option causes
398 @code{gcj} to generate stubs which will invoke the underlying JNI
401 @item -fno-optimize-static-class-initialization
402 When the optimization level is greather or equal to @code{-O2},
403 @code{gcj} will try to optimize the way calls into the runtime are made
404 to initialize static classes upon their first use (this optimization
405 isn't carried out if @code{-C} was specified.) When compiling to native
406 code, @code{-fno-optimize-static-class-initialization} will turn this
407 optimization off, regardless of the optimization level in use.
411 @node Configure-time Options
412 @section Configure-time Options
414 Some @code{gcj} code generations options affect the resulting ABI, and
415 so can only be meaningfully given when @code{libgcj}, the runtime
416 package, is configured. @code{libgcj} puts the appropriate options from
417 this group into a @samp{spec} file which is read by @code{gcj}. These
418 options are listed here for completeness; if you are using @code{libgcj}
419 then you won't want to touch these options.
423 This enables the use of the Boehm GC bitmap marking code. In particular
424 this causes @code{gcj} to put an object marking descriptor into each
427 @item -fhash-synchronization
428 By default, synchronization data (the data used for @code{synchronize},
429 @code{wait}, and @code{notify}) is pointed to by a word in each object.
430 With this option @code{gcj} assumes that this information is stored in a
431 hash table and not in the object itself.
433 @item -fuse-divide-subroutine
434 On some systems, a library routine is called to perform integer
435 division. This is required to get exception handling correct when
438 @item -fcheck-references
439 On some systems it's necessary to insert inline checks whenever
440 accessing an object via a reference. On other systems you won't need
441 this because null pointer accesses are caught automatically by the
448 @chapter Compatibility with the Java Platform
450 As we believe it is important that the Java platform not be fragmented,
451 @code{gcj} and @code{libgcj} try to conform to the relevant Java
452 specifications. However, limited manpower and incomplete and unclear
453 documentation work against us. So, there are caveats to using
456 This list of compatibility issues is by no means complete.
460 @code{gcj} implements the JDK 1.1 language. It supports inner classes,
461 though these are known to still be buggy. It does not yet support the
462 Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores
466 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
467 However, @code{libgcj} is missing many packages, most notably
468 @code{java.awt}. There are also individual missing classes and methods.
469 We currently do not have a list showing differences between
470 @code{libgcj} and the Java 2 platform.
473 Sometimes the @code{libgcj} implementation of a method or class differs
474 from the JDK implementation. This is not always a bug. Still, if it
475 affects you, it probably makes sense to report it so that we can discuss
476 the appropriate response.
481 @chapter Invoking gcjh
483 @c man title gcjh generate header files from Java class files
485 @c man begin DESCRIPTION gcjh
487 The @code{gcjh} program is used to generate header files from class
488 files. It can generate both CNI and JNI header files, as well as stub
489 implementation files which can be used as a basis for implementing the
490 required native methods.
495 @c man begin SYNOPSIS gcjh
496 gcjh [@option{-stubs}] [@option{-jni}]
497 [@option{-add}@var{text}] [@option{-append}@var{text}] [@option{-friend}@var{text}] [@option{-preprend}@var{text}]
498 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
499 [@option{-I}@var{dir}@dots{}] [@option{-d}@var{dir}@dots{}]
500 [@option{-o}@var{file}] [@option{-td}@var{dir}]
501 [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
502 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
503 @var{classname}@dots{}
505 @c man begin SEEALSO gcjh
506 gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
507 and the Info entries for @file{gcj} and @file{gcc}.
511 @c man begin OPTIONS gcjh
515 This causes @code{gcjh} to generate stub files instead of header files.
516 By default the stub file will be named after the class, with a suffix of
517 @samp{.cc}. In JNI mode, the default output file will have the suffix
521 This tells @code{gcjh} to generate a JNI header or stub. By default,
522 CNI headers are generated.
524 @item -add @var{text}
525 Inserts @var{text} into the class body. This is ignored in JNI mode.
527 @item -append @var{text}
528 Inserts @var{text} into the header file after the class declaration.
529 This is ignored in JNI mode.
531 @item -friend @var{text}
532 Inserts @var{text} into the class as a @code{friend} declaration.
533 This is ignored in JNI mode.
535 @item -prepend @var{text}
536 Inserts @var{text} into the header file before the class declaration.
537 This is ignored in JNI mode.
539 @item --classpath=@var{path}
540 @itemx --CLASSPATH=@var{path}
541 @itemx -I@var{directory}
542 @itemx -d @var{directory}
544 These options are all identical to the corresponding @code{gcj} options.
547 Sets the output file name. This cannot be used if there is more than
548 one class on the command line.
550 @item -td @var{directory}
551 Sets the name of the directory to use for temporary files.
554 Print all dependencies to stdout; suppress ordinary output.
557 Print non-system dependencies to stdout; suppress ordinary output.
560 Print all dependencies to stdout.
563 Print non-system dependencies to stdout.
566 Print help about @code{gcjh} and exit. No further processing is done.
569 Print version information for @code{gcjh} and exit. No further
573 Print extra information while running.
576 All remaining options are considered to be names of classes.
580 @node Invoking jv-scan
581 @chapter Invoking jv-scan
583 @c man title jv-scan print information about Java source file
585 @c man begin DESCRIPTION jv-scan
587 The @code{jv-scan} program can be used to print information about a Java
588 source file (@file{.java} file).
593 @c man begin SYNOPSIS jv-scan
594 jv-scan [@option{--complexity}] [@option{--encoding}@var{name}]
595 [@option{--print-main}] [@option{--list-class}] [@option{--list-filename}]
596 [@option{--version}] [@option{--help}]
597 [@option{-o}@var{file}] @var{inputfile}@dots{}
599 @c man begin SEEALSO jv-scan
600 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
601 and the Info entries for @file{gcj} and @file{gcc}.
605 @c man begin OPTIONS jv-scan
609 This prints a complexity measure, related to cyclomatic complexity, for
612 @item --encoding=@var{name}
613 This works like the corresponding @code{gcj} option.
616 This prints the name of the class in this file containing a @code{main}
620 This lists the names of all classes defined in the input files.
622 @item --list-filename
623 If @code{--list-class} is given, this option causes @code{jv-scan} to
624 also print the name of the file in which each class was found.
627 Print output to the named file.
630 Print help, then exit.
633 Print version number, then exit.
638 @node Invoking jcf-dump
639 @chapter Invoking jcf-dump
641 @c man title jcf-dump print information about Java class files
644 @c man begin SYNOPSIS jcf-dump
645 jcf-dump [@option{-c}] [@option{--javap}]
646 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
647 [@option{-I}@var{dir}@dots{}] [@option{-o}@var{file}]
648 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
649 @var{classname}@dots{}
651 @c man begin SEEALSO jcf-dump
652 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
653 and the Info entries for @file{gcj} and @file{gcc}.
657 @c man begin DESCRIPTION jcf-dump
659 This is a class file examiner, similar to @code{javap}. It will print
660 information about a number of classes, which are specifed by class name
665 @c man begin OPTIONS jcf-dump
669 Disassemble method bodies. By default method bodies are not printed.
672 Generate output in @code{javap} format. The implementation of this
673 feature is very incomplete.
675 @item --classpath=@var{path}
676 @itemx --CLASSPATH=@var{path}
677 @itemx -I@var{directory}
679 These options as the same as the corresponding @code{gcj} options.
682 Print help, then exit.
685 Print version number, then exit.
688 Print extra information while running.
694 @chapter Invoking gij
696 @c man title gij GNU interpreter for Java bytecode
699 @c man begin SYNOPSIS gij
700 gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
702 gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
704 [@option{-D}@var{name}[=@var{value}]@dots{}]
705 [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
706 [@option{--version}] [@option{--help}]
708 @c man begin SEEALSO gij
709 gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
710 and the Info entries for @file{gcj} and @file{gcc}.
714 @c man begin DESCRIPTION gij
716 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
717 @code{gij} is not available on every platform; porting it requires a
718 small amount of assembly programming which has not been done for all the
719 targets supported by @code{gcj}.
721 The primary argument to @code{gij} is the name of a class or, with
722 @code{-jar}, a jar file. Options before this argument are interpreted
723 by @code{gij}; remaining options are passed to the interpreted program.
725 If a class name is specified and this class does not have a @code{main}
726 method with the appropriate signature (a @code{static void} method with
727 a @code{String[]} as its sole argument), then @code{gij} will print an
730 If a jar file is specified then @code{gij} will use information in it to
731 determine which class' @code{main} method will be invoked.
733 @code{gij} will invoke the @code{main} method with all the remaining
734 command-line options.
736 Note that @code{gij} is not limited to interpreting code. Because
737 @code{libgcj} includes a class loader which can dynamically load shared
738 objects, it is possible to give @code{gij} the name of a class which has
739 been compiled and put into a shared library on the class path.
743 @c man begin OPTIONS gij
746 @item -D@var{name}[=@var{value}]
747 This defines a system property named @var{name} with value @var{value}.
748 If @var{value} is not specified then it defaults to the empty string.
749 These system properties are initialized at the program's startup and can
750 be retrieved at runtime using the @code{java.lang.System.getProperty}
753 @item -ms=@var{number}
754 This sets the initial heap size.
756 @item -mx=@var{number}
757 This sets the maximum heap size.
760 This indicates that the name passed to @code{gij} should be interpreted
761 as the name of a jar file, not a class.
764 Print help, then exit.
767 Print version number, then exit.
775 While writing @code{gcj} and @code{libgcj} we have, of course, relied
776 heavily on documentation from Sun Microsystems. In particular we have
777 used The Java Language Specification (both first and second editions),
778 the Java Class Libraries (volumes one and two), and the Java Virtual
779 Machine Specification. In addition we've used the online documentation
780 at @uref{http://java.sun.com/}.
782 The current @code{gcj} home page is
783 @uref{http://gcc.gnu.org/java/}.
785 For more information on gcc, see @uref{http://gcc.gnu.org/}.
787 Some @code{libgcj} testing is done using the Mauve test suite. This is
788 a free software Java class library test suite which is being written
789 because the JCK is not free. See
790 @uref{http://sources.redhat.com/mauve/} for more information.