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}
19 @dircategory Programming
21 * Gcj: (gcj). Ahead-of-time compiler for the Java language
24 @dircategory Individual utilities
26 * gcjh: (gcj)Invoking gcjh.
27 Generate header files from Java class files
28 * jv-scan: (gcj)Invoking jv-scan.
29 Print information about Java source files
30 * jcf-dump: (gcj)Invoking jcf-dump.
31 Print information about Java class files
32 * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
36 Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU Free Documentation License, Version 1.1 or
40 any later version published by the Free Software Foundation; with the
41 Invariant Sections being ``GNU General Public License'', the Front-Cover
42 texts being (a) (see below), and with the Back-Cover Texts being (b)
43 (see below). A copy of the license is included in the section entitled
44 ``GNU Free Documentation License''.
46 (a) The FSF's Front-Cover Text is:
50 (b) The FSF's Back-Cover Text is:
52 You have freedom to copy and modify this GNU Manual, like GNU
53 software. Copies published by the Free Software Foundation raise
54 funds for GNU development.
62 @vskip 0pt plus 1filll
63 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
65 For the @value{which-gcj} Version*
67 Published by the Free Software Foundation @*
68 59 Temple Place - Suite 330@*
69 Boston, MA 02111-1307, USA@*
71 Permission is granted to copy, distribute and/or modify this document
72 under the terms of the GNU Free Documentation License, Version 1.1 or
73 any later version published by the Free Software Foundation; with the
74 Invariant Sections being ``GNU General Public License'', the Front-Cover
75 texts being (a) (see below), and with the Back-Cover Texts being (b)
76 (see below). A copy of the license is included in the section entitled
77 ``GNU Free Documentation License''.
79 (a) The FSF's Front-Cover Text is:
83 (b) The FSF's Back-Cover Text is:
85 You have freedom to copy and modify this GNU Manual, like GNU
86 software. Copies published by the Free Software Foundation raise
87 funds for GNU development.
96 This manual describes how to use @code{gcj}, the GNU compiler for the
97 Java programming language. @code{gcj} can generate both @file{.class}
98 files and object files, and it can read both Java source code and
102 * Copying:: The GNU General Public License
103 * GNU Free Documentation License::
104 How you can share and copy this manual
105 * Invoking gcj:: Compiler options supported by @code{gcj}
106 * Compatibility:: Compatibility between gcj and other tools for Java
107 * Invoking gcjh:: Generate header files from class files
108 * Invoking jv-scan:: Print information about source files
109 * Invoking jcf-dump:: Print information about class files
110 * Invoking gij:: Interpreting Java bytecodes
111 * Resources:: Where to look for more information
121 @chapter Invoking gcj
123 As @code{gcj} is just another front end to @code{gcc}, it supports many
124 of the same options as gcc. @xref{Option Summary, , Option Summary,
125 gcc, Using the GNU Compiler Collection}. This manual only documents the
126 options specific to @code{gcj}.
129 * Input and output files::
130 * Input Options:: How gcj finds files
131 * Encodings:: Options controlling source file encoding
132 * Warnings:: Options controlling warnings specific to gcj
133 * Code Generation:: Options controlling the output of gcj
134 * Configure-time Options:: Options you won't use
137 @node Input and output files
138 @section Input and output files
140 A @code{gcj} command is like a @code{gcc} command, in that it
141 consists of a number of options and file names. The following kinds
142 of input file names are supported:
145 @item @var{file}.java
147 @item @var{file}.class
150 @itemx @var{file}.jar
151 An archive containing one or more @code{.class} files, all of
152 which are compiled. The archive may be compressed.
154 A file containing a whitespace-separated list of input file names.
155 (Currently, these must all be @code{.java} source files, but that
157 Each named file is compiled, just as if it had been on the command line.
158 @item @var{library}.a
159 @itemx @var{library}.so
160 @itemx -l@var{libname}
161 Libraries to use when linking. See the @code{gcc} manual.
164 You can specify more than one input file on the @code{gcj} command line,
165 in which case they will all be compiled. If you specify a
166 @code{-o @var{FILENAME}}
167 option, all the input files will be compiled together, producing a
168 single output file, named @var{FILENAME}.
169 This is allowed even when using @code{-S} or @code{-c},
170 but not when using @code{-C}.
171 (This is an extension beyond the what plain @code{gcc} allows.)
172 (If more than one input file is specified, all must currently
173 be @code{.java} files, though we hope to fix this.)
176 @section Input Options
180 @code{gcj} has options to control where it looks to find files it needs.
181 For instance, @code{gcj} might need to load a class that is referenced
182 by the file it has been asked to compile. Like other compilers for the
183 Java language, @code{gcj} has a notion of a @dfn{class path}. There are
184 several options and environment variables which can be used to
185 manipulate the class path. When @code{gcj} looks for a given class, it
186 searches the class path looking for matching @file{.class} or
187 @file{.java} file. @code{gcj} comes with a built-in class path which
188 points at the installed @file{libgcj.jar}, a file which contains all the
191 In the below, a directory or path component can refer either to an
192 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
193 file, which @code{gcj} will search as if it is a directory.
197 All directories specified by @code{-I} are kept in order and prepended
198 to the class path constructed from all the other options. Unless
199 compatibility with tools like @code{javac} is imported, we recommend
200 always using @code{-I} instead of the other options for manipulating the
203 @item --classpath=@var{path}
204 This sets the class path to @var{path}, a colon-separated list of paths
205 (on Windows-based systems, a semicolon-separate list of paths).
207 @item --CLASSPATH=@var{path}
208 This sets the class path to @var{path}, a colon-separated list of paths
209 (on Windows-based systems, a semicolon-separate list of paths). This
210 differs from the @code{--classpath} option in that it also suppresses
211 the built-in system path.
214 This is an environment variable which holds a list of paths.
217 The final class path is constructed like so:
221 First come all directories specified via @code{-I}.
224 If @code{--classpath} is specified, its value is appended and processing
225 stops. That is, @code{--classpath} suppresses all the options mentioned
229 If @code{--CLASSPATH} is specified, its value is appended and the
230 @code{CLASSPATH} environment variable is suppressed.
233 If the @code{CLASSPATH} environment variable is specified (and was not
234 suppressed by @code{--CLASSPATH}), then its value is appended.
237 Finally, the built-in system directory, @file{libgcj.jar}, is appended.
240 The classfile built by @code{gcj} for the class @code{java.lang.Object}
241 (and placed in @code{libgcj.jar}) contains a special zero length
242 attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
243 attribute when loading @code{java.lang.Object} and will report an error
244 if it isn't found, unless it compiles to bytecode (the option
245 @code{-fforce-classes-archive-check} can be used to overide this
246 behavior in this particular case.)
249 @item -fforce-classes-archive-check
250 This forces the compiler to always check for the special zero length
251 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
252 issue an error if it isn't found.
258 The Java programming language uses Unicode throughout. In an effort to
259 integrate well with other locales, @code{gcj} allows @file{.java} files
260 to be written using almost any encoding. @code{gcj} knows how to
261 convert these encodings into its internal encoding at compile time.
263 You can use the @code{--encoding=@var{NAME}} option to specify an
264 encoding (of a particular character set) to use for source files. If
265 this is not specified, the default encoding comes from your current
266 locale. If your host system has insufficient locale support, then
267 @code{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
270 To implement @code{--encoding}, @code{gcj} simply uses the host
271 platform's @code{iconv} conversion routine. This means that in practice
272 @code{gcj} is limited by the capabilities of the host platform.
274 The names allowed for the argument @code{--encoding} vary from platform
275 to platform (since they are not standardized anywhere). However,
276 @code{gcj} implements the encoding named @samp{UTF-8} internally, so if
277 you choose to use this for your source files you can be assured that it
278 will work on every host.
284 @code{gcj} implements several warnings. As with other generic
285 @code{gcc} warnings, if an option of the form @code{-Wfoo} enables a
286 warning, then @code{-Wno-foo} will disable it. Here we've chosen to
287 document the form of the warning which will have an effect -- the
288 default being the opposite of what is listed.
291 @item -Wredundant-modifiers
292 With this flag, @code{gcj} will warn about redundant modifiers. For
293 instance, it will warn if an interface method is declared @code{public}.
295 @item -Wextraneous-semicolon
296 This causes @code{gcj} to warn about empty statements. Empty statements
297 have been deprecated.
299 @item -Wno-out-of-date
300 This option will cause @code{gcj} not to warn when a source file is
301 newer than its matching class file. By default @code{gcj} will warn
305 This is the same as @code{gcc}'s @code{-Wunused}.
308 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
313 @node Code Generation
314 @section Code Generation
316 In addition to the many @code{gcc} options controlling code generation,
317 @code{gcj} has several options specific to itself.
320 @item --main=@var{CLASSNAME}
321 This option is used when linking to specify the name of the class whose
322 @code{main} method should be invoked when the resulting executable is
323 run. @footnote{The linker by default looks for a global function named
324 @code{main}. Since Java does not have global functions, and a
325 collection of Java classes may have more than one class with a
326 @code{main} method, you need to let the linker know which of those
327 @code{main} methods it should invoke when starting the application.}
329 @item -D@var{name}[=@var{value}]
330 This option can only be used with @code{--main}. It defines a system
331 property named @var{name} with value @var{value}. If @var{value} is not
332 specified then it defaults to the empty string. These system properties
333 are initialized at the program's startup and can be retrieved at runtime
334 using the @code{java.lang.System.getProperty} method.
337 This option is used to tell @code{gcj} to generate bytecode
338 (@file{.class} files) rather than object code.
340 @item -d @var{directory}
341 When used with @code{-C}, this causes all generated @file{.class} files
342 to be put in the appropriate subdirectory of @var{directory}. By
343 default they will be put in subdirectories of the current working
346 @item -fno-bounds-check
347 By default, @code{gcj} generates code which checks the bounds of all
348 array indexing operations. With this option, these checks are omitted.
349 Note that this can result in unpredictable behavior if the code in
350 question actually does violate array bounds constraints.
353 With @code{gcj} there are two options for writing native methods: CNI
354 and JNI. By default @code{gcj} assumes you are using CNI. If you are
355 compiling a class with native methods, and these methods are implemented
356 using JNI, then you must use @code{-fjni}. This option causes
357 @code{gcj} to generate stubs which will invoke the underlying JNI
360 @item -fno-optimize-static-class-initialization
361 When the optimization level is greather or equal to @code{-O2},
362 @code{gcj} will try to optimize the way calls into the runtime are made
363 to initialize static classes upon their first use (this optimization
364 isn't carried out if @code{-C} was specified.) When compiling to native
365 code, @code{-fno-optimize-static-class-initialization} will turn this
366 optimization off, regardless of the optimization level in use.
370 @node Configure-time Options
371 @section Configure-time Options
373 Some @code{gcj} code generations options affect the resulting ABI, and
374 so can only be meaningfully given when @code{libgcj}, the runtime
375 package, is configured. @code{libgcj} puts the appropriate options from
376 this group into a @samp{spec} file which is read by @code{gcj}. These
377 options are listed here for completeness; if you are using @code{libgcj}
378 then you won't want to touch these options.
382 This enables the use of the Boehm GC bitmap marking code. In particular
383 this causes @code{gcj} to put an object marking descriptor into each
386 @item -fhash-synchronization
387 By default, synchronization data (the data used for @code{synchronize},
388 @code{wait}, and @code{notify}) is pointed to by a word in each object.
389 With this option @code{gcj} assumes that this information is stored in a
390 hash table and not in the object itself.
392 @item -fuse-divide-subroutine
393 On some systems, a library routine is called to perform integer
394 division. This is required to get exception handling correct when
397 @item -fcheck-references
398 On some systems it's necessary to insert inline checks whenever
399 accessing an object via a reference. On other systems you won't need
400 this because null pointer accesses are caught automatically by the
406 @chapter Compatibility with the Java Platform
408 As we believe it is important that the Java platform not be fragmented,
409 @code{gcj} and @code{libgcj} try to conform to the relevant Java
410 specifications. However, limited manpower and incomplete and unclear
411 documentation work against us. So, there are caveats to using
414 This list of compatibility issues is by no means complete.
418 @code{gcj} implements the JDK 1.1 language. It supports inner classes,
419 though these are known to still be buggy. It does not yet support the
420 Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores
424 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
425 However, @code{libgcj} is missing many packages, most notably
426 @code{java.awt}. There are also individual missing classes and methods.
427 We currently do not have a list showing differences between
428 @code{libgcj} and the Java 2 platform.
431 Sometimes the @code{libgcj} implementation of a method or class differs
432 from the JDK implementation. This is not always a bug. Still, if it
433 affects you, it probably makes sense to report it so that we can discuss
434 the appropriate response.
439 @chapter Invoking gcjh
441 The @code{gcjh} program is used to generate header files from class
442 files. It can generate both CNI and JNI header files, as well as stub
443 implementation files which can be used as a basis for implementing the
444 required native methods.
448 This causes @code{gcjh} to generate stub files instead of header files.
449 By default the stub file will be named after the class, with a suffix of
450 @samp{.cc}. In JNI mode, the default output file will have the suffix
454 This tells @code{gcjh} to generate a JNI header or stub. By default,
455 CNI headers are generated.
457 @item -add @var{text}
458 Inserts @var{text} into the class body. This is ignored in JNI mode.
460 @item -append @var{text}
461 Inserts @var{text} into the header file after the class declaration.
462 This is ignored in JNI mode.
464 @item -friend @var{text}
465 Inserts @var{text} into the class as a @code{friend} declaration.
466 This is ignored in JNI mode.
468 @item -prepend @var{text}
469 Inserts @var{text} into the header file before the class declaration.
470 This is ignored in JNI mode.
472 @item --classpath=@var{path}
473 @itemx --CLASSPATH=@var{path}
474 @itemx -I@var{directory}
475 @itemx -d @var{directory}
477 These options are all identical to the corresponding @code{gcj} options.
480 Sets the output file name. This cannot be used if there is more than
481 one class on the command line.
483 @item -td @var{directory}
484 Sets the name of the directory to use for temporary files.
487 Print help about @code{gcjh} and exit. No further processing is done.
490 Print version information for @code{gcjh} and exit. No further
494 All remaining options are considered to be names of classes.
497 @node Invoking jv-scan
498 @chapter Invoking jv-scan
500 The @code{jv-scan} program can be used to print information about a Java
501 source file (@file{.java} file).
505 This prints a complexity measure, related to cyclomatic complexity, for
508 @item --encoding=@var{name}
509 This works like the corresponding @code{gcj} option.
512 This prints the name of the class in this file containing a @code{main}
516 This lists the names of all classes defined in the input files.
518 @item --list-filename
519 If @code{--list-class} is given, this option causes @code{jv-scan} to
520 also print the name of the file in which each class was found.
523 Print output to the named file.
527 @node Invoking jcf-dump
528 @chapter Invoking jcf-dump
530 This is a class file examiner, similar to @code{javap}. It will print
531 information about a number of classes, which are specifed by class name
536 Disassemble method bodies. By default method bodies are not printed.
539 Generate output in @code{javap} format. The implementation of this
540 feature is very incomplete.
542 @item --classpath=@var{path}
543 @itemx --CLASSPATH=@var{path}
544 @itemx -I@var{directory}
546 These options as the same as the corresponding @code{gcj} options.
551 @chapter Invoking gij
553 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
554 @code{gij} is not available on every platform; porting it requires a
555 small amount of assembly programming which has not been done for all the
556 targets supported by @code{gcj}.
558 The primary argument to @code{gij} is the name of a class or, with
559 @code{-jar}, a jar file. Options before this argument are interpreted
560 by @code{gij}; remaining options are passed to the interpreted program.
562 If a class name is specified and this class does not have a @code{main}
563 method with the appropriate signature (a @code{static void} method with
564 a @code{String[]} as its sole argument), then @code{gij} will print an
567 If a jar file is specified then @code{gij} will use information in it to
568 determine which class' @code{main} method will be invoked.
570 @code{gij} will invoke the @code{main} method with all the remaining
571 command-line options.
573 Note that @code{gij} is not limited to interpreting code. Because
574 @code{libgcj} includes a class loader which can dynamically load shared
575 objects, it is possible to give @code{gij} the name of a class which has
576 been compiled and put into a shared library on the class path.
579 @item -D@var{name}[=@var{value}]
580 This defines a system property named @var{name} with value @var{value}.
581 If @var{value} is not specified then it defaults to the empty string.
582 These system properties are initialized at the program's startup and can
583 be retrieved at runtime using the @code{java.lang.System.getProperty}
586 @item -ms=@var{number}
587 This sets the initial heap size
589 @item -mx=@var{number}
590 This sets the maximum heap size.
593 This indicates that the name passed to @code{gij} should be interpreted
594 as the name of a jar file, not a class.
601 While writing @code{gcj} and @code{libgcj} we have, of course, relied
602 heavily on documentation from Sun Microsystems. In particular we have
603 used The Java Language Specification (both first and second editions),
604 the Java Class Libraries (volumes one and two), and the Java Virtual
605 Machine Specification. In addition we've used the online documentation
606 at @uref{http://java.sun.com/}.
608 The current @code{gcj} home page is
609 @uref{http://gcc.gnu.org/java/}.
611 For more information on gcc, see @uref{http://gcc.gnu.org/}.
613 Some @code{libgcj} testing is done using the Mauve test suite. This is
614 a free software Java class library test suite which is being written
615 because the JCK is not free. See
616 @uref{http://sources.redhat.com/mauve/} for more information.