1*c87b03e5Sespie\input texinfo @c -*-texinfo-*- 2*c87b03e5Sespie@setfilename gcj.info 3*c87b03e5Sespie@settitle Guide to GNU gcj 4*c87b03e5Sespie 5*c87b03e5Sespie@include gcc-common.texi 6*c87b03e5Sespie 7*c87b03e5Sespie@c Note: When reading this manual you'll find lots of strange 8*c87b03e5Sespie@c circumlocutions like ``compiler for the Java language''. 9*c87b03e5Sespie@c This is necessary due to Sun's restrictions on the use of 10*c87b03e5Sespie@c the word ``Java'. 11*c87b03e5Sespie 12*c87b03e5Sespie@c When this manual is copyrighted. 13*c87b03e5Sespie@set copyrights-gcj 2001, 2002 14*c87b03e5Sespie 15*c87b03e5Sespie@c Versions 16*c87b03e5Sespie@set which-gcj GCC-@value{version-GCC} 17*c87b03e5Sespie 18*c87b03e5Sespie@copying 19*c87b03e5Sespie@c man begin COPYRIGHT 20*c87b03e5SespieCopyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc. 21*c87b03e5Sespie 22*c87b03e5SespiePermission is granted to copy, distribute and/or modify this document 23*c87b03e5Sespieunder the terms of the GNU Free Documentation License, Version 1.2 or 24*c87b03e5Sespieany later version published by the Free Software Foundation; with the 25*c87b03e5SespieInvariant Sections being ``GNU General Public License'', the Front-Cover 26*c87b03e5Sespietexts being (a) (see below), and with the Back-Cover Texts being (b) 27*c87b03e5Sespie(see below). A copy of the license is included in the 28*c87b03e5Sespie@c man end 29*c87b03e5Sespiesection entitled 30*c87b03e5Sespie``GNU Free Documentation License''. 31*c87b03e5Sespie@ignore 32*c87b03e5Sespie@c man begin COPYRIGHT 33*c87b03e5Sespieman page gfdl(7). 34*c87b03e5Sespie@c man end 35*c87b03e5Sespie@end ignore 36*c87b03e5Sespie 37*c87b03e5Sespie@c man begin COPYRIGHT 38*c87b03e5Sespie 39*c87b03e5Sespie(a) The FSF's Front-Cover Text is: 40*c87b03e5Sespie 41*c87b03e5Sespie A GNU Manual 42*c87b03e5Sespie 43*c87b03e5Sespie(b) The FSF's Back-Cover Text is: 44*c87b03e5Sespie 45*c87b03e5Sespie You have freedom to copy and modify this GNU Manual, like GNU 46*c87b03e5Sespie software. Copies published by the Free Software Foundation raise 47*c87b03e5Sespie funds for GNU development. 48*c87b03e5Sespie@c man end 49*c87b03e5Sespie@end copying 50*c87b03e5Sespie 51*c87b03e5Sespie@ifinfo 52*c87b03e5Sespie@format 53*c87b03e5Sespie@dircategory Programming 54*c87b03e5Sespie@direntry 55*c87b03e5Sespie* Gcj: (gcj). Ahead-of-time compiler for the Java language 56*c87b03e5Sespie@end direntry 57*c87b03e5Sespie 58*c87b03e5Sespie@dircategory Individual utilities 59*c87b03e5Sespie@direntry 60*c87b03e5Sespie* gcjh: (gcj)Invoking gcjh. 61*c87b03e5Sespie Generate header files from Java class files 62*c87b03e5Sespie* jv-scan: (gcj)Invoking jv-scan. 63*c87b03e5Sespie Print information about Java source files 64*c87b03e5Sespie* jcf-dump: (gcj)Invoking jcf-dump. 65*c87b03e5Sespie Print information about Java class files 66*c87b03e5Sespie* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode 67*c87b03e5Sespie* jv-convert: (gcj)Invoking jv-convert. 68*c87b03e5Sespie Convert file from one encoding to another 69*c87b03e5Sespie* rmic: (gcj)Invoking rmic. 70*c87b03e5Sespie Generate stubs for Remote Method Invocation. 71*c87b03e5Sespie* rmiregistry: (gcj)Invoking rmiregistry. 72*c87b03e5Sespie The remote object registry. 73*c87b03e5Sespie@end direntry 74*c87b03e5Sespie@end format 75*c87b03e5Sespie 76*c87b03e5Sespie@insertcopying 77*c87b03e5Sespie@end ifinfo 78*c87b03e5Sespie 79*c87b03e5Sespie@titlepage 80*c87b03e5Sespie@title GNU gcj 81*c87b03e5Sespie@author Tom Tromey 82*c87b03e5Sespie 83*c87b03e5Sespie@page 84*c87b03e5Sespie@vskip 0pt plus 1filll 85*c87b03e5SespieFor the @value{which-gcj} Version* 86*c87b03e5Sespie@sp 1 87*c87b03e5SespiePublished by the Free Software Foundation @* 88*c87b03e5Sespie59 Temple Place - Suite 330@* 89*c87b03e5SespieBoston, MA 02111-1307, USA@* 90*c87b03e5Sespie@sp 1 91*c87b03e5Sespie@insertcopying 92*c87b03e5Sespie@end titlepage 93*c87b03e5Sespie@contents 94*c87b03e5Sespie@page 95*c87b03e5Sespie 96*c87b03e5Sespie 97*c87b03e5Sespie@node Top 98*c87b03e5Sespie@top Introduction 99*c87b03e5Sespie 100*c87b03e5SespieThis manual describes how to use @command{gcj}, the GNU compiler for the 101*c87b03e5SespieJava programming language. @command{gcj} can generate both @file{.class} 102*c87b03e5Sespiefiles and object files, and it can read both Java source code and 103*c87b03e5Sespie@file{.class} files. 104*c87b03e5Sespie 105*c87b03e5Sespie@menu 106*c87b03e5Sespie* Copying:: The GNU General Public License 107*c87b03e5Sespie* GNU Free Documentation License:: 108*c87b03e5Sespie How you can share and copy this manual 109*c87b03e5Sespie* Invoking gcj:: Compiler options supported by @command{gcj} 110*c87b03e5Sespie* Compatibility:: Compatibility between gcj and other tools for Java 111*c87b03e5Sespie* Invoking gcjh:: Generate header files from class files 112*c87b03e5Sespie* Invoking jv-scan:: Print information about source files 113*c87b03e5Sespie* Invoking jcf-dump:: Print information about class files 114*c87b03e5Sespie* Invoking gij:: Interpreting Java bytecodes 115*c87b03e5Sespie* Invoking jv-convert:: Converting from one encoding to another 116*c87b03e5Sespie* Invoking rmic:: Generate stubs for Remote Method Invocation. 117*c87b03e5Sespie* Invoking rmiregistry:: The remote object registry. 118*c87b03e5Sespie* About CNI:: Description of the Cygnus Native Interface 119*c87b03e5Sespie* System properties:: Modifying runtime behavior of the libgcj library 120*c87b03e5Sespie* Resources:: Where to look for more information 121*c87b03e5Sespie@end menu 122*c87b03e5Sespie 123*c87b03e5Sespie 124*c87b03e5Sespie@include gpl.texi 125*c87b03e5Sespie 126*c87b03e5Sespie@include fdl.texi 127*c87b03e5Sespie 128*c87b03e5Sespie 129*c87b03e5Sespie@node Invoking gcj 130*c87b03e5Sespie@chapter Invoking gcj 131*c87b03e5Sespie 132*c87b03e5Sespie@c man title gcj Ahead-of-time compiler for the Java language 133*c87b03e5Sespie 134*c87b03e5Sespie@ignore 135*c87b03e5Sespie@c man begin SYNOPSIS gcj 136*c87b03e5Sespiegcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}] 137*c87b03e5Sespie [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}] 138*c87b03e5Sespie [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}] 139*c87b03e5Sespie [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}] 140*c87b03e5Sespie [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}] 141*c87b03e5Sespie [@option{-W}@var{warn}@dots{}] 142*c87b03e5Sespie @var{sourcefile}@dots{} 143*c87b03e5Sespie@c man end 144*c87b03e5Sespie@c man begin SEEALSO gcj 145*c87b03e5Sespiegcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7), 146*c87b03e5Sespieand the Info entries for @file{gcj} and @file{gcc}. 147*c87b03e5Sespie@c man end 148*c87b03e5Sespie@end ignore 149*c87b03e5Sespie 150*c87b03e5Sespie@c man begin DESCRIPTION gcj 151*c87b03e5Sespie 152*c87b03e5SespieAs @command{gcj} is just another front end to @command{gcc}, it supports many 153*c87b03e5Sespieof the same options as gcc. @xref{Option Summary, , Option Summary, 154*c87b03e5Sespiegcc, Using the GNU Compiler Collection (GCC)}. This manual only documents the 155*c87b03e5Sespieoptions specific to @command{gcj}. 156*c87b03e5Sespie 157*c87b03e5Sespie@c man end 158*c87b03e5Sespie 159*c87b03e5Sespie@menu 160*c87b03e5Sespie* Input and output files:: 161*c87b03e5Sespie* Input Options:: How gcj finds files 162*c87b03e5Sespie* Encodings:: Options controlling source file encoding 163*c87b03e5Sespie* Warnings:: Options controlling warnings specific to gcj 164*c87b03e5Sespie* Code Generation:: Options controlling the output of gcj 165*c87b03e5Sespie* Configure-time Options:: Options you won't use 166*c87b03e5Sespie@end menu 167*c87b03e5Sespie 168*c87b03e5Sespie@c man begin OPTIONS gcj 169*c87b03e5Sespie 170*c87b03e5Sespie@node Input and output files 171*c87b03e5Sespie@section Input and output files 172*c87b03e5Sespie 173*c87b03e5SespieA @command{gcj} command is like a @command{gcc} command, in that it 174*c87b03e5Sespieconsists of a number of options and file names. The following kinds 175*c87b03e5Sespieof input file names are supported: 176*c87b03e5Sespie 177*c87b03e5Sespie@table @gcctabopt 178*c87b03e5Sespie@item @var{file}.java 179*c87b03e5SespieJava source files. 180*c87b03e5Sespie@item @var{file}.class 181*c87b03e5SespieJava bytecode files. 182*c87b03e5Sespie@item @var{file}.zip 183*c87b03e5Sespie@itemx @var{file}.jar 184*c87b03e5SespieAn archive containing one or more @code{.class} files, all of 185*c87b03e5Sespiewhich are compiled. The archive may be compressed. 186*c87b03e5Sespie@item @@@var{file} 187*c87b03e5SespieA file containing a whitespace-separated list of input file names. 188*c87b03e5Sespie(Currently, these must all be @code{.java} source files, but that 189*c87b03e5Sespiemay change.) 190*c87b03e5SespieEach named file is compiled, just as if it had been on the command line. 191*c87b03e5Sespie@item @var{library}.a 192*c87b03e5Sespie@itemx @var{library}.so 193*c87b03e5Sespie@itemx -l@var{libname} 194*c87b03e5SespieLibraries to use when linking. See the @command{gcc} manual. 195*c87b03e5Sespie@end table 196*c87b03e5Sespie 197*c87b03e5SespieYou can specify more than one input file on the @command{gcj} command line, 198*c87b03e5Sespiein which case they will all be compiled. If you specify a 199*c87b03e5Sespie@code{-o @var{FILENAME}} 200*c87b03e5Sespieoption, all the input files will be compiled together, producing a 201*c87b03e5Sespiesingle output file, named @var{FILENAME}. 202*c87b03e5SespieThis is allowed even when using @code{-S} or @code{-c}, 203*c87b03e5Sespiebut not when using @code{-C} or @code{--resource}. 204*c87b03e5Sespie(This is an extension beyond the what plain @command{gcc} allows.) 205*c87b03e5Sespie(If more than one input file is specified, all must currently 206*c87b03e5Sespiebe @code{.java} files, though we hope to fix this.) 207*c87b03e5Sespie 208*c87b03e5Sespie@node Input Options 209*c87b03e5Sespie@section Input Options 210*c87b03e5Sespie 211*c87b03e5Sespie@cindex class path 212*c87b03e5Sespie 213*c87b03e5Sespie@command{gcj} has options to control where it looks to find files it needs. 214*c87b03e5SespieFor instance, @command{gcj} might need to load a class that is referenced 215*c87b03e5Sespieby the file it has been asked to compile. Like other compilers for the 216*c87b03e5SespieJava language, @command{gcj} has a notion of a @dfn{class path}. There are 217*c87b03e5Sespieseveral options and environment variables which can be used to 218*c87b03e5Sespiemanipulate the class path. When @command{gcj} looks for a given class, it 219*c87b03e5Sespiesearches the class path looking for matching @file{.class} or 220*c87b03e5Sespie@file{.java} file. @command{gcj} comes with a built-in class path which 221*c87b03e5Sespiepoints at the installed @file{libgcj.jar}, a file which contains all the 222*c87b03e5Sespiestandard classes. 223*c87b03e5Sespie 224*c87b03e5SespieIn the below, a directory or path component can refer either to an 225*c87b03e5Sespieactual directory on the filesystem, or to a @file{.zip} or @file{.jar} 226*c87b03e5Sespiefile, which @command{gcj} will search as if it is a directory. 227*c87b03e5Sespie 228*c87b03e5Sespie@table @gcctabopt 229*c87b03e5Sespie@item -I@var{dir} 230*c87b03e5SespieAll directories specified by @code{-I} are kept in order and prepended 231*c87b03e5Sespieto the class path constructed from all the other options. Unless 232*c87b03e5Sespiecompatibility with tools like @code{javac} is important, we recommend 233*c87b03e5Sespiealways using @code{-I} instead of the other options for manipulating the 234*c87b03e5Sespieclass path. 235*c87b03e5Sespie 236*c87b03e5Sespie@item --classpath=@var{path} 237*c87b03e5SespieThis sets the class path to @var{path}, a colon-separated list of paths 238*c87b03e5Sespie(on Windows-based systems, a semicolon-separate list of paths). 239*c87b03e5SespieThis does not override the builtin (``boot'') search path. 240*c87b03e5Sespie 241*c87b03e5Sespie@item --CLASSPATH=@var{path} 242*c87b03e5SespieDeprecated synonym for @code{--classpath}. 243*c87b03e5Sespie 244*c87b03e5Sespie@item --bootclasspath=@var{path} 245*c87b03e5SespieWhere to find the standard builtin classes, such as @code{java.lang.String}. 246*c87b03e5Sespie 247*c87b03e5Sespie@item --extdirs=@var{path} 248*c87b03e5SespieFor each directory in the @var{path}, place the contents of that 249*c87b03e5Sespiedirectory at the end of the class path. 250*c87b03e5Sespie 251*c87b03e5Sespie@item CLASSPATH 252*c87b03e5SespieThis is an environment variable which holds a list of paths. 253*c87b03e5Sespie@end table 254*c87b03e5Sespie 255*c87b03e5SespieThe final class path is constructed like so: 256*c87b03e5Sespie 257*c87b03e5Sespie@itemize @bullet 258*c87b03e5Sespie@item 259*c87b03e5SespieFirst come all directories specified via @code{-I}. 260*c87b03e5Sespie 261*c87b03e5Sespie@item 262*c87b03e5SespieIf @option{--classpath} is specified, its value is appended. 263*c87b03e5SespieOtherwise, if the @code{CLASSPATH} environment variable is specified, 264*c87b03e5Sespiethen its value is appended. 265*c87b03e5SespieOtherwise, the current directory (@code{"."}) is appended. 266*c87b03e5Sespie 267*c87b03e5Sespie@item 268*c87b03e5SespieIf @code{--bootclasspath} was specified, append its value. 269*c87b03e5SespieOtherwise, append the built-in system directory, @file{libgcj.jar}. 270*c87b03e5Sespie 271*c87b03e5Sespie@item 272*c87b03e5SespieFinally, if @code{--extdirs} was specified, append the contents of the 273*c87b03e5Sespiespecified directories at the end of the class path. Otherwise, append 274*c87b03e5Sespiethe contents of the built-in extdirs at @code{$(prefix)/share/java/ext}. 275*c87b03e5Sespie@end itemize 276*c87b03e5Sespie 277*c87b03e5SespieThe classfile built by @command{gcj} for the class @code{java.lang.Object} 278*c87b03e5Sespie(and placed in @code{libgcj.jar}) contains a special zero length 279*c87b03e5Sespieattribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this 280*c87b03e5Sespieattribute when loading @code{java.lang.Object} and will report an error 281*c87b03e5Sespieif it isn't found, unless it compiles to bytecode (the option 282*c87b03e5Sespie@code{-fforce-classes-archive-check} can be used to override this 283*c87b03e5Sespiebehavior in this particular case.) 284*c87b03e5Sespie 285*c87b03e5Sespie@table @gcctabopt 286*c87b03e5Sespie@item -fforce-classes-archive-check 287*c87b03e5SespieThis forces the compiler to always check for the special zero length 288*c87b03e5Sespieattribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and 289*c87b03e5Sespieissue an error if it isn't found. 290*c87b03e5Sespie@end table 291*c87b03e5Sespie 292*c87b03e5Sespie@node Encodings 293*c87b03e5Sespie@section Encodings 294*c87b03e5Sespie 295*c87b03e5SespieThe Java programming language uses Unicode throughout. In an effort to 296*c87b03e5Sespieintegrate well with other locales, @command{gcj} allows @file{.java} files 297*c87b03e5Sespieto be written using almost any encoding. @command{gcj} knows how to 298*c87b03e5Sespieconvert these encodings into its internal encoding at compile time. 299*c87b03e5Sespie 300*c87b03e5SespieYou can use the @code{--encoding=@var{NAME}} option to specify an 301*c87b03e5Sespieencoding (of a particular character set) to use for source files. If 302*c87b03e5Sespiethis is not specified, the default encoding comes from your current 303*c87b03e5Sespielocale. If your host system has insufficient locale support, then 304*c87b03e5Sespie@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding 305*c87b03e5Sespieof Unicode. 306*c87b03e5Sespie 307*c87b03e5SespieTo implement @code{--encoding}, @command{gcj} simply uses the host 308*c87b03e5Sespieplatform's @code{iconv} conversion routine. This means that in practice 309*c87b03e5Sespie@command{gcj} is limited by the capabilities of the host platform. 310*c87b03e5Sespie 311*c87b03e5SespieThe names allowed for the argument @code{--encoding} vary from platform 312*c87b03e5Sespieto platform (since they are not standardized anywhere). However, 313*c87b03e5Sespie@command{gcj} implements the encoding named @samp{UTF-8} internally, so if 314*c87b03e5Sespieyou choose to use this for your source files you can be assured that it 315*c87b03e5Sespiewill work on every host. 316*c87b03e5Sespie 317*c87b03e5Sespie 318*c87b03e5Sespie@node Warnings 319*c87b03e5Sespie@section Warnings 320*c87b03e5Sespie 321*c87b03e5Sespie@command{gcj} implements several warnings. As with other generic 322*c87b03e5Sespie@command{gcc} warnings, if an option of the form @code{-Wfoo} enables a 323*c87b03e5Sespiewarning, then @code{-Wno-foo} will disable it. Here we've chosen to 324*c87b03e5Sespiedocument the form of the warning which will have an effect -- the 325*c87b03e5Sespiedefault being the opposite of what is listed. 326*c87b03e5Sespie 327*c87b03e5Sespie@table @gcctabopt 328*c87b03e5Sespie@item -Wredundant-modifiers 329*c87b03e5SespieWith this flag, @command{gcj} will warn about redundant modifiers. For 330*c87b03e5Sespieinstance, it will warn if an interface method is declared @code{public}. 331*c87b03e5Sespie 332*c87b03e5Sespie@item -Wextraneous-semicolon 333*c87b03e5SespieThis causes @command{gcj} to warn about empty statements. Empty statements 334*c87b03e5Sespiehave been deprecated. 335*c87b03e5Sespie 336*c87b03e5Sespie@item -Wno-out-of-date 337*c87b03e5SespieThis option will cause @command{gcj} not to warn when a source file is 338*c87b03e5Sespienewer than its matching class file. By default @command{gcj} will warn 339*c87b03e5Sespieabout this. 340*c87b03e5Sespie 341*c87b03e5Sespie@item -Wunused 342*c87b03e5SespieThis is the same as @command{gcc}'s @code{-Wunused}. 343*c87b03e5Sespie 344*c87b03e5Sespie@item -Wall 345*c87b03e5SespieThis is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon 346*c87b03e5Sespie-Wunused}. 347*c87b03e5Sespie@end table 348*c87b03e5Sespie 349*c87b03e5Sespie 350*c87b03e5Sespie@node Code Generation 351*c87b03e5Sespie@section Code Generation 352*c87b03e5Sespie 353*c87b03e5SespieIn addition to the many @command{gcc} options controlling code generation, 354*c87b03e5Sespie@command{gcj} has several options specific to itself. 355*c87b03e5Sespie 356*c87b03e5Sespie@table @gcctabopt 357*c87b03e5Sespie@item --main=@var{CLASSNAME} 358*c87b03e5SespieThis option is used when linking to specify the name of the class whose 359*c87b03e5Sespie@code{main} method should be invoked when the resulting executable is 360*c87b03e5Sespierun. @footnote{The linker by default looks for a global function named 361*c87b03e5Sespie@code{main}. Since Java does not have global functions, and a 362*c87b03e5Sespiecollection of Java classes may have more than one class with a 363*c87b03e5Sespie@code{main} method, you need to let the linker know which of those 364*c87b03e5Sespie@code{main} methods it should invoke when starting the application.} 365*c87b03e5Sespie 366*c87b03e5Sespie@item -D@var{name}[=@var{value}] 367*c87b03e5SespieThis option can only be used with @code{--main}. It defines a system 368*c87b03e5Sespieproperty named @var{name} with value @var{value}. If @var{value} is not 369*c87b03e5Sespiespecified then it defaults to the empty string. These system properties 370*c87b03e5Sespieare initialized at the program's startup and can be retrieved at runtime 371*c87b03e5Sespieusing the @code{java.lang.System.getProperty} method. 372*c87b03e5Sespie 373*c87b03e5Sespie@item -C 374*c87b03e5SespieThis option is used to tell @command{gcj} to generate bytecode 375*c87b03e5Sespie(@file{.class} files) rather than object code. 376*c87b03e5Sespie 377*c87b03e5Sespie@item --resource @var{resource-name} 378*c87b03e5SespieThis option is used to tell @command{gcj} to compile the contents of a 379*c87b03e5Sespiegiven file to object code so it may be accessed at runtime with the core 380*c87b03e5Sespieprotocol handler as @samp{core:/@var{resource-name}}. Note that 381*c87b03e5Sespie@var{resource-name} is the name of the resource as found at runtime; for 382*c87b03e5Sespieinstance, it could be used in a call to @code{ResourceBundle.getBundle}. 383*c87b03e5SespieThe actual file name to be compiled this way must be specified 384*c87b03e5Sespieseparately. 385*c87b03e5Sespie 386*c87b03e5Sespie@item -d @var{directory} 387*c87b03e5SespieWhen used with @code{-C}, this causes all generated @file{.class} files 388*c87b03e5Sespieto be put in the appropriate subdirectory of @var{directory}. By 389*c87b03e5Sespiedefault they will be put in subdirectories of the current working 390*c87b03e5Sespiedirectory. 391*c87b03e5Sespie 392*c87b03e5Sespie@item -fno-bounds-check 393*c87b03e5SespieBy default, @command{gcj} generates code which checks the bounds of all 394*c87b03e5Sespiearray indexing operations. With this option, these checks are omitted, which 395*c87b03e5Sespiecan improve performance for code that uses arrays extensively. Note that this 396*c87b03e5Sespiecan result in unpredictable behavior if the code in question actually does 397*c87b03e5Sespieviolate array bounds constraints. It is safe to use this option if you are 398*c87b03e5Sespiesure that your code will never throw an @code{ArrayIndexOutOfBoundsException}. 399*c87b03e5Sespie 400*c87b03e5Sespie@item -fno-store-check 401*c87b03e5SespieDon't generate array store checks. When storing objects into arrays, a runtime 402*c87b03e5Sespiecheck is normally generated in order to ensure that the object is assignment 403*c87b03e5Sespiecompatible with the component type of the array (which may not be known 404*c87b03e5Sespieat compile-time). With this option, these checks are omitted. This can 405*c87b03e5Sespieimprove performance for code which stores objects into arrays frequently. 406*c87b03e5SespieIt is safe to use this option if you are sure your code will never throw an 407*c87b03e5Sespie@code{ArrayStoreException}. 408*c87b03e5Sespie 409*c87b03e5Sespie@item -fjni 410*c87b03e5SespieWith @command{gcj} there are two options for writing native methods: CNI 411*c87b03e5Sespieand JNI@. By default @command{gcj} assumes you are using CNI@. If you are 412*c87b03e5Sespiecompiling a class with native methods, and these methods are implemented 413*c87b03e5Sespieusing JNI, then you must use @code{-fjni}. This option causes 414*c87b03e5Sespie@command{gcj} to generate stubs which will invoke the underlying JNI 415*c87b03e5Sespiemethods. 416*c87b03e5Sespie 417*c87b03e5Sespie@item -fno-assert 418*c87b03e5SespieDon't recognize the @code{assert} keyword. This is for compatibility 419*c87b03e5Sespiewith older versions of the language specification. 420*c87b03e5Sespie 421*c87b03e5Sespie@item -fno-optimize-static-class-initialization 422*c87b03e5SespieWhen the optimization level is greater or equal to @code{-O2}, 423*c87b03e5Sespie@command{gcj} will try to optimize the way calls into the runtime are made 424*c87b03e5Sespieto initialize static classes upon their first use (this optimization 425*c87b03e5Sespieisn't carried out if @code{-C} was specified.) When compiling to native 426*c87b03e5Sespiecode, @code{-fno-optimize-static-class-initialization} will turn this 427*c87b03e5Sespieoptimization off, regardless of the optimization level in use. 428*c87b03e5Sespie@end table 429*c87b03e5Sespie 430*c87b03e5Sespie 431*c87b03e5Sespie@node Configure-time Options 432*c87b03e5Sespie@section Configure-time Options 433*c87b03e5Sespie 434*c87b03e5SespieSome @command{gcj} code generations options affect the resulting ABI, and 435*c87b03e5Sespieso can only be meaningfully given when @code{libgcj}, the runtime 436*c87b03e5Sespiepackage, is configured. @code{libgcj} puts the appropriate options from 437*c87b03e5Sespiethis group into a @samp{spec} file which is read by @command{gcj}. These 438*c87b03e5Sespieoptions are listed here for completeness; if you are using @code{libgcj} 439*c87b03e5Sespiethen you won't want to touch these options. 440*c87b03e5Sespie 441*c87b03e5Sespie@table @gcctabopt 442*c87b03e5Sespie@item -fuse-boehm-gc 443*c87b03e5SespieThis enables the use of the Boehm GC bitmap marking code. In particular 444*c87b03e5Sespiethis causes @command{gcj} to put an object marking descriptor into each 445*c87b03e5Sespievtable. 446*c87b03e5Sespie 447*c87b03e5Sespie@item -fhash-synchronization 448*c87b03e5SespieBy default, synchronization data (the data used for @code{synchronize}, 449*c87b03e5Sespie@code{wait}, and @code{notify}) is pointed to by a word in each object. 450*c87b03e5SespieWith this option @command{gcj} assumes that this information is stored in a 451*c87b03e5Sespiehash table and not in the object itself. 452*c87b03e5Sespie 453*c87b03e5Sespie@item -fuse-divide-subroutine 454*c87b03e5SespieOn some systems, a library routine is called to perform integer 455*c87b03e5Sespiedivision. This is required to get exception handling correct when 456*c87b03e5Sespiedividing by zero. 457*c87b03e5Sespie 458*c87b03e5Sespie@item -fcheck-references 459*c87b03e5SespieOn some systems it's necessary to insert inline checks whenever 460*c87b03e5Sespieaccessing an object via a reference. On other systems you won't need 461*c87b03e5Sespiethis because null pointer accesses are caught automatically by the 462*c87b03e5Sespieprocessor. 463*c87b03e5Sespie@end table 464*c87b03e5Sespie 465*c87b03e5Sespie@c man end 466*c87b03e5Sespie 467*c87b03e5Sespie@node Compatibility 468*c87b03e5Sespie@chapter Compatibility with the Java Platform 469*c87b03e5Sespie 470*c87b03e5SespieAs we believe it is important that the Java platform not be fragmented, 471*c87b03e5Sespie@command{gcj} and @code{libgcj} try to conform to the relevant Java 472*c87b03e5Sespiespecifications. However, limited manpower and incomplete and unclear 473*c87b03e5Sespiedocumentation work against us. So, there are caveats to using 474*c87b03e5Sespie@command{gcj}. 475*c87b03e5Sespie 476*c87b03e5Sespie@menu 477*c87b03e5Sespie* Limitations:: 478*c87b03e5Sespie* Extensions:: 479*c87b03e5Sespie@end menu 480*c87b03e5Sespie 481*c87b03e5Sespie@node Limitations 482*c87b03e5Sespie@section Standard features not yet supported 483*c87b03e5Sespie 484*c87b03e5SespieThis list of compatibility issues is by no means complete. 485*c87b03e5Sespie 486*c87b03e5Sespie@itemize @bullet 487*c87b03e5Sespie@item 488*c87b03e5Sespie@command{gcj} implements the JDK 1.2 language. It supports inner classes 489*c87b03e5Sespieand the new 1.4 @code{assert} keyword. It does not yet support the Java 2 490*c87b03e5Sespie@code{strictfp} keyword (it recognizes the keyword but ignores it). 491*c87b03e5Sespie 492*c87b03e5Sespie@item 493*c87b03e5Sespie@code{libgcj} is largely compatible with the JDK 1.2 libraries. 494*c87b03e5SespieHowever, @code{libgcj} is missing many packages, most notably 495*c87b03e5Sespie@code{java.awt}. There are also individual missing classes and methods. 496*c87b03e5SespieWe currently do not have a list showing differences between 497*c87b03e5Sespie@code{libgcj} and the Java 2 platform. 498*c87b03e5Sespie 499*c87b03e5Sespie@item 500*c87b03e5SespieSometimes the @code{libgcj} implementation of a method or class differs 501*c87b03e5Sespiefrom the JDK implementation. This is not always a bug. Still, if it 502*c87b03e5Sespieaffects you, it probably makes sense to report it so that we can discuss 503*c87b03e5Sespiethe appropriate response. 504*c87b03e5Sespie 505*c87b03e5Sespie@item 506*c87b03e5Sespie@command{gcj} does not currently allow for piecemeal replacement of 507*c87b03e5Sespiecomponents within @code{libgcj}. Unfortunately, programmers often want 508*c87b03e5Sespieto use newer versions of certain packages, such as those provided by 509*c87b03e5Sespiethe Apache Software Foundation's Jakarta project. This has forced us 510*c87b03e5Sespieto place the @code{org.w3c.dom} and @code{org.xml.sax} packages into 511*c87b03e5Sespietheir own libraries, separate from @code{libgcj}. If you intend to 512*c87b03e5Sespieuse these classes, you must link them explicitly with 513*c87b03e5Sespie@code{-l-org-w3c-dom} and @code{-l-org-xml-sax}. Future versions of 514*c87b03e5Sespie@command{gcj} may not have this restriction. 515*c87b03e5Sespie@end itemize 516*c87b03e5Sespie 517*c87b03e5Sespie@node Extensions 518*c87b03e5Sespie@section Extra features unique to gcj 519*c87b03e5Sespie 520*c87b03e5SespieThe main feature of @command{gcj} is that it can compile programs 521*c87b03e5Sespiewritten in the Java programming language to native code. Most 522*c87b03e5Sespieextensions that have been added are to facilitate this functionality. 523*c87b03e5Sespie 524*c87b03e5Sespie@itemize @bullet 525*c87b03e5Sespie@item 526*c87b03e5Sespie@command{gcj} makes it easy and efficient to mix code written in Java and C++. 527*c87b03e5Sespie@xref{About CNI}, for more info on how to use this in your programs. 528*c87b03e5Sespie 529*c87b03e5Sespie@item 530*c87b03e5SespieWhen you compile your classes into a shared library they can be automatically 531*c87b03e5Sespieloaded by the @code{libgcj} system classloader. When trying to load a class 532*c87b03e5Sespie@code{gnu.pkg.SomeClass} the system classloader will first try to load the 533*c87b03e5Sespieshared library @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the 534*c87b03e5Sespieclass then it will try to load @file{lib-gnu-pkg.so} and finally when the 535*c87b03e5Sespieclass is still not loaded it will try to load @file{lib-gnu.so}. Note that 536*c87b03e5Sespieall @samp{.}s will be transformed into @samp{-}s and that searching 537*c87b03e5Sespiefor inner classes starts with their outermost outer class. If the class 538*c87b03e5Sespiecannot be found this way the system classloader tries to use 539*c87b03e5Sespiethe @code{libgcj} bytecode interpreter to load the class from the standard 540*c87b03e5Sespieclasspath. 541*c87b03e5Sespie@end itemize 542*c87b03e5Sespie 543*c87b03e5Sespie@node Invoking gcjh 544*c87b03e5Sespie@chapter Invoking gcjh 545*c87b03e5Sespie 546*c87b03e5Sespie@c man title gcjh generate header files from Java class files 547*c87b03e5Sespie 548*c87b03e5Sespie@c man begin DESCRIPTION gcjh 549*c87b03e5Sespie 550*c87b03e5SespieThe @code{gcjh} program is used to generate header files from class 551*c87b03e5Sespiefiles. It can generate both CNI and JNI header files, as well as stub 552*c87b03e5Sespieimplementation files which can be used as a basis for implementing the 553*c87b03e5Sespierequired native methods. 554*c87b03e5Sespie 555*c87b03e5Sespie@c man end 556*c87b03e5Sespie 557*c87b03e5Sespie@ignore 558*c87b03e5Sespie@c man begin SYNOPSIS gcjh 559*c87b03e5Sespiegcjh [@option{-stubs}] [@option{-jni}] 560*c87b03e5Sespie [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}] 561*c87b03e5Sespie [@option{-preprend} @var{text}] 562*c87b03e5Sespie [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}] 563*c87b03e5Sespie [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}] 564*c87b03e5Sespie [@option{-o} @var{file}] [@option{-td} @var{dir}] 565*c87b03e5Sespie [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}] 566*c87b03e5Sespie [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}] 567*c87b03e5Sespie @var{classname}@dots{} 568*c87b03e5Sespie@c man end 569*c87b03e5Sespie@c man begin SEEALSO gcjh 570*c87b03e5Sespiegcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7), 571*c87b03e5Sespieand the Info entries for @file{gcj} and @file{gcc}. 572*c87b03e5Sespie@c man end 573*c87b03e5Sespie@end ignore 574*c87b03e5Sespie 575*c87b03e5Sespie@c man begin OPTIONS gcjh 576*c87b03e5Sespie 577*c87b03e5Sespie@table @gcctabopt 578*c87b03e5Sespie@item -stubs 579*c87b03e5SespieThis causes @code{gcjh} to generate stub files instead of header files. 580*c87b03e5SespieBy default the stub file will be named after the class, with a suffix of 581*c87b03e5Sespie@samp{.cc}. In JNI mode, the default output file will have the suffix 582*c87b03e5Sespie@samp{.c}. 583*c87b03e5Sespie 584*c87b03e5Sespie@item -jni 585*c87b03e5SespieThis tells @code{gcjh} to generate a JNI header or stub. By default, 586*c87b03e5SespieCNI headers are generated. 587*c87b03e5Sespie 588*c87b03e5Sespie@item -add @var{text} 589*c87b03e5SespieInserts @var{text} into the class body. This is ignored in JNI mode. 590*c87b03e5Sespie 591*c87b03e5Sespie@item -append @var{text} 592*c87b03e5SespieInserts @var{text} into the header file after the class declaration. 593*c87b03e5SespieThis is ignored in JNI mode. 594*c87b03e5Sespie 595*c87b03e5Sespie@item -friend @var{text} 596*c87b03e5SespieInserts @var{text} into the class as a @code{friend} declaration. 597*c87b03e5SespieThis is ignored in JNI mode. 598*c87b03e5Sespie 599*c87b03e5Sespie@item -prepend @var{text} 600*c87b03e5SespieInserts @var{text} into the header file before the class declaration. 601*c87b03e5SespieThis is ignored in JNI mode. 602*c87b03e5Sespie 603*c87b03e5Sespie@item --classpath=@var{path} 604*c87b03e5Sespie@itemx --CLASSPATH=@var{path} 605*c87b03e5Sespie@itemx -I@var{directory} 606*c87b03e5Sespie@itemx -d @var{directory} 607*c87b03e5Sespie@itemx -o @var{file} 608*c87b03e5SespieThese options are all identical to the corresponding @command{gcj} options. 609*c87b03e5Sespie 610*c87b03e5Sespie@item -o @var{file} 611*c87b03e5SespieSets the output file name. This cannot be used if there is more than 612*c87b03e5Sespieone class on the command line. 613*c87b03e5Sespie 614*c87b03e5Sespie@item -td @var{directory} 615*c87b03e5SespieSets the name of the directory to use for temporary files. 616*c87b03e5Sespie 617*c87b03e5Sespie@item -M 618*c87b03e5SespiePrint all dependencies to stdout; suppress ordinary output. 619*c87b03e5Sespie 620*c87b03e5Sespie@item -MM 621*c87b03e5SespiePrint non-system dependencies to stdout; suppress ordinary output. 622*c87b03e5Sespie 623*c87b03e5Sespie@item -MD 624*c87b03e5SespiePrint all dependencies to stdout. 625*c87b03e5Sespie 626*c87b03e5Sespie@item -MMD 627*c87b03e5SespiePrint non-system dependencies to stdout. 628*c87b03e5Sespie 629*c87b03e5Sespie@item --help 630*c87b03e5SespiePrint help about @code{gcjh} and exit. No further processing is done. 631*c87b03e5Sespie 632*c87b03e5Sespie@item --version 633*c87b03e5SespiePrint version information for @code{gcjh} and exit. No further 634*c87b03e5Sespieprocessing is done. 635*c87b03e5Sespie 636*c87b03e5Sespie@item -v, --verbose 637*c87b03e5SespiePrint extra information while running. 638*c87b03e5Sespie@end table 639*c87b03e5Sespie 640*c87b03e5SespieAll remaining options are considered to be names of classes. 641*c87b03e5Sespie 642*c87b03e5Sespie@c man end 643*c87b03e5Sespie 644*c87b03e5Sespie@node Invoking jv-scan 645*c87b03e5Sespie@chapter Invoking jv-scan 646*c87b03e5Sespie 647*c87b03e5Sespie@c man title jv-scan print information about Java source file 648*c87b03e5Sespie 649*c87b03e5Sespie@c man begin DESCRIPTION jv-scan 650*c87b03e5Sespie 651*c87b03e5SespieThe @code{jv-scan} program can be used to print information about a Java 652*c87b03e5Sespiesource file (@file{.java} file). 653*c87b03e5Sespie 654*c87b03e5Sespie@c man end 655*c87b03e5Sespie 656*c87b03e5Sespie@ignore 657*c87b03e5Sespie@c man begin SYNOPSIS jv-scan 658*c87b03e5Sespiejv-scan [@option{--no-assert}] [@option{--complexity}] 659*c87b03e5Sespie [@option{--encoding}=@var{name}] [@option{--print-main}] 660*c87b03e5Sespie [@option{--list-class}] [@option{--list-filename}] 661*c87b03e5Sespie [@option{--version}] [@option{--help}] 662*c87b03e5Sespie [@option{-o} @var{file}] @var{inputfile}@dots{} 663*c87b03e5Sespie@c man end 664*c87b03e5Sespie@c man begin SEEALSO jv-scan 665*c87b03e5Sespiegcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7), 666*c87b03e5Sespieand the Info entries for @file{gcj} and @file{gcc}. 667*c87b03e5Sespie@c man end 668*c87b03e5Sespie@end ignore 669*c87b03e5Sespie 670*c87b03e5Sespie@c man begin OPTIONS jv-scan 671*c87b03e5Sespie 672*c87b03e5Sespie@table @gcctabopt 673*c87b03e5Sespie@item --no-assert 674*c87b03e5SespieDon't recognize the @code{assert} keyword, for backwards compatibility 675*c87b03e5Sespiewith older versions of the language specification. 676*c87b03e5Sespie 677*c87b03e5Sespie@item --complexity 678*c87b03e5SespieThis prints a complexity measure, related to cyclomatic complexity, for 679*c87b03e5Sespieeach input file. 680*c87b03e5Sespie 681*c87b03e5Sespie@item --encoding=@var{name} 682*c87b03e5SespieThis works like the corresponding @command{gcj} option. 683*c87b03e5Sespie 684*c87b03e5Sespie@item --print-main 685*c87b03e5SespieThis prints the name of the class in this file containing a @code{main} 686*c87b03e5Sespiemethod. 687*c87b03e5Sespie 688*c87b03e5Sespie@item --list-class 689*c87b03e5SespieThis lists the names of all classes defined in the input files. 690*c87b03e5Sespie 691*c87b03e5Sespie@item --list-filename 692*c87b03e5SespieIf @code{--list-class} is given, this option causes @code{jv-scan} to 693*c87b03e5Sespiealso print the name of the file in which each class was found. 694*c87b03e5Sespie 695*c87b03e5Sespie@item -o @var{file} 696*c87b03e5SespiePrint output to the named file. 697*c87b03e5Sespie 698*c87b03e5Sespie@item --help 699*c87b03e5SespiePrint help, then exit. 700*c87b03e5Sespie 701*c87b03e5Sespie@item --version 702*c87b03e5SespiePrint version number, then exit. 703*c87b03e5Sespie@end table 704*c87b03e5Sespie 705*c87b03e5Sespie@c man end 706*c87b03e5Sespie 707*c87b03e5Sespie@node Invoking jcf-dump 708*c87b03e5Sespie@chapter Invoking jcf-dump 709*c87b03e5Sespie 710*c87b03e5Sespie@c man title jcf-dump print information about Java class files 711*c87b03e5Sespie 712*c87b03e5Sespie@ignore 713*c87b03e5Sespie@c man begin SYNOPSIS jcf-dump 714*c87b03e5Sespiejcf-dump [@option{-c}] [@option{--javap}] 715*c87b03e5Sespie [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}] 716*c87b03e5Sespie [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}] 717*c87b03e5Sespie [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}] 718*c87b03e5Sespie @var{classname}@dots{} 719*c87b03e5Sespie@c man end 720*c87b03e5Sespie@c man begin SEEALSO jcf-dump 721*c87b03e5Sespiegcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7), 722*c87b03e5Sespieand the Info entries for @file{gcj} and @file{gcc}. 723*c87b03e5Sespie@c man end 724*c87b03e5Sespie@end ignore 725*c87b03e5Sespie 726*c87b03e5Sespie@c man begin DESCRIPTION jcf-dump 727*c87b03e5Sespie 728*c87b03e5SespieThis is a class file examiner, similar to @code{javap}. It will print 729*c87b03e5Sespieinformation about a number of classes, which are specified by class name 730*c87b03e5Sespieor file name. 731*c87b03e5Sespie 732*c87b03e5Sespie@c man end 733*c87b03e5Sespie 734*c87b03e5Sespie@c man begin OPTIONS jcf-dump 735*c87b03e5Sespie 736*c87b03e5Sespie@table @gcctabopt 737*c87b03e5Sespie@item -c 738*c87b03e5SespieDisassemble method bodies. By default method bodies are not printed. 739*c87b03e5Sespie 740*c87b03e5Sespie@item --javap 741*c87b03e5SespieGenerate output in @code{javap} format. The implementation of this 742*c87b03e5Sespiefeature is very incomplete. 743*c87b03e5Sespie 744*c87b03e5Sespie@item --classpath=@var{path} 745*c87b03e5Sespie@itemx --CLASSPATH=@var{path} 746*c87b03e5Sespie@itemx -I@var{directory} 747*c87b03e5Sespie@itemx -o @var{file} 748*c87b03e5SespieThese options as the same as the corresponding @command{gcj} options. 749*c87b03e5Sespie 750*c87b03e5Sespie@item --help 751*c87b03e5SespiePrint help, then exit. 752*c87b03e5Sespie 753*c87b03e5Sespie@item --version 754*c87b03e5SespiePrint version number, then exit. 755*c87b03e5Sespie 756*c87b03e5Sespie@item -v, --verbose 757*c87b03e5SespiePrint extra information while running. 758*c87b03e5Sespie@end table 759*c87b03e5Sespie 760*c87b03e5Sespie@c man end 761*c87b03e5Sespie 762*c87b03e5Sespie@node Invoking gij 763*c87b03e5Sespie@chapter Invoking gij 764*c87b03e5Sespie 765*c87b03e5Sespie@c man title gij GNU interpreter for Java bytecode 766*c87b03e5Sespie 767*c87b03e5Sespie@ignore 768*c87b03e5Sespie@c man begin SYNOPSIS gij 769*c87b03e5Sespiegij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}] 770*c87b03e5Sespie 771*c87b03e5Sespiegij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}] 772*c87b03e5Sespie [@option{-cp} @var{path}] [@option{-classpath} @var{path}] 773*c87b03e5Sespie [@option{-D}@var{name}[=@var{value}]@dots{}] 774*c87b03e5Sespie [@option{-ms=}@var{number}] [@option{-mx=}@var{number}] 775*c87b03e5Sespie [@option{--showversion}] [@option{--version}] [@option{--help}] 776*c87b03e5Sespie@c man end 777*c87b03e5Sespie@c man begin SEEALSO gij 778*c87b03e5Sespiegcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7), 779*c87b03e5Sespieand the Info entries for @file{gcj} and @file{gcc}. 780*c87b03e5Sespie@c man end 781*c87b03e5Sespie@end ignore 782*c87b03e5Sespie 783*c87b03e5Sespie@c man begin DESCRIPTION gij 784*c87b03e5Sespie 785*c87b03e5Sespie@code{gij} is a Java bytecode interpreter included with @code{libgcj}. 786*c87b03e5Sespie@code{gij} is not available on every platform; porting it requires a 787*c87b03e5Sespiesmall amount of assembly programming which has not been done for all the 788*c87b03e5Sespietargets supported by @command{gcj}. 789*c87b03e5Sespie 790*c87b03e5SespieThe primary argument to @code{gij} is the name of a class or, with 791*c87b03e5Sespie@code{-jar}, a jar file. Options before this argument are interpreted 792*c87b03e5Sespieby @code{gij}; remaining options are passed to the interpreted program. 793*c87b03e5Sespie 794*c87b03e5SespieIf a class name is specified and this class does not have a @code{main} 795*c87b03e5Sespiemethod with the appropriate signature (a @code{static void} method with 796*c87b03e5Sespiea @code{String[]} as its sole argument), then @code{gij} will print an 797*c87b03e5Sespieerror and exit. 798*c87b03e5Sespie 799*c87b03e5SespieIf a jar file is specified then @code{gij} will use information in it to 800*c87b03e5Sespiedetermine which class' @code{main} method will be invoked. 801*c87b03e5Sespie 802*c87b03e5Sespie@code{gij} will invoke the @code{main} method with all the remaining 803*c87b03e5Sespiecommand-line options. 804*c87b03e5Sespie 805*c87b03e5SespieNote that @code{gij} is not limited to interpreting code. Because 806*c87b03e5Sespie@code{libgcj} includes a class loader which can dynamically load shared 807*c87b03e5Sespieobjects, it is possible to give @code{gij} the name of a class which has 808*c87b03e5Sespiebeen compiled and put into a shared library on the class path. 809*c87b03e5Sespie 810*c87b03e5Sespie@c man end 811*c87b03e5Sespie 812*c87b03e5Sespie@c man begin OPTIONS gij 813*c87b03e5Sespie 814*c87b03e5Sespie@table @gcctabopt 815*c87b03e5Sespie@item -cp @var{path} 816*c87b03e5Sespie@itemx -classpath @var{path} 817*c87b03e5SespieSet the initial class path. The class path is used for finding 818*c87b03e5Sespieclass and resource files. If specified, this option overrides the 819*c87b03e5Sespie@code{CLASSPATH} environment variable. Note that this option is 820*c87b03e5Sespieignored if @code{-jar} is used. 821*c87b03e5Sespie 822*c87b03e5Sespie@item -D@var{name}[=@var{value}] 823*c87b03e5SespieThis defines a system property named @var{name} with value @var{value}. 824*c87b03e5SespieIf @var{value} is not specified then it defaults to the empty string. 825*c87b03e5SespieThese system properties are initialized at the program's startup and can 826*c87b03e5Sespiebe retrieved at runtime using the @code{java.lang.System.getProperty} 827*c87b03e5Sespiemethod. 828*c87b03e5Sespie 829*c87b03e5Sespie@item -ms=@var{number} 830*c87b03e5SespieThis sets the initial heap size. 831*c87b03e5Sespie 832*c87b03e5Sespie@item -mx=@var{number} 833*c87b03e5SespieThis sets the maximum heap size. 834*c87b03e5Sespie 835*c87b03e5Sespie@item -jar 836*c87b03e5SespieThis indicates that the name passed to @code{gij} should be interpreted 837*c87b03e5Sespieas the name of a jar file, not a class. 838*c87b03e5Sespie 839*c87b03e5Sespie@item --help 840*c87b03e5SespiePrint help, then exit. 841*c87b03e5Sespie 842*c87b03e5Sespie@item --showversion 843*c87b03e5SespiePrint version number and continue. 844*c87b03e5Sespie 845*c87b03e5Sespie@item --version 846*c87b03e5SespiePrint version number, then exit. 847*c87b03e5Sespie@end table 848*c87b03e5Sespie 849*c87b03e5Sespie@c man end 850*c87b03e5Sespie 851*c87b03e5Sespie@node Invoking jv-convert 852*c87b03e5Sespie@chapter Invoking jv-convert 853*c87b03e5Sespie 854*c87b03e5Sespie@c man title jv-convert Convert file from one encoding to another 855*c87b03e5Sespie 856*c87b03e5Sespie@c man begin SYNOPSIS jv-convert 857*c87b03e5Sespie@command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]] 858*c87b03e5Sespie@ignore 859*c87b03e5Sespie 860*c87b03e5Sespie [@option{--encoding} @var{name}] 861*c87b03e5Sespie [@option{--from} @var{name}] 862*c87b03e5Sespie [@option{--to} @var{name}] 863*c87b03e5Sespie [@option{-i} @var{file}] [@option{-o} @var{file}] 864*c87b03e5Sespie [@option{--reverse}] [@option{--help}] [@option{--version}] 865*c87b03e5Sespie@end ignore 866*c87b03e5Sespie@c man end 867*c87b03e5Sespie 868*c87b03e5Sespie@c man begin DESCRIPTION jv-convert 869*c87b03e5Sespie 870*c87b03e5Sespie@command{jv-convert} is a utility included with @code{libgcj} which 871*c87b03e5Sespieconverts a file from one encoding to another. It is similar to the Unix 872*c87b03e5Sespie@command{iconv} utility. 873*c87b03e5Sespie 874*c87b03e5SespieThe encodings supported by @command{jv-convert} are platform-dependent. 875*c87b03e5SespieCurrently there is no way to get a list of all supported encodings. 876*c87b03e5Sespie 877*c87b03e5Sespie@c man end 878*c87b03e5Sespie 879*c87b03e5Sespie@c man begin OPTIONS jv-convert 880*c87b03e5Sespie 881*c87b03e5Sespie@table @gcctabopt 882*c87b03e5Sespie@item --encoding @var{name} 883*c87b03e5Sespie@itemx --from @var{name} 884*c87b03e5SespieUse @var{name} as the input encoding. The default is the current 885*c87b03e5Sespielocale's encoding. 886*c87b03e5Sespie 887*c87b03e5Sespie@item --to @var{name} 888*c87b03e5SespieUse @var{name} as the output encoding. The default is the 889*c87b03e5Sespie@code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for 890*c87b03e5Sespienon-ASCII characters. 891*c87b03e5Sespie 892*c87b03e5Sespie@item -i @var{file} 893*c87b03e5SespieRead from @var{file}. The default is to read from standard input. 894*c87b03e5Sespie 895*c87b03e5Sespie@item -o @var{file} 896*c87b03e5SespieWrite to @var{file}. The default is to write to standard output. 897*c87b03e5Sespie 898*c87b03e5Sespie@item --reverse 899*c87b03e5SespieSwap the input and output encodings. 900*c87b03e5Sespie 901*c87b03e5Sespie@item --help 902*c87b03e5SespiePrint a help message, then exit. 903*c87b03e5Sespie 904*c87b03e5Sespie@item --version 905*c87b03e5SespiePrint version information, then exit. 906*c87b03e5Sespie@end table 907*c87b03e5Sespie 908*c87b03e5Sespie@c man end 909*c87b03e5Sespie 910*c87b03e5Sespie@node Invoking rmic 911*c87b03e5Sespie@chapter Invoking rmic 912*c87b03e5Sespie 913*c87b03e5Sespie@c man title rmic Generate stubs for Remote Method Invocation 914*c87b03e5Sespie 915*c87b03e5Sespie@c man begin SYNOPSIS rmic 916*c87b03e5Sespie@command{rmic} [@option{OPTION}] @dots{} @var{class} @dots{} 917*c87b03e5Sespie@ignore 918*c87b03e5Sespie [@option{-keep}] 919*c87b03e5Sespie [@option{-keepgenerated}] 920*c87b03e5Sespie [@option{-v1.1}] 921*c87b03e5Sespie [@option{-vcompat}] 922*c87b03e5Sespie [@option{-v1.2}] 923*c87b03e5Sespie [@option{-nocompile}] 924*c87b03e5Sespie [@option{-verbose}] 925*c87b03e5Sespie [@option{-d} @var{directory}] 926*c87b03e5Sespie [@option{-help}] 927*c87b03e5Sespie [@option{-version}] 928*c87b03e5Sespie@end ignore 929*c87b03e5Sespie@c man end 930*c87b03e5Sespie 931*c87b03e5Sespie@c man begin DESCRIPTION rmic 932*c87b03e5Sespie 933*c87b03e5Sespie@command{rmic} is a utility included with @code{libgcj} which generates 934*c87b03e5Sespiestubs for remote objects. 935*c87b03e5Sespie 936*c87b03e5Sespie@c FIXME: Add real information here. 937*c87b03e5Sespie@c This really isn't much more than the --help output. 938*c87b03e5Sespie 939*c87b03e5SespieNote that this program isn't yet fully compatible with the JDK 940*c87b03e5Sespie@command{rmic}. Some options, such as @option{-classpath}, are 941*c87b03e5Sespierecognized but currently ignored. We have left these options 942*c87b03e5Sespieundocumented for now. 943*c87b03e5Sespie 944*c87b03e5SespieLong options can also be given with a GNU-style leading @samp{--}. For 945*c87b03e5Sespieinstance, @option{--help} is accepted. 946*c87b03e5Sespie 947*c87b03e5Sespie@c man end 948*c87b03e5Sespie 949*c87b03e5Sespie@c man begin OPTIONS rmic 950*c87b03e5Sespie 951*c87b03e5Sespie@table @gcctabopt 952*c87b03e5Sespie@item -keep 953*c87b03e5Sespie@itemx -keepgenerated 954*c87b03e5SespieBy default, @command{rmic} deletes intermediate files. Either of these 955*c87b03e5Sespieoptions causes it not to delete such files. 956*c87b03e5Sespie 957*c87b03e5Sespie@item -v1.1 958*c87b03e5SespieCause @command{rmic} to create stubs and skeletons for the 1.1 959*c87b03e5Sespieprotocol version. 960*c87b03e5Sespie 961*c87b03e5Sespie@item -vcompat 962*c87b03e5SespieCause @command{rmic} to create stubs and skeletons compatible with both 963*c87b03e5Sespiethe 1.1 and 1.2 protocol versions. This is the default. 964*c87b03e5Sespie 965*c87b03e5Sespie@item -v1.2 966*c87b03e5SespieCause @command{rmic} to create stubs and skeletons for the 1.2 967*c87b03e5Sespieprotocol version. 968*c87b03e5Sespie 969*c87b03e5Sespie@item -nocompile 970*c87b03e5SespieDon't compile the generated files. 971*c87b03e5Sespie 972*c87b03e5Sespie@item -verbose 973*c87b03e5SespiePrint information about what @command{rmic} is doing. 974*c87b03e5Sespie 975*c87b03e5Sespie@item -d @var{directory} 976*c87b03e5SespiePut output files in @var{directory}. By default the files are put in 977*c87b03e5Sespiethe current working directory. 978*c87b03e5Sespie 979*c87b03e5Sespie@item -help 980*c87b03e5SespiePrint a help message, then exit. 981*c87b03e5Sespie 982*c87b03e5Sespie@item -version 983*c87b03e5SespiePrint version information, then exit. 984*c87b03e5Sespie@end table 985*c87b03e5Sespie 986*c87b03e5Sespie@c man end 987*c87b03e5Sespie 988*c87b03e5Sespie 989*c87b03e5Sespie@node Invoking rmiregistry 990*c87b03e5Sespie@chapter Invoking rmiregistry 991*c87b03e5Sespie 992*c87b03e5Sespie@c man title rmiregistry Remote object registry 993*c87b03e5Sespie 994*c87b03e5Sespie@c man begin SYNOPSIS rmiregistry 995*c87b03e5Sespie@command{rmic} [@option{OPTION}] @dots{} [@var{port}] 996*c87b03e5Sespie@ignore 997*c87b03e5Sespie [@option{--help}] 998*c87b03e5Sespie [@option{--version}] 999*c87b03e5Sespie@end ignore 1000*c87b03e5Sespie@c man end 1001*c87b03e5Sespie 1002*c87b03e5Sespie@c man begin DESCRIPTION rmiregistry 1003*c87b03e5Sespie 1004*c87b03e5Sespie@command{rmiregistry} starts a remote object registry on the current 1005*c87b03e5Sespiehost. If no port number is specified, then port 1099 is used. 1006*c87b03e5Sespie 1007*c87b03e5Sespie@c FIXME: Add real information here. 1008*c87b03e5Sespie@c This really isn't much more than the --help output. 1009*c87b03e5Sespie 1010*c87b03e5Sespie@c man end 1011*c87b03e5Sespie 1012*c87b03e5Sespie@c man begin OPTIONS rmiregistry 1013*c87b03e5Sespie 1014*c87b03e5Sespie@table @gcctabopt 1015*c87b03e5Sespie@item --help 1016*c87b03e5SespiePrint a help message, then exit. 1017*c87b03e5Sespie 1018*c87b03e5Sespie@item --version 1019*c87b03e5SespiePrint version information, then exit. 1020*c87b03e5Sespie@end table 1021*c87b03e5Sespie 1022*c87b03e5Sespie@c man end 1023*c87b03e5Sespie 1024*c87b03e5Sespie 1025*c87b03e5Sespie@node About CNI 1026*c87b03e5Sespie@chapter About CNI 1027*c87b03e5Sespie 1028*c87b03e5SespieThis documents CNI, the Cygnus Native Interface, 1029*c87b03e5Sespiewhich is is a convenient way to write Java native methods using C++. 1030*c87b03e5SespieThis is a more efficient, more convenient, but less portable 1031*c87b03e5Sespiealternative to the standard JNI (Java Native Interface). 1032*c87b03e5Sespie 1033*c87b03e5Sespie@menu 1034*c87b03e5Sespie* Basic concepts:: Introduction to using CNI@. 1035*c87b03e5Sespie* Packages:: How packages are mapped to C++. 1036*c87b03e5Sespie* Primitive types:: Handling Java types in C++. 1037*c87b03e5Sespie* Interfaces:: How Java interfaces map to C++. 1038*c87b03e5Sespie* Objects and Classes:: C++ and Java classes. 1039*c87b03e5Sespie* Class Initialization:: How objects are initialized. 1040*c87b03e5Sespie* Object allocation:: How to create Java objects in C++. 1041*c87b03e5Sespie* Arrays:: Dealing with Java arrays in C++. 1042*c87b03e5Sespie* Methods:: Java methods in C++. 1043*c87b03e5Sespie* Strings:: Information about Java Strings. 1044*c87b03e5Sespie* Mixing with C++:: How CNI can interoperate with C++. 1045*c87b03e5Sespie* Exception Handling:: How exceptions are handled. 1046*c87b03e5Sespie* Synchronization:: Synchronizing between Java and C++. 1047*c87b03e5Sespie* Invocation:: Starting the Java runtime from C++. 1048*c87b03e5Sespie* Reflection:: Using reflection from C++. 1049*c87b03e5Sespie@end menu 1050*c87b03e5Sespie 1051*c87b03e5Sespie 1052*c87b03e5Sespie@node Basic concepts 1053*c87b03e5Sespie@section Basic concepts 1054*c87b03e5Sespie 1055*c87b03e5SespieIn terms of languages features, Java is mostly a subset 1056*c87b03e5Sespieof C++. Java has a few important extensions, plus a powerful standard 1057*c87b03e5Sespieclass library, but on the whole that does not change the basic similarity. 1058*c87b03e5SespieJava is a hybrid object-oriented language, with a few native types, 1059*c87b03e5Sespiein addition to class types. It is class-based, where a class may have 1060*c87b03e5Sespiestatic as well as per-object fields, and static as well as instance methods. 1061*c87b03e5SespieNon-static methods may be virtual, and may be overloaded. Overloading is 1062*c87b03e5Sespieresolved at compile time by matching the actual argument types against 1063*c87b03e5Sespiethe parameter types. Virtual methods are implemented using indirect calls 1064*c87b03e5Sespiethrough a dispatch table (virtual function table). Objects are 1065*c87b03e5Sespieallocated on the heap, and initialized using a constructor method. 1066*c87b03e5SespieClasses are organized in a package hierarchy. 1067*c87b03e5Sespie 1068*c87b03e5SespieAll of the listed attributes are also true of C++, though C++ has 1069*c87b03e5Sespieextra features (for example in C++ objects may be allocated not just 1070*c87b03e5Sespieon the heap, but also statically or in a local stack frame). Because 1071*c87b03e5Sespie@command{gcj} uses the same compiler technology as G++ (the GNU 1072*c87b03e5SespieC++ compiler), it is possible to make the intersection of the two 1073*c87b03e5Sespielanguages use the same ABI (object representation and calling 1074*c87b03e5Sespieconventions). The key idea in CNI is that Java objects are C++ 1075*c87b03e5Sespieobjects, and all Java classes are C++ classes (but not the other way 1076*c87b03e5Sespiearound). So the most important task in integrating Java and C++ is to 1077*c87b03e5Sespieremove gratuitous incompatibilities. 1078*c87b03e5Sespie 1079*c87b03e5SespieYou write CNI code as a regular C++ source file. (You do have to use 1080*c87b03e5Sespiea Java/CNI-aware C++ compiler, specifically a recent version of G++.) 1081*c87b03e5Sespie 1082*c87b03e5Sespie@noindent A CNI C++ source file must have: 1083*c87b03e5Sespie 1084*c87b03e5Sespie@example 1085*c87b03e5Sespie#include <gcj/cni.h> 1086*c87b03e5Sespie@end example 1087*c87b03e5Sespie 1088*c87b03e5Sespie@noindent and then must include one header file for each Java class it uses, e.g.: 1089*c87b03e5Sespie 1090*c87b03e5Sespie@example 1091*c87b03e5Sespie#include <java/lang/Character.h> 1092*c87b03e5Sespie#include <java/util/Date.h> 1093*c87b03e5Sespie#include <java/lang/IndexOutOfBoundsException.h> 1094*c87b03e5Sespie@end example 1095*c87b03e5Sespie 1096*c87b03e5Sespie@noindent These header files are automatically generated by @code{gcjh}. 1097*c87b03e5Sespie 1098*c87b03e5Sespie 1099*c87b03e5SespieCNI provides some functions and macros to make using Java objects and 1100*c87b03e5Sespieprimitive types from C++ easier. In general, these CNI functions and 1101*c87b03e5Sespiemacros start with the @code{Jv} prefix, for example the function 1102*c87b03e5Sespie@code{JvNewObjectArray}. This convention is used to avoid conflicts 1103*c87b03e5Sespiewith other libraries. Internal functions in CNI start with the prefix 1104*c87b03e5Sespie@code{_Jv_}. You should not call these; if you find a need to, let us 1105*c87b03e5Sespieknow and we will try to come up with an alternate solution. (This 1106*c87b03e5Sespiemanual lists @code{_Jv_AllocBytes} as an example; CNI should instead 1107*c87b03e5Sespieprovide a @code{JvAllocBytes} function.) 1108*c87b03e5Sespie 1109*c87b03e5Sespie 1110*c87b03e5Sespie@subsection Limitations 1111*c87b03e5Sespie 1112*c87b03e5SespieWhilst a Java class is just a C++ class that doesn't mean that you are 1113*c87b03e5Sespiefreed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the 1114*c87b03e5Sespierules of the Java programming language. 1115*c87b03e5Sespie 1116*c87b03e5SespieFor example: it is not possible to declare a method in a CNI class 1117*c87b03e5Sespiethat will take a C string (@code{char*}) as an argument, or to declare a 1118*c87b03e5Sespiemember variable of some non-Java datatype. 1119*c87b03e5Sespie 1120*c87b03e5Sespie 1121*c87b03e5Sespie@node Packages 1122*c87b03e5Sespie@section Packages 1123*c87b03e5Sespie 1124*c87b03e5SespieThe only global names in Java are class names, and packages. A 1125*c87b03e5Sespie@dfn{package} can contain zero or more classes, and also zero or more 1126*c87b03e5Sespiesub-packages. Every class belongs to either an unnamed package or a 1127*c87b03e5Sespiepackage that has a hierarchical and globally unique name. 1128*c87b03e5Sespie 1129*c87b03e5SespieA Java package is mapped to a C++ @dfn{namespace}. The Java class 1130*c87b03e5Sespie@code{java.lang.String} is in the package @code{java.lang}, which is a 1131*c87b03e5Sespiesub-package of @code{java}. The C++ equivalent is the class 1132*c87b03e5Sespie@code{java::lang::String}, which is in the namespace @code{java::lang} 1133*c87b03e5Sespiewhich is in the namespace @code{java}. 1134*c87b03e5Sespie 1135*c87b03e5Sespie@noindent Here is how you could express this: 1136*c87b03e5Sespie 1137*c87b03e5Sespie@example 1138*c87b03e5Sespie(// @r{Declare the class(es), possibly in a header file:} 1139*c87b03e5Sespienamespace java @{ 1140*c87b03e5Sespie namespace lang @{ 1141*c87b03e5Sespie class Object; 1142*c87b03e5Sespie class String; 1143*c87b03e5Sespie ... 1144*c87b03e5Sespie @} 1145*c87b03e5Sespie@} 1146*c87b03e5Sespie 1147*c87b03e5Sespieclass java::lang::String : public java::lang::Object 1148*c87b03e5Sespie@{ 1149*c87b03e5Sespie ... 1150*c87b03e5Sespie@}; 1151*c87b03e5Sespie@end example 1152*c87b03e5Sespie 1153*c87b03e5Sespie@noindent The @code{gcjh} tool automatically generates the necessary namespace 1154*c87b03e5Sespiedeclarations. 1155*c87b03e5Sespie 1156*c87b03e5Sespie 1157*c87b03e5Sespie@subsection Leaving out package names 1158*c87b03e5Sespie 1159*c87b03e5SespieAlways using the fully-qualified name of a java class can be 1160*c87b03e5Sespietiresomely verbose. Using the full qualified name also ties the code 1161*c87b03e5Sespieto a single package making code changes necessary should the class 1162*c87b03e5Sespiemove from one package to another. The Java @code{package} declaration 1163*c87b03e5Sespiespecifies that the following class declarations are in the named 1164*c87b03e5Sespiepackage, without having to explicitly name the full package 1165*c87b03e5Sespiequalifiers. The @code{package} declaration can be 1166*c87b03e5Sespiefollowed by zero or more @code{import} declarations, which 1167*c87b03e5Sespieallows either a single class or all the classes in a package to be 1168*c87b03e5Sespienamed by a simple identifier. C++ provides something similar with the 1169*c87b03e5Sespie@code{using} declaration and directive. 1170*c87b03e5Sespie 1171*c87b03e5Sespie@noindent In Java: 1172*c87b03e5Sespie 1173*c87b03e5Sespie@example 1174*c87b03e5Sespieimport @var{package-name}.@var{class-name}; 1175*c87b03e5Sespie@end example 1176*c87b03e5Sespie 1177*c87b03e5Sespie@noindent allows the program text to refer to @var{class-name} as a shorthand for 1178*c87b03e5Sespiethe fully qualified name: @code{@var{package-name}.@var{class-name}}. 1179*c87b03e5Sespie 1180*c87b03e5Sespie 1181*c87b03e5Sespie@noindent To achieve the same effect C++, you have to do this: 1182*c87b03e5Sespie 1183*c87b03e5Sespie@example 1184*c87b03e5Sespieusing @var{package-name}::@var{class-name}; 1185*c87b03e5Sespie@end example 1186*c87b03e5Sespie 1187*c87b03e5Sespie 1188*c87b03e5Sespie@noindent Java can also cause imports on demand, like this: 1189*c87b03e5Sespie 1190*c87b03e5Sespie@example 1191*c87b03e5Sespieimport @var{package-name}.*; 1192*c87b03e5Sespie@end example 1193*c87b03e5Sespie 1194*c87b03e5Sespie@noindent Doing this allows any class from the package @var{package-name} to be 1195*c87b03e5Sespiereferred to only by its class-name within the program text. 1196*c87b03e5Sespie 1197*c87b03e5Sespie 1198*c87b03e5Sespie@noindent The same effect can be achieved in C++ like this: 1199*c87b03e5Sespie 1200*c87b03e5Sespie@example 1201*c87b03e5Sespieusing namespace @var{package-name}; 1202*c87b03e5Sespie@end example 1203*c87b03e5Sespie 1204*c87b03e5Sespie 1205*c87b03e5Sespie@node Primitive types 1206*c87b03e5Sespie@section Primitive types 1207*c87b03e5Sespie 1208*c87b03e5SespieJava provides 8 @dfn{primitives} types which represent integers, floats, 1209*c87b03e5Sespiecharacters and booleans (and also the void type). C++ has its own 1210*c87b03e5Sespievery similar concrete types. Such types in C++ however are not always 1211*c87b03e5Sespieimplemented in the same way (an int might be 16, 32 or 64 bits for example) 1212*c87b03e5Sespieso CNI provides a special C++ type for each primitive Java type: 1213*c87b03e5Sespie 1214*c87b03e5Sespie@multitable @columnfractions .20 .25 .60 1215*c87b03e5Sespie@item @strong{Java type} @tab @strong{C/C++ typename} @tab @strong{Description} 1216*c87b03e5Sespie@item @code{char} @tab @code{jchar} @tab 16 bit Unicode character 1217*c87b03e5Sespie@item @code{boolean} @tab @code{jboolean} @tab logical (true or false) values 1218*c87b03e5Sespie@item @code{byte} @tab @code{jbyte} @tab 8-bit signed integer 1219*c87b03e5Sespie@item @code{short} @tab @code{jshort} @tab 16 bit signed integer 1220*c87b03e5Sespie@item @code{int} @tab @code{jint} @tab 32 bit signed integer 1221*c87b03e5Sespie@item @code{long} @tab @code{jlong} @tab 64 bit signed integer 1222*c87b03e5Sespie@item @code{float} @tab @code{jfloat} @tab 32 bit IEEE floating point number 1223*c87b03e5Sespie@item @code{double} @tab @code{jdouble} @tab 64 bit IEEE floating point number 1224*c87b03e5Sespie@item @code{void} @tab @code{void} @tab no value 1225*c87b03e5Sespie@end multitable 1226*c87b03e5Sespie 1227*c87b03e5SespieWhen referring to a Java type You should always use these C++ typenames (e.g.: @code{jint}) 1228*c87b03e5Sespieto avoid disappointment. 1229*c87b03e5Sespie 1230*c87b03e5Sespie 1231*c87b03e5Sespie@subsection Reference types associated with primitive types 1232*c87b03e5Sespie 1233*c87b03e5SespieIn Java each primitive type has an associated reference type, 1234*c87b03e5Sespiee.g.: @code{boolean} has an associated @code{java.lang.Boolean} class. 1235*c87b03e5SespieIn order to make working with such classes easier GCJ provides the macro 1236*c87b03e5Sespie@code{JvPrimClass}: 1237*c87b03e5Sespie 1238*c87b03e5Sespie@deffn macro JvPrimClass type 1239*c87b03e5SespieReturn a pointer to the @code{Class} object corresponding to the type supplied. 1240*c87b03e5Sespie 1241*c87b03e5Sespie@example 1242*c87b03e5SespieJvPrimClass(void) @result{} java.lang.Void.TYPE 1243*c87b03e5Sespie@end example 1244*c87b03e5Sespie 1245*c87b03e5Sespie@end deffn 1246*c87b03e5Sespie 1247*c87b03e5Sespie 1248*c87b03e5Sespie@node Interfaces 1249*c87b03e5Sespie@section Interfaces 1250*c87b03e5Sespie 1251*c87b03e5SespieA Java class can @dfn{implement} zero or more 1252*c87b03e5Sespie@dfn{interfaces}, in addition to inheriting from 1253*c87b03e5Sespiea single base class. 1254*c87b03e5Sespie 1255*c87b03e5Sespie@acronym{CNI} allows CNI code to implement methods of interfaces. 1256*c87b03e5SespieYou can also call methods through interface references, with some 1257*c87b03e5Sespielimitations. 1258*c87b03e5Sespie 1259*c87b03e5Sespie@acronym{CNI} doesn't understand interface inheritance at all yet. So, 1260*c87b03e5Sespieyou can only call an interface method when the declared type of the 1261*c87b03e5Sespiefield being called matches the interface which declares that 1262*c87b03e5Sespiemethod. The workaround is to cast the interface reference to the right 1263*c87b03e5Sespiesuperinterface. 1264*c87b03e5Sespie 1265*c87b03e5SespieFor example if you have: 1266*c87b03e5Sespie 1267*c87b03e5Sespie@example 1268*c87b03e5Sespieinterface A 1269*c87b03e5Sespie@{ 1270*c87b03e5Sespie void a(); 1271*c87b03e5Sespie@} 1272*c87b03e5Sespie 1273*c87b03e5Sespieinterface B extends A 1274*c87b03e5Sespie@{ 1275*c87b03e5Sespie void b(); 1276*c87b03e5Sespie@} 1277*c87b03e5Sespie@end example 1278*c87b03e5Sespie 1279*c87b03e5Sespieand declare a variable of type @code{B} in C++, you can't call 1280*c87b03e5Sespie@code{a()} unless you cast it to an @code{A} first. 1281*c87b03e5Sespie 1282*c87b03e5Sespie@node Objects and Classes 1283*c87b03e5Sespie@section Objects and Classes 1284*c87b03e5Sespie 1285*c87b03e5Sespie@subsection Classes 1286*c87b03e5Sespie 1287*c87b03e5SespieAll Java classes are derived from @code{java.lang.Object}. C++ does 1288*c87b03e5Sespienot have a unique root class, but we use the C++ class 1289*c87b03e5Sespie@code{java::lang::Object} as the C++ version of the 1290*c87b03e5Sespie@code{java.lang.Object} Java class. All other Java classes are mapped 1291*c87b03e5Sespieinto corresponding C++ classes derived from @code{java::lang::Object}. 1292*c87b03e5Sespie 1293*c87b03e5SespieInterface inheritance (the @code{implements} keyword) is currently not 1294*c87b03e5Sespiereflected in the C++ mapping. 1295*c87b03e5Sespie 1296*c87b03e5Sespie 1297*c87b03e5Sespie@subsection Object fields 1298*c87b03e5Sespie 1299*c87b03e5SespieEach object contains an object header, followed by the instance fields 1300*c87b03e5Sespieof the class, in order. The object header consists of a single 1301*c87b03e5Sespiepointer to a dispatch or virtual function table. (There may be extra 1302*c87b03e5Sespiefields @emph{in front of} the object, for example for memory 1303*c87b03e5Sespiemanagement, but this is invisible to the application, and the 1304*c87b03e5Sespiereference to the object points to the dispatch table pointer.) 1305*c87b03e5Sespie 1306*c87b03e5SespieThe fields are laid out in the same order, alignment, and size as in 1307*c87b03e5SespieC++. Specifically, 8-bite and 16-bit native types (@code{byte}, 1308*c87b03e5Sespie@code{short}, @code{char}, and @code{boolean}) are @emph{not} widened 1309*c87b03e5Sespieto 32 bits. Note that the Java VM does extend 8-bit and 16-bit types 1310*c87b03e5Sespieto 32 bits when on the VM stack or temporary registers. 1311*c87b03e5Sespie 1312*c87b03e5SespieIf you include the @code{gcjh}-generated header for a 1313*c87b03e5Sespieclass, you can access fields of Java classes in the @emph{natural} 1314*c87b03e5Sespieway. For example, given the following Java class: 1315*c87b03e5Sespie 1316*c87b03e5Sespie@example 1317*c87b03e5Sespiepublic class Int 1318*c87b03e5Sespie@{ 1319*c87b03e5Sespie public int i; 1320*c87b03e5Sespie public Integer (int i) @{ this.i = i; @} 1321*c87b03e5Sespie public static zero = new Integer(0); 1322*c87b03e5Sespie@} 1323*c87b03e5Sespie@end example 1324*c87b03e5Sespie 1325*c87b03e5Sespieyou can write: 1326*c87b03e5Sespie 1327*c87b03e5Sespie@example 1328*c87b03e5Sespie#include <gcj/cni.h>; 1329*c87b03e5Sespie#include <Int>; 1330*c87b03e5Sespie 1331*c87b03e5SespieInt* 1332*c87b03e5Sespiemult (Int *p, jint k) 1333*c87b03e5Sespie@{ 1334*c87b03e5Sespie if (k == 0) 1335*c87b03e5Sespie return Int::zero; // @r{Static member access.} 1336*c87b03e5Sespie return new Int(p->i * k); 1337*c87b03e5Sespie@} 1338*c87b03e5Sespie@end example 1339*c87b03e5Sespie 1340*c87b03e5Sespie 1341*c87b03e5Sespie@subsection Access specifiers 1342*c87b03e5Sespie 1343*c87b03e5SespieCNI does not strictly enforce the Java access 1344*c87b03e5Sespiespecifiers, because Java permissions cannot be directly mapped 1345*c87b03e5Sespieinto C++ permission. Private Java fields and methods are mapped 1346*c87b03e5Sespieto private C++ fields and methods, but other fields and methods 1347*c87b03e5Sespieare mapped to public fields and methods. 1348*c87b03e5Sespie 1349*c87b03e5Sespie 1350*c87b03e5Sespie 1351*c87b03e5Sespie@node Class Initialization 1352*c87b03e5Sespie@section Class Initialization 1353*c87b03e5Sespie 1354*c87b03e5SespieJava requires that each class be automatically initialized at the time 1355*c87b03e5Sespieof the first active use. Initializing a class involves 1356*c87b03e5Sespieinitializing the static fields, running code in class initializer 1357*c87b03e5Sespiemethods, and initializing base classes. There may also be 1358*c87b03e5Sespiesome implementation specific actions, such as allocating 1359*c87b03e5Sespie@code{String} objects corresponding to string literals in 1360*c87b03e5Sespiethe code. 1361*c87b03e5Sespie 1362*c87b03e5SespieThe GCJ compiler inserts calls to @code{JvInitClass} at appropriate 1363*c87b03e5Sespieplaces to ensure that a class is initialized when required. The C++ 1364*c87b03e5Sespiecompiler does not insert these calls automatically---it is the 1365*c87b03e5Sespieprogrammer's responsibility to make sure classes are initialized. 1366*c87b03e5SespieHowever, this is fairly painless because of the conventions assumed by 1367*c87b03e5Sespiethe Java system. 1368*c87b03e5Sespie 1369*c87b03e5SespieFirst, @code{libgcj} will make sure a class is initialized before an 1370*c87b03e5Sespieinstance of that object is created. This is one of the 1371*c87b03e5Sespieresponsibilities of the @code{new} operation. This is taken care of 1372*c87b03e5Sespieboth in Java code, and in C++ code. When G++ sees a @code{new} of a 1373*c87b03e5SespieJava class, it will call a routine in @code{libgcj} to allocate the 1374*c87b03e5Sespieobject, and that routine will take care of initializing the class. 1375*c87b03e5SespieNote however that this does not happen for Java arrays; you must 1376*c87b03e5Sespieallocate those using the appropriate CNI function. It follows that 1377*c87b03e5Sespieyou can access an instance field, or call an instance (non-static) 1378*c87b03e5Sespiemethod and be safe in the knowledge that the class and all of its base 1379*c87b03e5Sespieclasses have been initialized. 1380*c87b03e5Sespie 1381*c87b03e5SespieInvoking a static method is also safe. This is because the 1382*c87b03e5SespieJava compiler adds code to the start of a static method to make sure 1383*c87b03e5Sespiethe class is initialized. However, the C++ compiler does not 1384*c87b03e5Sespieadd this extra code. Hence, if you write a native static method 1385*c87b03e5Sespieusing CNI, you are responsible for calling @code{JvInitClass} 1386*c87b03e5Sespiebefore doing anything else in the method (unless you are sure 1387*c87b03e5Sespieit is safe to leave it out). 1388*c87b03e5Sespie 1389*c87b03e5SespieAccessing a static field also requires the class of the 1390*c87b03e5Sespiefield to be initialized. The Java compiler will generate code 1391*c87b03e5Sespieto call @code{Jv_InitClass} before getting or setting the field. 1392*c87b03e5SespieHowever, the C++ compiler will not generate this extra code, 1393*c87b03e5Sespieso it is your responsibility to make sure the class is 1394*c87b03e5Sespieinitialized before you access a static field from C++. 1395*c87b03e5Sespie 1396*c87b03e5Sespie 1397*c87b03e5Sespie@node Object allocation 1398*c87b03e5Sespie@section Object allocation 1399*c87b03e5Sespie 1400*c87b03e5SespieNew Java objects are allocated using a 1401*c87b03e5Sespie@dfn{class instance creation expression}, e.g.: 1402*c87b03e5Sespie 1403*c87b03e5Sespie@example 1404*c87b03e5Sespienew @var{Type} ( ... ) 1405*c87b03e5Sespie@end example 1406*c87b03e5Sespie 1407*c87b03e5SespieThe same syntax is used in C++. The main difference is that 1408*c87b03e5SespieC++ objects have to be explicitly deleted; in Java they are 1409*c87b03e5Sespieautomatically deleted by the garbage collector. 1410*c87b03e5SespieUsing @acronym{CNI}, you can allocate a new Java object 1411*c87b03e5Sespieusing standard C++ syntax and the C++ compiler will allocate 1412*c87b03e5Sespiememory from the garbage collector. If you have overloaded 1413*c87b03e5Sespieconstructors, the compiler will choose the correct one 1414*c87b03e5Sespieusing standard C++ overload resolution rules. 1415*c87b03e5Sespie 1416*c87b03e5Sespie@noindent For example: 1417*c87b03e5Sespie 1418*c87b03e5Sespie@example 1419*c87b03e5Sespiejava::util::Hashtable *ht = new java::util::Hashtable(120); 1420*c87b03e5Sespie@end example 1421*c87b03e5Sespie 1422*c87b03e5Sespie@deftypefun void* _Jv_AllocBytes (jsize @var{size}) 1423*c87b03e5SespieAllocates @var{size} bytes from the heap. The memory is not scanned 1424*c87b03e5Sespieby the garbage collector but it freed if no references to it are discovered. 1425*c87b03e5Sespie@end deftypefun 1426*c87b03e5Sespie 1427*c87b03e5Sespie 1428*c87b03e5Sespie@node Arrays 1429*c87b03e5Sespie@section Arrays 1430*c87b03e5Sespie 1431*c87b03e5SespieWhile in many ways Java is similar to C and C++, it is quite different 1432*c87b03e5Sespiein its treatment of arrays. C arrays are based on the idea of pointer 1433*c87b03e5Sespiearithmetic, which would be incompatible with Java's security 1434*c87b03e5Sespierequirements. Java arrays are true objects (array types inherit from 1435*c87b03e5Sespie@code{java.lang.Object}). An array-valued variable is one that 1436*c87b03e5Sespiecontains a reference (pointer) to an array object. 1437*c87b03e5Sespie 1438*c87b03e5SespieReferencing a Java array in C++ code is done using the 1439*c87b03e5Sespie@code{JArray} template, which as defined as follows: 1440*c87b03e5Sespie 1441*c87b03e5Sespie@example 1442*c87b03e5Sespieclass __JArray : public java::lang::Object 1443*c87b03e5Sespie@{ 1444*c87b03e5Sespiepublic: 1445*c87b03e5Sespie int length; 1446*c87b03e5Sespie@}; 1447*c87b03e5Sespie 1448*c87b03e5Sespietemplate<class T> 1449*c87b03e5Sespieclass JArray : public __JArray 1450*c87b03e5Sespie@{ 1451*c87b03e5Sespie T data[0]; 1452*c87b03e5Sespiepublic: 1453*c87b03e5Sespie T& operator[](jint i) @{ return data[i]; @} 1454*c87b03e5Sespie@}; 1455*c87b03e5Sespie@end example 1456*c87b03e5Sespie 1457*c87b03e5Sespie 1458*c87b03e5SespieThere are a number of @code{typedef}s which correspond to @code{typedef}s 1459*c87b03e5Sespiefrom the @acronym{JNI}. Each is the type of an array holding objects 1460*c87b03e5Sespieof the relevant type: 1461*c87b03e5Sespie 1462*c87b03e5Sespie@example 1463*c87b03e5Sespietypedef __JArray *jarray; 1464*c87b03e5Sespietypedef JArray<jobject> *jobjectArray; 1465*c87b03e5Sespietypedef JArray<jboolean> *jbooleanArray; 1466*c87b03e5Sespietypedef JArray<jbyte> *jbyteArray; 1467*c87b03e5Sespietypedef JArray<jchar> *jcharArray; 1468*c87b03e5Sespietypedef JArray<jshort> *jshortArray; 1469*c87b03e5Sespietypedef JArray<jint> *jintArray; 1470*c87b03e5Sespietypedef JArray<jlong> *jlongArray; 1471*c87b03e5Sespietypedef JArray<jfloat> *jfloatArray; 1472*c87b03e5Sespietypedef JArray<jdouble> *jdoubleArray; 1473*c87b03e5Sespie@end example 1474*c87b03e5Sespie 1475*c87b03e5Sespie 1476*c87b03e5Sespie@deftypemethod {template<class T>} T* elements (JArray<T> @var{array}) 1477*c87b03e5SespieThis template function can be used to get a pointer to the elements of 1478*c87b03e5Sespiethe @code{array}. For instance, you can fetch a pointer to the 1479*c87b03e5Sespieintegers that make up an @code{int[]} like so: 1480*c87b03e5Sespie 1481*c87b03e5Sespie@example 1482*c87b03e5Sespieextern jintArray foo; 1483*c87b03e5Sespiejint *intp = elements (foo); 1484*c87b03e5Sespie@end example 1485*c87b03e5Sespie 1486*c87b03e5SespieThe name of this function may change in the future. 1487*c87b03e5Sespie@end deftypemethod 1488*c87b03e5Sespie 1489*c87b03e5Sespie 1490*c87b03e5Sespie@deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init}) 1491*c87b03e5SespieHere @code{klass} is the type of elements of the array and 1492*c87b03e5Sespie@code{init} is the initial value put into every slot in the array. 1493*c87b03e5Sespie@end deftypefun 1494*c87b03e5Sespie 1495*c87b03e5Sespie 1496*c87b03e5Sespie@subsection Creating arrays 1497*c87b03e5Sespie 1498*c87b03e5SespieFor each primitive type there is a function which can be used to 1499*c87b03e5Sespiecreate a new array of that type. The name of the function is of the 1500*c87b03e5Sespieform: 1501*c87b03e5Sespie 1502*c87b03e5Sespie@example 1503*c87b03e5SespieJvNew@var{Type}Array 1504*c87b03e5Sespie@end example 1505*c87b03e5Sespie 1506*c87b03e5Sespie@noindent For example: 1507*c87b03e5Sespie 1508*c87b03e5Sespie@example 1509*c87b03e5SespieJvNewBooleanArray 1510*c87b03e5Sespie@end example 1511*c87b03e5Sespie 1512*c87b03e5Sespie@noindent can be used to create an array of Java primitive boolean types. 1513*c87b03e5Sespie 1514*c87b03e5Sespie@noindent The following function definition is the template for all such functions: 1515*c87b03e5Sespie 1516*c87b03e5Sespie@deftypefun jbooleanArray JvNewBooleanArray (jint @var{length}) 1517*c87b03e5SespieCreate's an array @var{length} indices long. 1518*c87b03e5Sespie@end deftypefun 1519*c87b03e5Sespie 1520*c87b03e5Sespie@deftypefun jsize JvGetArrayLength (jarray @var{array}) 1521*c87b03e5SespieReturns the length of the @var{array}. 1522*c87b03e5Sespie@end deftypefun 1523*c87b03e5Sespie 1524*c87b03e5Sespie 1525*c87b03e5Sespie@node Methods 1526*c87b03e5Sespie@section Methods 1527*c87b03e5Sespie 1528*c87b03e5SespieJava methods are mapped directly into C++ methods. 1529*c87b03e5SespieThe header files generated by @code{gcjh} 1530*c87b03e5Sespieinclude the appropriate method definitions. 1531*c87b03e5SespieBasically, the generated methods have the same names and 1532*c87b03e5Sespie@emph{corresponding} types as the Java methods, 1533*c87b03e5Sespieand are called in the natural manner. 1534*c87b03e5Sespie 1535*c87b03e5Sespie@subsection Overloading 1536*c87b03e5Sespie 1537*c87b03e5SespieBoth Java and C++ provide method overloading, where multiple 1538*c87b03e5Sespiemethods in a class have the same name, and the correct one is chosen 1539*c87b03e5Sespie(at compile time) depending on the argument types. 1540*c87b03e5SespieThe rules for choosing the correct method are (as expected) more complicated 1541*c87b03e5Sespiein C++ than in Java, but given a set of overloaded methods 1542*c87b03e5Sespiegenerated by @code{gcjh} the C++ compiler will choose 1543*c87b03e5Sespiethe expected one. 1544*c87b03e5Sespie 1545*c87b03e5SespieCommon assemblers and linkers are not aware of C++ overloading, 1546*c87b03e5Sespieso the standard implementation strategy is to encode the 1547*c87b03e5Sespieparameter types of a method into its assembly-level name. 1548*c87b03e5SespieThis encoding is called @dfn{mangling}, 1549*c87b03e5Sespieand the encoded name is the @dfn{mangled name}. 1550*c87b03e5SespieThe same mechanism is used to implement Java overloading. 1551*c87b03e5SespieFor C++/Java interoperability, it is important that both the Java 1552*c87b03e5Sespieand C++ compilers use the @emph{same} encoding scheme. 1553*c87b03e5Sespie 1554*c87b03e5Sespie@subsection Static methods 1555*c87b03e5Sespie 1556*c87b03e5SespieStatic Java methods are invoked in @acronym{CNI} using the standard 1557*c87b03e5SespieC++ syntax, using the @code{::} operator rather 1558*c87b03e5Sespiethan the @code{.} operator. 1559*c87b03e5Sespie 1560*c87b03e5Sespie@noindent For example: 1561*c87b03e5Sespie 1562*c87b03e5Sespie@example 1563*c87b03e5Sespiejint i = java::lang::Math::round((jfloat) 2.3); 1564*c87b03e5Sespie@end example 1565*c87b03e5Sespie 1566*c87b03e5Sespie@noindent C++ method definition syntax is used to define a static native method. 1567*c87b03e5SespieFor example: 1568*c87b03e5Sespie 1569*c87b03e5Sespie@example 1570*c87b03e5Sespie#include <java/lang/Integer> 1571*c87b03e5Sespiejava::lang::Integer* 1572*c87b03e5Sespiejava::lang::Integer::getInteger(jstring str) 1573*c87b03e5Sespie@{ 1574*c87b03e5Sespie ... 1575*c87b03e5Sespie@} 1576*c87b03e5Sespie@end example 1577*c87b03e5Sespie 1578*c87b03e5Sespie 1579*c87b03e5Sespie@subsection Object Constructors 1580*c87b03e5Sespie 1581*c87b03e5SespieConstructors are called implicitly as part of object allocation 1582*c87b03e5Sespieusing the @code{new} operator. 1583*c87b03e5Sespie 1584*c87b03e5Sespie@noindent For example: 1585*c87b03e5Sespie 1586*c87b03e5Sespie@example 1587*c87b03e5Sespiejava::lang::Integer *x = new java::lang::Integer(234); 1588*c87b03e5Sespie@end example 1589*c87b03e5Sespie 1590*c87b03e5SespieJava does not allow a constructor to be a native method. 1591*c87b03e5SespieThis limitation can be coded round however because a constructor 1592*c87b03e5Sespiecan @emph{call} a native method. 1593*c87b03e5Sespie 1594*c87b03e5Sespie 1595*c87b03e5Sespie@subsection Instance methods 1596*c87b03e5Sespie 1597*c87b03e5SespieCalling a Java instance method from a C++ @acronym{CNI} method is done 1598*c87b03e5Sespieusing the standard C++ syntax, e.g.: 1599*c87b03e5Sespie 1600*c87b03e5Sespie@example 1601*c87b03e5Sespie// @r{First create the Java object.} 1602*c87b03e5Sespiejava::lang::Integer *x = new java::lang::Integer(234); 1603*c87b03e5Sespie// @r{Now call a method.} 1604*c87b03e5Sespiejint prim_value = x->intValue(); 1605*c87b03e5Sespieif (x->longValue == 0) 1606*c87b03e5Sespie ... 1607*c87b03e5Sespie@end example 1608*c87b03e5Sespie 1609*c87b03e5Sespie@noindent Defining a Java native instance method is also done the natural way: 1610*c87b03e5Sespie 1611*c87b03e5Sespie@example 1612*c87b03e5Sespie#include <java/lang/Integer.h> 1613*c87b03e5Sespie 1614*c87b03e5Sespiejdouble 1615*c87b03e5Sespiejava::lang:Integer::doubleValue() 1616*c87b03e5Sespie@{ 1617*c87b03e5Sespie return (jdouble) value; 1618*c87b03e5Sespie@} 1619*c87b03e5Sespie@end example 1620*c87b03e5Sespie 1621*c87b03e5Sespie 1622*c87b03e5Sespie@subsection Interface methods 1623*c87b03e5Sespie 1624*c87b03e5SespieIn Java you can call a method using an interface reference. This is 1625*c87b03e5Sespiesupported, but not completely. @xref{Interfaces}. 1626*c87b03e5Sespie 1627*c87b03e5Sespie 1628*c87b03e5Sespie 1629*c87b03e5Sespie 1630*c87b03e5Sespie@node Strings 1631*c87b03e5Sespie@section Strings 1632*c87b03e5Sespie 1633*c87b03e5Sespie@acronym{CNI} provides a number of utility functions for 1634*c87b03e5Sespieworking with Java Java @code{String} objects. 1635*c87b03e5SespieThe names and interfaces are analogous to those of @acronym{JNI}. 1636*c87b03e5Sespie 1637*c87b03e5Sespie 1638*c87b03e5Sespie@deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len}) 1639*c87b03e5SespieReturns a Java @code{String} object with characters from the C string 1640*c87b03e5Sespie@var{chars} up to the index @var{len} in that array. 1641*c87b03e5Sespie@end deftypefun 1642*c87b03e5Sespie 1643*c87b03e5Sespie@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len}) 1644*c87b03e5SespieReturns a Java @code{String} made up of @var{len} bytes from @var{bytes}. 1645*c87b03e5Sespie@end deftypefun 1646*c87b03e5Sespie 1647*c87b03e5Sespie 1648*c87b03e5Sespie@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}) 1649*c87b03e5SespieAs above but the length of the @code{String} is @code{strlen(@var{bytes})}. 1650*c87b03e5Sespie@end deftypefun 1651*c87b03e5Sespie 1652*c87b03e5Sespie@deftypefun jstring JvNewStringUTF (const char* @var{bytes}) 1653*c87b03e5SespieReturns a @code{String} which is made up of the UTF encoded characters 1654*c87b03e5Sespiepresent in the C string @var{bytes}. 1655*c87b03e5Sespie@end deftypefun 1656*c87b03e5Sespie 1657*c87b03e5Sespie@deftypefun jchar* JvGetStringChars (jstring @var{str}) 1658*c87b03e5SespieReturns a pointer to an array of characters making up the @code{String} @var{str}. 1659*c87b03e5Sespie@end deftypefun 1660*c87b03e5Sespie 1661*c87b03e5Sespie@deftypefun int JvGetStringUTFLength (jstring @var{str}) 1662*c87b03e5SespieReturns the number of bytes required to encode the contents of the 1663*c87b03e5Sespie@code{String} @var{str} in UTF-8. 1664*c87b03e5Sespie@end deftypefun 1665*c87b03e5Sespie 1666*c87b03e5Sespie@deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf}) 1667*c87b03e5SespiePuts the UTF-8 encoding of a region of the @code{String} @var{str} into 1668*c87b03e5Sespiethe buffer @code{buf}. The region to fetch is marked by @var{start} and @var{len}. 1669*c87b03e5Sespie 1670*c87b03e5SespieNote that @var{buf} is a buffer, not a C string. It is @emph{not} 1671*c87b03e5Sespienull terminated. 1672*c87b03e5Sespie@end deftypefun 1673*c87b03e5Sespie 1674*c87b03e5Sespie 1675*c87b03e5Sespie@node Mixing with C++ 1676*c87b03e5Sespie@section Interoperating with C/C++ 1677*c87b03e5Sespie 1678*c87b03e5SespieBecause @acronym{CNI} is designed to represent Java classes and methods it 1679*c87b03e5Sespiecannot be mixed readily with C/C++ types. 1680*c87b03e5Sespie 1681*c87b03e5SespieOne important restriction is that Java classes cannot have non-Java 1682*c87b03e5Sespietype instance or static variables and cannot have methods which take 1683*c87b03e5Sespienon-Java types as arguments or return non-Java types. 1684*c87b03e5Sespie 1685*c87b03e5Sespie@noindent None of the following is possible with CNI: 1686*c87b03e5Sespie 1687*c87b03e5Sespie@example 1688*c87b03e5Sespie 1689*c87b03e5Sespieclass ::MyClass : public java::lang::Object 1690*c87b03e5Sespie@{ 1691*c87b03e5Sespie char* variable; // @r{char* is not a valid Java type.} 1692*c87b03e5Sespie@} 1693*c87b03e5Sespie 1694*c87b03e5Sespie 1695*c87b03e5Sespieuint 1696*c87b03e5Sespie::SomeClass::someMethod (char *arg) 1697*c87b03e5Sespie@{ 1698*c87b03e5Sespie . 1699*c87b03e5Sespie . 1700*c87b03e5Sespie . 1701*c87b03e5Sespie@} // @r{@code{uint} is not a valid Java type, neither is @code{char*}} 1702*c87b03e5Sespie@end example 1703*c87b03e5Sespie 1704*c87b03e5Sespie@noindent Of course, it is ok to use C/C++ types within the scope of a method: 1705*c87b03e5Sespie 1706*c87b03e5Sespie 1707*c87b03e5Sespie@example 1708*c87b03e5Sespiejint 1709*c87b03e5Sespie::SomeClass::otherMethod (jstring str) 1710*c87b03e5Sespie@{ 1711*c87b03e5Sespie char *arg = ... 1712*c87b03e5Sespie . 1713*c87b03e5Sespie . 1714*c87b03e5Sespie . 1715*c87b03e5Sespie@} 1716*c87b03e5Sespie@end example 1717*c87b03e5Sespie 1718*c87b03e5SespieBut this restriction can cause a problem so @acronym{CNI} includes the 1719*c87b03e5Sespie@code{gnu.gcj.RawData} class. The @code{RawData} class is a 1720*c87b03e5Sespie@dfn{non-scanned reference} type. In other words variables declared 1721*c87b03e5Sespieof type @code{RawData} can contain any data and are not checked by the 1722*c87b03e5Sespiecompiler in any way. 1723*c87b03e5Sespie 1724*c87b03e5SespieThis means that you can put C/C++ data structures (including classes) 1725*c87b03e5Sespiein your @acronym{CNI} classes, as long as you use the appropriate cast. 1726*c87b03e5Sespie 1727*c87b03e5Sespie@noindent Here are some examples: 1728*c87b03e5Sespie 1729*c87b03e5Sespie@example 1730*c87b03e5Sespie 1731*c87b03e5Sespieclass ::MyClass : public java::lang::Object 1732*c87b03e5Sespie@{ 1733*c87b03e5Sespie gnu.gcj.RawData string; 1734*c87b03e5Sespie 1735*c87b03e5Sespie MyClass (); 1736*c87b03e5Sespie gnu.gcj.RawData getText (); 1737*c87b03e5Sespie void printText (); 1738*c87b03e5Sespie@} 1739*c87b03e5Sespie 1740*c87b03e5Sespie::MyClass::MyClass () 1741*c87b03e5Sespie@{ 1742*c87b03e5Sespie char* text = ... 1743*c87b03e5Sespie string = text; 1744*c87b03e5Sespie@} 1745*c87b03e5Sespie 1746*c87b03e5Sespiegnu.gcj.RawData 1747*c87b03e5Sespie::MyClass::getText () 1748*c87b03e5Sespie@{ 1749*c87b03e5Sespie return string; 1750*c87b03e5Sespie@} 1751*c87b03e5Sespie 1752*c87b03e5Sespievoid 1753*c87b03e5Sespie::MyClass::printText () 1754*c87b03e5Sespie@{ 1755*c87b03e5Sespie printf("%s\n", (char*) string); 1756*c87b03e5Sespie@} 1757*c87b03e5Sespie@end example 1758*c87b03e5Sespie 1759*c87b03e5Sespie 1760*c87b03e5Sespie@node Exception Handling 1761*c87b03e5Sespie@section Exception Handling 1762*c87b03e5Sespie 1763*c87b03e5SespieWhile C++ and Java share a common exception handling framework, 1764*c87b03e5Sespiethings are not yet perfectly integrated. The main issue is that the 1765*c87b03e5Sespierun-time type information facilities of the two 1766*c87b03e5Sespielanguages are not integrated. 1767*c87b03e5Sespie 1768*c87b03e5SespieStill, things work fairly well. You can throw a Java exception from 1769*c87b03e5SespieC++ using the ordinary @code{throw} construct, and this 1770*c87b03e5Sespieexception can be caught by Java code. Similarly, you can catch an 1771*c87b03e5Sespieexception thrown from Java using the C++ @code{catch} 1772*c87b03e5Sespieconstruct. 1773*c87b03e5Sespie 1774*c87b03e5Sespie@noindent Here is an example: 1775*c87b03e5Sespie 1776*c87b03e5Sespie@example 1777*c87b03e5Sespieif (i >= count) 1778*c87b03e5Sespie throw new java::lang::IndexOutOfBoundsException(); 1779*c87b03e5Sespie@end example 1780*c87b03e5Sespie 1781*c87b03e5SespieNormally, G++ will automatically detect when you are writing C++ 1782*c87b03e5Sespiecode that uses Java exceptions, and handle them appropriately. 1783*c87b03e5SespieHowever, if C++ code only needs to execute destructors when Java 1784*c87b03e5Sespieexceptions are thrown through it, GCC will guess incorrectly. Sample 1785*c87b03e5Sespieproblematic code: 1786*c87b03e5Sespie 1787*c87b03e5Sespie@example 1788*c87b03e5Sespiestruct S @{ ~S(); @}; 1789*c87b03e5Sespie 1790*c87b03e5Sespieextern void bar(); // @r{Is implemented in Java and may throw exceptions.} 1791*c87b03e5Sespie 1792*c87b03e5Sespievoid foo() 1793*c87b03e5Sespie@{ 1794*c87b03e5Sespie S s; 1795*c87b03e5Sespie bar(); 1796*c87b03e5Sespie@} 1797*c87b03e5Sespie@end example 1798*c87b03e5Sespie 1799*c87b03e5SespieThe usual effect of an incorrect guess is a link failure, complaining of 1800*c87b03e5Sespiea missing routine called @code{__gxx_personality_v0}. 1801*c87b03e5Sespie 1802*c87b03e5SespieYou can inform the compiler that Java exceptions are to be used in a 1803*c87b03e5Sespietranslation unit, irrespective of what it might think, by writing 1804*c87b03e5Sespie@code{#pragma GCC java_exceptions} at the head of the 1805*c87b03e5Sespiefile. This @code{#pragma} must appear before any 1806*c87b03e5Sespiefunctions that throw or catch exceptions, or run destructors when 1807*c87b03e5Sespieexceptions are thrown through them. 1808*c87b03e5Sespie 1809*c87b03e5Sespie@node Synchronization 1810*c87b03e5Sespie@section Synchronization 1811*c87b03e5Sespie 1812*c87b03e5SespieEach Java object has an implicit monitor. 1813*c87b03e5SespieThe Java VM uses the instruction @code{monitorenter} to acquire 1814*c87b03e5Sespieand lock a monitor, and @code{monitorexit} to release it. 1815*c87b03e5Sespie 1816*c87b03e5SespieThe corresponding CNI macros are @code{JvMonitorEnter} and 1817*c87b03e5Sespie@code{JvMonitorExit} (JNI has similar methods @code{MonitorEnter} 1818*c87b03e5Sespieand @code{MonitorExit}). 1819*c87b03e5Sespie 1820*c87b03e5Sespie 1821*c87b03e5SespieThe Java source language does not provide direct access to these primitives. 1822*c87b03e5SespieInstead, there is a @code{synchronized} statement that does an 1823*c87b03e5Sespieimplicit @code{monitorenter} before entry to the block, 1824*c87b03e5Sespieand does a @code{monitorexit} on exit from the block. 1825*c87b03e5SespieNote that the lock has to be released even when the block is abnormally 1826*c87b03e5Sespieterminated by an exception, which means there is an implicit 1827*c87b03e5Sespie@code{try finally} surrounding synchronization locks. 1828*c87b03e5Sespie 1829*c87b03e5SespieFrom C++, it makes sense to use a destructor to release a lock. 1830*c87b03e5Sespie@acronym{CNI} defines the following utility class: 1831*c87b03e5Sespie 1832*c87b03e5Sespie@example 1833*c87b03e5Sespieclass JvSynchronize() @{ 1834*c87b03e5Sespie jobject obj; 1835*c87b03e5Sespie JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @} 1836*c87b03e5Sespie ~JvSynchronize() @{ JvMonitorExit(obj); @} 1837*c87b03e5Sespie@}; 1838*c87b03e5Sespie@end example 1839*c87b03e5Sespie 1840*c87b03e5SespieSo this Java code: 1841*c87b03e5Sespie 1842*c87b03e5Sespie@example 1843*c87b03e5Sespiesynchronized (OBJ) 1844*c87b03e5Sespie@{ 1845*c87b03e5Sespie CODE 1846*c87b03e5Sespie@} 1847*c87b03e5Sespie@end example 1848*c87b03e5Sespie 1849*c87b03e5Sespie@noindent might become this C++ code: 1850*c87b03e5Sespie 1851*c87b03e5Sespie@example 1852*c87b03e5Sespie@{ 1853*c87b03e5Sespie JvSynchronize dummy (OBJ); 1854*c87b03e5Sespie CODE; 1855*c87b03e5Sespie@} 1856*c87b03e5Sespie@end example 1857*c87b03e5Sespie 1858*c87b03e5SespieJava also has methods with the @code{synchronized} attribute. 1859*c87b03e5SespieThis is equivalent to wrapping the entire method body in a 1860*c87b03e5Sespie@code{synchronized} statement. 1861*c87b03e5Sespie(Alternatively, an implementation could require the caller to do 1862*c87b03e5Sespiethe synchronization. This is not practical for a compiler, because 1863*c87b03e5Sespieeach virtual method call would have to test at run-time if 1864*c87b03e5Sespiesynchronization is needed.) Since in @command{gcj} 1865*c87b03e5Sespiethe @code{synchronized} attribute is handled by the 1866*c87b03e5Sespiemethod implementation, it is up to the programmer 1867*c87b03e5Sespieof a synchronized native method to handle the synchronization 1868*c87b03e5Sespie(in the C++ implementation of the method). 1869*c87b03e5SespieIn other words, you need to manually add @code{JvSynchronize} 1870*c87b03e5Sespiein a @code{native synchronized} method. 1871*c87b03e5Sespie 1872*c87b03e5Sespie@node Invocation 1873*c87b03e5Sespie@section Invocation 1874*c87b03e5Sespie 1875*c87b03e5SespieCNI permits C++ applications to make calls into Java classes, in addition to 1876*c87b03e5Sespieallowing Java code to call into C++. Several functions, known as the 1877*c87b03e5Sespie@dfn{invocation API}, are provided to support this. 1878*c87b03e5Sespie 1879*c87b03e5Sespie@deftypefun jint JvCreateJavaVM (void* @var{vm_args}) 1880*c87b03e5SespieInitializes the Java runtime. This function performs essential initialization 1881*c87b03e5Sespieof the threads interface, garbage collector, exception handling and other key 1882*c87b03e5Sespieaspects of the runtime. It must be called once by an application with 1883*c87b03e5Sespiea non-Java @code{main()} function, before any other Java or CNI calls are made. 1884*c87b03e5SespieIt is safe, but not recommended, to call @code{JvCreateJavaVM()} more than 1885*c87b03e5Sespieonce provided it is only called from a single thread. 1886*c87b03e5SespieThe @var{vmargs} parameter can be used to specify initialization parameters 1887*c87b03e5Sespiefor the Java runtime. It may be @code{NULL}. 1888*c87b03e5SespieThis function returns @code{0} upon success, or @code{-1} if the runtime is 1889*c87b03e5Sespiealready initialized. 1890*c87b03e5Sespie 1891*c87b03e5Sespie@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It may be 1892*c87b03e5Sespieused in a future release. 1893*c87b03e5Sespie@end deftypefun 1894*c87b03e5Sespie 1895*c87b03e5Sespie@deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group}) 1896*c87b03e5SespieRegisters an existing thread with the Java runtime. This must be called once 1897*c87b03e5Sespiefrom each thread, before that thread makes any other Java or CNI calls. It 1898*c87b03e5Sespiemust be called after @code{JvCreateJavaVM}. 1899*c87b03e5Sespie@var{name} specifies a name for the thread. It may be @code{NULL}, in which 1900*c87b03e5Sespiecase a name will be generated. 1901*c87b03e5Sespie@var{group} is the ThreadGroup in which this thread will be a member. If it 1902*c87b03e5Sespieis @code{NULL}, the thread will be a member of the main thread group. 1903*c87b03e5SespieThe return value is the Java @code{Thread} object that represents the thread. 1904*c87b03e5SespieIt is safe to call @code{JvAttachCurrentThread()} more than once from the same 1905*c87b03e5Sespiethread. If the thread is already attached, the call is ignored and the current 1906*c87b03e5Sespiethread object is returned. 1907*c87b03e5Sespie@end deftypefun 1908*c87b03e5Sespie 1909*c87b03e5Sespie@deftypefun jint JvDetachCurrentThread () 1910*c87b03e5SespieUnregisters a thread from the Java runtime. This should be called by threads 1911*c87b03e5Sespiethat were attached using @code{JvAttachCurrentThread()}, after they have 1912*c87b03e5Sespiefinished making calls to Java code. This ensures that any resources associated 1913*c87b03e5Sespiewith the thread become eligible for garbage collection. 1914*c87b03e5SespieThis function returns @code{0} upon success, or @code{-1} if the current thread 1915*c87b03e5Sespieis not attached. 1916*c87b03e5Sespie@end deftypefun 1917*c87b03e5Sespie 1918*c87b03e5Sespie@subsection Handling uncaught exceptions 1919*c87b03e5Sespie 1920*c87b03e5SespieIf an exception is thrown from Java code called using the invocation API, and 1921*c87b03e5Sespieno handler for the exception can be found, the runtime will abort the 1922*c87b03e5Sespieapplication. In order to make the application more robust, it is recommended 1923*c87b03e5Sespiethat code which uses the invocation API be wrapped by a top-level try/catch 1924*c87b03e5Sespieblock that catches all Java exceptions. 1925*c87b03e5Sespie 1926*c87b03e5Sespie@subsection Example 1927*c87b03e5Sespie 1928*c87b03e5SespieThe following code demonstrates the use of the invocation API. In this 1929*c87b03e5Sespieexample, the C++ application initializes the Java runtime and attaches 1930*c87b03e5Sespieitself. The @code{java.lang.System} class is initialized in order to 1931*c87b03e5Sespieaccess its @code{out} field, and a Java string is printed. Finally, the thread 1932*c87b03e5Sespieis detached from the runtime once it has finished making Java calls. Everything 1933*c87b03e5Sespieis wrapped with a try/catch block to provide a default handler for any uncaught 1934*c87b03e5Sespieexceptions. 1935*c87b03e5Sespie 1936*c87b03e5SespieThe example can be compiled with @command{c++ test.cc -lgcj}. 1937*c87b03e5Sespie 1938*c87b03e5Sespie@example 1939*c87b03e5Sespie// test.cc 1940*c87b03e5Sespie#include <gcj/cni.h> 1941*c87b03e5Sespie#include <java/lang/System.h> 1942*c87b03e5Sespie#include <java/io/PrintStream.h> 1943*c87b03e5Sespie#include <java/lang/Throwable.h> 1944*c87b03e5Sespie 1945*c87b03e5Sespieint main(int argc, char *argv) 1946*c87b03e5Sespie@{ 1947*c87b03e5Sespie using namespace java::lang; 1948*c87b03e5Sespie 1949*c87b03e5Sespie try 1950*c87b03e5Sespie @{ 1951*c87b03e5Sespie JvCreateJavaVM(NULL); 1952*c87b03e5Sespie JvAttachCurrentThread(NULL, NULL); 1953*c87b03e5Sespie 1954*c87b03e5Sespie String *message = JvNewStringLatin1("Hello from C++"); 1955*c87b03e5Sespie JvInitClass(&System::class$); 1956*c87b03e5Sespie System::out->println(message); 1957*c87b03e5Sespie 1958*c87b03e5Sespie JvDetachCurrentThread(); 1959*c87b03e5Sespie @} 1960*c87b03e5Sespie catch (Throwable *t) 1961*c87b03e5Sespie @{ 1962*c87b03e5Sespie System::err->println(JvNewStringLatin1("Unhandled Java exception:")); 1963*c87b03e5Sespie t->printStackTrace(); 1964*c87b03e5Sespie @} 1965*c87b03e5Sespie@} 1966*c87b03e5Sespie@end example 1967*c87b03e5Sespie 1968*c87b03e5Sespie@node Reflection 1969*c87b03e5Sespie@section Reflection 1970*c87b03e5Sespie 1971*c87b03e5SespieReflection is possible with CNI code, it functions similarly to how it 1972*c87b03e5Sespiefunctions with JNI@. 1973*c87b03e5Sespie 1974*c87b03e5Sespie@c clean this up... I mean, what are the types jfieldID and jmethodID in JNI? 1975*c87b03e5SespieThe types @code{jfieldID} and @code{jmethodID} 1976*c87b03e5Sespieare as in JNI@. 1977*c87b03e5Sespie 1978*c87b03e5Sespie@noindent The functions: 1979*c87b03e5Sespie 1980*c87b03e5Sespie@itemize 1981*c87b03e5Sespie@item @code{JvFromReflectedField}, 1982*c87b03e5Sespie@item @code{JvFromReflectedMethod}, 1983*c87b03e5Sespie@item @code{JvToReflectedField} 1984*c87b03e5Sespie@item @code{JvToFromReflectedMethod} 1985*c87b03e5Sespie@end itemize 1986*c87b03e5Sespie 1987*c87b03e5Sespie@noindent will be added shortly, as will other functions corresponding to JNI@. 1988*c87b03e5Sespie 1989*c87b03e5Sespie 1990*c87b03e5Sespie@node System properties 1991*c87b03e5Sespie@chapter System properties 1992*c87b03e5Sespie 1993*c87b03e5SespieThe runtime behavior of the @code{libgcj} library can be modified by setting 1994*c87b03e5Sespiecertain system properties. These properties can be compiled into the program 1995*c87b03e5Sespieusing the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by 1996*c87b03e5Sespiesetting them explicitly in the program by calling the 1997*c87b03e5Sespie@code{java.lang.System.setProperty()} method. Some system properties are only 1998*c87b03e5Sespieused for informational purposes (like giving a version number or a user name). 1999*c87b03e5SespieA program can inspect the current value of a property by calling the 2000*c87b03e5Sespie@code{java.lang.System.getProperty()} method. 2001*c87b03e5Sespie 2002*c87b03e5Sespie@menu 2003*c87b03e5Sespie* Standard Properties:: Standard properties supported by @code{libgcj} 2004*c87b03e5Sespie* GNU Classpath Properties:: Properties found in Classpath based libraries 2005*c87b03e5Sespie* libgcj Runtime Properties:: Properties specific to @code{libgcj} 2006*c87b03e5Sespie@end menu 2007*c87b03e5Sespie 2008*c87b03e5Sespie@node Standard Properties 2009*c87b03e5Sespie@section Standard Properties 2010*c87b03e5Sespie 2011*c87b03e5SespieThe following properties are normally found in all implementations of the core 2012*c87b03e5Sespielibraries for the Java language. 2013*c87b03e5Sespie 2014*c87b03e5Sespie@table @gcctabopt 2015*c87b03e5Sespie 2016*c87b03e5Sespie@item java.version 2017*c87b03e5SespieThe @code{libgcj} version number. 2018*c87b03e5Sespie 2019*c87b03e5Sespie@item java.vendor 2020*c87b03e5SespieSet to @samp{The Free Software Foundation, Inc.} 2021*c87b03e5Sespie 2022*c87b03e5Sespie@item java.vendor.url 2023*c87b03e5SespieSet to @uref{http://gcc.gnu.org/java/}. 2024*c87b03e5Sespie 2025*c87b03e5Sespie@item java.home 2026*c87b03e5SespieThe directory where @code{gcj} was installed. Taken from the @code{--prefix} 2027*c87b03e5Sespieoption given to @command{configure}. 2028*c87b03e5Sespie 2029*c87b03e5Sespie@item java.class.version 2030*c87b03e5SespieThe class format version number supported by the libgcj byte code interpreter. 2031*c87b03e5Sespie(Currently @samp{46.0}) 2032*c87b03e5Sespie 2033*c87b03e5Sespie@item java.vm.specification.version 2034*c87b03e5SespieThe Virtual Machine Specification version implemented by @code{libgcj}. 2035*c87b03e5Sespie(Currently @samp{1.0}) 2036*c87b03e5Sespie 2037*c87b03e5Sespie@item java.vm.specification.vendor 2038*c87b03e5SespieThe name of the Virtual Machine specification designer. 2039*c87b03e5Sespie 2040*c87b03e5Sespie@item java.vm.specification.name 2041*c87b03e5SespieThe name of the Virtual Machine specification 2042*c87b03e5Sespie(Set to @samp{Java Virtual Machine Specification}). 2043*c87b03e5Sespie 2044*c87b03e5Sespie@item java.vm.version 2045*c87b03e5SespieThe @command{gcj} version number. 2046*c87b03e5Sespie 2047*c87b03e5Sespie@item java.vm.vendor 2048*c87b03e5SespieSet to @samp{The Free Software Foundation, Inc.} 2049*c87b03e5Sespie 2050*c87b03e5Sespie@item java.vm.name 2051*c87b03e5SespieSet to @samp{GNU libgcj}. 2052*c87b03e5Sespie 2053*c87b03e5Sespie@item java.specification.version 2054*c87b03e5SespieThe Runtime Environment specification version implemented by @code{libgcj}. 2055*c87b03e5Sespie(Currently set to @samp{1.3}) 2056*c87b03e5Sespie 2057*c87b03e5Sespie@item java.specification.vendor 2058*c87b03e5SespieThe Runtime Environment specification designer. 2059*c87b03e5Sespie 2060*c87b03e5Sespie@item java.specification.name 2061*c87b03e5SespieThe name of the Runtime Environment specification 2062*c87b03e5Sespie(Set to @samp{Java Platform API Specification}). 2063*c87b03e5Sespie 2064*c87b03e5Sespie@item java.class.path 2065*c87b03e5SespieThe paths (jar files, zip files and directories) used for finding class files. 2066*c87b03e5Sespie 2067*c87b03e5Sespie@item java.library.path 2068*c87b03e5SespieDirectory path used for finding native libraries. 2069*c87b03e5Sespie 2070*c87b03e5Sespie@item java.io.tmpdir 2071*c87b03e5SespieThe directory used to put temporary files in. 2072*c87b03e5Sespie 2073*c87b03e5Sespie@item java.compiler 2074*c87b03e5SespieName of the Just In Time compiler to use by the byte code interpreter. 2075*c87b03e5SespieCurrently not used in @code{libgcj}. 2076*c87b03e5Sespie 2077*c87b03e5Sespie@item java.ext.dirs 2078*c87b03e5SespieDirectories containing jar files with extra libraries. Will be used when 2079*c87b03e5Sespieresolving classes. Currently not used in @code{libgcj}. 2080*c87b03e5Sespie 2081*c87b03e5Sespie@item java.protocol.handler.pkgs 2082*c87b03e5SespieA @samp{|} separated list of package names that is used to find classes that 2083*c87b03e5Sespieimplement handlers for @code{java.net.URL}. 2084*c87b03e5Sespie 2085*c87b03e5Sespie@item java.rmi.server.codebase 2086*c87b03e5SespieA list of URLs that is used by the @code{java.rmi.server.RMIClassLoader} 2087*c87b03e5Sespieto load classes from. 2088*c87b03e5Sespie 2089*c87b03e5Sespie@item jdbc.drivers 2090*c87b03e5SespieA list of class names that will be loaded by the @code{java.sql.DriverManager} 2091*c87b03e5Sespiewhen it starts up. 2092*c87b03e5Sespie 2093*c87b03e5Sespie@item file.separator 2094*c87b03e5SespieThe separator used in when directories are included in a filename 2095*c87b03e5Sespie(normally @samp{/} or @samp{\} ). 2096*c87b03e5Sespie 2097*c87b03e5Sespie@item file.encoding 2098*c87b03e5SespieThe default character encoding used when converting platform native files to 2099*c87b03e5SespieUnicode (usually set to @samp{8859_1}). 2100*c87b03e5Sespie 2101*c87b03e5Sespie@item path.separator 2102*c87b03e5SespieThe standard separator used when a string contains multiple paths 2103*c87b03e5Sespie(normally @samp{:} or @samp{;}), the string is usually not a valid character 2104*c87b03e5Sespieto use in normal directory names.) 2105*c87b03e5Sespie 2106*c87b03e5Sespie@item line.separator 2107*c87b03e5SespieThe default line separator used on the platform (normally @samp{\n}, @samp{\r} 2108*c87b03e5Sespieor a combination of those two characters). 2109*c87b03e5Sespie 2110*c87b03e5Sespie@item policy.provider 2111*c87b03e5SespieThe class name used for the default policy provider returned by 2112*c87b03e5Sespie@code{java.security.Policy.getPolicy}. 2113*c87b03e5Sespie 2114*c87b03e5Sespie@item user.name 2115*c87b03e5SespieThe name of the user running the program. Can be the full name, the login name 2116*c87b03e5Sespieor empty if unknown. 2117*c87b03e5Sespie 2118*c87b03e5Sespie@item user.home 2119*c87b03e5SespieThe default directory to put user specific files in. 2120*c87b03e5Sespie 2121*c87b03e5Sespie@item user.dir 2122*c87b03e5SespieThe current working directory from which the program was started. 2123*c87b03e5Sespie 2124*c87b03e5Sespie@item user.language 2125*c87b03e5SespieThe default language as used by the @code{java.util.Locale} class. 2126*c87b03e5Sespie 2127*c87b03e5Sespie@item user.region 2128*c87b03e5SespieThe default region as used by the @code{java.util.Local} class. 2129*c87b03e5Sespie 2130*c87b03e5Sespie@item user.variant 2131*c87b03e5SespieThe default variant of the language and region local used. 2132*c87b03e5Sespie 2133*c87b03e5Sespie@item user.timezone 2134*c87b03e5SespieThe default timezone as used by the @code{java.util.TimeZone} class. 2135*c87b03e5Sespie 2136*c87b03e5Sespie@item os.name 2137*c87b03e5SespieThe operating system/kernel name that the program runs on. 2138*c87b03e5Sespie 2139*c87b03e5Sespie@item os.arch 2140*c87b03e5SespieThe hardware that we are running on. 2141*c87b03e5Sespie 2142*c87b03e5Sespie@item os.version 2143*c87b03e5SespieThe version number of the operating system/kernel. 2144*c87b03e5Sespie 2145*c87b03e5Sespie@item awt.appletWarning 2146*c87b03e5SespieThe string to display when an untrusted applet is displayed. 2147*c87b03e5SespieReturned by @code{java.awt.Window.getWarningString()} when the window is 2148*c87b03e5Sespie``insecure''. 2149*c87b03e5Sespie 2150*c87b03e5Sespie@item awt.toolkit 2151*c87b03e5SespieThe class name used for initializing the default @code{java.awt.Toolkit}. 2152*c87b03e5SespieDefaults to @code{gnu.awt.gtk.GtkToolkit}. 2153*c87b03e5Sespie 2154*c87b03e5Sespie@item http.proxyHost 2155*c87b03e5SespieName of proxy host for http connections. 2156*c87b03e5Sespie 2157*c87b03e5Sespie@item http.proxyPort 2158*c87b03e5SespiePort number to use when a proxy host is in use. 2159*c87b03e5Sespie 2160*c87b03e5Sespie@end table 2161*c87b03e5Sespie 2162*c87b03e5Sespie@node GNU Classpath Properties 2163*c87b03e5Sespie@section GNU Classpath Properties 2164*c87b03e5Sespie 2165*c87b03e5Sespie@code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a 2166*c87b03e5SespieGNU project to create free core class libraries for use with virtual machines 2167*c87b03e5Sespieand compilers for the Java language. The following properties are common to 2168*c87b03e5Sespielibraries based on GNU Classpath. 2169*c87b03e5Sespie 2170*c87b03e5Sespie@table @gcctabopt 2171*c87b03e5Sespie 2172*c87b03e5Sespie@item gcj.dumpobject 2173*c87b03e5SespieEnables printing serialization debugging by the @code{java.io.ObjectInput} and 2174*c87b03e5Sespie@code{java.io.ObjectOutput} classes when set to something else then the empty 2175*c87b03e5Sespiestring. Only used when running a debug build of the library. 2176*c87b03e5Sespie 2177*c87b03e5Sespie@item gnu.classpath.vm.shortname 2178*c87b03e5SespieThis is a succint name of the virtual machine. For @code{libgcj}, 2179*c87b03e5Sespiethis will always be @samp{libgcj}. 2180*c87b03e5Sespie 2181*c87b03e5Sespie@item gnu.classpath.home.url 2182*c87b03e5SespieA base URL used for finding system property files (e.g., 2183*c87b03e5Sespie@file{classpath.security}). By default this is a @samp{file:} URL 2184*c87b03e5Sespiepointing to the @file{lib} directory under @samp{java.home}. 2185*c87b03e5Sespie 2186*c87b03e5Sespie@end table 2187*c87b03e5Sespie 2188*c87b03e5Sespie@node libgcj Runtime Properties 2189*c87b03e5Sespie@section libgcj Runtime Properties 2190*c87b03e5Sespie 2191*c87b03e5SespieThe following properties are specific to the @code{libgcj} runtime and will 2192*c87b03e5Sespienormally not be found in other core libraries for the java language. 2193*c87b03e5Sespie 2194*c87b03e5Sespie@table @gcctabopt 2195*c87b03e5Sespie 2196*c87b03e5Sespie@item java.fullversion 2197*c87b03e5SespieThe combination of @code{java.vm.name} and @code{java.vm.version}. 2198*c87b03e5Sespie 2199*c87b03e5Sespie@item java.vm.info 2200*c87b03e5SespieSame as @code{java.fullversion}. 2201*c87b03e5Sespie 2202*c87b03e5Sespie@item impl.prefix 2203*c87b03e5SespieUsed by the @code{java.net.DatagramSocket} class when set to something else 2204*c87b03e5Sespiethen the empty string. When set all newly created @code{DatagramSocket}s will 2205*c87b03e5Sespietry to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of 2206*c87b03e5Sespiethe normal @code{java.net.PlainDatagramSocketImpl}. 2207*c87b03e5Sespie 2208*c87b03e5Sespie@item gnu.gcj.progname 2209*c87b03e5SespieThe name that was used to invoked the program. 2210*c87b03e5Sespie 2211*c87b03e5Sespie@item gnu.gcj.runtime.NameFinder.demangle 2212*c87b03e5SespieWhether names in a stack trace should be demangled. Defaults to @code{true}. 2213*c87b03e5Sespie 2214*c87b03e5Sespie@item gnu.gcj.runtime.NameFinder.sanitize 2215*c87b03e5SespieWhether calls to initialize exceptions and starting the runtime system 2216*c87b03e5Sespieshould be removed from the stack trace. Only done when names are 2217*c87b03e5Sespiedemangled. Defaults to @code{true}. 2218*c87b03e5Sespie 2219*c87b03e5Sespie@item gnu.gcj.runtime.NameFinder.remove_unknown 2220*c87b03e5SespieWhether calls to unknown functions (class and method names are unknown) 2221*c87b03e5Sespieshould be removed from the stack trace. Only done when the stack is 2222*c87b03e5Sespiesanitized. Ignored if this means no stack trace information would be 2223*c87b03e5Sespieavailable anymore. Defaults to @code{true}. 2224*c87b03e5Sespie 2225*c87b03e5Sespie@item gnu.gcj.runtime.NameFinder.remove_interpreter 2226*c87b03e5SespieWhether runtime interpreter calls (methods in the @code{_Jv_InterpMethod} class 2227*c87b03e5Sespieand functions starting with @samp{ffi_}) should be removed from the stack 2228*c87b03e5Sespietrace. Only done when the stack is sanitized. Defaults to @code{true}. 2229*c87b03e5Sespie 2230*c87b03e5Sespie 2231*c87b03e5Sespie@item gnu.gcj.runtime.NameFinder.use_addr2line 2232*c87b03e5SespieWhether an external process (@command{addr2line} or @command{addr2name.awk}) 2233*c87b03e5Sespieshould be used as fallback to convert the addresses to function names when 2234*c87b03e5Sespiethe runtime is unable to do it through @code{dladdr}. 2235*c87b03e5Sespie 2236*c87b03e5Sespie@end table 2237*c87b03e5Sespie 2238*c87b03e5Sespie 2239*c87b03e5Sespie@node Resources 2240*c87b03e5Sespie@chapter Resources 2241*c87b03e5Sespie 2242*c87b03e5SespieWhile writing @command{gcj} and @code{libgcj} we have, of course, relied 2243*c87b03e5Sespieheavily on documentation from Sun Microsystems. In particular we have 2244*c87b03e5Sespieused The Java Language Specification (both first and second editions), 2245*c87b03e5Sespiethe Java Class Libraries (volumes one and two), and the Java Virtual 2246*c87b03e5SespieMachine Specification. In addition we've used the online documentation 2247*c87b03e5Sespieat @uref{http://java.sun.com/}. 2248*c87b03e5Sespie 2249*c87b03e5SespieThe current @command{gcj} home page is 2250*c87b03e5Sespie@uref{http://gcc.gnu.org/java/}. 2251*c87b03e5Sespie 2252*c87b03e5SespieFor more information on gcc, see @uref{http://gcc.gnu.org/}. 2253*c87b03e5Sespie 2254*c87b03e5SespieSome @code{libgcj} testing is done using the Mauve test suite. This is 2255*c87b03e5Sespiea free software Java class library test suite which is being written 2256*c87b03e5Sespiebecause the JCK is not free. See 2257*c87b03e5Sespie@uref{http://sources.redhat.com/mauve/} for more information. 2258*c87b03e5Sespie 2259*c87b03e5Sespie@bye 2260