1GCJ(1)                                GNU                               GCJ(1)
2
3
4

NAME

6       gcj - Ahead-of-time compiler for the Java language
7

SYNOPSIS

9       gcj [-Idir...] [-d dir...]
10           [--CLASSPATH=path] [--classpath=path]
11           [-foption...] [--encoding=name]
12           [--main=classname] [-Dname[=value]...]
13           [-C] [--resource resource-name] [-d directory]
14           [-Wwarn...]
15           sourcefile...
16

DESCRIPTION

18       As gcj is just another front end to gcc, it supports many of the same
19       options as gcc.    This manual only documents the options specific to
20       gcj.
21

OPTIONS

23   Input and output files
24       A gcj command is like a gcc command, in that it consists of a number of
25       options and file names.  The following kinds of input file names are
26       supported:
27
28       file.java
29           Java source files.
30
31       file.class
32           Java bytecode files.
33
34       file.zip
35       file.jar
36           An archive containing one or more ".class" files, all of which are
37           compiled.  The archive may be compressed.  Files in an archive
38           which don't end with .class are treated as resource files; they are
39           compiled into the resulting object file as core: URLs.
40
41       @file
42           A file containing a whitespace-separated list of input file names.
43           (Currently, these must all be ".java" source files, but that may
44           change.)  Each named file is compiled, just as if it had been on
45           the command line.
46
47       library.a
48       library.so
49       -llibname
50           Libraries to use when linking.  See the gcc manual.
51
52       You can specify more than one input file on the gcj command line, in
53       which case they will all be compiled.  If you specify a "-o FILENAME"
54       option, all the input files will be compiled together, producing a
55       single output file, named FILENAME.  This is allowed even when using
56       "-S" or "-c", but not when using "-C" or "--resource".  (This is an
57       extension beyond the what plain gcc allows.)  (If more than one input
58       file is specified, all must currently be ".java" files, though we hope
59       to fix this.)
60
61   Input Options
62       gcj has options to control where it looks to find files it needs.  For
63       instance, gcj might need to load a class that is referenced by the file
64       it has been asked to compile.  Like other compilers for the Java
65       language, gcj has a notion of a class path.  There are several options
66       and environment variables which can be used to manipulate the class
67       path.  When gcj looks for a given class, it searches the class path
68       looking for matching .class or .java file.  gcj comes with a built-in
69       class path which points at the installed libgcj.jar, a file which
70       contains all the standard classes.
71
72       In the text below, a directory or path component can refer either to an
73       actual directory on the filesystem, or to a .zip or .jar file, which
74       gcj will search as if it is a directory.
75
76       -Idir
77           All directories specified by "-I" are kept in order and prepended
78           to the class path constructed from all the other options.  Unless
79           compatibility with tools like "javac" is important, we recommend
80           always using "-I" instead of the other options for manipulating the
81           class path.
82
83       --classpath=path
84           This sets the class path to path, a colon-separated list of paths
85           (on Windows-based systems, a semicolon-separate list of paths).
86           This does not override the builtin ("boot") search path.
87
88       --CLASSPATH=path
89           Deprecated synonym for "--classpath".
90
91       --bootclasspath=path
92           Where to find the standard builtin classes, such as
93           "java.lang.String".
94
95       --extdirs=path
96           For each directory in the path, place the contents of that
97           directory at the end of the class path.
98
99       CLASSPATH
100           This is an environment variable which holds a list of paths.
101
102       The final class path is constructed like so:
103
104       ·   First come all directories specified via "-I".
105
106       ·   If --classpath is specified, its value is appended.  Otherwise, if
107           the "CLASSPATH" environment variable is specified, then its value
108           is appended.  Otherwise, the current directory (".") is appended.
109
110       ·   If "--bootclasspath" was specified, append its value.  Otherwise,
111           append the built-in system directory, libgcj.jar.
112
113       ·   Finally, if "--extdirs" was specified, append the contents of the
114           specified directories at the end of the class path.  Otherwise,
115           append the contents of the built-in extdirs at
116           "$(prefix)/share/java/ext".
117
118       The classfile built by gcj for the class "java.lang.Object" (and placed
119       in "libgcj.jar") contains a special zero length attribute
120       "gnu.gcj.gcj-compiled". The compiler looks for this attribute when
121       loading "java.lang.Object" and will report an error if it isn't found,
122       unless it compiles to bytecode (the option
123       "-fforce-classes-archive-check" can be used to override this behavior
124       in this particular case.)
125
126       -fforce-classes-archive-check
127           This forces the compiler to always check for the special zero
128           length attribute "gnu.gcj.gcj-compiled" in "java.lang.Object" and
129           issue an error if it isn't found.
130
131       -fsource=VERSION
132           This option is used to choose the source version accepted by gcj.
133           The default is 1.5.
134
135   Encodings
136       The Java programming language uses Unicode throughout.  In an effort to
137       integrate well with other locales, gcj allows .java files to be written
138       using almost any encoding.  gcj knows how to convert these encodings
139       into its internal encoding at compile time.
140
141       You can use the "--encoding=NAME" option to specify an encoding (of a
142       particular character set) to use for source files.  If this is not
143       specified, the default encoding comes from your current locale.  If
144       your host system has insufficient locale support, then gcj assumes the
145       default encoding to be the UTF-8 encoding of Unicode.
146
147       To implement "--encoding", gcj simply uses the host platform's "iconv"
148       conversion routine.  This means that in practice gcj is limited by the
149       capabilities of the host platform.
150
151       The names allowed for the argument "--encoding" vary from platform to
152       platform (since they are not standardized anywhere).  However, gcj
153       implements the encoding named UTF-8 internally, so if you choose to use
154       this for your source files you can be assured that it will work on
155       every host.
156
157   Warnings
158       gcj implements several warnings.  As with other generic gcc warnings,
159       if an option of the form "-Wfoo" enables a warning, then "-Wno-foo"
160       will disable it.  Here we've chosen to document the form of the warning
161       which will have an effect -- the default being the opposite of what is
162       listed.
163
164       -Wredundant-modifiers
165           With this flag, gcj will warn about redundant modifiers.  For
166           instance, it will warn if an interface method is declared "public".
167
168       -Wextraneous-semicolon
169           This causes gcj to warn about empty statements.  Empty statements
170           have been deprecated.
171
172       -Wno-out-of-date
173           This option will cause gcj not to warn when a source file is newer
174           than its matching class file.  By default gcj will warn about this.
175
176       -Wno-deprecated
177           Warn if a deprecated class, method, or field is referred to.
178
179       -Wunused
180           This is the same as gcc's "-Wunused".
181
182       -Wall
183           This is the same as "-Wredundant-modifiers -Wextraneous-semicolon
184           -Wunused".
185
186   Linking
187       To turn a Java application into an executable program, you need to link
188       it with the needed libraries, just as for C or C++.  The linker by
189       default looks for a global function named "main".  Since Java does not
190       have global functions, and a collection of Java classes may have more
191       than one class with a "main" method, you need to let the linker know
192       which of those "main" methods it should invoke when starting the
193       application.  You can do that in any of these ways:
194
195       ·   Specify the class containing the desired "main" method when you
196           link the application, using the "--main" flag, described below.
197
198       ·   Link the Java package(s) into a shared library (dll) rather than an
199           executable.  Then invoke the application using the "gij" program,
200           making sure that "gij" can find the libraries it needs.
201
202       ·   Link the Java packages(s) with the flag "-lgij", which links in the
203           "main" routine from the "gij" command.  This allows you to select
204           the class whose "main" method you want to run when you run the
205           application.  You can also use other "gij" flags, such as "-D"
206           flags to set properties.  Using the "-lgij" library (rather than
207           the "gij" program of the previous mechanism) has some advantages:
208           it is compatible with static linking, and does not require
209           configuring or installing libraries.
210
211       These "gij" options relate to linking an executable:
212
213       --main=CLASSNAME
214           This option is used when linking to specify the name of the class
215           whose "main" method should be invoked when the resulting executable
216           is run.
217
218       -Dname[=value]
219           This option can only be used with "--main".  It defines a system
220           property named name with value value.  If value is not specified
221           then it defaults to the empty string.  These system properties are
222           initialized at the program's startup and can be retrieved at
223           runtime using the "java.lang.System.getProperty" method.
224
225       -lgij
226           Create an application whose command-line processing is that of the
227           "gij" command.
228
229           This option is an alternative to using "--main"; you cannot use
230           both.
231
232       -static-libgcj
233           This option causes linking to be done against a static version of
234           the libgcj runtime library.  This option is only available if
235           corresponding linker support exists.
236
237           Caution: Static linking of libgcj may cause essential parts of
238           libgcj to be omitted.  Some parts of libgcj use reflection to load
239           classes at runtime.  Since the linker does not see these references
240           at link time, it can omit the referred to classes.  The result is
241           usually (but not always) a "ClassNotFoundException" being thrown at
242           runtime. Caution must be used when using this option.  For more
243           details see:
244           <http://gcc.gnu.org/wiki/Statically%20linking%20libgcj>
245
246   Code Generation
247       In addition to the many gcc options controlling code generation, gcj
248       has several options specific to itself.
249
250       -C  This option is used to tell gcj to generate bytecode (.class files)
251           rather than object code.
252
253       --resource resource-name
254           This option is used to tell gcj to compile the contents of a given
255           file to object code so it may be accessed at runtime with the core
256           protocol handler as core:/resource-name.  Note that resource-name
257           is the name of the resource as found at runtime; for instance, it
258           could be used in a call to "ResourceBundle.getBundle".  The actual
259           file name to be compiled this way must be specified separately.
260
261       -ftarget=VERSION
262           This can be used with -C to choose the version of bytecode emitted
263           by gcj.  The default is 1.5.  When not generating bytecode, this
264           option has no effect.
265
266       -d directory
267           When used with "-C", this causes all generated .class files to be
268           put in the appropriate subdirectory of directory.  By default they
269           will be put in subdirectories of the current working directory.
270
271       -fno-bounds-check
272           By default, gcj generates code which checks the bounds of all array
273           indexing operations.  With this option, these checks are omitted,
274           which can improve performance for code that uses arrays
275           extensively.  Note that this can result in unpredictable behavior
276           if the code in question actually does violate array bounds
277           constraints.  It is safe to use this option if you are sure that
278           your code will never throw an "ArrayIndexOutOfBoundsException".
279
280       -fno-store-check
281           Don't generate array store checks.  When storing objects into
282           arrays, a runtime check is normally generated in order to ensure
283           that the object is assignment compatible with the component type of
284           the array (which may not be known at compile-time).  With this
285           option, these checks are omitted.  This can improve performance for
286           code which stores objects into arrays frequently.  It is safe to
287           use this option if you are sure your code will never throw an
288           "ArrayStoreException".
289
290       -fjni
291           With gcj there are two options for writing native methods: CNI and
292           JNI.  By default gcj assumes you are using CNI.  If you are
293           compiling a class with native methods, and these methods are
294           implemented using JNI, then you must use "-fjni".  This option
295           causes gcj to generate stubs which will invoke the underlying JNI
296           methods.
297
298       -fno-assert
299           Don't recognize the "assert" keyword.  This is for compatibility
300           with older versions of the language specification.
301
302       -fno-optimize-static-class-initialization
303           When the optimization level is greater or equal to "-O2", gcj will
304           try to optimize the way calls into the runtime are made to
305           initialize static classes upon their first use (this optimization
306           isn't carried out if "-C" was specified.) When compiling to native
307           code, "-fno-optimize-static-class-initialization" will turn this
308           optimization off, regardless of the optimization level in use.
309
310       --disable-assertions[=class-or-package]
311           Don't include code for checking assertions in the compiled code.
312           If "=class-or-package" is missing disables assertion code
313           generation for all classes, unless overridden by a more specific
314           "--enable-assertions" flag.  If class-or-package is a class name,
315           only disables generating assertion checks within the named class or
316           its inner classes.  If class-or-package is a package name, disables
317           generating assertion checks within the named package or a
318           subpackage.
319
320           By default, assertions are enabled when generating class files or
321           when not optimizing, and disabled when generating optimized
322           binaries.
323
324       --enable-assertions[=class-or-package]
325           Generates code to check assertions.  The option is perhaps
326           misnamed, as you still need to turn on assertion checking at run-
327           time, and we don't support any easy way to do that.  So this flag
328           isn't very useful yet, except to partially override
329           "--disable-assertions".
330
331       -findirect-dispatch
332           gcj has a special binary compatibility ABI, which is enabled by the
333           "-findirect-dispatch" option.  In this mode, the code generated by
334           gcj honors the binary compatibility guarantees in the Java Language
335           Specification, and the resulting object files do not need to be
336           directly linked against their dependencies.  Instead, all
337           dependencies are looked up at runtime.  This allows free mixing of
338           interpreted and compiled code.
339
340           Note that, at present, "-findirect-dispatch" can only be used when
341           compiling .class files.  It will not work when compiling from
342           source.  CNI also does not yet work with the binary compatibility
343           ABI.  These restrictions will be lifted in some future release.
344
345           However, if you compile CNI code with the standard ABI, you can
346           call it from code built with the binary compatibility ABI.
347
348       -fbootstrap-classes
349           This option can be use to tell "libgcj" that the compiled classes
350           should be loaded by the bootstrap loader, not the system class
351           loader.  By default, if you compile a class and link it into an
352           executable, it will be treated as if it was loaded using the system
353           class loader.  This is convenient, as it means that things like
354           "Class.forName()" will search CLASSPATH to find the desired class.
355
356       -freduced-reflection
357           This option causes the code generated by gcj to contain a reduced
358           amount of the class meta-data used to support runtime reflection.
359           The cost of this savings is the loss of the ability to use certain
360           reflection capabilities of the standard Java runtime environment.
361           When set all meta-data except for that which is needed to obtain
362           correct runtime semantics is eliminated.
363
364           For code that does not use reflection (i.e. serialization, RMI,
365           CORBA or call methods in the "java.lang.reflect" package),
366           "-freduced-reflection" will result in proper operation with a
367           savings in executable code size.
368
369           JNI ("-fjni") and the binary compatibility ABI
370           ("-findirect-dispatch") do not work properly without full
371           reflection meta-data.  Because of this, it is an error to use these
372           options with "-freduced-reflection".
373
374           Caution: If there is no reflection meta-data, code that uses a
375           "SecurityManager" may not work properly.  Also calling
376           "Class.forName()" may fail if the calling method has no reflection
377           meta-data.
378
379   Configure-time Options
380       Some gcj code generations options affect the resulting ABI, and so can
381       only be meaningfully given when "libgcj", the runtime package, is
382       configured.  "libgcj" puts the appropriate options from this group into
383       a spec file which is read by gcj.  These options are listed here for
384       completeness; if you are using "libgcj" then you won't want to touch
385       these options.
386
387       -fuse-boehm-gc
388           This enables the use of the Boehm GC bitmap marking code.  In
389           particular this causes gcj to put an object marking descriptor into
390           each vtable.
391
392       -fhash-synchronization
393           By default, synchronization data (the data used for "synchronize",
394           "wait", and "notify") is pointed to by a word in each object.  With
395           this option gcj assumes that this information is stored in a hash
396           table and not in the object itself.
397
398       -fuse-divide-subroutine
399           On some systems, a library routine is called to perform integer
400           division.  This is required to get exception handling correct when
401           dividing by zero.
402
403       -fcheck-references
404           On some systems it's necessary to insert inline checks whenever
405           accessing an object via a reference.  On other systems you won't
406           need this because null pointer accesses are caught automatically by
407           the processor.
408

SEE ALSO

410       gcc(1), gcjh(1), gjnih(1), gij(1), jcf-dump(1), gfdl(7), and the Info
411       entries for gcj and gcc.
412
414       Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free
415       Software Foundation, Inc.
416
417       Permission is granted to copy, distribute and/or modify this document
418       under the terms of the GNU Free Documentation License, Version 1.2 or
419       any later version published by the Free Software Foundation; with no
420       Invariant Sections, the Front-Cover Texts being (a) (see below), and
421       with the Back-Cover Texts being (b) (see below).  A copy of the license
422       is included in the man page gfdl(7).
423
424       (a) The FSF's Front-Cover Text is:
425
426            A GNU Manual
427
428       (b) The FSF's Back-Cover Text is:
429
430            You have freedom to copy and modify this GNU Manual, like GNU
431            software.  Copies published by the Free Software Foundation raise
432            funds for GNU development.
433
434
435
436gcc-4.4.7                         2012-03-13                            GCJ(1)
Impressum