Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/gcj.1 @ 0:a06113de4d67

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
first commit
author kent <kent@cr.ie.u-ryukyu.ac.jp>
date Fri, 17 Jul 2009 14:47:48 +0900
parents
children 58ad6c70ea60
comparison
equal deleted inserted replaced
-1:000000000000 0:a06113de4d67
1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.07)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 . ds -- \(*W-
36 . ds PI pi
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39 . ds L" ""
40 . ds R" ""
41 . ds C` ""
42 . ds C' ""
43 'br\}
44 .el\{\
45 . ds -- \|\(em\|
46 . ds PI \(*p
47 . ds L" ``
48 . ds R" ''
49 'br\}
50 .\"
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
52 .ie \n(.g .ds Aq \(aq
53 .el .ds Aq '
54 .\"
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD. Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
59 .ie \nF \{\
60 . de IX
61 . tm Index:\\$1\t\\n%\t"\\$2"
62 ..
63 . nr % 0
64 . rr F
65 .\}
66 .el \{\
67 . de IX
68 ..
69 .\}
70 .\"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear. Run. Save yourself. No user-serviceable parts.
73 . \" fudge factors for nroff and troff
74 .if n \{\
75 . ds #H 0
76 . ds #V .8m
77 . ds #F .3m
78 . ds #[ \f1
79 . ds #] \fP
80 .\}
81 .if t \{\
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83 . ds #V .6m
84 . ds #F 0
85 . ds #[ \&
86 . ds #] \&
87 .\}
88 . \" simple accents for nroff and troff
89 .if n \{\
90 . ds ' \&
91 . ds ` \&
92 . ds ^ \&
93 . ds , \&
94 . ds ~ ~
95 . ds /
96 .\}
97 .if t \{\
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
104 .\}
105 . \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 . \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 . \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
120 \{\
121 . ds : e
122 . ds 8 ss
123 . ds o a
124 . ds d- d\h'-1'\(ga
125 . ds D- D\h'-1'\(hy
126 . ds th \o'bp'
127 . ds Th \o'LP'
128 . ds ae ae
129 . ds Ae AE
130 .\}
131 .rm #[ #] #H #V #F C
132 .\" ========================================================================
133 .\"
134 .IX Title "GCJ 1"
135 .TH GCJ 1 "2009-04-21" "gcc-4.4.0" "GNU"
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
138 .if n .ad l
139 .nh
140 .SH "NAME"
141 gcj \- Ahead\-of\-time compiler for the Java language
142 .SH "SYNOPSIS"
143 .IX Header "SYNOPSIS"
144 gcj [\fB\-I\fR\fIdir\fR...] [\fB\-d\fR \fIdir\fR...]
145 [\fB\-\-CLASSPATH\fR=\fIpath\fR] [\fB\-\-classpath\fR=\fIpath\fR]
146 [\fB\-f\fR\fIoption\fR...] [\fB\-\-encoding\fR=\fIname\fR]
147 [\fB\-\-main\fR=\fIclassname\fR] [\fB\-D\fR\fIname\fR[=\fIvalue\fR]...]
148 [\fB\-C\fR] [\fB\-\-resource\fR \fIresource-name\fR] [\fB\-d\fR \fIdirectory\fR]
149 [\fB\-W\fR\fIwarn\fR...]
150 \fIsourcefile\fR...
151 .SH "DESCRIPTION"
152 .IX Header "DESCRIPTION"
153 As \fBgcj\fR is just another front end to \fBgcc\fR, it supports many
154 of the same options as gcc. This manual only documents the
155 options specific to \fBgcj\fR.
156 .SH "OPTIONS"
157 .IX Header "OPTIONS"
158 .Sh "Input and output files"
159 .IX Subsection "Input and output files"
160 A \fBgcj\fR command is like a \fBgcc\fR command, in that it
161 consists of a number of options and file names. The following kinds
162 of input file names are supported:
163 .IP "\fIfile\fR\fB.java\fR" 4
164 .IX Item "file.java"
165 Java source files.
166 .IP "\fIfile\fR\fB.class\fR" 4
167 .IX Item "file.class"
168 Java bytecode files.
169 .IP "\fIfile\fR\fB.zip\fR" 4
170 .IX Item "file.zip"
171 .PD 0
172 .IP "\fIfile\fR\fB.jar\fR" 4
173 .IX Item "file.jar"
174 .PD
175 An archive containing one or more \f(CW\*(C`.class\*(C'\fR files, all of
176 which are compiled. The archive may be compressed. Files in
177 an archive which don't end with \fB.class\fR are treated as
178 resource files; they are compiled into the resulting object file
179 as \fBcore:\fR URLs.
180 .IP "\fB@\fR\fIfile\fR" 4
181 .IX Item "@file"
182 A file containing a whitespace-separated list of input file names.
183 (Currently, these must all be \f(CW\*(C`.java\*(C'\fR source files, but that
184 may change.)
185 Each named file is compiled, just as if it had been on the command line.
186 .IP "\fIlibrary\fR\fB.a\fR" 4
187 .IX Item "library.a"
188 .PD 0
189 .IP "\fIlibrary\fR\fB.so\fR" 4
190 .IX Item "library.so"
191 .IP "\fB\-l\fR\fIlibname\fR" 4
192 .IX Item "-llibname"
193 .PD
194 Libraries to use when linking. See the \fBgcc\fR manual.
195 .PP
196 You can specify more than one input file on the \fBgcj\fR command line,
197 in which case they will all be compiled. If you specify a
198 \&\f(CW\*(C`\-o \f(CIFILENAME\f(CW\*(C'\fR
199 option, all the input files will be compiled together, producing a
200 single output file, named \fI\s-1FILENAME\s0\fR.
201 This is allowed even when using \f(CW\*(C`\-S\*(C'\fR or \f(CW\*(C`\-c\*(C'\fR,
202 but not when using \f(CW\*(C`\-C\*(C'\fR or \f(CW\*(C`\-\-resource\*(C'\fR.
203 (This is an extension beyond the what plain \fBgcc\fR allows.)
204 (If more than one input file is specified, all must currently
205 be \f(CW\*(C`.java\*(C'\fR files, though we hope to fix this.)
206 .Sh "Input Options"
207 .IX Subsection "Input Options"
208 \&\fBgcj\fR has options to control where it looks to find files it needs.
209 For instance, \fBgcj\fR might need to load a class that is referenced
210 by the file it has been asked to compile. Like other compilers for the
211 Java language, \fBgcj\fR has a notion of a \fIclass path\fR. There are
212 several options and environment variables which can be used to
213 manipulate the class path. When \fBgcj\fR looks for a given class, it
214 searches the class path looking for matching \fI.class\fR or
215 \&\fI.java\fR file. \fBgcj\fR comes with a built-in class path which
216 points at the installed \fIlibgcj.jar\fR, a file which contains all the
217 standard classes.
218 .PP
219 In the text below, a directory or path component can refer either to an
220 actual directory on the filesystem, or to a \fI.zip\fR or \fI.jar\fR
221 file, which \fBgcj\fR will search as if it is a directory.
222 .IP "\fB\-I\fR\fIdir\fR" 4
223 .IX Item "-Idir"
224 All directories specified by \f(CW\*(C`\-I\*(C'\fR are kept in order and prepended
225 to the class path constructed from all the other options. Unless
226 compatibility with tools like \f(CW\*(C`javac\*(C'\fR is important, we recommend
227 always using \f(CW\*(C`\-I\*(C'\fR instead of the other options for manipulating the
228 class path.
229 .IP "\fB\-\-classpath=\fR\fIpath\fR" 4
230 .IX Item "--classpath=path"
231 This sets the class path to \fIpath\fR, a colon-separated list of paths
232 (on Windows-based systems, a semicolon-separate list of paths).
233 This does not override the builtin (\*(L"boot\*(R") search path.
234 .IP "\fB\-\-CLASSPATH=\fR\fIpath\fR" 4
235 .IX Item "--CLASSPATH=path"
236 Deprecated synonym for \f(CW\*(C`\-\-classpath\*(C'\fR.
237 .IP "\fB\-\-bootclasspath=\fR\fIpath\fR" 4
238 .IX Item "--bootclasspath=path"
239 Where to find the standard builtin classes, such as \f(CW\*(C`java.lang.String\*(C'\fR.
240 .IP "\fB\-\-extdirs=\fR\fIpath\fR" 4
241 .IX Item "--extdirs=path"
242 For each directory in the \fIpath\fR, place the contents of that
243 directory at the end of the class path.
244 .IP "\fB\s-1CLASSPATH\s0\fR" 4
245 .IX Item "CLASSPATH"
246 This is an environment variable which holds a list of paths.
247 .PP
248 The final class path is constructed like so:
249 .IP "\(bu" 4
250 First come all directories specified via \f(CW\*(C`\-I\*(C'\fR.
251 .IP "\(bu" 4
252 If \fB\-\-classpath\fR is specified, its value is appended.
253 Otherwise, if the \f(CW\*(C`CLASSPATH\*(C'\fR environment variable is specified,
254 then its value is appended.
255 Otherwise, the current directory (\f(CW"."\fR) is appended.
256 .IP "\(bu" 4
257 If \f(CW\*(C`\-\-bootclasspath\*(C'\fR was specified, append its value.
258 Otherwise, append the built-in system directory, \fIlibgcj.jar\fR.
259 .IP "\(bu" 4
260 Finally, if \f(CW\*(C`\-\-extdirs\*(C'\fR was specified, append the contents of the
261 specified directories at the end of the class path. Otherwise, append
262 the contents of the built-in extdirs at \f(CW\*(C`$(prefix)/share/java/ext\*(C'\fR.
263 .PP
264 The classfile built by \fBgcj\fR for the class \f(CW\*(C`java.lang.Object\*(C'\fR
265 (and placed in \f(CW\*(C`libgcj.jar\*(C'\fR) contains a special zero length
266 attribute \f(CW\*(C`gnu.gcj.gcj\-compiled\*(C'\fR. The compiler looks for this
267 attribute when loading \f(CW\*(C`java.lang.Object\*(C'\fR and will report an error
268 if it isn't found, unless it compiles to bytecode (the option
269 \&\f(CW\*(C`\-fforce\-classes\-archive\-check\*(C'\fR can be used to override this
270 behavior in this particular case.)
271 .IP "\fB\-fforce\-classes\-archive\-check\fR" 4
272 .IX Item "-fforce-classes-archive-check"
273 This forces the compiler to always check for the special zero length
274 attribute \f(CW\*(C`gnu.gcj.gcj\-compiled\*(C'\fR in \f(CW\*(C`java.lang.Object\*(C'\fR and
275 issue an error if it isn't found.
276 .IP "\fB\-fsource=\fR\fI\s-1VERSION\s0\fR" 4
277 .IX Item "-fsource=VERSION"
278 This option is used to choose the source version accepted by
279 \&\fBgcj\fR. The default is \fB1.5\fR.
280 .Sh "Encodings"
281 .IX Subsection "Encodings"
282 The Java programming language uses Unicode throughout. In an effort to
283 integrate well with other locales, \fBgcj\fR allows \fI.java\fR files
284 to be written using almost any encoding. \fBgcj\fR knows how to
285 convert these encodings into its internal encoding at compile time.
286 .PP
287 You can use the \f(CW\*(C`\-\-encoding=\f(CINAME\f(CW\*(C'\fR option to specify an
288 encoding (of a particular character set) to use for source files. If
289 this is not specified, the default encoding comes from your current
290 locale. If your host system has insufficient locale support, then
291 \&\fBgcj\fR assumes the default encoding to be the \fB\s-1UTF\-8\s0\fR encoding
292 of Unicode.
293 .PP
294 To implement \f(CW\*(C`\-\-encoding\*(C'\fR, \fBgcj\fR simply uses the host
295 platform's \f(CW\*(C`iconv\*(C'\fR conversion routine. This means that in practice
296 \&\fBgcj\fR is limited by the capabilities of the host platform.
297 .PP
298 The names allowed for the argument \f(CW\*(C`\-\-encoding\*(C'\fR vary from platform
299 to platform (since they are not standardized anywhere). However,
300 \&\fBgcj\fR implements the encoding named \fB\s-1UTF\-8\s0\fR internally, so if
301 you choose to use this for your source files you can be assured that it
302 will work on every host.
303 .Sh "Warnings"
304 .IX Subsection "Warnings"
305 \&\fBgcj\fR implements several warnings. As with other generic
306 \&\fBgcc\fR warnings, if an option of the form \f(CW\*(C`\-Wfoo\*(C'\fR enables a
307 warning, then \f(CW\*(C`\-Wno\-foo\*(C'\fR will disable it. Here we've chosen to
308 document the form of the warning which will have an effect \*(-- the
309 default being the opposite of what is listed.
310 .IP "\fB\-Wredundant\-modifiers\fR" 4
311 .IX Item "-Wredundant-modifiers"
312 With this flag, \fBgcj\fR will warn about redundant modifiers. For
313 instance, it will warn if an interface method is declared \f(CW\*(C`public\*(C'\fR.
314 .IP "\fB\-Wextraneous\-semicolon\fR" 4
315 .IX Item "-Wextraneous-semicolon"
316 This causes \fBgcj\fR to warn about empty statements. Empty statements
317 have been deprecated.
318 .IP "\fB\-Wno\-out\-of\-date\fR" 4
319 .IX Item "-Wno-out-of-date"
320 This option will cause \fBgcj\fR not to warn when a source file is
321 newer than its matching class file. By default \fBgcj\fR will warn
322 about this.
323 .IP "\fB\-Wno\-deprecated\fR" 4
324 .IX Item "-Wno-deprecated"
325 Warn if a deprecated class, method, or field is referred to.
326 .IP "\fB\-Wunused\fR" 4
327 .IX Item "-Wunused"
328 This is the same as \fBgcc\fR's \f(CW\*(C`\-Wunused\*(C'\fR.
329 .IP "\fB\-Wall\fR" 4
330 .IX Item "-Wall"
331 This is the same as \f(CW\*(C`\-Wredundant\-modifiers \-Wextraneous\-semicolon
332 \&\-Wunused\*(C'\fR.
333 .Sh "Linking"
334 .IX Subsection "Linking"
335 To turn a Java application into an executable program,
336 you need to link it with the needed libraries, just as for C or \*(C+.
337 The linker by default looks for a global function named \f(CW\*(C`main\*(C'\fR.
338 Since Java does not have global functions, and a
339 collection of Java classes may have more than one class with a
340 \&\f(CW\*(C`main\*(C'\fR method, you need to let the linker know which of those
341 \&\f(CW\*(C`main\*(C'\fR methods it should invoke when starting the application.
342 You can do that in any of these ways:
343 .IP "\(bu" 4
344 Specify the class containing the desired \f(CW\*(C`main\*(C'\fR method
345 when you link the application, using the \f(CW\*(C`\-\-main\*(C'\fR flag,
346 described below.
347 .IP "\(bu" 4
348 Link the Java package(s) into a shared library (dll) rather than an
349 executable. Then invoke the application using the \f(CW\*(C`gij\*(C'\fR program,
350 making sure that \f(CW\*(C`gij\*(C'\fR can find the libraries it needs.
351 .IP "\(bu" 4
352 Link the Java packages(s) with the flag \f(CW\*(C`\-lgij\*(C'\fR, which links
353 in the \f(CW\*(C`main\*(C'\fR routine from the \f(CW\*(C`gij\*(C'\fR command.
354 This allows you to select the class whose \f(CW\*(C`main\*(C'\fR method you
355 want to run when you run the application. You can also use
356 other \f(CW\*(C`gij\*(C'\fR flags, such as \f(CW\*(C`\-D\*(C'\fR flags to set properties.
357 Using the \f(CW\*(C`\-lgij\*(C'\fR library (rather than the \f(CW\*(C`gij\*(C'\fR program
358 of the previous mechanism) has some advantages: it is compatible with
359 static linking, and does not require configuring or installing libraries.
360 .PP
361 These \f(CW\*(C`gij\*(C'\fR options relate to linking an executable:
362 .IP "\fB\-\-main=\fR\fI\s-1CLASSNAME\s0\fR" 4
363 .IX Item "--main=CLASSNAME"
364 This option is used when linking to specify the name of the class whose
365 \&\f(CW\*(C`main\*(C'\fR method should be invoked when the resulting executable is
366 run.
367 .IP "\fB\-D\fR\fIname\fR\fB[=\fR\fIvalue\fR\fB]\fR" 4
368 .IX Item "-Dname[=value]"
369 This option can only be used with \f(CW\*(C`\-\-main\*(C'\fR. It defines a system
370 property named \fIname\fR with value \fIvalue\fR. If \fIvalue\fR 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 \f(CW\*(C`java.lang.System.getProperty\*(C'\fR method.
374 .IP "\fB\-lgij\fR" 4
375 .IX Item "-lgij"
376 Create an application whose command-line processing is that
377 of the \f(CW\*(C`gij\*(C'\fR command.
378 .Sp
379 This option is an alternative to using \f(CW\*(C`\-\-main\*(C'\fR; you cannot use both.
380 .IP "\fB\-static\-libgcj\fR" 4
381 .IX Item "-static-libgcj"
382 This option causes linking to be done against a static version of the
383 libgcj runtime library. This option is only available if
384 corresponding linker support exists.
385 .Sp
386 \&\fBCaution:\fR Static linking of libgcj may cause essential parts
387 of libgcj to be omitted. Some parts of libgcj use reflection to load
388 classes at runtime. Since the linker does not see these references at
389 link time, it can omit the referred to classes. The result is usually
390 (but not always) a \f(CW\*(C`ClassNotFoundException\*(C'\fR being thrown at
391 runtime. Caution must be used when using this option. For more
392 details see:
393 <\fBhttp://gcc.gnu.org/wiki/Statically%20linking%20libgcj\fR>
394 .Sh "Code Generation"
395 .IX Subsection "Code Generation"
396 In addition to the many \fBgcc\fR options controlling code generation,
397 \&\fBgcj\fR has several options specific to itself.
398 .IP "\fB\-C\fR" 4
399 .IX Item "-C"
400 This option is used to tell \fBgcj\fR to generate bytecode
401 (\fI.class\fR files) rather than object code.
402 .IP "\fB\-\-resource\fR \fIresource-name\fR" 4
403 .IX Item "--resource resource-name"
404 This option is used to tell \fBgcj\fR to compile the contents of a
405 given file to object code so it may be accessed at runtime with the core
406 protocol handler as \fBcore:/\fR\fIresource-name\fR. Note that
407 \&\fIresource-name\fR is the name of the resource as found at runtime; for
408 instance, it could be used in a call to \f(CW\*(C`ResourceBundle.getBundle\*(C'\fR.
409 The actual file name to be compiled this way must be specified
410 separately.
411 .IP "\fB\-ftarget=\fR\fI\s-1VERSION\s0\fR" 4
412 .IX Item "-ftarget=VERSION"
413 This can be used with \fB\-C\fR to choose the version of bytecode
414 emitted by \fBgcj\fR. The default is \fB1.5\fR. When not
415 generating bytecode, this option has no effect.
416 .IP "\fB\-d\fR \fIdirectory\fR" 4
417 .IX Item "-d directory"
418 When used with \f(CW\*(C`\-C\*(C'\fR, this causes all generated \fI.class\fR files
419 to be put in the appropriate subdirectory of \fIdirectory\fR. By
420 default they will be put in subdirectories of the current working
421 directory.
422 .IP "\fB\-fno\-bounds\-check\fR" 4
423 .IX Item "-fno-bounds-check"
424 By default, \fBgcj\fR generates code which checks the bounds of all
425 array indexing operations. With this option, these checks are omitted, which
426 can improve performance for code that uses arrays extensively. Note that this
427 can result in unpredictable behavior if the code in question actually does
428 violate array bounds constraints. It is safe to use this option if you are
429 sure that your code will never throw an \f(CW\*(C`ArrayIndexOutOfBoundsException\*(C'\fR.
430 .IP "\fB\-fno\-store\-check\fR" 4
431 .IX Item "-fno-store-check"
432 Don't generate array store checks. When storing objects into arrays, a runtime
433 check is normally generated in order to ensure that the object is assignment
434 compatible with the component type of the array (which may not be known
435 at compile-time). With this option, these checks are omitted. This can
436 improve performance for code which stores objects into arrays frequently.
437 It is safe to use this option if you are sure your code will never throw an
438 \&\f(CW\*(C`ArrayStoreException\*(C'\fR.
439 .IP "\fB\-fjni\fR" 4
440 .IX Item "-fjni"
441 With \fBgcj\fR there are two options for writing native methods: \s-1CNI\s0
442 and \s-1JNI\s0. By default \fBgcj\fR assumes you are using \s-1CNI\s0. If you are
443 compiling a class with native methods, and these methods are implemented
444 using \s-1JNI\s0, then you must use \f(CW\*(C`\-fjni\*(C'\fR. This option causes
445 \&\fBgcj\fR to generate stubs which will invoke the underlying \s-1JNI\s0
446 methods.
447 .IP "\fB\-fno\-assert\fR" 4
448 .IX Item "-fno-assert"
449 Don't recognize the \f(CW\*(C`assert\*(C'\fR keyword. This is for compatibility
450 with older versions of the language specification.
451 .IP "\fB\-fno\-optimize\-static\-class\-initialization\fR" 4
452 .IX Item "-fno-optimize-static-class-initialization"
453 When the optimization level is greater or equal to \f(CW\*(C`\-O2\*(C'\fR,
454 \&\fBgcj\fR will try to optimize the way calls into the runtime are made
455 to initialize static classes upon their first use (this optimization
456 isn't carried out if \f(CW\*(C`\-C\*(C'\fR was specified.) When compiling to native
457 code, \f(CW\*(C`\-fno\-optimize\-static\-class\-initialization\*(C'\fR will turn this
458 optimization off, regardless of the optimization level in use.
459 .IP "\fB\-\-disable\-assertions[=\fR\fIclass-or-package\fR\fB]\fR" 4
460 .IX Item "--disable-assertions[=class-or-package]"
461 Don't include code for checking assertions in the compiled code.
462 If \f(CW\*(C`=\f(CIclass\-or\-package\f(CW\*(C'\fR is missing disables assertion code
463 generation for all classes, unless overridden by a more
464 specific \f(CW\*(C`\-\-enable\-assertions\*(C'\fR flag.
465 If \fIclass-or-package\fR is a class name, only disables generating
466 assertion checks within the named class or its inner classes.
467 If \fIclass-or-package\fR is a package name, disables generating
468 assertion checks within the named package or a subpackage.
469 .Sp
470 By default, assertions are enabled when generating class files
471 or when not optimizing, and disabled when generating optimized binaries.
472 .IP "\fB\-\-enable\-assertions[=\fR\fIclass-or-package\fR\fB]\fR" 4
473 .IX Item "--enable-assertions[=class-or-package]"
474 Generates code to check assertions. The option is perhaps misnamed,
475 as you still need to turn on assertion checking at run-time,
476 and we don't support any easy way to do that.
477 So this flag isn't very useful yet, except to partially override
478 \&\f(CW\*(C`\-\-disable\-assertions\*(C'\fR.
479 .IP "\fB\-findirect\-dispatch\fR" 4
480 .IX Item "-findirect-dispatch"
481 \&\fBgcj\fR has a special binary compatibility \s-1ABI\s0, which is enabled
482 by the \f(CW\*(C`\-findirect\-dispatch\*(C'\fR option. In this mode, the code
483 generated by \fBgcj\fR honors the binary compatibility guarantees
484 in the Java Language Specification, and the resulting object files do
485 not need to be directly linked against their dependencies. Instead,
486 all dependencies are looked up at runtime. This allows free mixing of
487 interpreted and compiled code.
488 .Sp
489 Note that, at present, \f(CW\*(C`\-findirect\-dispatch\*(C'\fR can only be used
490 when compiling \fI.class\fR files. It will not work when compiling
491 from source. \s-1CNI\s0 also does not yet work with the binary compatibility
492 \&\s-1ABI\s0. These restrictions will be lifted in some future release.
493 .Sp
494 However, if you compile \s-1CNI\s0 code with the standard \s-1ABI\s0, you can call
495 it from code built with the binary compatibility \s-1ABI\s0.
496 .IP "\fB\-fbootstrap\-classes\fR" 4
497 .IX Item "-fbootstrap-classes"
498 This option can be use to tell \f(CW\*(C`libgcj\*(C'\fR that the compiled classes
499 should be loaded by the bootstrap loader, not the system class loader.
500 By default, if you compile a class and link it into an executable, it
501 will be treated as if it was loaded using the system class loader.
502 This is convenient, as it means that things like
503 \&\f(CW\*(C`Class.forName()\*(C'\fR will search \fB\s-1CLASSPATH\s0\fR to find the
504 desired class.
505 .IP "\fB\-freduced\-reflection\fR" 4
506 .IX Item "-freduced-reflection"
507 This option causes the code generated by \fBgcj\fR to contain a
508 reduced amount of the class meta-data used to support runtime
509 reflection. The cost of this savings is the loss of
510 the ability to use certain reflection capabilities of the standard
511 Java runtime environment. When set all meta-data except for that
512 which is needed to obtain correct runtime semantics is eliminated.
513 .Sp
514 For code that does not use reflection (i.e. serialization, \s-1RMI\s0, \s-1CORBA\s0
515 or call methods in the \f(CW\*(C`java.lang.reflect\*(C'\fR package),
516 \&\f(CW\*(C`\-freduced\-reflection\*(C'\fR will result in proper operation with a
517 savings in executable code size.
518 .Sp
519 \&\s-1JNI\s0 (\f(CW\*(C`\-fjni\*(C'\fR) and the binary compatibility \s-1ABI\s0
520 (\f(CW\*(C`\-findirect\-dispatch\*(C'\fR) do not work properly without full
521 reflection meta-data. Because of this, it is an error to use these options
522 with \f(CW\*(C`\-freduced\-reflection\*(C'\fR.
523 .Sp
524 \&\fBCaution:\fR If there is no reflection meta-data, code that uses
525 a \f(CW\*(C`SecurityManager\*(C'\fR may not work properly. Also calling
526 \&\f(CW\*(C`Class.forName()\*(C'\fR may fail if the calling method has no
527 reflection meta-data.
528 .Sh "Configure-time Options"
529 .IX Subsection "Configure-time Options"
530 Some \fBgcj\fR code generations options affect the resulting \s-1ABI\s0, and
531 so can only be meaningfully given when \f(CW\*(C`libgcj\*(C'\fR, the runtime
532 package, is configured. \f(CW\*(C`libgcj\*(C'\fR puts the appropriate options from
533 this group into a \fBspec\fR file which is read by \fBgcj\fR. These
534 options are listed here for completeness; if you are using \f(CW\*(C`libgcj\*(C'\fR
535 then you won't want to touch these options.
536 .IP "\fB\-fuse\-boehm\-gc\fR" 4
537 .IX Item "-fuse-boehm-gc"
538 This enables the use of the Boehm \s-1GC\s0 bitmap marking code. In particular
539 this causes \fBgcj\fR to put an object marking descriptor into each
540 vtable.
541 .IP "\fB\-fhash\-synchronization\fR" 4
542 .IX Item "-fhash-synchronization"
543 By default, synchronization data (the data used for \f(CW\*(C`synchronize\*(C'\fR,
544 \&\f(CW\*(C`wait\*(C'\fR, and \f(CW\*(C`notify\*(C'\fR) is pointed to by a word in each object.
545 With this option \fBgcj\fR assumes that this information is stored in a
546 hash table and not in the object itself.
547 .IP "\fB\-fuse\-divide\-subroutine\fR" 4
548 .IX Item "-fuse-divide-subroutine"
549 On some systems, a library routine is called to perform integer
550 division. This is required to get exception handling correct when
551 dividing by zero.
552 .IP "\fB\-fcheck\-references\fR" 4
553 .IX Item "-fcheck-references"
554 On some systems it's necessary to insert inline checks whenever
555 accessing an object via a reference. On other systems you won't need
556 this because null pointer accesses are caught automatically by the
557 processor.
558 .SH "SEE ALSO"
559 .IX Header "SEE ALSO"
560 \&\fIgcc\fR\|(1), \fIgcjh\fR\|(1), \fIgjnih\fR\|(1), \fIgij\fR\|(1), \fIjcf\-dump\fR\|(1), \fIgfdl\fR\|(7),
561 and the Info entries for \fIgcj\fR and \fIgcc\fR.
562 .SH "COPYRIGHT"
563 .IX Header "COPYRIGHT"
564 Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
565 .PP
566 Permission is granted to copy, distribute and/or modify this document
567 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.2 or
568 any later version published by the Free Software Foundation; with no
569 Invariant Sections, the Front-Cover Texts being (a) (see below), and
570 with the Back-Cover Texts being (b) (see below).
571 A copy of the license is included in the
572 man page \fIgfdl\fR\|(7).
573 .PP
574 (a) The \s-1FSF\s0's Front-Cover Text is:
575 .PP
576 .Vb 1
577 \& A GNU Manual
578 .Ve
579 .PP
580 (b) The \s-1FSF\s0's Back-Cover Text is:
581 .PP
582 .Vb 3
583 \& You have freedom to copy and modify this GNU Manual, like GNU
584 \& software. Copies published by the Free Software Foundation raise
585 \& funds for GNU development.
586 .Ve