From: Tom Tromey Date: Wed, 17 Jan 2001 23:14:11 +0000 (+0000) Subject: gcj.texi: New file. X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=bc65b5ecf694d5e6a9559c5bad47c75af3121473;p=gcc.git gcj.texi: New file. * gcj.texi: New file. * Make-lang.in ($(srcdir)/java/gcj.info): New target. (java.info): Depend on gcj.info. (java/gcj.dvi): New target. (java.dvi): Depend on gcj.dvi. (java.install-info): Wrote. From-SVN: r39101 --- diff --git a/gcc/java/.cvsignore b/gcc/java/.cvsignore index dbe7c59cf5d..82f4237915d 100644 --- a/gcc/java/.cvsignore +++ b/gcc/java/.cvsignore @@ -1,2 +1,3 @@ parse.c parse-scan.c +gcj.info* diff --git a/gcc/java/ChangeLog b/gcc/java/ChangeLog index 3192ad40734..313a1122389 100644 --- a/gcc/java/ChangeLog +++ b/gcc/java/ChangeLog @@ -1,3 +1,12 @@ +2001-01-17 Tom Tromey + + * gcj.texi: New file. + * Make-lang.in ($(srcdir)/java/gcj.info): New target. + (java.info): Depend on gcj.info. + (java/gcj.dvi): New target. + (java.dvi): Depend on gcj.dvi. + (java.install-info): Wrote. + 2001-01-16 Jeff Sturm * expr.c (java_lang_expand_expr): Use TREE_SYMBOL_REFERENCED after diff --git a/gcc/java/Make-lang.in b/gcc/java/Make-lang.in index 08ced3d85d9..c16fc84c28e 100644 --- a/gcc/java/Make-lang.in +++ b/gcc/java/Make-lang.in @@ -145,8 +145,8 @@ java.all.cross: $(GCJ)-cross$(exeext) java.start.encap: $(GCJ)$(exeext) java.rest.encap: -java.info: -java.dvi: +java.info: $(srcdir)/java/gcj.info +java.dvi: java/gcj.dvi # Install hooks: # jc1, gcj, jvgenmain, and gcjh are installed elsewhere as part @@ -182,6 +182,21 @@ java.uninstall: -rm -rf $(bindir)/$(JAVA_CROSS_NAME)$(exeext) java.install-info: + if [ -f jc1$(exeext) ] ; then \ + if [ -f $(srcdir)/java/gcj.info ]; then \ + rm -f $(infodir)/gcj.info*; \ + for f in $(srcdir)/java/gcj.info*; do \ + realfile=`echo $$f | sed -e 's|.*/\([^/]*\)$$|\1|'`; \ + $(INSTALL_DATA) $$f $(infodir)/$$realfile; \ + done; \ + chmod a-x $(infodir)/gcj.info*; \ + else true; fi; \ + else true; fi + -if [ -f jc1$(exeext) ] && [ -f $(infodir)/gcj.info ]; then \ + if $(SHELL) -c 'install-info --version' >/dev/null 2>&1; then \ + install-info --dir-file=$(infodir)/dir $(infodir)/gcj.info; \ + else true; fi; \ + else true; fi # # Clean hooks: @@ -274,3 +289,14 @@ java/jcf-path.o: java/jcf-path.c $(CONFIG_H) system.h java/jcf.h -DLIBGCJ_ZIP_FILE='"$(prefix)/share/libgcj.jar"' \ $(srcdir)/java/jcf-path.c $(OUTPUT_OPTION) +# Documentation +$(srcdir)/java/gcj.info: $(srcdir)/java/gcj.texi + if test "x$(BUILD_INFO)" = xinfo; then \ + rm -f $(srcdir)/java/gcc.info*; \ + cd $(srcdir)/java && $(MAKEINFO) -o gcj.info gcj.texi; \ + else true; fi + +java/gcj.dvi: $(srcdir)/java/gcj.texi + TEXINPUTS=${texidir}:$(srcdir)/java:$$TEXINPUTS tex gcj.texi + texindex gcj.?? + TEXINPUTS=${texidir}:$(srcdir)/java:$$TEXINPUTS tex gcj.texi diff --git a/gcc/java/gcj.texi b/gcc/java/gcj.texi new file mode 100644 index 00000000000..1c665097657 --- /dev/null +++ b/gcc/java/gcj.texi @@ -0,0 +1,483 @@ +@\input texinfo @c -*-texinfo-*- +@setfilename gcj.info +@settitle Guide to GNU gcj + +@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'. + + +@ifinfo +@format +@dircategory Programming +@direntry +* Gcj: (gcj). Ahead-of-time compiler for the Java language +@end direntry + +@dircategory Individual utilities +@direntry +* gcjh: (gcj)Invoking gcjh. + Generate header files from Java class files +* jv-scan: (gcj)Invoking jv-scan. + Print information about Java source files +* jcf-dump: (gcj)Invoking jcf-dump. + Print information about Java class files +* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode +@end direntry +@end format +@end ifinfo + +@titlepage +@title GNU gcj +@author Tom Tromey +@end titlepage + +@node Top +@top Introduction + +This manual describes how to use @code{gcj}, the GNU compiler for the +Java programming language. @code{gcj} can generate both @file{.class} +files and object files, and it can read both Java source code and +@file{.class} files. + +@menu +* Invoking gcj:: Compiler options supported by @code{gcj} +* Compatibility:: Compatibility between gcj and other tools for Java +* Invoking gcjh:: Generate header files from class files +* Invoking jv-scan:: Print information about source files +* Invoking jcf-dump:: Print information about class files +* Invoking gij:: Interpreting Java bytecodes +* Resources:: Where to look for more information +@end menu + + +@node Invoking gcj +@chapter Invoking gcj + +As @code{gcj} is just another front end to @code{gcc}, it supports many +of the same options as gcc. @xref{Option Summary, , Option Summary, +gcc, Using the GNU Compiler Collection}. This manual only documents the +options specific to @code{gcj}. + +@menu +* Input Options:: How to find input files +* Encodings:: Options controlling source file encoding +* Warnings:: Options controlling warnings specific to gcj +* Code Generation:: Options controlling the output of gcj +* Configure-time Options:: Options you won't use +@end menu + + +@node Input Options +@section Input Options + +@cindex class path + +@code{gcj} has options to control where it looks to find input files. +Like other compilers for the Java language, @code{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 @code{gcj} looks +for a given class, it searches the class path looking for the +corresponding @file{.class} file. @code{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 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 @code{gcj} will search as if it is a directory. + +@table @code +@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 imported, 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). + +@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 +differs from the @code{--classpath} option in that it also suppresses +the built-in system 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 @code{--classpath} is specified, its value is appended and processing +stops. That is, @code{--classpath} suppresses all the options mentioned +later in this list. + +@item +If @code{--CLASSPATH} is specified, its value is appended and the +@code{CLASSPATH} environment variable is suppressed. + +@item +If the @code{CLASSPATH} environment variable is specified (and was not +suppressed by @code{--CLASSPATH}), then its value is appended. + +@item +Finally, the built-in system directory, @file{libgcj.jar}, is appended. +@end itemize + + +@node Encodings +@section Encodings + +The Java programming language uses Unicode throughout. In an effort to +integrate well with other locales, @code{gcj} allows @file{.java} files +to be written using almost any encoding. @code{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 +@code{gcj} assumes the default encoding to be the @samp{UTF-8} encoding +of Unicode. + +To implement @code{--encoding}, @code{gcj} simply uses the host +platform's @code{iconv} conversion routine. This means that in practice +@code{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, +@code{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 + +@code{gcj} implements several warnings. As with other generic +@code{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 @code +@item -Wunsupported-jdk11 +This will cause @code{gcj} to warn that @code{final} local variables are +being treated as non-final. +@c FIXME: why do we want this? Is it just not implemented yet? + +@item -Wredundant-modifiers +With this flag, @code{gcj} will warn about redundant modifiers. For +instance, it will warn if an interface method is declared @code{public}. + +@item -Wextraneous-semicolon +This causes @code{gcj} to warn about empty statements. Empty statements +have been deprecated. + +@item -Wno-out-of-date +This option will cause @code{gcj} not to warn when a source file is +newer than its matching class file. By default @code{gcj} will warn +about this. + +@item -Wunused +This is the same as @code{gcc}'s @code{-Wunused}. + +@item -Wall +This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon +-Wunused}. +@end table + + +@node Code Generation +@section Code Generation + +In addition to the many @code{gcc} options controlling code generation, +@code{gcj} has several options specific to itself. + +@table @code +@item --main=@var{CLASSNAME} +This option is used when linking. Since the linker expects to find a +method simply named @code{main}, and since Java programs won't have such +a method (due to name mangling), at link time @code{gcj} will generate a +stub @code{main} function which will initialize the runtime and then +invoke the @code{main} method of the appropriate class. This option is +used to specify the name of the class whose @code{main} method should be +invoked when the resulting executable is run. + +@item -D@var{name}[=@var{value}] +This option can only be used with @code{--main}. It defines a system +property named @var{name} with value @var{value}. If @var{value} is not +specified then it defaults to the empty string. These system properties +are initialized at the program's startup and can be retrieved at runtime +using the @code{java.lang.System.getProperty} method. + +@item -C +This option is used to tell @code{gcj} to generate bytecode +(@file{.class} files) rather than object code. + +@item -d @var{directory} +When used with @code{-C}, this causes all generated @file{.class} files +to be put in the appropriate subdirectory of @var{directory}. By +default they will be put in subdirectories of the current working +directory. + +@c @item -fassume-compiled +@c Nobody is sure what this does and anyway it doesn't work. + +@item -fno-bounds-check +By default, @code{gcj} generates code which checks the bounds of all +array indexing operations. With this option, these checks are omitted. +Note that this can result in unpredictable behavior if the code in +question actually does violate array bounds constraints. + +@item -fjni +With @code{gcj} there are two options for writing native methods: CNI +and JNI. By default @code{gcj} assumes you are using CNI. If you are +compiling a class with native methods, and these methods are implemented +using JNI, then you must use @code{-fjni}. This option causes +@code{gcj} to generate stubs which will invoke the underlying JNI +methods. +@end table + + +@node Configure-time Options +@section Configure-time Options + +Some @code{gcj} code generations options affect the resulting ABI, and +so can only be meaningfully given when @code{libgcj}, the runtime +package, is configured. @code{libgcj} puts the appropriate options from +this group into a @samp{spec} file which is read by @code{gcj}. These +options are listed here for completeness; if you are using @code{libgcj} +then you won't want to touch these options. + +@table @code +@item -fuse-boehm-gc +This enables the use of the Boehm GC bitmap marking code. In particular +this causes @code{gcj} to put an object marking descriptor into each +vtable. + +@item -fhash-synchronization +By default, synchronization data (the data used for @code{synchronize}, +@code{wait}, and @code{notify}) is pointed to by a word in each object. +With this option @code{gcj} assumes that this information is stored in a +hash table and not in the object itself. + +@item -fuse-divide-subroutine +On some systems, a library routine is called to perform integer +division. This is required to get exception handling correct when +dividing by zero. +@end table + + +@node Compatibility +@chapter Compatibility + +As we believe it is important that the Java platform not be fragmented, +@code{gcj} and @code{libgcj} try to conform to the relevant Java +specifications. However, limited manpower and incomplete and unclear +documentation work against us. So, there are caveats to using +@code{gcj}. + +This list of compatibility issues is by no means complete. + +@itemize @bullet +@item +@code{gcj} implements the JDK 1.1 language. It supports inner classes, +though these are known to still be buggy. It does not yet support the +Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores +it). + +@item +@code{libgcj} is missing many packages, most notably @code{java.awt}. + +@item +Sometimes the @code{libgcj} implementation of a method or class differs +from the JDK implementation. This is not always a bug. Still, if it +affects you, it probably makes sense to report it so that we can discuss +the appropriate response. +@end itemize + + +@node Invoking gcjh +@chapter Invoking gcjh + +The @code{gcjh} program is used to generate header files from class +files. It can generate both CNI and JNI header files, as well as stub +implementation files which can be used as a basis for implementing the +required native methods. + +@table @code +@item -stubs +This causes @code{gcjh} to generate stub files instead of header files. +By default the stub file will be named after the class, with a suffix of +@samp{.cc}. In JNI mode, the default output file will have the suffix +@samp{.c}. + +@item -jni +This tells @code{gcjh} to generate a JNI header or stub. By default, +CNI headers are generated. + +@item -add @var{text} +Inserts @var{text} into the class body. This is ignored in JNI mode. + +@item -append @var{text} +Inserts @var{text} into the header file after the class declaration. +This is ignored in JNI mode. + +@item -friend @var{text} +Inserts @var{text} into the class as a @code{friend} declaration. +This is ignored in JNI mode. + +@item -prepend @var{text} +Inserts @var{text} into the header file before the class declaration. +This is ignored in JNI mode. + +@item --classpath=@var{path} +@itemx --CLASSPATH=@var{path} +@itemx -I@var{directory} +@itemx -d @var{directory} +@itemx -o @var{file} +These options are all identical to the corresponding @code{gcj} options. + +@item -o @var{file} +Sets the output file name. This cannot be used if there is more than +one class on the command line. + +@item -td @var{directory} +Sets the name of the directory to use for temporary files. + +@item --help +Print help about @code{gcjh} and exit. No further processing is done. + +@item --version +Print version information for @code{gcjh} and exit. No further +processing is done. +@end table + +All remaining options are considered to be names of classes. + + +@node Invoking jv-scan +@chapter Invoking jv-scan + +The @code{jv-scan} program can be used to print information about a Java +source file (@file{.java} file). + +@table @code +@item --complexity +This prints a complexity measure, related to cyclomatic complexity, for +each input file. + +@item --encoding=@var{name} +This works like the corresponding @code{gcj} option. + +@item --print-main +This prints the name of the class in this file containing a @code{main} +method. + +@item --list-class +This lists the names of all classes defined in the input files. + +@item --list-filename +If @code{--list-class} is given, this option causes @code{jv-scan} to +also print the name of the file in which each class was found. + +@item -o @var{file} +Print output to the named file. +@end table + + +@node Invoking jcf-dump +@chapter Invoking jcf-dump + +This is a class file examiner, similar to @code{javap}. It will print +information about a number of classes, which are specifed by class name +or file name. + +@table @code +@item -c +Disassemble method bodies. By default method bodies are not printed. + +@item --javap +Generate output in @code{javap} format. + +@item --classpath=@var{path} +@itemx --CLASSPATH=@var{path} +@itemx -I@var{directory} +@itemx -o @var{file} +These options as the same as the corresponding @code{gcj} options. +@end table + + +@node Invoking gij +@chapter Invoking gij + +@code{gij} is a Java bytecode interpreter included with @code{libgcj}. +@code{gij} is not available on every platform; porting it requires a +small amount of assembly programming which has not been done for all the +targets supported by @code{gcj}. + +The primary argument to @code{gij} is the name of a class or, with +@code{-jar}, a jar file. Options before this argument are interpreted +by @code{gij}; remaining options are passed to the interpreted program. + +If a class name is specified and this class does not have a @code{main} +method with the appropriate signature (a @code{static void} method with +a @code{String[]} as its sole argument), then @code{gij} will print an +error and exit. + +If a jar file is specified then @code{gij} will use information in it to +determine which class' @code{main} method will be invoked. + +@code{gij} will invoke the @code{main} method with all the remaining +command-line options. + +Note that @code{gij} is not limited to interpreting code. Because +@code{libgcj} includes a class loader which can dynamically load shared +objects, it is possible to give @code{gij} the name of a class which has +been compiled and put into a shared library on the class path. + +@table @code +@item -D@var{name}[=@var{value}] +This defines a system property named @var{name} with value @var{value}. +If @var{value} is not specified then it defaults to the empty string. +These system properties are initialized at the program's startup and can +be retrieved at runtime using the @code{java.lang.System.getProperty} +method. + +@item -ms=@var{number} +This sets the initial heap size + +@item -mx=@var{number} +This sets the maximum heap size. + +@item -jar +This indicates that the name passed to @code{gij} should be interpreted +as the name of a jar file, not a class. +@end table + + +@node Resources +@chapter Resources + +The current @code{gcj} home page is +@uref{http://sources.redhat.com/java/}. This is likely to change in the +near future. + +For more information on gcc, see @uref{http://gcc.gnu.org/}. + +Some @code{libgcj} testing is done using the Mauve test suite. This is +a free software Java class library test suite which is being written +because the JCK is not free. See +@uref{http://sources.redhat.com/mauve/} for more information. + +@contents +@bye