OSDN Git Service

3a0087022b3b623d320731aef0df4df826d2fddc
[pf3gnuchains/gcc-fork.git] / gcc / java / gcj.texi
1 @\input texinfo @c -*-texinfo-*-
2 @setfilename gcj.info
3 @settitle Guide to GNU gcj
4
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
8 @c the word ``Java'.
9
10 @c When this manual is copyrighted.
11 @set copyrights-gcj 2001
12
13 @c Versions
14 @set version-gcc 3.1
15 @set which-gcj GCC-@value{version-gcc}
16
17 @macro gcctabopt{body}
18 @code{\body\}
19 @end macro
20
21 @ifinfo
22 @format
23 @dircategory Programming
24 @direntry
25 * Gcj: (gcj).               Ahead-of-time compiler for the Java language
26 @end direntry
27
28 @dircategory Individual utilities
29 @direntry
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
37 * jv-convert: (gcj)Invoking jv-convert.
38                             Convert file from one encoding to another
39 @end direntry
40 @end format
41
42 @c man begin COPYRIGHT
43 Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
44
45 Permission is granted to copy, distribute and/or modify this document
46 under the terms of the GNU Free Documentation License, Version 1.1 or
47 any later version published by the Free Software Foundation; with the
48 Invariant Sections being ``GNU General Public License'', the Front-Cover
49 texts being (a) (see below), and with the Back-Cover Texts being (b)
50 (see below).  A copy of the license is included in the
51 @c man end
52 section entitled
53 ``GNU Free Documentation License''.
54 @ignore
55 @c man begin COPYRIGHT
56 man page gfdl(7).
57 @c man end
58 @end ignore
59
60 (a) The FSF's Front-Cover Text is:
61
62      A GNU Manual
63
64 (b) The FSF's Back-Cover Text is:
65
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.
69 @end ifinfo
70
71 @titlepage
72 @title GNU gcj
73 @author Tom Tromey
74
75 @page
76 @vskip 0pt plus 1filll
77 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
78 @sp 2
79 For the @value{which-gcj} Version*
80 @sp 1
81 Published by the Free Software Foundation @*
82 59 Temple Place - Suite 330@*
83 Boston, MA 02111-1307, USA@*
84 @sp 1
85 Permission is granted to copy, distribute and/or modify this document
86 under the terms of the GNU Free Documentation License, Version 1.1 or
87 any later version published by the Free Software Foundation; with the
88 Invariant Sections being ``GNU General Public License'', the Front-Cover
89 texts being (a) (see below), and with the Back-Cover Texts being (b)
90 (see below).  A copy of the license is included in the section entitled
91 ``GNU Free Documentation License''.
92
93 (a) The FSF's Front-Cover Text is:
94
95      A GNU Manual
96
97 (b) The FSF's Back-Cover Text is:
98
99      You have freedom to copy and modify this GNU Manual, like GNU
100      software.  Copies published by the Free Software Foundation raise
101      funds for GNU development.
102 @end titlepage
103 @contents
104 @page
105
106
107 @node Top
108 @top Introduction
109
110 This manual describes how to use @code{gcj}, the GNU compiler for the
111 Java programming language.  @code{gcj} can generate both @file{.class}
112 files and object files, and it can read both Java source code and
113 @file{.class} files.
114
115 @menu
116 * Copying::             The GNU General Public License
117 * GNU Free Documentation License::
118                         How you can share and copy this manual
119 * Invoking gcj::        Compiler options supported by @code{gcj}
120 * Compatibility::       Compatibility between gcj and other tools for Java
121 * Invoking gcjh::       Generate header files from class files
122 * Invoking jv-scan::    Print information about source files
123 * Invoking jcf-dump::   Print information about class files
124 * Invoking gij::        Interpreting Java bytecodes
125 * Invoking jv-convert:: Converting from one encoding to another
126 * Resources::           Where to look for more information
127 @end menu
128
129
130 @include gpl.texi
131
132 @include fdl.texi
133
134
135 @node Invoking gcj
136 @chapter Invoking gcj
137
138 @c man title gcj Ahead-of-time compiler for the Java language
139
140 @ignore
141 @c man begin SYNOPSIS gcj
142 gcj [@option{-I}@var{dir}@dots{}] [@option{-d}@var{dir}@dots{}]
143     [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
144     [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
145     [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
146     [@option{-C}] [@option{-R} @var{resource-name}] [@option{-d} @var{directory}]
147     [@option{-W}@var{warn}@dots{}]
148     @var{sourcefile}@dots{}
149 @c man end
150 @c man begin SEEALSO gcj
151 gcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
152 and the Info entries for @file{gcj} and @file{gcc}.
153 @c man end
154 @end ignore
155
156 @c man begin DESCRIPTION gcj
157
158 As @code{gcj} is just another front end to @code{gcc}, it supports many
159 of the same options as gcc.  @xref{Option Summary, , Option Summary,
160 gcc, Using the GNU Compiler Collection (GCC)}.  This manual only documents the
161 options specific to @code{gcj}.
162
163 @c man end
164
165 @menu
166 * Input and output files::
167 * Input Options::               How gcj finds files
168 * Encodings::                   Options controlling source file encoding
169 * Warnings::                    Options controlling warnings specific to gcj
170 * Code Generation::             Options controlling the output of gcj
171 * Configure-time Options::      Options you won't use
172 @end menu
173
174 @c man begin OPTIONS gcj
175
176 @node Input and output files
177 @section Input and output files
178
179 A @code{gcj} command is like a @code{gcc} command, in that it
180 consists of a number of options and file names.  The following kinds
181 of input file names are supported:
182
183 @table @gcctabopt
184 @item @var{file}.java
185 Java source files.
186 @item @var{file}.class
187 Java bytecode files.
188 @item @var{file}.zip
189 @itemx @var{file}.jar
190 An archive containing one or more @code{.class} files, all of
191 which are compiled.  The archive may be compressed.
192 @item @@@var{file}
193 A file containing a whitespace-separated list of input file names.
194 (Currently, these must all be @code{.java} source files, but that
195 may change.)
196 Each named file is compiled, just as if it had been on the command line.
197 @item @var{library}.a
198 @itemx @var{library}.so
199 @itemx -l@var{libname}
200 Libraries to use when linking.  See the @code{gcc} manual.
201 @end table
202
203 You can specify more than one input file on the @code{gcj} command line,
204 in which case they will all be compiled.  If you specify a
205 @code{-o @var{FILENAME}}
206 option, all the input files will be compiled together, producing a
207 single output file, named @var{FILENAME}.
208 This is allowed even when using @code{-S} or @code{-c},
209 but not when using @code{-C} or @code{-R}.
210 (This is an extension beyond the what plain @code{gcc} allows.)
211 (If more than one input file is specified, all must currently
212 be @code{.java} files, though we hope to fix this.)
213
214 @node Input Options
215 @section Input Options
216
217 @cindex class path
218
219 @code{gcj} has options to control where it looks to find files it needs.
220 For instance, @code{gcj} might need to load a class that is referenced
221 by the file it has been asked to compile.  Like other compilers for the
222 Java language, @code{gcj} has a notion of a @dfn{class path}.  There are
223 several options and environment variables which can be used to
224 manipulate the class path.  When @code{gcj} looks for a given class, it
225 searches the class path looking for matching @file{.class} or
226 @file{.java} file.  @code{gcj} comes with a built-in class path which
227 points at the installed @file{libgcj.jar}, a file which contains all the
228 standard classes.
229
230 In the below, a directory or path component can refer either to an
231 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
232 file, which @code{gcj} will search as if it is a directory.
233
234 @table @gcctabopt
235 @item -I@var{dir}
236 All directories specified by @code{-I} are kept in order and prepended
237 to the class path constructed from all the other options.  Unless
238 compatibility with tools like @code{javac} is imported, we recommend
239 always using @code{-I} instead of the other options for manipulating the
240 class path.
241
242 @item --classpath=@var{path}
243 This sets the class path to @var{path}, a colon-separated list of paths
244 (on Windows-based systems, a semicolon-separate list of paths).
245
246 @item --CLASSPATH=@var{path}
247 This sets the class path to @var{path}, a colon-separated list of paths
248 (on Windows-based systems, a semicolon-separate list of paths).  This
249 differs from the @code{--classpath} option in that it also suppresses
250 the built-in system path.
251
252 @item CLASSPATH
253 This is an environment variable which holds a list of paths.
254 @end table
255
256 The final class path is constructed like so:
257
258 @itemize @bullet
259 @item
260 First come all directories specified via @code{-I}.
261
262 @item
263 If @code{--classpath} is specified, its value is appended and processing
264 stops.  That is, @code{--classpath} suppresses all the options mentioned
265 later in this list.
266
267 @item
268 If @code{--CLASSPATH} is specified, its value is appended and the
269 @code{CLASSPATH} environment variable is suppressed.
270
271 @item
272 If the @code{CLASSPATH} environment variable is specified (and was not
273 suppressed by @code{--CLASSPATH}), then its value is appended.
274
275 @item
276 Finally, the built-in system directory, @file{libgcj.jar}, is appended.
277 @end itemize
278
279 The classfile built by @code{gcj} for the class @code{java.lang.Object}
280 (and placed in @code{libgcj.jar}) contains a special zero length
281 attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
282 attribute when loading @code{java.lang.Object} and will report an error
283 if it isn't found, unless it compiles to bytecode (the option
284 @code{-fforce-classes-archive-check} can be used to override this
285 behavior in this particular case.)
286
287 @table @gcctabopt
288 @item -fforce-classes-archive-check
289 This forces the compiler to always check for the special zero length
290 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
291 issue an error if it isn't found.
292 @end table
293
294 @node Encodings
295 @section Encodings
296
297 The Java programming language uses Unicode throughout.  In an effort to
298 integrate well with other locales, @code{gcj} allows @file{.java} files
299 to be written using almost any encoding.  @code{gcj} knows how to
300 convert these encodings into its internal encoding at compile time.
301
302 You can use the @code{--encoding=@var{NAME}} option to specify an
303 encoding (of a particular character set) to use for source files.  If
304 this is not specified, the default encoding comes from your current
305 locale.  If your host system has insufficient locale support, then
306 @code{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
307 of Unicode.
308
309 To implement @code{--encoding}, @code{gcj} simply uses the host
310 platform's @code{iconv} conversion routine.  This means that in practice
311 @code{gcj} is limited by the capabilities of the host platform.
312
313 The names allowed for the argument @code{--encoding} vary from platform
314 to platform (since they are not standardized anywhere).  However,
315 @code{gcj} implements the encoding named @samp{UTF-8} internally, so if
316 you choose to use this for your source files you can be assured that it
317 will work on every host.
318
319
320 @node Warnings
321 @section Warnings
322
323 @code{gcj} implements several warnings.  As with other generic
324 @code{gcc} warnings, if an option of the form @code{-Wfoo} enables a
325 warning, then @code{-Wno-foo} will disable it.  Here we've chosen to
326 document the form of the warning which will have an effect -- the
327 default being the opposite of what is listed.
328
329 @table @gcctabopt
330 @item -Wredundant-modifiers
331 With this flag, @code{gcj} will warn about redundant modifiers.  For
332 instance, it will warn if an interface method is declared @code{public}.
333
334 @item -Wextraneous-semicolon
335 This causes @code{gcj} to warn about empty statements.  Empty statements
336 have been deprecated.
337
338 @item -Wno-out-of-date
339 This option will cause @code{gcj} not to warn when a source file is
340 newer than its matching class file.  By default @code{gcj} will warn
341 about this.
342
343 @item -Wunused
344 This is the same as @code{gcc}'s @code{-Wunused}.
345
346 @item -Wall
347 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
348 -Wunused}.
349 @end table
350
351
352 @node Code Generation
353 @section Code Generation
354
355 In addition to the many @code{gcc} options controlling code generation,
356 @code{gcj} has several options specific to itself.
357
358 @table @gcctabopt
359 @item --main=@var{CLASSNAME}
360 This option is used when linking to specify the name of the class whose
361 @code{main} method should be invoked when the resulting executable is
362 run.  @footnote{The linker by default looks for a global function named
363 @code{main}.  Since Java does not have global functions, and a
364 collection of Java classes may have more than one class with a
365 @code{main} method, you need to let the linker know which of those
366 @code{main} methods it should invoke when starting the application.}
367
368 @item -D@var{name}[=@var{value}]
369 This option can only be used with @code{--main}.  It defines a system
370 property named @var{name} with value @var{value}.  If @var{value} is not
371 specified then it defaults to the empty string.  These system properties
372 are initialized at the program's startup and can be retrieved at runtime
373 using the @code{java.lang.System.getProperty} method.
374
375 @item -C
376 This option is used to tell @code{gcj} to generate bytecode
377 (@file{.class} files) rather than object code.
378
379 @item -R @var{resource-name}
380 This option is used to tell @code{gcj} to compile the contents of a
381 given file to object code so it may be accessed at runtime with the core
382 protocol handler as @var{core:/resource-name}.
383
384 @item -d @var{directory}
385 When used with @code{-C}, this causes all generated @file{.class} files
386 to be put in the appropriate subdirectory of @var{directory}.  By
387 default they will be put in subdirectories of the current working
388 directory.
389
390 @item -fno-bounds-check
391 By default, @code{gcj} generates code which checks the bounds of all
392 array indexing operations.  With this option, these checks are omitted.
393 Note that this can result in unpredictable behavior if the code in
394 question actually does violate array bounds constraints.
395
396 @item -fjni
397 With @code{gcj} there are two options for writing native methods: CNI
398 and JNI.  By default @code{gcj} assumes you are using CNI.  If you are
399 compiling a class with native methods, and these methods are implemented
400 using JNI, then you must use @code{-fjni}.  This option causes
401 @code{gcj} to generate stubs which will invoke the underlying JNI
402 methods.
403
404 @item -fno-optimize-static-class-initialization
405 When the optimization level is greather or equal to @code{-O2},
406 @code{gcj} will try to optimize the way calls into the runtime are made
407 to initialize static classes upon their first use (this optimization
408 isn't carried out if @code{-C} was specified.) When compiling to native
409 code, @code{-fno-optimize-static-class-initialization} will turn this
410 optimization off, regardless of the optimization level in use.
411 @end table
412
413
414 @node Configure-time Options
415 @section Configure-time Options
416
417 Some @code{gcj} code generations options affect the resulting ABI, and
418 so can only be meaningfully given when @code{libgcj}, the runtime
419 package, is configured.  @code{libgcj} puts the appropriate options from
420 this group into a @samp{spec} file which is read by @code{gcj}.  These
421 options are listed here for completeness; if you are using @code{libgcj}
422 then you won't want to touch these options.
423
424 @table @gcctabopt
425 @item -fuse-boehm-gc
426 This enables the use of the Boehm GC bitmap marking code.  In particular
427 this causes @code{gcj} to put an object marking descriptor into each
428 vtable.
429
430 @item -fhash-synchronization
431 By default, synchronization data (the data used for @code{synchronize},
432 @code{wait}, and @code{notify}) is pointed to by a word in each object.
433 With this option @code{gcj} assumes that this information is stored in a
434 hash table and not in the object itself.
435
436 @item -fuse-divide-subroutine
437 On some systems, a library routine is called to perform integer
438 division.  This is required to get exception handling correct when
439 dividing by zero.
440
441 @item -fcheck-references
442 On some systems it's necessary to insert inline checks whenever
443 accessing an object via a reference.  On other systems you won't need
444 this because null pointer accesses are caught automatically by the
445 processor.
446 @end table
447
448 @c man end
449
450 @node Compatibility
451 @chapter Compatibility with the Java Platform
452
453 As we believe it is important that the Java platform not be fragmented,
454 @code{gcj} and @code{libgcj} try to conform to the relevant Java
455 specifications.  However, limited manpower and incomplete and unclear
456 documentation work against us.  So, there are caveats to using
457 @code{gcj}.
458
459 This list of compatibility issues is by no means complete.
460
461 @itemize @bullet
462 @item
463 @code{gcj} implements the JDK 1.1 language.  It supports inner classes,
464 though these are known to still be buggy.  It does not yet support the
465 Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores
466 it).
467
468 @item
469 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
470 However, @code{libgcj} is missing many packages, most notably
471 @code{java.awt}.  There are also individual missing classes and methods.
472 We currently do not have a list showing differences between
473 @code{libgcj} and the Java 2 platform.
474
475 @item
476 Sometimes the @code{libgcj} implementation of a method or class differs
477 from the JDK implementation.  This is not always a bug.  Still, if it
478 affects you, it probably makes sense to report it so that we can discuss
479 the appropriate response.
480 @end itemize
481
482
483 @node Invoking gcjh
484 @chapter Invoking gcjh
485
486 @c man title gcjh generate header files from Java class files
487
488 @c man begin DESCRIPTION gcjh
489
490 The @code{gcjh} program is used to generate header files from class
491 files.  It can generate both CNI and JNI header files, as well as stub
492 implementation files which can be used as a basis for implementing the
493 required native methods.
494
495 @c man end
496
497 @ignore
498 @c man begin SYNOPSIS gcjh
499 gcjh [@option{-stubs}] [@option{-jni}]
500     [@option{-add}@var{text}] [@option{-append}@var{text}] [@option{-friend}@var{text}] [@option{-preprend}@var{text}]
501     [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
502     [@option{-I}@var{dir}@dots{}] [@option{-d}@var{dir}@dots{}]
503     [@option{-o}@var{file}] [@option{-td}@var{dir}]
504     [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
505     [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
506     @var{classname}@dots{}
507 @c man end
508 @c man begin SEEALSO gcjh
509 gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
510 and the Info entries for @file{gcj} and @file{gcc}.
511 @c man end
512 @end ignore
513
514 @c man begin OPTIONS gcjh
515
516 @table @gcctabopt
517 @item -stubs
518 This causes @code{gcjh} to generate stub files instead of header files.
519 By default the stub file will be named after the class, with a suffix of
520 @samp{.cc}.  In JNI mode, the default output file will have the suffix
521 @samp{.c}.
522
523 @item -jni
524 This tells @code{gcjh} to generate a JNI header or stub.  By default,
525 CNI headers are generated.
526
527 @item -add @var{text}
528 Inserts @var{text} into the class body.  This is ignored in JNI mode.
529
530 @item -append @var{text}
531 Inserts @var{text} into the header file after the class declaration.
532 This is ignored in JNI mode.
533
534 @item -friend @var{text}
535 Inserts @var{text} into the class as a @code{friend} declaration.
536 This is ignored in JNI mode.
537
538 @item -prepend @var{text}
539 Inserts @var{text} into the header file before the class declaration.
540 This is ignored in JNI mode.
541
542 @item --classpath=@var{path}
543 @itemx --CLASSPATH=@var{path}
544 @itemx -I@var{directory}
545 @itemx -d @var{directory}
546 @itemx -o @var{file}
547 These options are all identical to the corresponding @code{gcj} options.
548
549 @item -o @var{file}
550 Sets the output file name.  This cannot be used if there is more than
551 one class on the command line.
552
553 @item -td @var{directory}
554 Sets the name of the directory to use for temporary files.
555
556 @item -M
557 Print all dependencies to stdout; suppress ordinary output.
558
559 @item -MM
560 Print non-system dependencies to stdout; suppress ordinary output.
561
562 @item -MD
563 Print all dependencies to stdout.
564
565 @item -MMD
566 Print non-system dependencies to stdout.
567
568 @item --help
569 Print help about @code{gcjh} and exit.  No further processing is done.
570
571 @item --version
572 Print version information for @code{gcjh} and exit.  No further
573 processing is done.
574
575 @item -v, --verbose
576 Print extra information while running.
577 @end table
578
579 All remaining options are considered to be names of classes.
580
581 @c man end
582
583 @node Invoking jv-scan
584 @chapter Invoking jv-scan
585
586 @c man title jv-scan print information about Java source file
587
588 @c man begin DESCRIPTION jv-scan
589
590 The @code{jv-scan} program can be used to print information about a Java
591 source file (@file{.java} file).
592
593 @c man end
594
595 @ignore
596 @c man begin SYNOPSIS jv-scan
597 jv-scan [@option{--complexity}] [@option{--encoding}@var{name}]
598     [@option{--print-main}] [@option{--list-class}] [@option{--list-filename}]
599     [@option{--version}] [@option{--help}]
600     [@option{-o}@var{file}] @var{inputfile}@dots{}
601 @c man end
602 @c man begin SEEALSO jv-scan
603 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
604 and the Info entries for @file{gcj} and @file{gcc}.
605 @c man end
606 @end ignore
607
608 @c man begin OPTIONS jv-scan
609
610 @table @gcctabopt
611 @item --complexity
612 This prints a complexity measure, related to cyclomatic complexity, for
613 each input file.
614
615 @item --encoding=@var{name}
616 This works like the corresponding @code{gcj} option.
617
618 @item --print-main
619 This prints the name of the class in this file containing a @code{main}
620 method.
621
622 @item --list-class
623 This lists the names of all classes defined in the input files.
624
625 @item --list-filename
626 If @code{--list-class} is given, this option causes @code{jv-scan} to
627 also print the name of the file in which each class was found.
628
629 @item -o @var{file}
630 Print output to the named file.
631
632 @item --help
633 Print help, then exit.
634
635 @item --version
636 Print version number, then exit.
637 @end table
638
639 @c man end
640
641 @node Invoking jcf-dump
642 @chapter Invoking jcf-dump
643
644 @c man title jcf-dump print information about Java class files
645
646 @ignore
647 @c man begin SYNOPSIS jcf-dump
648 jcf-dump [@option{-c}] [@option{--javap}]
649     [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
650     [@option{-I}@var{dir}@dots{}] [@option{-o}@var{file}]
651     [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
652     @var{classname}@dots{}
653 @c man end
654 @c man begin SEEALSO jcf-dump
655 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
656 and the Info entries for @file{gcj} and @file{gcc}.
657 @c man end
658 @end ignore
659
660 @c man begin DESCRIPTION jcf-dump
661
662 This is a class file examiner, similar to @code{javap}.  It will print
663 information about a number of classes, which are specifed by class name
664 or file name.
665
666 @c man end
667
668 @c man begin OPTIONS jcf-dump
669
670 @table @gcctabopt
671 @item -c
672 Disassemble method bodies.  By default method bodies are not printed.
673
674 @item --javap
675 Generate output in @code{javap} format.  The implementation of this
676 feature is very incomplete.
677
678 @item --classpath=@var{path}
679 @itemx --CLASSPATH=@var{path}
680 @itemx -I@var{directory}
681 @itemx -o @var{file}
682 These options as the same as the corresponding @code{gcj} options.
683
684 @item --help
685 Print help, then exit.
686
687 @item --version
688 Print version number, then exit.
689
690 @item -v, --verbose
691 Print extra information while running.
692 @end table
693
694 @c man end
695
696 @node Invoking gij
697 @chapter Invoking gij
698
699 @c man title gij GNU interpreter for Java bytecode
700
701 @ignore
702 @c man begin SYNOPSIS gij
703 gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
704
705 gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
706
707   [@option{-D}@var{name}[=@var{value}]@dots{}]
708   [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
709   [@option{--version}] [@option{--help}]
710 @c man end
711 @c man begin SEEALSO gij
712 gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
713 and the Info entries for @file{gcj} and @file{gcc}.
714 @c man end
715 @end ignore
716
717 @c man begin DESCRIPTION gij
718
719 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
720 @code{gij} is not available on every platform; porting it requires a
721 small amount of assembly programming which has not been done for all the
722 targets supported by @code{gcj}.
723
724 The primary argument to @code{gij} is the name of a class or, with
725 @code{-jar}, a jar file.  Options before this argument are interpreted
726 by @code{gij}; remaining options are passed to the interpreted program.
727
728 If a class name is specified and this class does not have a @code{main}
729 method with the appropriate signature (a @code{static void} method with
730 a @code{String[]} as its sole argument), then @code{gij} will print an
731 error and exit.
732
733 If a jar file is specified then @code{gij} will use information in it to
734 determine which class' @code{main} method will be invoked.
735
736 @code{gij} will invoke the @code{main} method with all the remaining
737 command-line options.
738
739 Note that @code{gij} is not limited to interpreting code.  Because
740 @code{libgcj} includes a class loader which can dynamically load shared
741 objects, it is possible to give @code{gij} the name of a class which has
742 been compiled and put into a shared library on the class path.
743
744 @c man end
745
746 @c man begin OPTIONS gij
747
748 @table @gcctabopt
749 @item -D@var{name}[=@var{value}]
750 This defines a system property named @var{name} with value @var{value}.
751 If @var{value} is not specified then it defaults to the empty string.
752 These system properties are initialized at the program's startup and can
753 be retrieved at runtime using the @code{java.lang.System.getProperty}
754 method.
755
756 @item -ms=@var{number}
757 This sets the initial heap size.
758
759 @item -mx=@var{number}
760 This sets the maximum heap size.
761
762 @item -jar
763 This indicates that the name passed to @code{gij} should be interpreted
764 as the name of a jar file, not a class.
765
766 @item --help
767 Print help, then exit.
768
769 @item --version
770 Print version number, then exit.
771 @end table
772
773 @c man end
774
775 @node Invoking jv-convert
776 @chapter Invoking jv-convert
777
778 @c man title jv-convert Convert file from one encoding to another
779
780 @c man begin synopsis jv-convert
781 @command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
782 @ignore
783
784   [@option{--encoding} @var{name}]
785   [@option{--from} @var{name}]
786   [@option{--to} @var{name}]
787   [@option{-i} @var{file}] [@option{-o} @var{file}]
788   [@option{--reverse}] [@option{--help}] [@option{--version}]
789 @end ignore
790 @c man end
791
792 @c man begin DESCRIPTION jv-convert
793
794 @command{jv-convert} is a utility included with @code{libgcj} which
795 converts a file from one encoding to another.  It is similar to the Unix
796 @command{iconv} utility.
797
798 The encodings supported by @command{jv-convert} are platform-dependent.
799 Currently there is no way to get a list of all supported encodings.
800
801 @c man end
802
803 @c man begin OPTIONS jv-convert
804
805 @table @gcctabopt
806 @item --encoding @var{name}
807 @itemx --from @var{name}
808 Use @var{name} as the input encoding.  The default is the current
809 locale's encoding.
810
811 @item --to @var{name}
812 Use @var{name} as the output encoding.  The default is the
813 @code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
814 non-ASCII characters.
815
816 @item -i @var{file}
817 Read from @var{file}.  The default is to read from standard input.
818
819 @item -o @var{file}
820 Write to @var{file}.  The default is to write to standard output.
821
822 @item --reverse
823 Swap the input and output encodings.
824
825 @item --help
826 Print a help message, then exit.
827
828 @item --version
829 Print version information, then exit.
830 @end table
831
832 @c man end
833
834 @node Resources
835 @chapter Resources
836
837 While writing @code{gcj} and @code{libgcj} we have, of course, relied
838 heavily on documentation from Sun Microsystems.  In particular we have
839 used The Java Language Specification (both first and second editions),
840 the Java Class Libraries (volumes one and two), and the Java Virtual
841 Machine Specification.  In addition we've used the online documentation
842 at @uref{http://java.sun.com/}.
843
844 The current @code{gcj} home page is
845 @uref{http://gcc.gnu.org/java/}.
846
847 For more information on gcc, see @uref{http://gcc.gnu.org/}.
848
849 Some @code{libgcj} testing is done using the Mauve test suite.  This is
850 a free software Java class library test suite which is being written
851 because the JCK is not free.  See
852 @uref{http://sources.redhat.com/mauve/} for more information.
853
854 @bye