gcj.texi

来自「理解和实践操作系统的一本好书」· TEXI 代码 · 共 1,908 行 · 第 1/5 页

\input texinfo @c -*-texinfo-*-
@setfilename gcj.info
@settitle Guide to GNU gcj

@c Merge the standard indexes into a single one.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp

@include gcc-common.texi

@c Note: When reading this manual you'll find lots of strange
@c circumlocutions like ``compiler for the Java language''.
@c This is necessary due to Sun's restrictions on the use of
@c the word ``Java'.

@c When this manual is copyrighted.
@set copyrights-gcj 2001, 2002, 2003, 2004, 2005, 2006, 2007

@copying
@c man begin COPYRIGHT
Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'', the Front-Cover
texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the
@c man end
section entitled
``GNU Free Documentation License''.
@ignore
@c man begin COPYRIGHT
man page gfdl(7).
@c man end
@end ignore

@c man begin COPYRIGHT

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@c man end
@end copying

@ifinfo
@format
@dircategory Software development
@direntry
* Gcj: (gcj).               Ahead-of-time compiler for the Java language
@end direntry

@dircategory Individual utilities
@direntry
* jcf-dump: (gcj)Invoking jcf-dump.
                            Print information about Java class files
* gij: (gcj)Invoking gij.   GNU interpreter for Java bytecode
* gcj-dbtool: (gcj)Invoking gcj-dbtool.
                            Tool for manipulating class file databases.
* jv-convert: (gcj)Invoking jv-convert.
                            Convert file from one encoding to another
* grmic: (gcj)Invoking grmic.
                            Generate stubs for Remote Method Invocation.
* gc-analyze: (gcj)Invoking gc-analyze.
                            Analyze Garbage Collector (GC) memory dumps.
@end direntry
@end format

@insertcopying
@end ifinfo

@titlepage
@title GNU gcj
@versionsubtitle
@author Tom Tromey

@page
@vskip 0pt plus 1filll
Published by the Free Software Foundation @*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@sp 1
@insertcopying
@end titlepage
@contents
@page


@node Top
@top Introduction

This manual describes how to use @command{gcj}, the GNU compiler for the
Java programming language.  @command{gcj} can generate both @file{.class}
files and object files, and it can read both Java source code and
@file{.class} files.

@menu
* Copying::		 The GNU General Public License
* GNU Free Documentation License::
			How you can share and copy this manual
* Invoking gcj::	Compiler options supported by @command{gcj}
* Compatibility::	Compatibility between gcj and other tools for Java
* Invoking jcf-dump::   Print information about class files
* Invoking gij::	Interpreting Java bytecodes
* Invoking gcj-dbtool:: Tool for manipulating class file databases.
* Invoking jv-convert:: Converting from one encoding to another
* Invoking grmic::      Generate stubs for Remote Method Invocation.
* Invoking gc-analyze:: Analyze Garbage Collector (GC) memory dumps.
* About CNI::           Description of the Compiled Native Interface
* System properties::   Modifying runtime behavior of the libgcj library
* Resources::		Where to look for more information
* Index::               Index.
@end menu


@include gpl_v3.texi

@include fdl.texi


@node Invoking gcj
@chapter Invoking gcj

@c man title gcj Ahead-of-time compiler for the Java language

@ignore
@c man begin SYNOPSIS gcj
gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
    [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
    [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
    [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
    [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
    [@option{-W}@var{warn}@dots{}]
    @var{sourcefile}@dots{}
@c man end
@c man begin SEEALSO gcj
gcc(1), gcjh(1), gjnih(1), gij(1), jcf-dump(1), gfdl(7),
and the Info entries for @file{gcj} and @file{gcc}.
@c man end
@end ignore

@c man begin DESCRIPTION gcj

As @command{gcj} is just another front end to @command{gcc}, it supports many
of the same options as gcc.  @xref{Option Summary, , Option Summary,
gcc, Using the GNU Compiler Collection (GCC)}.  This manual only documents the
options specific to @command{gcj}.

@c man end

@menu
* Input and output files::
* Input Options::		How gcj finds files
* Encodings::                   Options controlling source file encoding
* Warnings::			Options controlling warnings specific to gcj
* Linking::			Options for making an executable
* Code Generation::		Options controlling the output of gcj
* Configure-time Options::	Options you won't use
@end menu

@c man begin OPTIONS gcj

@node Input and output files
@section Input and output files

A @command{gcj} command is like a @command{gcc} command, in that it
consists of a number of options and file names.  The following kinds
of input file names are supported:

@table @gcctabopt
@item @var{file}.java
Java source files.
@item @var{file}.class
Java bytecode files.
@item @var{file}.zip
@itemx @var{file}.jar
An archive containing one or more @code{.class} files, all of
which are compiled.  The archive may be compressed.  Files in
an archive which don't end with @samp{.class} are treated as
resource files; they are compiled into the resulting object file
as @samp{core:} URLs.
@item @@@var{file}
A file containing a whitespace-separated list of input file names.
(Currently, these must all be @code{.java} source files, but that
may change.)
Each named file is compiled, just as if it had been on the command line.
@item @var{library}.a
@itemx @var{library}.so
@itemx -l@var{libname}
Libraries to use when linking.  See the @command{gcc} manual.
@end table

You can specify more than one input file on the @command{gcj} command line,
in which case they will all be compiled.  If you specify a
@code{-o @var{FILENAME}}
option, all the input files will be compiled together, producing a
single output file, named @var{FILENAME}.
This is allowed even when using @code{-S} or @code{-c},
but not when using @code{-C} or @code{--resource}.
(This is an extension beyond the what plain @command{gcc} allows.)
(If more than one input file is specified, all must currently
be @code{.java} files, though we hope to fix this.)

@node Input Options
@section Input Options

@cindex class path

@command{gcj} has options to control where it looks to find files it needs.
For instance, @command{gcj} might need to load a class that is referenced
by the file it has been asked to compile.  Like other compilers for the
Java language, @command{gcj} has a notion of a @dfn{class path}.  There are
several options and environment variables which can be used to
manipulate the class path.  When @command{gcj} looks for a given class, it
searches the class path looking for matching @file{.class} or
@file{.java} file.  @command{gcj} comes with a built-in class path which
points at the installed @file{libgcj.jar}, a file which contains all the
standard classes.

In the text below, a directory or path component can refer either to an
actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
file, which @command{gcj} will search as if it is a directory.

@table @gcctabopt
@item -I@var{dir}
All directories specified by @code{-I} are kept in order and prepended
to the class path constructed from all the other options.  Unless
compatibility with tools like @code{javac} is important, we recommend
always using @code{-I} instead of the other options for manipulating the
class path.

@item --classpath=@var{path}
This sets the class path to @var{path}, a colon-separated list of paths
(on Windows-based systems, a semicolon-separate list of paths).
This does not override the builtin (``boot'') search path.

@item --CLASSPATH=@var{path}
Deprecated synonym for @code{--classpath}.

@item --bootclasspath=@var{path}
Where to find the standard builtin classes, such as @code{java.lang.String}.

@item --extdirs=@var{path}
For each directory in the @var{path}, place the contents of that
directory at the end of the class path.

@item CLASSPATH
This is an environment variable which holds a list of paths.
@end table

The final class path is constructed like so:

@itemize @bullet
@item
First come all directories specified via @code{-I}.

@item
If @option{--classpath} is specified, its value is appended.
Otherwise, if the @code{CLASSPATH} environment variable is specified,
then its value is appended.
Otherwise, the current directory (@code{"."}) is appended.

@item
If @code{--bootclasspath} was specified, append its value.
Otherwise, append the built-in system directory, @file{libgcj.jar}.

@item
Finally, if @code{--extdirs} was specified, append the contents of the
specified directories at the end of the class path.  Otherwise, append
the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
@end itemize

The classfile built by @command{gcj} for the class @code{java.lang.Object}
(and placed in @code{libgcj.jar}) contains a special zero length
attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
attribute when loading @code{java.lang.Object} and will report an error
if it isn't found, unless it compiles to bytecode (the option
@code{-fforce-classes-archive-check} can be used to override this
behavior in this particular case.)

@table @gcctabopt
@item -fforce-classes-archive-check
This forces the compiler to always check for the special zero length
attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
issue an error if it isn't found.

@item -fsource=@var{VERSION}
This option is used to choose the source version accepted by
@command{gcj}.  The default is @samp{1.5}.
@end table

@node Encodings
@section Encodings

The Java programming language uses Unicode throughout.  In an effort to
integrate well with other locales, @command{gcj} allows @file{.java} files
to be written using almost any encoding.  @command{gcj} knows how to
convert these encodings into its internal encoding at compile time.

You can use the @code{--encoding=@var{NAME}} option to specify an
encoding (of a particular character set) to use for source files.  If
this is not specified, the default encoding comes from your current
locale.  If your host system has insufficient locale support, then
@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
of Unicode.

To implement @code{--encoding}, @command{gcj} simply uses the host
platform's @code{iconv} conversion routine.  This means that in practice
@command{gcj} is limited by the capabilities of the host platform.

The names allowed for the argument @code{--encoding} vary from platform
to platform (since they are not standardized anywhere).  However,
@command{gcj} implements the encoding named @samp{UTF-8} internally, so if
you choose to use this for your source files you can be assured that it
will work on every host.


@node Warnings
@section Warnings

@command{gcj} implements several warnings.  As with other generic
@command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
warning, then @code{-Wno-foo} will disable it.  Here we've chosen to
document the form of the warning which will have an effect -- the
default being the opposite of what is listed.

@table @gcctabopt
@item -Wredundant-modifiers
With this flag, @command{gcj} will warn about redundant modifiers.  For
instance, it will warn if an interface method is declared @code{public}.

@item -Wextraneous-semicolon
This causes @command{gcj} to warn about empty statements.  Empty statements
have been deprecated.

@item -Wno-out-of-date
This option will cause @command{gcj} not to warn when a source file is
newer than its matching class file.  By default @command{gcj} will warn
about this.

@item -Wno-deprecated
Warn if a deprecated class, method, or field is referred to.

@item -Wunused
This is the same as @command{gcc}'s @code{-Wunused}.

@item -Wall
This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
-Wunused}.
@end table


@node Linking
@section Linking

To turn a Java application into an executable program,
you need to link it with the needed libraries, just as for C or C++.
The linker by default looks for a global function named @code{main}.
Since Java does not have global functions, and a
collection of Java classes may have more than one class with a
@code{main} method, you need to let the linker know which of those
@code{main} methods it should invoke when starting the application.
You can do that in any of these ways:

@itemize @bullet
@item
Specify the class containing the desired @code{main} method
when you link the application, using the @code{--main} flag,
described below.
@item
Link the Java package(s) into a shared library (dll) rather than an
executable.  Then invoke the application using the @code{gij} program,
making sure that @code{gij} can find the libraries it needs.