OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [gcc/] [java/] [gcj.texi] - Blame information for rev 294

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 287 jeremybenn
\input texinfo @c -*-texinfo-*-
2
@setfilename gcj.info
3
@settitle Guide to GNU gcj
4
 
5
@c Merge the standard indexes into a single one.
6
@syncodeindex fn cp
7
@syncodeindex vr cp
8
@syncodeindex ky cp
9
@syncodeindex pg cp
10
@syncodeindex tp cp
11
 
12
@include gcc-common.texi
13
 
14
@c Note: When reading this manual you'll find lots of strange
15
@c circumlocutions like ``compiler for the Java language''.
16
@c This is necessary due to Sun's restrictions on the use of
17
@c the word ``Java'.
18
 
19
@c When this manual is copyrighted.
20
@set copyrights-gcj 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
21
 
22
@copying
23
@c man begin COPYRIGHT
24
Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
25
 
26
Permission is granted to copy, distribute and/or modify this document
27
under the terms of the GNU Free Documentation License, Version 1.2 or
28
any later version published by the Free Software Foundation; with no
29
Invariant Sections, the Front-Cover Texts being (a) (see below), and
30
with the Back-Cover Texts being (b) (see below).
31
A copy of the license is included in the
32
@c man end
33
section entitled ``GNU Free Documentation License''.
34
@ignore
35
@c man begin COPYRIGHT
36
man page gfdl(7).
37
@c man end
38
@end ignore
39
 
40
@c man begin COPYRIGHT
41
 
42
(a) The FSF's Front-Cover Text is:
43
 
44
     A GNU Manual
45
 
46
(b) The FSF's Back-Cover Text is:
47
 
48
     You have freedom to copy and modify this GNU Manual, like GNU
49
     software.  Copies published by the Free Software Foundation raise
50
     funds for GNU development.
51
@c man end
52
@end copying
53
 
54
@ifinfo
55
@format
56
@dircategory Software development
57
@direntry
58
* Gcj: (gcj).               Ahead-of-time compiler for the Java language
59
@end direntry
60
 
61
@dircategory Individual utilities
62
@direntry
63
* jcf-dump: (gcj)Invoking jcf-dump.
64
                            Print information about Java class files
65
* gij: (gcj)Invoking gij.   GNU interpreter for Java bytecode
66
* gcj-dbtool: (gcj)Invoking gcj-dbtool.
67
                            Tool for manipulating class file databases.
68
* jv-convert: (gcj)Invoking jv-convert.
69
                            Convert file from one encoding to another
70
* grmic: (gcj)Invoking grmic.
71
                            Generate stubs for Remote Method Invocation.
72
* gc-analyze: (gcj)Invoking gc-analyze.
73
                            Analyze Garbage Collector (GC) memory dumps.
74
* aot-compile: (gcj)Invoking aot-compile.
75
                            Compile bytecode to native and generate databases.
76
* rebuild-gcj-db: (gcj)Invoking rebuild-gcj-db.
77
                            Merge the per-solib databases made by aot-compile
78
                            into one system-wide database.
79
@end direntry
80
@end format
81
 
82
@insertcopying
83
@end ifinfo
84
 
85
@titlepage
86
@title GNU gcj
87
@versionsubtitle
88
@author Tom Tromey
89
 
90
@page
91
@vskip 0pt plus 1filll
92
Published by the Free Software Foundation @*
93
51 Franklin Street, Fifth Floor@*
94
Boston, MA 02110-1301, USA@*
95
@sp 1
96
@insertcopying
97
@end titlepage
98
@contents
99
@page
100
 
101
 
102
@node Top
103
@top Introduction
104
 
105
This manual describes how to use @command{gcj}, the GNU compiler for the
106
Java programming language.  @command{gcj} can generate both @file{.class}
107
files and object files, and it can read both Java source code and
108
@file{.class} files.
109
 
110
@menu
111
* Copying::             The GNU General Public License
112
* GNU Free Documentation License::
113
                        How you can share and copy this manual
114
* Invoking gcj::        Compiler options supported by @command{gcj}
115
* Compatibility::       Compatibility between gcj and other tools for Java
116
* Invoking jcf-dump::   Print information about class files
117
* Invoking gij::        Interpreting Java bytecodes
118
* Invoking gcj-dbtool:: Tool for manipulating class file databases.
119
* Invoking jv-convert:: Converting from one encoding to another
120
* Invoking grmic::      Generate stubs for Remote Method Invocation.
121
* Invoking gc-analyze:: Analyze Garbage Collector (GC) memory dumps.
122
* Invoking aot-compile:: Compile bytecode to native and generate databases.
123
* Invoking rebuild-gcj-db:: Merge the per-solib databases made by aot-compile
124
                            into one system-wide database.
125
* About CNI::           Description of the Compiled Native Interface
126
* System properties::   Modifying runtime behavior of the libgcj library
127
* Resources::           Where to look for more information
128
* Index::               Index.
129
@end menu
130
 
131
 
132
@include gpl_v3.texi
133
 
134
@include fdl.texi
135
 
136
 
137
@node Invoking gcj
138
@chapter Invoking gcj
139
 
140
@c man title gcj Ahead-of-time compiler for the Java language
141
 
142
@ignore
143
@c man begin SYNOPSIS gcj
144
gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
145
    [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
146
    [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
147
    [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
148
    [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
149
    [@option{-W}@var{warn}@dots{}]
150
    @var{sourcefile}@dots{}
151
@c man end
152
@c man begin SEEALSO gcj
153
gcc(1), gcjh(1), gjnih(1), gij(1), jcf-dump(1), gfdl(7),
154
and the Info entries for @file{gcj} and @file{gcc}.
155
@c man end
156
@end ignore
157
 
158
@c man begin DESCRIPTION gcj
159
 
160
As @command{gcj} is just another front end to @command{gcc}, it supports many
161
of the same options as gcc.  @xref{Option Summary, , Option Summary,
162
gcc, Using the GNU Compiler Collection (GCC)}.  This manual only documents the
163
options specific to @command{gcj}.
164
 
165
@c man end
166
 
167
@menu
168
* Input and output files::
169
* Input Options::               How gcj finds files
170
* Encodings::                   Options controlling source file encoding
171
* Warnings::                    Options controlling warnings specific to gcj
172
* Linking::                     Options for making an executable
173
* Code Generation::             Options controlling the output of gcj
174
* Configure-time Options::      Options you won't use
175
@end menu
176
 
177
@c man begin OPTIONS gcj
178
 
179
@node Input and output files
180
@section Input and output files
181
 
182
A @command{gcj} command is like a @command{gcc} command, in that it
183
consists of a number of options and file names.  The following kinds
184
of input file names are supported:
185
 
186
@table @gcctabopt
187
@item @var{file}.java
188
Java source files.
189
@item @var{file}.class
190
Java bytecode files.
191
@item @var{file}.zip
192
@itemx @var{file}.jar
193
An archive containing one or more @code{.class} files, all of
194
which are compiled.  The archive may be compressed.  Files in
195
an archive which don't end with @samp{.class} are treated as
196
resource files; they are compiled into the resulting object file
197
as @samp{core:} URLs.
198
@item @@@var{file}
199
A file containing a whitespace-separated list of input file names.
200
(Currently, these must all be @code{.java} source files, but that
201
may change.)
202
Each named file is compiled, just as if it had been on the command line.
203
@item @var{library}.a
204
@itemx @var{library}.so
205
@itemx -l@var{libname}
206
Libraries to use when linking.  See the @command{gcc} manual.
207
@end table
208
 
209
You can specify more than one input file on the @command{gcj} command line,
210
in which case they will all be compiled.  If you specify a
211
@code{-o @var{FILENAME}}
212
option, all the input files will be compiled together, producing a
213
single output file, named @var{FILENAME}.
214
This is allowed even when using @code{-S} or @code{-c},
215
but not when using @code{-C} or @code{--resource}.
216
(This is an extension beyond the what plain @command{gcc} allows.)
217
(If more than one input file is specified, all must currently
218
be @code{.java} files, though we hope to fix this.)
219
 
220
@node Input Options
221
@section Input Options
222
 
223
@cindex class path
224
 
225
@command{gcj} has options to control where it looks to find files it needs.
226
For instance, @command{gcj} might need to load a class that is referenced
227
by the file it has been asked to compile.  Like other compilers for the
228
Java language, @command{gcj} has a notion of a @dfn{class path}.  There are
229
several options and environment variables which can be used to
230
manipulate the class path.  When @command{gcj} looks for a given class, it
231
searches the class path looking for matching @file{.class} or
232
@file{.java} file.  @command{gcj} comes with a built-in class path which
233
points at the installed @file{libgcj.jar}, a file which contains all the
234
standard classes.
235
 
236
In the text below, a directory or path component can refer either to an
237
actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
238
file, which @command{gcj} will search as if it is a directory.
239
 
240
@table @gcctabopt
241
@item -I@var{dir}
242
All directories specified by @code{-I} are kept in order and prepended
243
to the class path constructed from all the other options.  Unless
244
compatibility with tools like @code{javac} is important, we recommend
245
always using @code{-I} instead of the other options for manipulating the
246
class path.
247
 
248
@item --classpath=@var{path}
249
This sets the class path to @var{path}, a colon-separated list of paths
250
(on Windows-based systems, a semicolon-separate list of paths).
251
This does not override the builtin (``boot'') search path.
252
 
253
@item --CLASSPATH=@var{path}
254
Deprecated synonym for @code{--classpath}.
255
 
256
@item --bootclasspath=@var{path}
257
Where to find the standard builtin classes, such as @code{java.lang.String}.
258
 
259
@item --extdirs=@var{path}
260
For each directory in the @var{path}, place the contents of that
261
directory at the end of the class path.
262
 
263
@item CLASSPATH
264
This is an environment variable which holds a list of paths.
265
@end table
266
 
267
The final class path is constructed like so:
268
 
269
@itemize @bullet
270
@item
271
First come all directories specified via @code{-I}.
272
 
273
@item
274
If @option{--classpath} is specified, its value is appended.
275
Otherwise, if the @code{CLASSPATH} environment variable is specified,
276
then its value is appended.
277
Otherwise, the current directory (@code{"."}) is appended.
278
 
279
@item
280
If @code{--bootclasspath} was specified, append its value.
281
Otherwise, append the built-in system directory, @file{libgcj.jar}.
282
 
283
@item
284
Finally, if @code{--extdirs} was specified, append the contents of the
285
specified directories at the end of the class path.  Otherwise, append
286
the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
287
@end itemize
288
 
289
The classfile built by @command{gcj} for the class @code{java.lang.Object}
290
(and placed in @code{libgcj.jar}) contains a special zero length
291
attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
292
attribute when loading @code{java.lang.Object} and will report an error
293
if it isn't found, unless it compiles to bytecode (the option
294
@code{-fforce-classes-archive-check} can be used to override this
295
behavior in this particular case.)
296
 
297
@table @gcctabopt
298
@item -fforce-classes-archive-check
299
This forces the compiler to always check for the special zero length
300
attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
301
issue an error if it isn't found.
302
 
303
@item -fsource=@var{VERSION}
304
This option is used to choose the source version accepted by
305
@command{gcj}.  The default is @samp{1.5}.
306
@end table
307
 
308
@node Encodings
309
@section Encodings
310
 
311
The Java programming language uses Unicode throughout.  In an effort to
312
integrate well with other locales, @command{gcj} allows @file{.java} files
313
to be written using almost any encoding.  @command{gcj} knows how to
314
convert these encodings into its internal encoding at compile time.
315
 
316
You can use the @code{--encoding=@var{NAME}} option to specify an
317
encoding (of a particular character set) to use for source files.  If
318
this is not specified, the default encoding comes from your current
319
locale.  If your host system has insufficient locale support, then
320
@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
321
of Unicode.
322
 
323
To implement @code{--encoding}, @command{gcj} simply uses the host
324
platform's @code{iconv} conversion routine.  This means that in practice
325
@command{gcj} is limited by the capabilities of the host platform.
326
 
327
The names allowed for the argument @code{--encoding} vary from platform
328
to platform (since they are not standardized anywhere).  However,
329
@command{gcj} implements the encoding named @samp{UTF-8} internally, so if
330
you choose to use this for your source files you can be assured that it
331
will work on every host.
332
 
333
 
334
@node Warnings
335
@section Warnings
336
 
337
@command{gcj} implements several warnings.  As with other generic
338
@command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
339
warning, then @code{-Wno-foo} will disable it.  Here we've chosen to
340
document the form of the warning which will have an effect -- the
341
default being the opposite of what is listed.
342
 
343
@table @gcctabopt
344
@item -Wredundant-modifiers
345
With this flag, @command{gcj} will warn about redundant modifiers.  For
346
instance, it will warn if an interface method is declared @code{public}.
347
 
348
@item -Wextraneous-semicolon
349
This causes @command{gcj} to warn about empty statements.  Empty statements
350
have been deprecated.
351
 
352
@item -Wno-out-of-date
353
This option will cause @command{gcj} not to warn when a source file is
354
newer than its matching class file.  By default @command{gcj} will warn
355
about this.
356
 
357
@item -Wno-deprecated
358
Warn if a deprecated class, method, or field is referred to.
359
 
360
@item -Wunused
361
This is the same as @command{gcc}'s @code{-Wunused}.
362
 
363
@item -Wall
364
This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
365
-Wunused}.
366
@end table
367
 
368
 
369
@node Linking
370
@section Linking
371
 
372
To turn a Java application into an executable program,
373
you need to link it with the needed libraries, just as for C or C++.
374
The linker by default looks for a global function named @code{main}.
375
Since Java does not have global functions, and a
376
collection of Java classes may have more than one class with a
377
@code{main} method, you need to let the linker know which of those
378
@code{main} methods it should invoke when starting the application.
379
You can do that in any of these ways:
380
 
381
@itemize @bullet
382
@item
383
Specify the class containing the desired @code{main} method
384
when you link the application, using the @code{--main} flag,
385
described below.
386
@item
387
Link the Java package(s) into a shared library (dll) rather than an
388
executable.  Then invoke the application using the @code{gij} program,
389
making sure that @code{gij} can find the libraries it needs.
390
@item
391
Link the Java packages(s) with the flag @code{-lgij}, which links
392
in the @code{main} routine from the @code{gij} command.
393
This allows you to select the class whose @code{main} method you
394
want to run when you run the application.  You can also use
395
other @code{gij} flags, such as @code{-D} flags to set properties.
396
Using the @code{-lgij} library (rather than the @code{gij} program
397
of the previous mechanism) has some advantages: it is compatible with
398
static linking, and does not require configuring or installing libraries.
399
@end itemize
400
 
401
These @code{gij} options relate to linking an executable:
402
 
403
@table @gcctabopt
404
@item --main=@var{CLASSNAME}
405
This option is used when linking to specify the name of the class whose
406
@code{main} method should be invoked when the resulting executable is
407
run.
408
 
409
@item -D@var{name}[=@var{value}]
410
This option can only be used with @code{--main}.  It defines a system
411
property named @var{name} with value @var{value}.  If @var{value} is not
412
specified then it defaults to the empty string.  These system properties
413
are initialized at the program's startup and can be retrieved at runtime
414
using the @code{java.lang.System.getProperty} method.
415
 
416
@item -lgij
417
Create an application whose command-line processing is that
418
of the @code{gij} command.
419
 
420
This option is an alternative to using @code{--main}; you cannot use both.
421
 
422
@item -static-libgcj
423
This option causes linking to be done against a static version of the
424
libgcj runtime library.  This option is only available if
425
corresponding linker support exists.
426
 
427
@strong{Caution:} Static linking of libgcj may cause essential parts
428
of libgcj to be omitted.  Some parts of libgcj use reflection to load
429
classes at runtime.  Since the linker does not see these references at
430
link time, it can omit the referred to classes.  The result is usually
431
(but not always) a @code{ClassNotFoundException} being thrown at
432
runtime. Caution must be used when using this option.  For more
433
details see:
434
@w{@uref{http://gcc.gnu.org/wiki/Statically%20linking%20libgcj}}
435
@end table
436
 
437
@node Code Generation
438
@section Code Generation
439
 
440
In addition to the many @command{gcc} options controlling code generation,
441
@command{gcj} has several options specific to itself.
442
 
443
@table @gcctabopt
444
 
445
@item -C
446
This option is used to tell @command{gcj} to generate bytecode
447
(@file{.class} files) rather than object code.
448
 
449
@item --resource @var{resource-name}
450
This option is used to tell @command{gcj} to compile the contents of a
451
given file to object code so it may be accessed at runtime with the core
452
protocol handler as @samp{core:/@var{resource-name}}.  Note that
453
@var{resource-name} is the name of the resource as found at runtime; for
454
instance, it could be used in a call to @code{ResourceBundle.getBundle}.
455
The actual file name to be compiled this way must be specified
456
separately.
457
 
458
@item -ftarget=@var{VERSION}
459
This can be used with @option{-C} to choose the version of bytecode
460
emitted by @command{gcj}.  The default is @samp{1.5}.  When not
461
generating bytecode, this option has no effect.
462
 
463
@item -d @var{directory}
464
When used with @code{-C}, this causes all generated @file{.class} files
465
to be put in the appropriate subdirectory of @var{directory}.  By
466
default they will be put in subdirectories of the current working
467
directory.
468
 
469
@item -fno-bounds-check
470
By default, @command{gcj} generates code which checks the bounds of all
471
array indexing operations.  With this option, these checks are omitted, which
472
can improve performance for code that uses arrays extensively.  Note that this
473
can result in unpredictable behavior if the code in question actually does
474
violate array bounds constraints.  It is safe to use this option if you are
475
sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.
476
 
477
@item -fno-store-check
478
Don't generate array store checks.  When storing objects into arrays, a runtime
479
check is normally generated in order to ensure that the object is assignment
480
compatible with the component type of the array (which may not be known
481
at compile-time).  With this option, these checks are omitted.  This can
482
improve performance for code which stores objects into arrays frequently.
483
It is safe to use this option if you are sure your code will never throw an
484
@code{ArrayStoreException}.
485
 
486
@item -fjni
487
With @command{gcj} there are two options for writing native methods: CNI
488
and JNI@.  By default @command{gcj} assumes you are using CNI@.  If you are
489
compiling a class with native methods, and these methods are implemented
490
using JNI, then you must use @code{-fjni}.  This option causes
491
@command{gcj} to generate stubs which will invoke the underlying JNI
492
methods.
493
 
494
@item -fno-assert
495
Don't recognize the @code{assert} keyword.  This is for compatibility
496
with older versions of the language specification.
497
 
498
@item -fno-optimize-static-class-initialization
499
When the optimization level is greater or equal to @code{-O2},
500
@command{gcj} will try to optimize the way calls into the runtime are made
501
to initialize static classes upon their first use (this optimization
502
isn't carried out if @code{-C} was specified.) When compiling to native
503
code, @code{-fno-optimize-static-class-initialization} will turn this
504
optimization off, regardless of the optimization level in use.
505
 
506
@item --disable-assertions[=@var{class-or-package}]
507
Don't include code for checking assertions in the compiled code.
508
If @code{=@var{class-or-package}} is missing disables assertion code
509
generation for all classes, unless overridden by a more
510
specific @code{--enable-assertions} flag.
511
If @var{class-or-package} is a class name, only disables generating
512
assertion checks within the named class or its inner classes.
513
If @var{class-or-package} is a package name, disables generating
514
assertion checks within the named package or a subpackage.
515
 
516
By default, assertions are enabled when generating class files
517
or when not optimizing, and disabled when generating optimized binaries.
518
 
519
@item --enable-assertions[=@var{class-or-package}]
520
Generates code to check assertions.  The option is perhaps misnamed,
521
as you still need to turn on assertion checking at run-time,
522
and we don't support any easy way to do that.
523
So this flag isn't very useful yet, except to partially override
524
@code{--disable-assertions}.
525
 
526
@item -findirect-dispatch
527
@command{gcj} has a special binary compatibility ABI, which is enabled
528
by the @code{-findirect-dispatch} option.  In this mode, the code
529
generated by @command{gcj} honors the binary compatibility guarantees
530
in the Java Language Specification, and the resulting object files do
531
not need to be directly linked against their dependencies.  Instead,
532
all dependencies are looked up at runtime.  This allows free mixing of
533
interpreted and compiled code.
534
 
535
Note that, at present, @code{-findirect-dispatch} can only be used
536
when compiling @file{.class} files.  It will not work when compiling
537
from source.  CNI also does not yet work with the binary compatibility
538
ABI.  These restrictions will be lifted in some future release.
539
 
540
However, if you compile CNI code with the standard ABI, you can call
541
it from code built with the binary compatibility ABI.
542
 
543
@item -fbootstrap-classes
544
This option can be use to tell @code{libgcj} that the compiled classes
545
should be loaded by the bootstrap loader, not the system class loader.
546
By default, if you compile a class and link it into an executable, it
547
will be treated as if it was loaded using the system class loader.
548
This is convenient, as it means that things like
549
@code{Class.forName()} will search @samp{CLASSPATH} to find the
550
desired class.
551
 
552
@item -freduced-reflection
553
This option causes the code generated by @command{gcj} to contain a
554
reduced amount of the class meta-data used to support runtime
555
reflection. The cost of this savings is the loss of
556
the ability to use certain reflection capabilities of the standard
557
Java runtime environment. When set all meta-data except for that
558
which is needed to obtain correct runtime semantics is eliminated.
559
 
560
For code that does not use reflection (i.e. serialization, RMI, CORBA
561
or call methods in the @code{java.lang.reflect} package),
562
@code{-freduced-reflection} will result in proper operation with a
563
savings in executable code size.
564
 
565
JNI (@code{-fjni}) and the binary compatibility ABI
566
(@code{-findirect-dispatch}) do not work properly without full
567
reflection meta-data.  Because of this, it is an error to use these options
568
with @code{-freduced-reflection}.
569
 
570
@strong{Caution:} If there is no reflection meta-data, code that uses
571
a @code{SecurityManager} may not work properly.  Also calling
572
@code{Class.forName()} may fail if the calling method has no
573
reflection meta-data.
574
 
575
@end table
576
 
577
 
578
@node Configure-time Options
579
@section Configure-time Options
580
 
581
Some @command{gcj} code generations options affect the resulting ABI, and
582
so can only be meaningfully given when @code{libgcj}, the runtime
583
package, is configured.  @code{libgcj} puts the appropriate options from
584
this group into a @samp{spec} file which is read by @command{gcj}.  These
585
options are listed here for completeness; if you are using @code{libgcj}
586
then you won't want to touch these options.
587
 
588
@table @gcctabopt
589
@item -fuse-boehm-gc
590
This enables the use of the Boehm GC bitmap marking code.  In particular
591
this causes @command{gcj} to put an object marking descriptor into each
592
vtable.
593
 
594
@item -fhash-synchronization
595
By default, synchronization data (the data used for @code{synchronize},
596
@code{wait}, and @code{notify}) is pointed to by a word in each object.
597
With this option @command{gcj} assumes that this information is stored in a
598
hash table and not in the object itself.
599
 
600
@item -fuse-divide-subroutine
601
On some systems, a library routine is called to perform integer
602
division.  This is required to get exception handling correct when
603
dividing by zero.
604
 
605
@item -fcheck-references
606
On some systems it's necessary to insert inline checks whenever
607
accessing an object via a reference.  On other systems you won't need
608
this because null pointer accesses are caught automatically by the
609
processor.
610
 
611
@item -fuse-atomic-builtins
612
On some systems, gcc can generate code for built-in atomic operations.
613
Use this option to force gcj to use these builtins when compiling Java
614
code.  Where this capability is present it should be automatically
615
detected, so you won't usually need to use this option.
616
 
617
@end table
618
 
619
@c man end
620
 
621
@node Compatibility
622
@chapter Compatibility with the Java Platform
623
 
624
As we believe it is important that the Java platform not be fragmented,
625
@command{gcj} and @code{libgcj} try to conform to the relevant Java
626
specifications.  However, limited manpower and incomplete and unclear
627
documentation work against us.  So, there are caveats to using
628
@command{gcj}.
629
 
630
@menu
631
* Limitations::
632
* Extensions::
633
@end menu
634
 
635
@node Limitations
636
@section Standard features not yet supported
637
 
638
This list of compatibility issues is by no means complete.
639
 
640
@itemize @bullet
641
@item
642
@command{gcj} implements the JDK 1.2 language.  It supports inner classes
643
and the new 1.4 @code{assert} keyword.  It does not yet support the Java 2
644
@code{strictfp} keyword (it recognizes the keyword but ignores it).
645
 
646
@item
647
@code{libgcj} is largely compatible with the JDK 1.2 libraries.
648
However, @code{libgcj} is missing many packages, most notably
649
@code{java.awt}.  There are also individual missing classes and methods.
650
We currently do not have a list showing differences between
651
@code{libgcj} and the Java 2 platform.
652
 
653
@item
654
Sometimes the @code{libgcj} implementation of a method or class differs
655
from the JDK implementation.  This is not always a bug.  Still, if it
656
affects you, it probably makes sense to report it so that we can discuss
657
the appropriate response.
658
 
659
@item
660
@command{gcj} does not currently allow for piecemeal replacement of
661
components within @code{libgcj}. Unfortunately, programmers often want
662
to use newer versions of certain packages, such as those provided by
663
the Apache Software Foundation's Jakarta project.  This has forced us
664
to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
665
their own libraries, separate from @code{libgcj}.  If you intend to
666
use these classes, you must link them explicitly with
667
@code{-l-org-w3c-dom} and @code{-l-org-xml-sax}.  Future versions of
668
@command{gcj} may not have this restriction.
669
@end itemize
670
 
671
@node Extensions
672
@section Extra features unique to gcj
673
 
674
The main feature of @command{gcj} is that it can compile programs written in
675
the Java programming language to native code.  Most extensions that have been
676
added are to facilitate this functionality.
677
 
678
@itemize @bullet
679
@item
680
@command{gcj} makes it easy and efficient to mix code written in Java and C++.
681
@xref{About CNI}, for more info on how to use this in your programs.
682
 
683
@item
684
When you compile your classes into a shared library using
685
@code{-findirect-dispatch} then add them to the system-wide
686
classmap.db file using @code{gcj-dbtool}, they will be automatically
687
loaded by the @code{libgcj} system classloader.  This is the new,
688
preferred classname-to-library resolution mechanism.  @xref{Invoking
689
gcj-dbtool}, for more information on using the classmap database.
690
 
691
@item
692
The old classname-to-library lookup mechanism is still supported
693
through the @code{gnu.gcj.runtime.VMClassLoader.library_control}
694
property, but it is deprecated and will likely be removed in some
695
future release.  When trying to load a class @code{gnu.pkg.SomeClass}
696
the system classloader will first try to load the shared library
697
@file{lib-gnu-pkg-SomeClass.so}, if that fails to load the class then
698
it will try to load @file{lib-gnu-pkg.so} and finally when the class
699
is still not loaded it will try to load @file{lib-gnu.so}.  Note that
700
all @samp{.}s will be transformed into @samp{-}s and that searching
701
for inner classes starts with their outermost outer class.  If the
702
class cannot be found this way the system classloader tries to use the
703
@code{libgcj} bytecode interpreter to load the class from the standard
704
classpath.  This process can be controlled to some degree via the
705
@code{gnu.gcj.runtime.VMClassLoader.library_control} property;
706
@xref{libgcj Runtime Properties}.
707
 
708
@item
709
@code{libgcj} includes a special @samp{gcjlib} URL type.  A URL of
710
this form is like a @code{jar} URL, and looks like
711
@samp{gcjlib:/path/to/shared/library.so!/path/to/resource}.  An access
712
to one of these URLs causes the shared library to be @code{dlopen()}d,
713
and then the resource is looked for in that library.  These URLs are
714
most useful when used in conjunction with @code{java.net.URLClassLoader}.
715
Note that, due to implementation limitations, currently any such URL
716
can be accessed by only one class loader, and libraries are never
717
unloaded.  This means some care must be exercised to make sure that
718
a @code{gcjlib} URL is not accessed by more than one class loader at once.
719
In a future release this limitation will be lifted, and such
720
libraries will be mapped privately.
721
 
722
@item
723
A program compiled by @command{gcj} will examine the
724
@env{GCJ_PROPERTIES} environment variable and change its behavior in
725
some ways.  In particular @env{GCJ_PROPERTIES} holds a list of
726
assignments to global properties, such as would be set with the
727
@option{-D} option to @command{java}.  For instance,
728
@samp{java.compiler=gcj} is a valid (but currently meaningless)
729
setting.
730
@cindex GCJ_PROPERTIES
731
@vindex GCJ_PROPERTIES
732
 
733
@end itemize
734
 
735
 
736
@node Invoking jcf-dump
737
@chapter Invoking jcf-dump
738
 
739
@c man title jcf-dump print information about Java class files
740
 
741
@ignore
742
@c man begin SYNOPSIS jcf-dump
743
jcf-dump [@option{-c}] [@option{--javap}]
744
    [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
745
    [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
746
    [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
747
    @var{classname}@dots{}
748
@c man end
749
@c man begin SEEALSO jcf-dump
750
gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
751
and the Info entries for @file{gcj} and @file{gcc}.
752
@c man end
753
@end ignore
754
 
755
@c man begin DESCRIPTION jcf-dump
756
 
757
This is a class file examiner, similar to @code{javap}.  It will print
758
information about a number of classes, which are specified by class name
759
or file name.
760
 
761
@c man end
762
 
763
@c man begin OPTIONS jcf-dump
764
 
765
@table @gcctabopt
766
@item -c
767
Disassemble method bodies.  By default method bodies are not printed.
768
 
769
@item --print-constants
770
Print the constant pool.  When printing a reference to a constant
771
also print its index in the constant pool.
772
 
773
@item --javap
774
Generate output in @code{javap} format.  The implementation of this
775
feature is very incomplete.
776
 
777
@item --classpath=@var{path}
778
@itemx --CLASSPATH=@var{path}
779
@itemx -I@var{directory}
780
@itemx -o @var{file}
781
These options as the same as the corresponding @command{gcj} options.
782
 
783
@item --help
784
Print help, then exit.
785
 
786
@item --version
787
Print version number, then exit.
788
 
789
@item -v, --verbose
790
Print extra information while running.
791
Implies @code{--print-constants}.
792
@end table
793
 
794
@c man end
795
 
796
@node Invoking gij
797
@chapter Invoking gij
798
 
799
@c man title gij GNU interpreter for Java bytecode
800
 
801
@ignore
802
@c man begin SYNOPSIS gij
803
gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
804
 
805
gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
806
  [@option{-cp} @var{path}] [@option{-classpath} @var{path}]
807
  [@option{-D}@var{name}[=@var{value}]@dots{}]
808
  [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
809
  [@option{-X@var{argument}}] [@option{-verbose}] [@option{-verbose:class}]
810
  [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
811
@c man end
812
@c man begin SEEALSO gij
813
gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
814
and the Info entries for @file{gcj} and @file{gcc}.
815
@c man end
816
@end ignore
817
 
818
@c man begin DESCRIPTION gij
819
 
820
@code{gij} is a Java bytecode interpreter included with @code{libgcj}.
821
@code{gij} is not available on every platform; porting it requires a
822
small amount of assembly programming which has not been done for all the
823
targets supported by @command{gcj}.
824
 
825
The primary argument to @code{gij} is the name of a class or, with
826
@code{-jar}, a jar file.  Options before this argument are interpreted
827
by @code{gij}; remaining options are passed to the interpreted program.
828
 
829
If a class name is specified and this class does not have a @code{main}
830
method with the appropriate signature (a @code{static void} method with
831
a @code{String[]} as its sole argument), then @code{gij} will print an
832
error and exit.
833
 
834
If a jar file is specified then @code{gij} will use information in it to
835
determine which class' @code{main} method will be invoked.
836
 
837
@code{gij} will invoke the @code{main} method with all the remaining
838
command-line options.
839
 
840
Note that @code{gij} is not limited to interpreting code.  Because
841
@code{libgcj} includes a class loader which can dynamically load shared
842
objects, it is possible to give @code{gij} the name of a class which has
843
been compiled and put into a shared library on the class path.
844
 
845
@c man end
846
 
847
@c man begin OPTIONS gij
848
 
849
@table @gcctabopt
850
@item -cp @var{path}
851
@itemx -classpath @var{path}
852
Set the initial class path.  The class path is used for finding
853
class and resource files.  If specified, this option overrides the
854
@code{CLASSPATH} environment variable.  Note that this option is
855
ignored if @code{-jar} is used.
856
 
857
@item -D@var{name}[=@var{value}]
858
This defines a system property named @var{name} with value @var{value}.
859
If @var{value} is not specified then it defaults to the empty string.
860
These system properties are initialized at the program's startup and can
861
be retrieved at runtime using the @code{java.lang.System.getProperty}
862
method.
863
 
864
@item -ms=@var{number}
865
Equivalent to @code{-Xms}.
866
 
867
@item -mx=@var{number}
868
Equivalent to @code{-Xmx}.
869
 
870
@item -noverify
871
Do not verify compliance of bytecode with the VM specification. In addition,
872
this option disables type verification which is otherwise performed on BC-ABI
873
compiled code.
874
 
875
@item -X
876
@itemx -X@var{argument}
877
Supplying @code{-X} by itself will cause @code{gij} to list all the
878
supported @code{-X} options.  Currently these options are supported:
879
 
880
@table @gcctabopt
881
@item -Xms@var{size}
882
Set the initial heap size.
883
 
884
@item -Xmx@var{size}
885
Set the maximum heap size.
886
 
887
@item -Xss@var{size}
888
Set the thread stack size.
889
@end table
890
 
891
Unrecognized @code{-X} options are ignored, for compatibility with
892
other runtimes.
893
 
894
@item -jar
895
This indicates that the name passed to @code{gij} should be interpreted
896
as the name of a jar file, not a class.
897
 
898
@item --help
899
@itemx -?
900
Print help, then exit.
901
 
902
@item --showversion
903
Print version number and continue.
904
 
905
@item --fullversion
906
Print detailed version information, then exit.
907
 
908
@item --version
909
Print version number, then exit.
910
 
911
@item -verbose
912
@itemx -verbose:class
913
Each time a class is initialized, print a short message on standard error.
914
@end table
915
 
916
@code{gij} also recognizes and ignores the following options, for
917
compatibility with existing application launch scripts:
918
@code{-client}, @code{-server}, @code{-hotspot}, @code{-jrockit},
919
@code{-agentlib}, @code{-agentpath}, @code{-debug}, @code{-d32},
920
@code{-d64}, @code{-javaagent}, @code{-noclassgc}, @code{-verify},
921
and @code{-verifyremote}.
922
 
923
@c man end
924
 
925
@node Invoking gcj-dbtool
926
@chapter Invoking gcj-dbtool.
927
 
928
@c man title gcj-dbtool Manipulate class file mapping databases for libgcj
929
 
930
@ignore
931
@c man begin SYNOPSIS gcj-dbtool
932
gcj-dbtool @option{OPTION} @var{DBFILE} [@option{MORE}] @dots{}
933
 
934
gcj-dbtool [@option{-0}] [@option{-}] [@option{-n}] [@option{-a}] [@option{-f}]
935
  [@option{-t}] [@option{-l}] [@option{-p} [@var{LIBDIR}]]
936
  [@option{-v}] [@option{-m}] [@option{--version}] [@option{--help}]
937
 
938
@c man end
939
@c man begin SEEALSO gcj-dbtool
940
gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
941
and the Info entries for @file{gcj} and @file{gcc}.
942
@c man end
943
@end ignore
944
 
945
@c man begin DESCRIPTION gcj-dbtool
946
 
947
@code{gcj-dbtool} is a tool for creating and manipulating class file
948
mapping databases.  @code{libgcj} can use these databases to find a
949
shared library corresponding to the bytecode representation of a
950
class.  This functionality is useful for ahead-of-time compilation of
951
a program that has no knowledge of @code{gcj}.
952
 
953
@code{gcj-dbtool} works best if all the jar files added to it are
954
compiled using @code{-findirect-dispatch}.
955
 
956
Note that @code{gcj-dbtool} is currently available as ``preview
957
technology''.  We believe it is a reasonable way to allow
958
application-transparent ahead-of-time compilation, but this is an
959
unexplored area.  We welcome your comments.
960
 
961
@c man end
962
 
963
@c man begin OPTIONS gcj-dbtool
964
 
965
@table @gcctabopt
966
@item -n @var{DBFILE} [@var{SIZE}]
967
This creates a new database.  Currently, databases cannot be resized;
968
you can choose a larger initial size if desired.  The default size is
969
32,749.
970
 
971
@item -a @var{DBFILE} @var{JARFILE} @var{LIB}
972
@itemx -f @var{DBFILE} @var{JARFILE} @var{LIB}
973
This adds a jar file to the database.  For each class file in the jar,
974
a cryptographic signature of the bytecode representation of the class
975
is recorded in the database.  At runtime, a class is looked up by its
976
signature and the compiled form of the class is looked for in the
977
corresponding shared library.  The @option{-a} option will verify
978
that @var{LIB} exists before adding it to the database; @option{-f}
979
skips this check.
980
 
981
@item [@option{-}][@option{-0}] -m @var{DBFILE} @var{DBFILE},[@var{DBFILE}]
982
Merge a number of databases.  The output database overwrites any
983
existing database.  To add databases into an existing database,
984
include the destination in the list of sources.
985
 
986
If @option{-} or @option{-0} are used, the list of files to read is
987
taken from standard input instead of the command line.  For
988
@option{-0}, Input filenames are terminated by a null character
989
instead of by whitespace.  Useful when arguments might contain white
990
space.  The GNU find -print0 option produces input suitable for this
991
mode.
992
 
993
@item -t @var{DBFILE}
994
Test a database.
995
 
996
@item -l @var{DBFILE}
997
List the contents of a database.
998
 
999
@item -p
1000
Print the name of the default database.  If there is no default
1001
database, this prints a blank line.  If @var{LIBDIR} is specified, use
1002
it instead of the default library directory component of the database
1003
name.
1004
 
1005
@item --help
1006
Print a help message, then exit.
1007
 
1008
@item --version
1009
@itemx -v
1010
Print version information, then exit.
1011
 
1012
@end table
1013
 
1014
@c man end
1015
 
1016
@node Invoking jv-convert
1017
@chapter Invoking jv-convert
1018
 
1019
@c man title jv-convert Convert file from one encoding to another
1020
 
1021
@c man begin SYNOPSIS jv-convert
1022
@command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
1023
@ignore
1024
 
1025
  [@option{--encoding} @var{name}]
1026
  [@option{--from} @var{name}]
1027
  [@option{--to} @var{name}]
1028
  [@option{-i} @var{file}] [@option{-o} @var{file}]
1029
  [@option{--reverse}] [@option{--help}] [@option{--version}]
1030
@end ignore
1031
@c man end
1032
 
1033
@c man begin DESCRIPTION jv-convert
1034
 
1035
@command{jv-convert} is a utility included with @code{libgcj} which
1036
converts a file from one encoding to another.  It is similar to the Unix
1037
@command{iconv} utility.
1038
 
1039
The encodings supported by @command{jv-convert} are platform-dependent.
1040
Currently there is no way to get a list of all supported encodings.
1041
 
1042
@c man end
1043
 
1044
@c man begin OPTIONS jv-convert
1045
 
1046
@table @gcctabopt
1047
@item --encoding @var{name}
1048
@itemx --from @var{name}
1049
Use @var{name} as the input encoding.  The default is the current
1050
locale's encoding.
1051
 
1052
@item --to @var{name}
1053
Use @var{name} as the output encoding.  The default is the
1054
@code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
1055
non-ASCII characters.
1056
 
1057
@item -i @var{file}
1058
Read from @var{file}.  The default is to read from standard input.
1059
 
1060
@item -o @var{file}
1061
Write to @var{file}.  The default is to write to standard output.
1062
 
1063
@item --reverse
1064
Swap the input and output encodings.
1065
 
1066
@item --help
1067
Print a help message, then exit.
1068
 
1069
@item --version
1070
Print version information, then exit.
1071
@end table
1072
 
1073
@c man end
1074
 
1075
@node Invoking grmic
1076
@chapter Invoking grmic
1077
 
1078
@c man title grmic Generate stubs for Remote Method Invocation
1079
 
1080
@c man begin SYNOPSIS grmic
1081
@command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
1082
@ignore
1083
  [@option{-keep}]
1084
  [@option{-keepgenerated}]
1085
  [@option{-v1.1}]
1086
  [@option{-vcompat}]
1087
  [@option{-v1.2}]
1088
  [@option{-nocompile}]
1089
  [@option{-verbose}]
1090
  [@option{-d} @var{directory}]
1091
  [@option{-help}]
1092
  [@option{-version}]
1093
@end ignore
1094
@c man end
1095
 
1096
@c man begin DESCRIPTION grmic
1097
 
1098
@command{grmic} is a utility included with @code{libgcj} which generates
1099
stubs for remote objects.
1100
 
1101
@c FIXME: Add real information here.
1102
@c This really isn't much more than the --help output.
1103
 
1104
Note that this program isn't yet fully compatible with the JDK
1105
@command{grmic}.  Some options, such as @option{-classpath}, are
1106
recognized but currently ignored.  We have left these options
1107
undocumented for now.
1108
 
1109
Long options can also be given with a GNU-style leading @samp{--}.  For
1110
instance, @option{--help} is accepted.
1111
 
1112
@c man end
1113
 
1114
@c man begin OPTIONS grmic
1115
 
1116
@table @gcctabopt
1117
@item -keep
1118
@itemx -keepgenerated
1119
By default, @command{grmic} deletes intermediate files.  Either of these
1120
options causes it not to delete such files.
1121
 
1122
@item -v1.1
1123
Cause @command{grmic} to create stubs and skeletons for the 1.1
1124
protocol version.
1125
 
1126
@item -vcompat
1127
Cause @command{grmic} to create stubs and skeletons compatible with both
1128
the 1.1 and 1.2 protocol versions.  This is the default.
1129
 
1130
@item -v1.2
1131
Cause @command{grmic} to create stubs and skeletons for the 1.2
1132
protocol version.
1133
 
1134
@item -nocompile
1135
Don't compile the generated files.
1136
 
1137
@item -verbose
1138
Print information about what @command{grmic} is doing.
1139
 
1140
@item -d @var{directory}
1141
Put output files in @var{directory}.  By default the files are put in
1142
the current working directory.
1143
 
1144
@item -help
1145
Print a help message, then exit.
1146
 
1147
@item -version
1148
Print version information, then exit.
1149
@end table
1150
 
1151
@c man end
1152
 
1153
 
1154
@node Invoking gc-analyze
1155
@chapter Invoking gc-analyze
1156
 
1157
@c man title gc-analyze Analyze Garbage Collector (GC) memory dumps
1158
 
1159
@c man begin SYNOPSIS gc-analyze
1160
@command{gc-analyze} [@option{OPTION}] @dots{} [@var{file}]
1161
@ignore
1162
  [@option{-v}]
1163
  [@option{--verbose}]
1164
  [@option{-p} @var{tool-prefix}]
1165
  [@option{-d} @var{directory}]
1166
  [@option{--version}]
1167
  [@option{--help}]
1168
@end ignore
1169
@c man end
1170
 
1171
@c man begin DESCRIPTION gc-analyze
1172
 
1173
@command{gc-analyze} prints an analysis of a GC memory dump to
1174
standard out.
1175
 
1176
The memory dumps may be created by calling
1177
@code{gnu.gcj.util.GCInfo.enumerate(String namePrefix)} from java
1178
code.  A memory dump will be created on an out of memory condition if
1179
@code{gnu.gcj.util.GCInfo.setOOMDump(String namePrefix)} is called
1180
before the out of memory occurs.
1181
 
1182
Running this program will create two files: @file{TestDump001} and
1183
@file{TestDump001.bytes}.
1184
 
1185
@example
1186
import gnu.gcj.util.*;
1187
import java.util.*;
1188
 
1189
public class GCDumpTest
1190
@{
1191
    static public void main(String args[])
1192
    @{
1193
        ArrayList<String> l = new ArrayList<String>(1000);
1194
 
1195
        for (int i = 1; i < 1500; i++) @{
1196
            l.add("This is string #" + i);
1197
        @}
1198
        GCInfo.enumerate("TestDump");
1199
    @}
1200
@}
1201
@end example
1202
 
1203
The memory dump may then be displayed by running:
1204
 
1205
@example
1206
gc-analyze -v TestDump001
1207
@end example
1208
 
1209
@c FIXME: Add real information here.
1210
@c This really isn't much more than the --help output.
1211
 
1212
@c man end
1213
 
1214
@c man begin OPTIONS gc-analyze
1215
 
1216
@table @gcctabopt
1217
@item --verbose
1218
@itemx -v
1219
Verbose output.
1220
 
1221
@item -p @var{tool-prefix}
1222
Prefix added to the names of the @command{nm} and @command{readelf} commands.
1223
 
1224
@item -d @var{directory}
1225
Directory that contains the executable and shared libraries used when
1226
the dump was generated.
1227
 
1228
@item --help
1229
Print a help message, then exit.
1230
 
1231
@item --version
1232
Print version information, then exit.
1233
@end table
1234
 
1235
@c man end
1236
 
1237
@node Invoking aot-compile
1238
@chapter Invoking aot-compile
1239
 
1240
@c man title aot-compile Compile bytecode to native and generate databases
1241
 
1242
@ignore
1243
 
1244
@c man begin SYNOPSIS aot-compile
1245
aot-compile [@option{OPTION}] @dots{} @var{SRCDIR} @var{DSTDIR}
1246
 
1247
aot-compile [@option{-M, --make}=@var{PATH}] [@option{-C, --gcj}=@var{PATH}]
1248
  [@option{-D, --dbtool}=@var{PATH}] [@option{-m, --makeflags}=@var{FLAGS}]
1249
  [@option{-c, --gcjflags}=@var{FLAGS}] [@option{-l, --ldflags}=@var{FLAGS}]
1250
  [@option{-e, --exclude}=@var{PATH}]
1251
@c man end
1252
 
1253
@c man begin SEEALSO aot-compile
1254
gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
1255
and the Info entries for @file{gcj} and @file{gcc}.
1256
@c man end
1257
 
1258
@end ignore
1259
 
1260
@c man begin DESCRIPTION aot-compile
1261
@code{aot-compile} is a script that searches a directory for Java bytecode
1262
(as class files, or in jars) and uses @code{gcj} to compile it to native
1263
code and generate the databases from it.
1264
@c man end
1265
 
1266
@c man begin OPTIONS aot-compile
1267
@table @gcctabopt
1268
@item -M, --make=@var{PATH}
1269
Specify the path to the @code{make} executable to use.
1270
 
1271
@item -C, --gcj=@var{PATH}
1272
Specify the path to the @code{gcj} executable to use.
1273
 
1274
@item -D, --dbtool=@var{PATH}
1275
Specify the path to the @code{gcj-dbtool} executable to use.
1276
 
1277
@item -m, --makeflags=@var{FLAGS}
1278
Specify flags to pass to @code{make} during the build.
1279
 
1280
@item -c, --gcjflags=@var{FLAGS}
1281
Specify flags to pass to @code{gcj} during compilation, in addition to
1282
'-fPIC -findirect-dispatch -fjni'.
1283
 
1284
@item -l, --ldflags=@var{FLAGS}
1285
Specify flags to pass to @code{gcj} during linking, in addition to
1286
'-Wl,-Bsymbolic'.
1287
 
1288
@item -e, --exclude=@var{PATH}
1289
Do not compile @var{PATH}.
1290
 
1291
@end table
1292
 
1293
@c man end
1294
 
1295
@node Invoking rebuild-gcj-db
1296
@chapter Invoking rebuild-gcj-db
1297
 
1298
@c man title rebuild-gcj-db Merge the per-solib databases made by aot-compile into one system-wide database.
1299
@ignore
1300
 
1301
@c man begin SYNOPSIS rebuild-gcj-db
1302
rebuild-gcj-db
1303
@c man end
1304
 
1305
@c man begin SEEALSO rebuild-gcj-db
1306
gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
1307
and the Info entries for @file{gcj} and @file{gcc}.
1308
@c man end
1309
 
1310
@end ignore
1311
 
1312
@c man begin DESCRIPTION rebuild-gcj-db
1313
@code{rebuild-gcj-db} is a script that merges the per-solib databases made by
1314
@code{aot-compile} into one system-wide database so @code{gij} can find the
1315
solibs.
1316
@c man end
1317
 
1318
@node About CNI
1319
@chapter About CNI
1320
 
1321
This documents CNI, the Compiled Native Interface,
1322
which is is a convenient way to write Java native methods using C++.
1323
This is a more efficient, more convenient, but less portable
1324
alternative to the standard JNI (Java Native Interface).
1325
 
1326
@menu
1327
* Basic concepts::              Introduction to using CNI@.
1328
* Packages::                    How packages are mapped to C++.
1329
* Primitive types::             Handling primitive Java types in C++.
1330
* Reference types::             Handling Java reference types in C++.
1331
* Interfaces::                  How Java interfaces map to C++.
1332
* Objects and Classes::         C++ and Java classes.
1333
* Class Initialization::        How objects are initialized.
1334
* Object allocation::           How to create Java objects in C++.
1335
* Memory allocation::           How to allocate and free memory.
1336
* Arrays::                      Dealing with Java arrays in C++.
1337
* Methods::                     Java methods in C++.
1338
* Strings::                     Information about Java Strings.
1339
* Mixing with C++::             How CNI can interoperate with C++.
1340
* Exception Handling::          How exceptions are handled.
1341
* Synchronization::             Synchronizing between Java and C++.
1342
* Invocation::                  Starting the Java runtime from C++.
1343
* Reflection::                  Using reflection from C++.
1344
@end menu
1345
 
1346
 
1347
@node Basic concepts
1348
@section Basic concepts
1349
 
1350
In terms of languages features, Java is mostly a subset
1351
of C++.  Java has a few important extensions, plus a powerful standard
1352
class library, but on the whole that does not change the basic similarity.
1353
Java is a hybrid object-oriented language, with a few native types,
1354
in addition to class types.  It is class-based, where a class may have
1355
static as well as per-object fields, and static as well as instance methods.
1356
Non-static methods may be virtual, and may be overloaded.  Overloading is
1357
resolved at compile time by matching the actual argument types against
1358
the parameter types.  Virtual methods are implemented using indirect calls
1359
through a dispatch table (virtual function table).  Objects are
1360
allocated on the heap, and initialized using a constructor method.
1361
Classes are organized in a package hierarchy.
1362
 
1363
All of the listed attributes are also true of C++, though C++ has
1364
extra features (for example in C++ objects may be allocated not just
1365
on the heap, but also statically or in a local stack frame).  Because
1366
@command{gcj} uses the same compiler technology as G++ (the GNU
1367
C++ compiler), it is possible to make the intersection of the two
1368
languages use the same ABI (object representation and calling
1369
conventions).  The key idea in CNI is that Java objects are C++
1370
objects, and all Java classes are C++ classes (but not the other way
1371
around).  So the most important task in integrating Java and C++ is to
1372
remove gratuitous incompatibilities.
1373
 
1374
You write CNI code as a regular C++ source file.  (You do have to use
1375
a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
1376
 
1377
@noindent A CNI C++ source file must have:
1378
 
1379
@example
1380
#include <gcj/cni.h>
1381
@end example
1382
 
1383
@noindent and then must include one header file for each Java class it uses, e.g.:
1384
 
1385
@example
1386
#include <java/lang/Character.h>
1387
#include <java/util/Date.h>
1388
#include <java/lang/IndexOutOfBoundsException.h>
1389
@end example
1390
 
1391
@noindent These header files are automatically generated by @code{gcjh}.
1392
 
1393
 
1394
CNI provides some functions and macros to make using Java objects and
1395
primitive types from C++ easier.  In general, these CNI functions and
1396
macros start with the @code{Jv} prefix, for example the function
1397
@code{JvNewObjectArray}.  This convention is used to avoid conflicts
1398
with other libraries.  Internal functions in CNI start with the prefix
1399
@code{_Jv_}.  You should not call these; if you find a need to, let us
1400
know and we will try to come up with an alternate solution.
1401
 
1402
 
1403
@subsection Limitations
1404
 
1405
Whilst a Java class is just a C++ class that doesn't mean that you are
1406
freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
1407
rules of the Java programming language.
1408
 
1409
For example: it is not possible to declare a method in a CNI class
1410
that will take a C string (@code{char*}) as an argument, or to declare a
1411
member variable of some non-Java datatype.
1412
 
1413
 
1414
@node Packages
1415
@section Packages
1416
 
1417
The only global names in Java are class names, and packages.  A
1418
@dfn{package} can contain zero or more classes, and also zero or more
1419
sub-packages.  Every class belongs to either an unnamed package or a
1420
package that has a hierarchical and globally unique name.
1421
 
1422
A Java package is mapped to a C++ @dfn{namespace}.  The Java class
1423
@code{java.lang.String} is in the package @code{java.lang}, which is a
1424
sub-package of @code{java}.  The C++ equivalent is the class
1425
@code{java::lang::String}, which is in the namespace @code{java::lang}
1426
which is in the namespace @code{java}.
1427
 
1428
@noindent Here is how you could express this:
1429
 
1430
@example
1431
(// @r{Declare the class(es), possibly in a header file:}
1432
namespace java @{
1433
  namespace lang @{
1434
    class Object;
1435
    class String;
1436
    ...
1437
  @}
1438
@}
1439
 
1440
class java::lang::String : public java::lang::Object
1441
@{
1442
  ...
1443
@};
1444
@end example
1445
 
1446
@noindent The @code{gcjh} tool automatically generates the necessary namespace
1447
declarations.
1448
 
1449
 
1450
@subsection Leaving out package names
1451
 
1452
Always using the fully-qualified name of a java class can be
1453
tiresomely verbose.  Using the full qualified name also ties the code
1454
to a single package making code changes necessary should the class
1455
move from one package to another.  The Java @code{package} declaration
1456
specifies that the following class declarations are in the named
1457
package, without having to explicitly name the full package
1458
qualifiers.  The @code{package} declaration can be
1459
followed by zero or more @code{import} declarations, which
1460
allows either a single class or all the classes in a package to be
1461
named by a simple identifier.  C++ provides something similar with the
1462
@code{using} declaration and directive.
1463
 
1464
@noindent In Java:
1465
 
1466
@example
1467
import @var{package-name}.@var{class-name};
1468
@end example
1469
 
1470
@noindent allows the program text to refer to @var{class-name} as a shorthand for
1471
the fully qualified name: @code{@var{package-name}.@var{class-name}}.
1472
 
1473
 
1474
@noindent To achieve the same effect C++, you have to do this:
1475
 
1476
@example
1477
using @var{package-name}::@var{class-name};
1478
@end example
1479
 
1480
 
1481
@noindent Java can also cause imports on demand, like this:
1482
 
1483
@example
1484
import @var{package-name}.*;
1485
@end example
1486
 
1487
@noindent Doing this allows any class from the package @var{package-name} to be
1488
referred to only by its class-name within the program text.
1489
 
1490
 
1491
@noindent The same effect can be achieved in C++ like this:
1492
 
1493
@example
1494
using namespace @var{package-name};
1495
@end example
1496
 
1497
 
1498
@node Primitive types
1499
@section Primitive types
1500
 
1501
Java provides 8 @dfn{primitives} types which represent integers, floats,
1502
characters and booleans (and also the void type).  C++ has its own
1503
very similar concrete types.  Such types in C++ however are not always
1504
implemented in the same way (an int might be 16, 32 or 64 bits for example)
1505
so CNI provides a special C++ type for each primitive Java type:
1506
 
1507
@multitable @columnfractions .20 .25 .60
1508
@item @strong{Java type}   @tab @strong{C/C++ typename} @tab @strong{Description}
1509
@item @code{char}        @tab @code{jchar}          @tab 16 bit Unicode character
1510
@item @code{boolean}     @tab @code{jboolean}       @tab logical (true or false) values
1511
@item @code{byte}        @tab @code{jbyte}          @tab 8-bit signed integer
1512
@item @code{short}       @tab @code{jshort}         @tab 16 bit signed integer
1513
@item @code{int}         @tab @code{jint}           @tab 32 bit signed integer
1514
@item @code{long}        @tab @code{jlong}          @tab 64 bit signed integer
1515
@item @code{float}       @tab @code{jfloat}         @tab 32 bit IEEE floating point number
1516
@item @code{double}      @tab @code{jdouble}        @tab 64 bit IEEE floating point number
1517
@item @code{void}        @tab @code{void}           @tab no value
1518
@end multitable
1519
 
1520
When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
1521
to avoid disappointment.
1522
 
1523
 
1524
@subsection Reference types associated with primitive types
1525
 
1526
In Java each primitive type has an associated reference type,
1527
e.g.: @code{boolean} has an associated @code{java.lang.Boolean.TYPE} class.
1528
In order to make working with such classes easier GCJ provides the macro
1529
@code{JvPrimClass}:
1530
 
1531
@deffn macro JvPrimClass type
1532
Return a pointer to the @code{Class} object corresponding to the type supplied.
1533
 
1534
@example
1535
JvPrimClass(void) @result{} java.lang.Void.TYPE
1536
@end example
1537
 
1538
@end deffn
1539
 
1540
 
1541
@node Reference types
1542
@section Reference types
1543
 
1544
A Java reference type is treated as a class in C++.  Classes and
1545
interfaces are handled this way.  A Java reference is translated to a
1546
C++ pointer, so for instance a Java @code{java.lang.String} becomes,
1547
in C++, @code{java::lang::String *}.
1548
 
1549
CNI provides a few built-in typedefs for the most common classes:
1550
@multitable @columnfractions .30 .25 .60
1551
@item @strong{Java type} @tab @strong{C++ typename} @tab @strong{Description}
1552
@item @code{java.lang.Object} @tab @code{jobject} @tab Object type
1553
@item @code{java.lang.String} @tab @code{jstring} @tab String type
1554
@item @code{java.lang.Class} @tab @code{jclass} @tab Class type
1555
@end multitable
1556
@cindex jobject
1557
@cindex jstring
1558
@cindex jclass
1559
 
1560
Every Java class or interface has a corresponding @code{Class}
1561
instance.  These can be accessed in CNI via the static @code{class$}
1562
field of a class.  The @code{class$} field is of type @code{Class}
1563
(and not @code{Class *}), so you will typically take the address of
1564
it.
1565
@cindex class$
1566
 
1567
Here is how you can refer to the class of @code{String}, which in
1568
Java would be written @code{String.class}:
1569
 
1570
@example
1571
using namespace java::lang;
1572
doSomething (&String::class$);
1573
@end example
1574
 
1575
 
1576
@node Interfaces
1577
@section Interfaces
1578
 
1579
A Java class can @dfn{implement} zero or more
1580
@dfn{interfaces}, in addition to inheriting from
1581
a single base class.
1582
 
1583
@acronym{CNI} allows CNI code to implement methods of interfaces.
1584
You can also call methods through interface references, with some
1585
limitations.
1586
 
1587
@acronym{CNI} doesn't understand interface inheritance at all yet.  So,
1588
you can only call an interface method when the declared type of the
1589
field being called matches the interface which declares that
1590
method.  The workaround is to cast the interface reference to the right
1591
superinterface.
1592
 
1593
For example if you have:
1594
 
1595
@example
1596
interface A
1597
@{
1598
  void a();
1599
@}
1600
 
1601
interface B extends A
1602
@{
1603
  void b();
1604
@}
1605
@end example
1606
 
1607
and declare a variable of type @code{B} in C++, you can't call
1608
@code{a()} unless you cast it to an @code{A} first.
1609
 
1610
@node Objects and Classes
1611
@section Objects and Classes
1612
 
1613
@subsection Classes
1614
 
1615
All Java classes are derived from @code{java.lang.Object}.  C++ does
1616
not have a unique root class, but we use the C++ class
1617
@code{java::lang::Object} as the C++ version of the
1618
@code{java.lang.Object} Java class.  All other Java classes are mapped
1619
into corresponding C++ classes derived from @code{java::lang::Object}.
1620
 
1621
Interface inheritance (the @code{implements} keyword) is currently not
1622
reflected in the C++ mapping.
1623
 
1624
 
1625
@subsection Object fields
1626
 
1627
Each object contains an object header, followed by the instance fields
1628
of the class, in order.  The object header consists of a single
1629
pointer to a dispatch or virtual function table.  (There may be extra
1630
fields @emph{in front of} the object, for example for memory
1631
management, but this is invisible to the application, and the
1632
reference to the object points to the dispatch table pointer.)
1633
 
1634
The fields are laid out in the same order, alignment, and size as in
1635
C++.  Specifically, 8-bit and 16-bit native types (@code{byte},
1636
@code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
1637
to 32 bits.  Note that the Java VM does extend 8-bit and 16-bit types
1638
to 32 bits when on the VM stack or temporary registers.
1639
 
1640
If you include the @code{gcjh}-generated header for a
1641
class, you can access fields of Java classes in the @emph{natural}
1642
way.  For example, given the following Java class:
1643
 
1644
@example
1645
public class Int
1646
@{
1647
  public int i;
1648
  public Int (int i) @{ this.i = i; @}
1649
  public static Int zero = new Int(0);
1650
@}
1651
@end example
1652
 
1653
you can write:
1654
 
1655
@example
1656
#include <gcj/cni.h>;
1657
#include <Int>;
1658
 
1659
Int*
1660
mult (Int *p, jint k)
1661
@{
1662
  if (k == 0)
1663
    return Int::zero;  // @r{Static member access.}
1664
  return new Int(p->i * k);
1665
@}
1666
@end example
1667
 
1668
 
1669
@subsection Access specifiers
1670
 
1671
CNI does not strictly enforce the Java access
1672
specifiers, because Java permissions cannot be directly mapped
1673
into C++ permission.  Private Java fields and methods are mapped
1674
to private C++ fields and methods, but other fields and methods
1675
are mapped to public fields and methods.
1676
 
1677
 
1678
 
1679
@node Class Initialization
1680
@section Class Initialization
1681
 
1682
Java requires that each class be automatically initialized at the time
1683
of the first active use.  Initializing a class involves
1684
initializing the static fields, running code in class initializer
1685
methods, and initializing base classes.  There may also be
1686
some implementation specific actions, such as allocating
1687
@code{String} objects corresponding to string literals in
1688
the code.
1689
 
1690
The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
1691
places to ensure that a class is initialized when required.  The C++
1692
compiler does not insert these calls automatically---it is the
1693
programmer's responsibility to make sure classes are initialized.
1694
However, this is fairly painless because of the conventions assumed by
1695
the Java system.
1696
 
1697
First, @code{libgcj} will make sure a class is initialized before an
1698
instance of that object is created.  This is one of the
1699
responsibilities of the @code{new} operation.  This is taken care of
1700
both in Java code, and in C++ code.  When G++ sees a @code{new} of a
1701
Java class, it will call a routine in @code{libgcj} to allocate the
1702
object, and that routine will take care of initializing the class.
1703
Note however that this does not happen for Java arrays; you must
1704
allocate those using the appropriate CNI function.  It follows that
1705
you can access an instance field, or call an instance (non-static)
1706
method and be safe in the knowledge that the class and all of its base
1707
classes have been initialized.
1708
 
1709
Invoking a static method is also safe.  This is because the
1710
Java compiler adds code to the start of a static method to make sure
1711
the class is initialized.  However, the C++ compiler does not
1712
add this extra code.  Hence, if you write a native static method
1713
using CNI, you are responsible for calling @code{JvInitClass}
1714
before doing anything else in the method (unless you are sure
1715
it is safe to leave it out).
1716
 
1717
Accessing a static field also requires the class of the
1718
field to be initialized.  The Java compiler will generate code
1719
to call @code{JvInitClass} before getting or setting the field.
1720
However, the C++ compiler will not generate this extra code,
1721
so it is your responsibility to make sure the class is
1722
initialized before you access a static field from C++.
1723
 
1724
 
1725
@node Object allocation
1726
@section Object allocation
1727
 
1728
New Java objects are allocated using a
1729
@dfn{class instance creation expression}, e.g.:
1730
 
1731
@example
1732
new @var{Type} ( ... )
1733
@end example
1734
 
1735
The same syntax is used in C++.  The main difference is that
1736
C++ objects have to be explicitly deleted; in Java they are
1737
automatically deleted by the garbage collector.
1738
Using @acronym{CNI}, you can allocate a new Java object
1739
using standard C++ syntax and the C++ compiler will allocate
1740
memory from the garbage collector.  If you have overloaded
1741
constructors, the compiler will choose the correct one
1742
using standard C++ overload resolution rules.
1743
 
1744
@noindent For example:
1745
 
1746
@example
1747
java::util::Hashtable *ht = new java::util::Hashtable(120);
1748
@end example
1749
 
1750
 
1751
@node Memory allocation
1752
@section Memory allocation
1753
 
1754
When allocating memory in @acronym{CNI} methods it is best to handle
1755
out-of-memory conditions by throwing a Java exception.  These
1756
functions are provided for that purpose:
1757
 
1758
@deftypefun void* JvMalloc (jsize @var{size})
1759
Calls malloc.  Throws @code{java.lang.OutOfMemoryError} if allocation
1760
fails.
1761
@end deftypefun
1762
 
1763
@deftypefun void* JvRealloc (void* @var{ptr}, jsize @var{size})
1764
Calls realloc.  Throws @code{java.lang.OutOfMemoryError} if
1765
reallocation fails.
1766
@end deftypefun
1767
 
1768
@deftypefun void JvFree (void* @var{ptr})
1769
Calls free.
1770
@end deftypefun
1771
 
1772
@node Arrays
1773
@section Arrays
1774
 
1775
While in many ways Java is similar to C and C++, it is quite different
1776
in its treatment of arrays.  C arrays are based on the idea of pointer
1777
arithmetic, which would be incompatible with Java's security
1778
requirements.  Java arrays are true objects (array types inherit from
1779
@code{java.lang.Object}).  An array-valued variable is one that
1780
contains a reference (pointer) to an array object.
1781
 
1782
Referencing a Java array in C++ code is done using the
1783
@code{JArray} template, which as defined as follows:
1784
 
1785
@example
1786
class __JArray : public java::lang::Object
1787
@{
1788
public:
1789
  int length;
1790
@};
1791
 
1792
template<class T>
1793
class JArray : public __JArray
1794
@{
1795
  T data[0];
1796
public:
1797
  T& operator[](jint i) @{ return data[i]; @}
1798
@};
1799
@end example
1800
 
1801
 
1802
There are a number of @code{typedef}s which correspond to @code{typedef}s
1803
from the @acronym{JNI}.  Each is the type of an array holding objects
1804
of the relevant type:
1805
 
1806
@example
1807
typedef __JArray *jarray;
1808
typedef JArray<jobject> *jobjectArray;
1809
typedef JArray<jboolean> *jbooleanArray;
1810
typedef JArray<jbyte> *jbyteArray;
1811
typedef JArray<jchar> *jcharArray;
1812
typedef JArray<jshort> *jshortArray;
1813
typedef JArray<jint> *jintArray;
1814
typedef JArray<jlong> *jlongArray;
1815
typedef JArray<jfloat> *jfloatArray;
1816
typedef JArray<jdouble> *jdoubleArray;
1817
@end example
1818
 
1819
 
1820
@deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
1821
This template function can be used to get a pointer to the elements of
1822
the @code{array}.  For instance, you can fetch a pointer to the
1823
integers that make up an @code{int[]} like so:
1824
 
1825
@example
1826
extern jintArray foo;
1827
jint *intp = elements (foo);
1828
@end example
1829
 
1830
The name of this function may change in the future.
1831
@end deftypemethod
1832
 
1833
 
1834
@deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
1835
This creates a new array whose elements have reference type.
1836
@code{klass} is the type of elements of the array and
1837
@code{init} is the initial value put into every slot in the array.
1838
@end deftypefun
1839
 
1840
@example
1841
using namespace java::lang;
1842
JArray<String *> *array
1843
  = (JArray<String *> *) JvNewObjectArray(length, &String::class$, NULL);
1844
@end example
1845
 
1846
 
1847
@subsection Creating arrays
1848
 
1849
For each primitive type there is a function which can be used to
1850
create a new array of that type.  The name of the function is of the
1851
form:
1852
 
1853
@example
1854
JvNew@var{Type}Array
1855
@end example
1856
 
1857
@noindent For example:
1858
 
1859
@example
1860
JvNewBooleanArray
1861
@end example
1862
 
1863
@noindent can be used to create an array of Java primitive boolean types.
1864
 
1865
@noindent The following function definition is the template for all such functions:
1866
 
1867
@deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
1868
Creates an array @var{length} indices long.
1869
@end deftypefun
1870
 
1871
@deftypefun jsize JvGetArrayLength (jarray @var{array})
1872
Returns the length of the @var{array}.
1873
@end deftypefun
1874
 
1875
 
1876
@node Methods
1877
@section Methods
1878
 
1879
Java methods are mapped directly into C++ methods.
1880
The header files generated by @code{gcjh}
1881
include the appropriate method definitions.
1882
Basically, the generated methods have the same names and
1883
@emph{corresponding} types as the Java methods,
1884
and are called in the natural manner.
1885
 
1886
@subsection Overloading
1887
 
1888
Both Java and C++ provide method overloading, where multiple
1889
methods in a class have the same name, and the correct one is chosen
1890
(at compile time) depending on the argument types.
1891
The rules for choosing the correct method are (as expected) more complicated
1892
in C++ than in Java, but given a set of overloaded methods
1893
generated by @code{gcjh} the C++ compiler will choose
1894
the expected one.
1895
 
1896
Common assemblers and linkers are not aware of C++ overloading,
1897
so the standard implementation strategy is to encode the
1898
parameter types of a method into its assembly-level name.
1899
This encoding is called @dfn{mangling},
1900
and the encoded name is the @dfn{mangled name}.
1901
The same mechanism is used to implement Java overloading.
1902
For C++/Java interoperability, it is important that both the Java
1903
and C++ compilers use the @emph{same} encoding scheme.
1904
 
1905
@subsection Static methods
1906
 
1907
Static Java methods are invoked in @acronym{CNI} using the standard
1908
C++ syntax, using the @code{::} operator rather
1909
than the @code{.} operator.
1910
 
1911
@noindent For example:
1912
 
1913
@example
1914
jint i = java::lang::Math::round((jfloat) 2.3);
1915
@end example
1916
 
1917
@noindent C++ method definition syntax is used to define a static native method.
1918
For example:
1919
 
1920
@example
1921
#include <java/lang/Integer>
1922
java::lang::Integer*
1923
java::lang::Integer::getInteger(jstring str)
1924
@{
1925
  ...
1926
@}
1927
@end example
1928
 
1929
 
1930
@subsection Object Constructors
1931
 
1932
Constructors are called implicitly as part of object allocation
1933
using the @code{new} operator.
1934
 
1935
@noindent For example:
1936
 
1937
@example
1938
java::lang::Integer *x = new java::lang::Integer(234);
1939
@end example
1940
 
1941
Java does not allow a constructor to be a native method.
1942
This limitation can be coded round however because a constructor
1943
can @emph{call} a native method.
1944
 
1945
 
1946
@subsection Instance methods
1947
 
1948
Calling a Java instance method from a C++ @acronym{CNI} method is done
1949
using the standard C++ syntax, e.g.:
1950
 
1951
@example
1952
// @r{First create the Java object.}
1953
java::lang::Integer *x = new java::lang::Integer(234);
1954
// @r{Now call a method.}
1955
jint prim_value = x->intValue();
1956
if (x->longValue == 0)
1957
  ...
1958
@end example
1959
 
1960
@noindent Defining a Java native instance method is also done the natural way:
1961
 
1962
@example
1963
#include <java/lang/Integer.h>
1964
 
1965
jdouble
1966
java::lang:Integer::doubleValue()
1967
@{
1968
  return (jdouble) value;
1969
@}
1970
@end example
1971
 
1972
 
1973
@subsection Interface methods
1974
 
1975
In Java you can call a method using an interface reference.  This is
1976
supported, but not completely.  @xref{Interfaces}.
1977
 
1978
 
1979
 
1980
 
1981
@node Strings
1982
@section Strings
1983
 
1984
@acronym{CNI} provides a number of utility functions for
1985
working with Java Java @code{String} objects.
1986
The names and interfaces are analogous to those of @acronym{JNI}.
1987
 
1988
 
1989
@deftypefun jstring JvNewString (const jchar* @var{chars}, jsize @var{len})
1990
Returns a Java @code{String} object with characters from the array of
1991
Unicode characters @var{chars} up to the index @var{len} in that array.
1992
@end deftypefun
1993
 
1994
@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
1995
Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
1996
@end deftypefun
1997
 
1998
 
1999
@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
2000
As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
2001
@end deftypefun
2002
 
2003
@deftypefun jstring JvNewStringUTF (const char* @var{bytes})
2004
Returns a @code{String} which is made up of the UTF encoded characters
2005
present in the C string @var{bytes}.
2006
@end deftypefun
2007
 
2008
@deftypefun jchar* JvGetStringChars (jstring @var{str})
2009
Returns a pointer to an array of characters making up the @code{String} @var{str}.
2010
@end deftypefun
2011
 
2012
@deftypefun int JvGetStringUTFLength (jstring @var{str})
2013
Returns the number of bytes required to encode the contents of the
2014
@code{String} @var{str} in UTF-8.
2015
@end deftypefun
2016
 
2017
@deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
2018
Puts the UTF-8 encoding of a region of the @code{String} @var{str} into
2019
the buffer @code{buf}.  The region to fetch is marked by @var{start} and @var{len}.
2020
 
2021
Note that @var{buf} is a buffer, not a C string.  It is @emph{not}
2022
null terminated.
2023
@end deftypefun
2024
 
2025
 
2026
@node Mixing with C++
2027
@section Interoperating with C/C++
2028
 
2029
Because @acronym{CNI} is designed to represent Java classes and methods it
2030
cannot be mixed readily with C/C++ types.
2031
 
2032
One important restriction is that Java classes cannot have non-Java
2033
type instance or static variables and cannot have methods which take
2034
non-Java types as arguments or return non-Java types.
2035
 
2036
@noindent None of the following is possible with CNI:
2037
 
2038
@example
2039
 
2040
class ::MyClass : public java::lang::Object
2041
@{
2042
   char* variable;  // @r{char* is not a valid Java type.}
2043
@}
2044
 
2045
 
2046
uint
2047
::SomeClass::someMethod (char *arg)
2048
@{
2049
  .
2050
  .
2051
  .
2052
@}   // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
2053
@end example
2054
 
2055
@noindent Of course, it is ok to use C/C++ types within the scope of a method:
2056
 
2057
 
2058
@example
2059
jint
2060
::SomeClass::otherMethod (jstring str)
2061
@{
2062
   char *arg = ...
2063
   .
2064
   .
2065
   .
2066
@}
2067
@end example
2068
 
2069
@subsection RawData
2070
 
2071
The above restriction can be problematic, so @acronym{CNI} includes the
2072
@code{gnu.gcj.RawData} class.  The @code{RawData} class is a
2073
@dfn{non-scanned reference} type.  In other words variables declared
2074
of type @code{RawData} can contain any data and are not checked by the
2075
compiler or memory manager in any way.
2076
 
2077
This means that you can put C/C++ data structures (including classes)
2078
in your @acronym{CNI} classes, as long as you use the appropriate cast.
2079
 
2080
@noindent Here are some examples:
2081
 
2082
@example
2083
 
2084
class ::MyClass : public java::lang::Object
2085
@{
2086
   gnu.gcj.RawData string;
2087
 
2088
   MyClass ();
2089
   gnu.gcj.RawData getText ();
2090
   void printText ();
2091
@}
2092
 
2093
::MyClass::MyClass ()
2094
@{
2095
   char* text = ...
2096
   string = text;
2097
@}
2098
 
2099
gnu.gcj.RawData
2100
::MyClass::getText ()
2101
@{
2102
   return string;
2103
@}
2104
 
2105
void
2106
::MyClass::printText ()
2107
@{
2108
  printf("%s\n", (char*) string);
2109
@}
2110
@end example
2111
 
2112
 
2113
@subsection RawDataManaged
2114
 
2115
@code{gnu.gcj.RawDataManaged} is another type used to indicate special data used
2116
by native code. Unlike the @code{RawData} type, fields declared as
2117
@code{RawDataManaged} will be "marked" by the memory manager and
2118
considered for garbage collection.
2119
 
2120
Native data which is allocated using CNI's @code{JvAllocBytes()}
2121
function and stored in a @code{RawDataManaged} will be automatically
2122
freed when the Java object it is associated with becomes unreachable.
2123
 
2124
@subsection Native memory allocation
2125
 
2126
@deftypefun void* JvAllocBytes (jsize @var{size})
2127
Allocates @var{size} bytes from the heap.  The memory returned is zeroed.
2128
This memory is not scanned for pointers by the garbage collector, but will
2129
be freed if no references to it are discovered.
2130
 
2131
This function can be useful if you need to associate some native data with a
2132
Java object. Using a CNI's special @code{RawDataManaged} type, native data
2133
allocated with @code{JvAllocBytes} will be automatically freed when the Java
2134
object itself becomes unreachable.
2135
@end deftypefun
2136
 
2137
@subsection Posix signals
2138
 
2139
On Posix based systems the @code{libgcj} library uses several signals
2140
internally.  @acronym{CNI} code should not attempt to use the same
2141
signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
2142
code to fail.
2143
 
2144
SIGSEGV is used on many systems to generate
2145
@code{NullPointerExceptions}.  SIGCHLD is used internally by
2146
@code{Runtime.exec()}.  Several other signals (that vary from platform to
2147
platform) can be used by the memory manager and by
2148
@code{Thread.interrupt()}.
2149
 
2150
@node Exception Handling
2151
@section Exception Handling
2152
 
2153
While C++ and Java share a common exception handling framework,
2154
things are not yet perfectly integrated.  The main issue is that the
2155
run-time type information facilities of the two
2156
languages are not integrated.
2157
 
2158
Still, things work fairly well.  You can throw a Java exception from
2159
C++ using the ordinary @code{throw} construct, and this
2160
exception can be caught by Java code.  Similarly, you can catch an
2161
exception thrown from Java using the C++ @code{catch}
2162
construct.
2163
 
2164
@noindent Here is an example:
2165
 
2166
@example
2167
if (i >= count)
2168
   throw new java::lang::IndexOutOfBoundsException();
2169
@end example
2170
 
2171
Normally, G++ will automatically detect when you are writing C++
2172
code that uses Java exceptions, and handle them appropriately.
2173
However, if C++ code only needs to execute destructors when Java
2174
exceptions are thrown through it, GCC will guess incorrectly.  Sample
2175
problematic code:
2176
 
2177
@example
2178
struct S @{ ~S(); @};
2179
 
2180
extern void bar();    // @r{Is implemented in Java and may throw exceptions.}
2181
 
2182
void foo()
2183
@{
2184
  S s;
2185
  bar();
2186
@}
2187
@end example
2188
 
2189
The usual effect of an incorrect guess is a link failure, complaining of
2190
a missing routine called @code{__gxx_personality_v0}.
2191
 
2192
You can inform the compiler that Java exceptions are to be used in a
2193
translation unit, irrespective of what it might think, by writing
2194
@code{#pragma GCC java_exceptions} at the head of the
2195
file.  This @code{#pragma} must appear before any
2196
functions that throw or catch exceptions, or run destructors when
2197
exceptions are thrown through them.
2198
 
2199
@node Synchronization
2200
@section Synchronization
2201
 
2202
Each Java object has an implicit monitor.
2203
The Java VM uses the instruction @code{monitorenter} to acquire
2204
and lock a monitor, and @code{monitorexit} to release it.
2205
 
2206
The corresponding CNI macros are @code{JvMonitorEnter} and
2207
@code{JvMonitorExit} (JNI has similar  methods @code{MonitorEnter}
2208
and @code{MonitorExit}).
2209
 
2210
 
2211
The Java source language does not provide direct access to these primitives.
2212
Instead, there is a @code{synchronized} statement that does an
2213
implicit @code{monitorenter} before entry to the block,
2214
and does a @code{monitorexit} on exit from the block.
2215
Note that the lock has to be released even when the block is abnormally
2216
terminated by an exception, which means there is an implicit
2217
@code{try finally} surrounding synchronization locks.
2218
 
2219
From C++, it makes sense to use a destructor to release a lock.
2220
@acronym{CNI} defines the following utility class:
2221
 
2222
@example
2223
class JvSynchronize() @{
2224
  jobject obj;
2225
  JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
2226
  ~JvSynchronize() @{ JvMonitorExit(obj); @}
2227
@};
2228
@end example
2229
 
2230
So this Java code:
2231
 
2232
@example
2233
synchronized (OBJ)
2234
@{
2235
   CODE
2236
@}
2237
@end example
2238
 
2239
@noindent might become this C++ code:
2240
 
2241
@example
2242
@{
2243
   JvSynchronize dummy (OBJ);
2244
   CODE;
2245
@}
2246
@end example
2247
 
2248
Java also has methods with the @code{synchronized} attribute.
2249
This is equivalent to wrapping the entire method body in a
2250
@code{synchronized} statement.
2251
(Alternatively, an implementation could require the caller to do
2252
the synchronization.  This is not practical for a compiler, because
2253
each virtual method call would have to test at run-time if
2254
synchronization is needed.)  Since in @command{gcj}
2255
the @code{synchronized} attribute is handled by the
2256
method implementation, it is up to the programmer
2257
of a synchronized native method to handle the synchronization
2258
(in the C++ implementation of the method).
2259
In other words, you need to manually add @code{JvSynchronize}
2260
in a @code{native synchronized} method.
2261
 
2262
@node Invocation
2263
@section Invocation
2264
 
2265
CNI permits C++ applications to make calls into Java classes, in addition to
2266
allowing Java code to call into C++. Several functions, known as the
2267
@dfn{invocation API}, are provided to support this.
2268
 
2269
@deftypefun jint JvCreateJavaVM (JvVMInitArgs* @var{vm_args})
2270
 
2271
Initializes the Java runtime. This function performs essential initialization
2272
of the threads interface, garbage collector, exception handling and other key
2273
aspects of the runtime. It must be called once by an application with
2274
a non-Java @code{main()} function, before any other Java or CNI calls are made.
2275
It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
2276
once provided it is only called from a single thread.
2277
The @var{vmargs} parameter can be used to specify initialization parameters
2278
for the Java runtime. It may be @code{NULL}.
2279
 
2280
JvVMInitArgs represents a list of virtual machine initialization
2281
arguments. @code{JvCreateJavaVM()} ignores the version field.
2282
 
2283
@example
2284
typedef struct JvVMOption
2285
@{
2286
  // a VM initialization option
2287
  char* optionString;
2288
  // extra information associated with this option
2289
  void* extraInfo;
2290
@} JvVMOption;
2291
 
2292
typedef struct JvVMInitArgs
2293
@{
2294
  // for compatibility with JavaVMInitArgs
2295
  jint version;
2296
 
2297
  // number of VM initialization options
2298
  jint nOptions;
2299
 
2300
  // an array of VM initialization options
2301
  JvVMOption* options;
2302
 
2303
  // true if the option parser should ignore unrecognized options
2304
  jboolean ignoreUnrecognized;
2305
@} JvVMInitArgs;
2306
@end example
2307
 
2308
@code{JvCreateJavaVM()} returns @code{0} upon success, or @code{-1} if
2309
the runtime is already initialized.
2310
 
2311
@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It
2312
is recognized and used as of release 4.0.
2313
@end deftypefun
2314
 
2315
@deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
2316
Registers an existing thread with the Java runtime.  This must be called once
2317
from each thread, before that thread makes any other Java or CNI calls. It
2318
must be called after @code{JvCreateJavaVM}.
2319
@var{name} specifies a name for the thread. It may be @code{NULL}, in which
2320
case a name will be generated.
2321
@var{group} is the ThreadGroup in which this thread will be a member. If it
2322
is @code{NULL}, the thread will be a member of the main thread group.
2323
The return value is the Java @code{Thread} object that represents the thread.
2324
It is safe to call @code{JvAttachCurrentThread()} more than once from the same
2325
thread. If the thread is already attached, the call is ignored and the current
2326
thread object is returned.
2327
@end deftypefun
2328
 
2329
@deftypefun jint JvDetachCurrentThread ()
2330
Unregisters a thread from the Java runtime. This should be called by threads
2331
that were attached using @code{JvAttachCurrentThread()}, after they have
2332
finished making calls to Java code. This ensures that any resources associated
2333
with the thread become eligible for garbage collection.
2334
This function returns @code{0} upon success, or @code{-1} if the current thread
2335
is not attached.
2336
@end deftypefun
2337
 
2338
@subsection Handling uncaught exceptions
2339
 
2340
If an exception is thrown from Java code called using the invocation API, and
2341
no handler for the exception can be found, the runtime will abort the
2342
application. In order to make the application more robust, it is recommended
2343
that code which uses the invocation API be wrapped by a top-level try/catch
2344
block that catches all Java exceptions.
2345
 
2346
@subsection Example
2347
 
2348
The following code demonstrates the use of the invocation API. In this
2349
example, the C++ application initializes the Java runtime and attaches
2350
itself. The @code{java.lang.System} class is initialized in order to
2351
access its @code{out} field, and a Java string is printed. Finally, the thread
2352
is detached from the runtime once it has finished making Java calls. Everything
2353
is wrapped with a try/catch block to provide a default handler for any uncaught
2354
exceptions.
2355
 
2356
The example can be compiled with @command{c++ -c test.cc; gcj test.o}.
2357
 
2358
@example
2359
// test.cc
2360
#include <gcj/cni.h>
2361
#include <java/lang/System.h>
2362
#include <java/io/PrintStream.h>
2363
#include <java/lang/Throwable.h>
2364
 
2365
int main(int argc, char *argv[])
2366
@{
2367
  using namespace java::lang;
2368
 
2369
  try
2370
  @{
2371
    JvCreateJavaVM(NULL);
2372
    JvAttachCurrentThread(NULL, NULL);
2373
 
2374
    String *message = JvNewStringLatin1("Hello from C++");
2375
    JvInitClass(&System::class$);
2376
    System::out->println(message);
2377
 
2378
    JvDetachCurrentThread();
2379
  @}
2380
  catch (Throwable *t)
2381
  @{
2382
    System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
2383
    t->printStackTrace();
2384
  @}
2385
@}
2386
@end example
2387
 
2388
@node Reflection
2389
@section Reflection
2390
 
2391
Reflection is possible with CNI code, it functions similarly to how it
2392
functions with JNI@.
2393
 
2394
@c clean this up...  I mean, what are the types jfieldID and jmethodID in JNI?
2395
The types @code{jfieldID} and @code{jmethodID}
2396
are as in JNI@.
2397
 
2398
@noindent The functions:
2399
 
2400
@itemize
2401
@item @code{JvFromReflectedField},
2402
@item @code{JvFromReflectedMethod},
2403
@item @code{JvToReflectedField}
2404
@item @code{JvToFromReflectedMethod}
2405
@end itemize
2406
 
2407
@noindent will be added shortly, as will other functions corresponding to JNI@.
2408
 
2409
 
2410
@node System properties
2411
@chapter System properties
2412
 
2413
The runtime behavior of the @code{libgcj} library can be modified by setting
2414
certain system properties.  These properties can be compiled into the program
2415
using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
2416
setting them explicitly in the program by calling the
2417
@code{java.lang.System.setProperty()} method.  Some system properties are only
2418
used for informational purposes (like giving a version number or a user name).
2419
A program can inspect the current value of a property by calling the
2420
@code{java.lang.System.getProperty()} method.
2421
 
2422
@menu
2423
* Standard Properties::         Standard properties supported by @code{libgcj}
2424
* GNU Classpath Properties::    Properties found in Classpath based libraries
2425
* libgcj Runtime Properties::   Properties specific to @code{libgcj}
2426
@end menu
2427
 
2428
@node Standard Properties
2429
@section Standard Properties
2430
 
2431
The following properties are normally found in all implementations of the core
2432
libraries for the Java language.
2433
 
2434
@table @gcctabopt
2435
 
2436
@item java.version
2437
The @code{libgcj} version number.
2438
 
2439
@item java.vendor
2440
Set to @samp{The Free Software Foundation, Inc.}
2441
 
2442
@item java.vendor.url
2443
Set to @uref{http://gcc.gnu.org/java/}.
2444
 
2445
@item java.home
2446
The directory where @code{gcj} was installed.  Taken from the @code{--prefix}
2447
option given to @command{configure}.
2448
 
2449
@item java.class.version
2450
The class format version number supported by the libgcj byte code interpreter.
2451
(Currently @samp{46.0})
2452
 
2453
@item java.vm.specification.version
2454
The Virtual Machine Specification version implemented by @code{libgcj}.
2455
(Currently @samp{1.0})
2456
 
2457
@item java.vm.specification.vendor
2458
The name of the Virtual Machine specification designer.
2459
 
2460
@item java.vm.specification.name
2461
The name of the Virtual Machine specification
2462
(Set to @samp{Java Virtual Machine Specification}).
2463
 
2464
@item java.vm.version
2465
The @command{gcj} version number.
2466
 
2467
@item java.vm.vendor
2468
Set to @samp{The Free Software Foundation, Inc.}
2469
 
2470
@item java.vm.name
2471
Set to @samp{GNU libgcj}.
2472
 
2473
@item java.specification.version
2474
The Runtime Environment specification version implemented by @code{libgcj}.
2475
(Currently set to @samp{1.3})
2476
 
2477
@item java.specification.vendor
2478
The Runtime Environment specification designer.
2479
 
2480
@item java.specification.name
2481
The name of the Runtime Environment specification
2482
(Set to @samp{Java Platform API Specification}).
2483
 
2484
@item java.class.path
2485
The paths (jar files, zip files and directories) used for finding class files.
2486
 
2487
@item java.library.path
2488
Directory path used for finding native libraries.
2489
 
2490
@item java.io.tmpdir
2491
The directory used to put temporary files in.
2492
 
2493
@item java.compiler
2494
Name of the Just In Time compiler to use by the byte code interpreter.
2495
Currently not used in @code{libgcj}.
2496
 
2497
@item java.ext.dirs
2498
Directories containing jar files with extra libraries.  Will be used when
2499
resolving classes.
2500
 
2501
@item java.protocol.handler.pkgs
2502
A @samp{|} separated list of package names that is used to find classes that
2503
implement handlers for @code{java.net.URL}.
2504
 
2505
@item java.rmi.server.codebase
2506
A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
2507
to load classes from.
2508
 
2509
@item jdbc.drivers
2510
A list of class names that will be loaded by the @code{java.sql.DriverManager}
2511
when it starts up.
2512
 
2513
@item file.separator
2514
The separator used in when directories are included in a filename
2515
(normally @samp{/} or @samp{\} ).
2516
 
2517
@item file.encoding
2518
The default character encoding used when converting platform native files to
2519
Unicode (usually set to @samp{8859_1}).
2520
 
2521
@item path.separator
2522
The standard separator used when a string contains multiple paths
2523
(normally @samp{:} or @samp{;}), the string is usually not a valid character
2524
to use in normal directory names.)
2525
 
2526
@item line.separator
2527
The default line separator used on the platform (normally @samp{\n}, @samp{\r}
2528
or a combination of those two characters).
2529
 
2530
@item policy.provider
2531
The class name used for the default policy provider returned by
2532
@code{java.security.Policy.getPolicy}.
2533
 
2534
@item user.name
2535
The name of the user running the program.  Can be the full name, the login name
2536
or empty if unknown.
2537
 
2538
@item user.home
2539
The default directory to put user specific files in.
2540
 
2541
@item user.dir
2542
The current working directory from which the program was started.
2543
 
2544
@item user.language
2545
The default language as used by the @code{java.util.Locale} class.
2546
 
2547
@item user.region
2548
The default region as used by the @code{java.util.Local} class.
2549
 
2550
@item user.variant
2551
The default variant of the language and region local used.
2552
 
2553
@item user.timezone
2554
The default timezone as used by the @code{java.util.TimeZone} class.
2555
 
2556
@item os.name
2557
The operating system/kernel name that the program runs on.
2558
 
2559
@item os.arch
2560
The hardware that we are running on.
2561
 
2562
@item os.version
2563
The version number of the operating system/kernel.
2564
 
2565
@item awt.appletWarning
2566
The string to display when an untrusted applet is displayed.
2567
Returned by @code{java.awt.Window.getWarningString()} when the window is
2568
``insecure''.
2569
 
2570
@item awt.toolkit
2571
The class name used for initializing the default @code{java.awt.Toolkit}.
2572
Defaults to @code{gnu.awt.gtk.GtkToolkit}.
2573
 
2574
@item http.proxyHost
2575
Name of proxy host for http connections.
2576
 
2577
@item http.proxyPort
2578
Port number to use when a proxy host is in use.
2579
 
2580
@end table
2581
 
2582
@node GNU Classpath Properties
2583
@section GNU Classpath Properties
2584
 
2585
@code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
2586
GNU project to create free core class libraries for use with virtual machines
2587
and compilers for the Java language.  The following properties are common to
2588
libraries based on GNU Classpath.
2589
 
2590
@table @gcctabopt
2591
 
2592
@item gcj.dumpobject
2593
Enables printing serialization debugging by the @code{java.io.ObjectInput} and
2594
@code{java.io.ObjectOutput} classes when set to something else then the empty
2595
string.  Only used when running a debug build of the library.
2596
 
2597
@item gnu.classpath.vm.shortname
2598
This is a succinct name of the virtual machine.  For @code{libgcj},
2599
this will always be @samp{libgcj}.
2600
 
2601
@item gnu.classpath.home.url
2602
A base URL used for finding system property files (e.g.,
2603
@file{classpath.security}).  By default this is a @samp{file:} URL
2604
pointing to the @file{lib} directory under @samp{java.home}.
2605
 
2606
@end table
2607
 
2608
@node libgcj Runtime Properties
2609
@section libgcj Runtime Properties
2610
 
2611
The following properties are specific to the @code{libgcj} runtime and will
2612
normally not be found in other core libraries for the java language.
2613
 
2614
@table @gcctabopt
2615
 
2616
@item java.fullversion
2617
The combination of @code{java.vm.name} and @code{java.vm.version}.
2618
 
2619
@item java.vm.info
2620
Same as @code{java.fullversion}.
2621
 
2622
@item impl.prefix
2623
Used by the @code{java.net.DatagramSocket} class when set to something else
2624
then the empty string.  When set all newly created @code{DatagramSocket}s will
2625
try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
2626
the normal @code{java.net.PlainDatagramSocketImpl}.
2627
 
2628
@item gnu.gcj.progname
2629
The class or binary name that was used to invoke the program. This will be
2630
the name of the "main" class in the case where the @code{gij} front end is
2631
used, or the program binary name in the case where an application is compiled
2632
to a native binary.
2633
 
2634
@item gnu.gcj.user.realname
2635
The real name of the user, as taken from the password file.  This may
2636
not always hold only the user's name (as some sites put extra
2637
information in this field).  Also, this property is not available on
2638
all platforms.
2639
 
2640
@item gnu.gcj.runtime.NameFinder.use_addr2line
2641
Whether an external process, @command{addr2line}, should be used to determine
2642
line number information when tracing the stack. Setting this to @code{false}
2643
may suppress line numbers when printing stack traces and when using
2644
the java.util.logging infrastructure. However, performance may improve
2645
significantly for applications that print stack traces or make logging calls
2646
frequently.
2647
 
2648
@item gnu.gcj.runtime.NameFinder.show_raw
2649
Whether the address of a stack frame should be printed when the line
2650
number is unavailable. Setting this to @code{true} will cause the name
2651
of the object and the offset within that object to be printed when no
2652
line number is available.  This allows for off-line decoding of
2653
stack traces if necessary debug information is available.  The default
2654
is @code{false}, no raw addresses are printed.
2655
 
2656
@item gnu.gcj.runtime.NameFinder.remove_unknown
2657
Whether stack frames for non-java code should be included in a stack
2658
trace.  The default value is @code{true}, stack frames for non-java
2659
code are suppressed.  Setting this to @code{false} will cause any
2660
non-java stack frames to be printed in addition to frames for the java
2661
code.
2662
 
2663
@item gnu.gcj.runtime.VMClassLoader.library_control
2664
This controls how shared libraries are automatically loaded by the
2665
built-in class loader.  If this property is set to @samp{full}, a full
2666
search is done for each requested class.  If this property is set to
2667
@samp{cache}, then any failed lookups are cached and not tried again.
2668
If this property is set to @samp{never} (the default), then lookups
2669
are never done.  For more information, @xref{Extensions}.
2670
 
2671
@item gnu.gcj.runtime.endorsed.dirs
2672
This is like the standard @code{java.endorsed.dirs}, property, but
2673
specifies some extra directories which are searched after the standard
2674
endorsed directories.  This is primarily useful for telling
2675
@code{libgcj} about additional libraries which are ordinarily
2676
incorporated into the JDK, and which should be loaded by the bootstrap
2677
class loader, but which are not yet part of @code{libgcj} itself for
2678
some reason.
2679
 
2680
@item gnu.gcj.jit.compiler
2681
@c FIXME we should probably have a whole node on this...
2682
This is the full path to @command{gcj} executable which should be
2683
used to compile classes just-in-time when
2684
@code{ClassLoader.defineClass} is called.  If not set, @command{gcj}
2685
will not be invoked by the runtime; this can also be controlled via
2686
@code{Compiler.disable}.
2687
 
2688
@item gnu.gcj.jit.options
2689
This is a space-separated string of options which should be passed to
2690
@command{gcj} when in JIT mode.  If not set, a sensible default is
2691
chosen.
2692
 
2693
@item gnu.gcj.jit.cachedir
2694
This is the directory where cached shared library files are
2695
stored.  If not set, JIT compilation is disabled.  This should never
2696
be set to a directory that is writable by any other user.
2697
 
2698
@item gnu.gcj.precompiled.db.path
2699
This is a sequence of file names, each referring to a file created by
2700
@command{gcj-dbtool}.  These files will be used by @code{libgcj} to
2701
find shared libraries corresponding to classes that are loaded from
2702
bytecode.  @code{libgcj} often has a built-in default database; it
2703
can be queried using @code{gcj-dbtool -p}.
2704
 
2705
@end table
2706
 
2707
 
2708
@node Resources
2709
@chapter Resources
2710
 
2711
While writing @command{gcj} and @code{libgcj} we have, of course, relied
2712
heavily on documentation from Sun Microsystems.  In particular we have
2713
used The Java Language Specification (both first and second editions),
2714
the Java Class Libraries (volumes one and two), and the Java Virtual
2715
Machine Specification.  In addition we've used the online documentation
2716
at @uref{http://java.sun.com/}.
2717
 
2718
The current @command{gcj} home page is
2719
@uref{http://gcc.gnu.org/java/}.
2720
 
2721
For more information on gcc, see @uref{http://gcc.gnu.org/}.
2722
 
2723
Some @code{libgcj} testing is done using the Mauve test suite.  This is
2724
a free software Java class library test suite which is being written
2725
because the JCK is not free.  See
2726
@uref{http://sources.redhat.com/mauve/} for more information.
2727
 
2728
 
2729
@node Index
2730
@unnumbered Index
2731
 
2732
@printindex cp
2733
 
2734
@bye

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.