From 9dc7fa2aab60decf4abad15a66d26c50f67b9510 Mon Sep 17 00:00:00 2001
From: Maximilian Downey Twiss <creatorsmithmdt@gmail.com>
Date: Fri, 25 Nov 2022 18:28:09 +1100
Subject: [PATCH 03/56] Re-add documentation for Java front-end and library.
gcc/ChangeLog:
* doc/cfg.texi: Re-add references to Java front-end and library.
* doc/extend.texi: Likewise.
* doc/frontends.texi: Likewise.
* doc/generic.texi: Likewise.
* doc/install.texi: Likewise.
* doc/invoke.texi: Likewise.
* doc/md.texi: Likewise.
* doc/sourcebuild.texi: Likewise.
* doc/standards.texi: Likewise.
---
gcc/doc/cfg.texi | 5 +-
gcc/doc/extend.texi | 44 ++++++
gcc/doc/frontends.texi | 3 +-
gcc/doc/generic.texi | 5 +
gcc/doc/install.texi | 319 +++++++++++++++++++++++++++++++++++++--
gcc/doc/invoke.texi | 17 ++-
gcc/doc/md.texi | 3 +-
gcc/doc/sourcebuild.texi | 34 ++++-
gcc/doc/standards.texi | 3 +
9 files changed, 406 insertions(+), 27 deletions(-)
diff --git a/gcc/doc/cfg.texi b/gcc/doc/cfg.texi
index 32aacdd0aa8..2c341b3cef2 100644
--- a/gcc/doc/cfg.texi
+++ b/gcc/doc/cfg.texi
@@ -285,7 +285,7 @@ is needed. Note that this may require creation of a new basic block.
Exception handling edges represent possible control transfers from a
trapping instruction to an exception handler. The definition of
``trapping'' varies. In C++, only function calls can throw, but for
-Ada exceptions like division by zero or segmentation fault are
+Java and Ada, exceptions like division by zero or segmentation fault are
defined and thus each instruction possibly throwing this kind of
exception needs to be handled as control flow instruction. Exception
edges have the @code{EDGE_ABNORMAL} and @code{EDGE_EH} flags set.
@@ -594,7 +594,8 @@ can just use @code{NEXT_INSN} and @code{PREV_INSN} instead. @xref{Insns}.
Usually a code manipulating pass simplifies the instruction stream and
the flow of control, possibly eliminating some edges. This may for
example happen when a conditional jump is replaced with an
-unconditional jump. Updating of edges
+unconditional jump, but also when simplifying possibly trapping
+instruction to non-trapping while compiling Java. Updating of edges
is not transparent and each optimization pass is required to do so
manually. However only few cases occur in practice. The pass may
call @code{purge_dead_edges} on a given basic block to remove
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index b1dd39e64b8..fa1c00c16b2 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -24457,6 +24457,7 @@ Predefined Macros,cpp,The GNU C Preprocessor}).
* Function Multiversioning:: Declaring multiple function versions.
* Type Traits:: Compiler support for type traits.
* C++ Concepts:: Improved support for generic programming.
+* Java Exceptions:: Tweaking exception handling to work with Java.
* Deprecated Features:: Things will disappear from G++.
* Backwards Compatibility:: Compatibilities with earlier definitions of C++.
@end menu
@@ -24976,6 +24977,14 @@ Some_Class B __attribute__ ((init_priority (543)));
Note that the particular values of @var{priority} do not matter; only their
relative ordering.
+@item java_interface
+@cindex @code{java_interface} type attribute
+
+This type attribute informs C++ that the class is a Java interface. It may
+only be applied to classes declared within an @code{extern "Java"} block.
+Calls to methods declared in this interface are dispatched using GCJ's
+interface table mechanism, instead of regular virtual table dispatch.
+
@item warn_unused
@cindex @code{warn_unused} type attribute
@@ -25261,6 +25270,41 @@ A binary type trait: @code{true} whenever the type arguments are the same.
@end table
+@node Java Exceptions
+@section Java Exceptions
+
+The Java language uses a slightly different exception handling model
+from C++. Normally, GNU C++ automatically detects when you are
+writing C++ code that uses Java exceptions, and handle them
+appropriately. However, if C++ code only needs to execute destructors
+when Java exceptions are thrown through it, GCC guesses incorrectly.
+Sample problematic code is:
+
+@smallexample
+ struct S @{ ~S(); @};
+ extern void bar(); // @r{is written in Java, and may throw exceptions}
+ void foo()
+ @{
+ S s;
+ bar();
+ @}
+@end smallexample
+
+@noindent
+The usual effect of an incorrect guess is a link failure, complaining of
+a missing routine called @samp{__gxx_personality_v0}.
+
+You can inform the compiler that Java exceptions are to be used in a
+translation unit, irrespective of what it might think, by writing
+@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This
+@samp{#pragma} must appear before any functions that throw or catch
+exceptions, or run destructors when exceptions are thrown through them.
+
+You cannot mix Java and C++ exceptions in the same translation unit. It
+is believed to be safe to throw a C++ exception from one file through
+another file compiled for the Java exception model, or vice versa, but
+there may be bugs in this area.
+
@node Deprecated Features
@section Deprecated Features
diff --git a/gcc/doc/frontends.texi b/gcc/doc/frontends.texi
index e1b5b6153fc..6579d99d933 100644
--- a/gcc/doc/frontends.texi
+++ b/gcc/doc/frontends.texi
@@ -12,11 +12,12 @@
@cindex D
@cindex Fortran
@cindex Go
+@cindex Java
@cindex Objective-C
@cindex Objective-C++
GCC stands for ``GNU Compiler Collection''. GCC is an integrated
distribution of compilers for several major programming languages. These
-languages currently include C, C++, Objective-C, Objective-C++,
+languages currently include C, C++, Objective-C, Objective-C++, Java,
Fortran, Ada, D, and Go.
The abbreviation @dfn{GCC} has multiple meanings in common use. The
diff --git a/gcc/doc/generic.texi b/gcc/doc/generic.texi
index e5f9d1be8ea..3fa7ea0e388 100644
--- a/gcc/doc/generic.texi
+++ b/gcc/doc/generic.texi
@@ -43,6 +43,7 @@ seems inelegant.
* Functions:: Function bodies, linkage, and other aspects.
* Language-dependent trees:: Topics and trees specific to language front ends.
* C and C++ Trees:: Trees specific to C and C++.
+* Java Trees:: Trees specific to Java.
@end menu
@c ---------------------------------------------------------------------
@@ -3617,3 +3618,7 @@ In either case, the expression is void.
@end table
+
+
+@node Java Trees
+@section Java Trees
diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index 589c64965b2..0676f19d75e 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -371,6 +371,10 @@ Used by various scripts to generate some files included in the source
repository (mainly Unicode-related and rarely changing) from source
tables.
+@item @command{jar}, or InfoZIP (@command{zip} and @command{unzip})
+
+Necessary to build libgcj, the GCJ runtime.
+
Used by @command{automake}.
@end table
@@ -539,6 +543,27 @@ Useful when submitting patches for the GCC source code.
Necessary when applying patches, created with @command{diff}, to one's
own sources.
+@item ecj1
+@itemx gjavah
+If you wish to modify @file{.java} files in libjava, you will need to
+configure with @option{--enable-java-maintainer-mode}, and you will need
+to have executables named @command{ecj1} and @command{gjavah} in your path.
+The @command{ecj1} executable should run the Eclipse Java compiler via
+the GCC-specific entry point. You can download a suitable jar from
+@uref{ftp://sourceware.org/pub/java/}, or by running the script
+@command{contrib/download_ecj}.
+
+@item antlr.jar version 2.7.1 (or later)
+@itemx antlr binary
+
+If you wish to build the @command{gjdoc} binary in libjava, you will
+need to have an @file{antlr.jar} library available. The library is
+searched for in system locations but can be specified with
+@option{--with-antlr-jar=} instead. When configuring with
+@option{--enable-java-maintainer-mode}, you will need to have one of
+the executables named @command{cantlr}, @command{runantlr} or
+@command{antlr} in your path.
+
@end table
@html
@@ -568,9 +593,9 @@ HTTPS as tarballs compressed with @command{gzip} or @command{bzip2}.
Please refer to the @uref{https://gcc.gnu.org/releases.html,,releases web page}
for information on how to obtain GCC@.
-The source distribution includes the C, C++, Objective-C, Fortran,
+The source distribution includes the C, C++, Objective-C, Fortran, Java,
and Ada (in the case of GCC 3.1 and later) compilers, as well as
-runtime libraries for C++, Objective-C, and Fortran.
+runtime libraries for C++, Objective-C, Fortran and Java.
For previous versions these were downloadable as separate components such
as the core GCC distribution, which included the C language front end and
shared components, and language-specific distributions including the
@@ -1014,7 +1039,7 @@ only for the listed packages. For other packages, only static libraries
will be built. Package names currently recognized in the GCC tree are
@samp{libgcc} (also known as @samp{gcc}), @samp{libstdc++} (not
@samp{libstdc++-v3}), @samp{libffi}, @samp{zlib}, @samp{boehm-gc},
-@samp{ada}, @samp{libada}, @samp{libgo}, @samp{libobjc}, and @samp{libphobos}.
+@samp{ada}, @samp{libada}, @samp{libjava}, @samp{libgo}, @samp{libobjc}, and @samp{libphobos}.
Note @samp{libiberty} does not support shared libraries at all.
Use @option{--disable-shared} to build only static libraries. Note that
@@ -1384,7 +1409,7 @@ Use little endian by default. Provide a multilib for big endian.
@item --enable-threads
Specify that the target
supports threads. This affects the Objective-C compiler and runtime
-library, and exception handling for other languages like C++.
+library, and exception handling for other languages like C++ and Java.
On some systems, this is the default.
In general, the best (and, in many cases, the only known) threading
@@ -1401,7 +1426,7 @@ This is an alias for @option{--enable-threads=single}.
Specify that
@var{lib} is the thread support library. This affects the Objective-C
compiler and runtime library, and exception handling for other languages
-like C++. The possibilities for @var{lib} are:
+like C++ and Java. The possibilities for @var{lib} are:
@table @code
@item aix
@@ -1853,7 +1878,7 @@ grep ^language= */config-lang.in
@end smallexample
Currently, you can use any of the following:
@code{all}, @code{default}, @code{ada}, @code{c}, @code{c++}, @code{d},
-@code{fortran}, @code{go}, @code{jit}, @code{lto}, @code{objc}, @code{obj-c++}.
+@code{fortran}, @code{go}, @code{java}, @code{jit}, @code{lto}, @code{objc}, @code{obj-c++}.
Building the Ada compiler has special requirements, see below.
If you do not pass this flag, or specify the option @code{default}, then the
default languages available in the @file{gcc} sub-tree will be configured.
@@ -2565,6 +2590,240 @@ When you use this option, you should ensure that @var{dir} includes
tools.
@end table
+@subheading Java-Specific Options
+
+The following option applies to the build of the Java front end.
+
+@table @code
+@item --disable-libgcj
+Specify that the run-time libraries
+used by GCJ should not be built. This is useful in case you intend
+to use GCJ with some other run-time, or you're going to install it
+separately, or it just happens not to build on your particular
+machine. In general, if the Java front end is enabled, the GCJ
+libraries will be enabled too, unless they're known to not work on
+the target platform. If GCJ is enabled but @samp{libgcj} isn't built, you
+may need to port it; in this case, before modifying the top-level
+@file{configure.ac} so that @samp{libgcj} is enabled by default on this platform,
+you may use @option{--enable-libgcj} to override the default.
+
+@end table
+
+The following options apply to building @samp{libgcj}.
+
+@subsubheading General Options
+
+@table @code
+@item --enable-java-maintainer-mode
+By default the @samp{libjava} build will not attempt to compile the
+@file{.java} source files to @file{.class}. Instead, it will use the
+@file{.class} files from the source tree. If you use this option you
+must have executables named @command{ecj1} and @command{gjavah} in your path
+for use by the build. You must use this option if you intend to
+modify any @file{.java} files in @file{libjava}.
+
+@item --with-java-home=@var{dirname}
+This @samp{libjava} option overrides the default value of the
+@samp{java.home} system property. It is also used to set
+@samp{sun.boot.class.path} to @file{@var{dirname}/lib/rt.jar}. By
+default @samp{java.home} is set to @file{@var{prefix}} and
+@samp{sun.boot.class.path} to
+@file{@var{datadir}/java/libgcj-@var{version}.jar}.
+
+@item --with-ecj-jar=@var{filename}
+This option can be used to specify the location of an external jar
+file containing the Eclipse Java compiler. A specially modified
+version of this compiler is used by @command{gcj} to parse
+@file{.java} source files. If this option is given, the
+@samp{libjava} build will create and install an @file{ecj1} executable
+which uses this jar file at runtime.
+
+If this option is not given, but an @file{ecj.jar} file is found in
+the topmost source tree at configure time, then the @samp{libgcj}
+build will create and install @file{ecj1}, and will also install the
+discovered @file{ecj.jar} into a suitable place in the install tree.
+
+If @file{ecj1} is not installed, then the user will have to supply one
+on his path in order for @command{gcj} to properly parse @file{.java}
+source files. A suitable jar is available from
+@uref{ftp://sourceware.org/pub/java/}.
+
+@item --disable-getenv-properties
+Don't set system properties from @env{GCJ_PROPERTIES}.
+
+@item --enable-hash-synchronization
+Use a global hash table for monitor locks. Ordinarily,
+@samp{libgcj}'s @samp{configure} script automatically makes
+the correct choice for this option for your platform. Only use
+this if you know you need the library to be configured differently.
+
+@item --enable-interpreter
+Enable the Java interpreter. The interpreter is automatically
+enabled by default on all platforms that support it. This option
+is really only useful if you want to disable the interpreter
+(using @option{--disable-interpreter}).
+
+@item --disable-java-net
+Disable java.net. This disables the native part of java.net only,
+using non-functional stubs for native method implementations.
+
+@item --disable-jvmpi
+Disable JVMPI support.
+
+@item --disable-libgcj-bc
+Disable BC ABI compilation of certain parts of libgcj. By default,
+some portions of libgcj are compiled with @option{-findirect-dispatch}
+and @option{-fno-indirect-classes}, allowing them to be overridden at
+run-time.
+
+If @option{--disable-libgcj-bc} is specified, libgcj is built without
+these options. This allows the compile-time linker to resolve
+dependencies when statically linking to libgcj. However it makes it
+impossible to override the affected portions of libgcj at run-time.
+
+@item --enable-reduced-reflection
+Build most of libgcj with @option{-freduced-reflection}. This reduces
+the size of libgcj at the expense of not being able to do accurate
+reflection on the classes it contains. This option is safe if you
+know that code using libgcj will never use reflection on the standard
+runtime classes in libgcj (including using serialization, RMI or CORBA).
+
+@item --with-ecos
+Enable runtime eCos target support.
+
+@item --without-libffi
+Don't use @samp{libffi}. This will disable the interpreter and JNI
+support as well, as these require @samp{libffi} to work.
+
+@item --enable-libgcj-debug
+Enable runtime debugging code.
+
+@item --enable-libgcj-multifile
+If specified, causes all @file{.java} source files to be
+compiled into @file{.class} files in one invocation of
+@samp{gcj}. This can speed up build time, but is more
+resource-intensive. If this option is unspecified or
+disabled, @samp{gcj} is invoked once for each @file{.java}
+file to compile into a @file{.class} file.
+
+@item --with-libiconv-prefix=DIR
+Search for libiconv in @file{DIR/include} and @file{DIR/lib}.
+
+@item --enable-sjlj-exceptions
+Force use of the @code{setjmp}/@code{longjmp}-based scheme for exceptions.
+@samp{configure} ordinarily picks the correct value based on the platform.
+Only use this option if you are sure you need a different setting.
+
+@item --with-system-zlib
+Use installed @samp{zlib} rather than that included with GCC@.
+
+@item --with-win32-nlsapi=ansi, unicows or unicode
+Indicates how MinGW @samp{libgcj} translates between UNICODE
+characters and the Win32 API@.
+
+@item --enable-java-home
+If enabled, this creates a JPackage compatible SDK environment during install.
+Note that if --enable-java-home is used, --with-arch-directory=ARCH must also
+be specified.
+
+@item --with-arch-directory=ARCH
+Specifies the name to use for the @file{jre/lib/ARCH} directory in the SDK
+environment created when --enable-java-home is passed. Typical names for this
+directory include i386, amd64, ia64, etc.
+
+@item --with-os-directory=DIR
+Specifies the OS directory for the SDK include directory. This is set to auto
+detect, and is typically 'linux'.
+
+@item --with-origin-name=NAME
+Specifies the JPackage origin name. This defaults to the 'gcj' in
+java-1.5.0-gcj.
+
+@item --with-arch-suffix=SUFFIX
+Specifies the suffix for the sdk directory. Defaults to the empty string.
+Examples include '.x86_64' in 'java-1.5.0-gcj-1.5.0.0.x86_64'.
+
+@item --with-jvm-root-dir=DIR
+Specifies where to install the SDK. Default is $(prefix)/lib/jvm.
+
+@item --with-jvm-jar-dir=DIR
+Specifies where to install jars. Default is $(prefix)/lib/jvm-exports.
+
+@item --with-python-dir=DIR
+Specifies where to install the Python modules used for aot-compile. DIR should
+not include the prefix used in installation. For example, if the Python modules
+are to be installed in /usr/lib/python2.5/site-packages, then
+--with-python-dir=/lib/python2.5/site-packages should be passed. If this is
+not specified, then the Python modules are installed in $(prefix)/share/python.
+
+@item --enable-aot-compile-rpm
+Adds aot-compile-rpm to the list of installed scripts.
+
+@item --enable-browser-plugin
+Build the gcjwebplugin web browser plugin.
+
+@item --enable-static-libjava
+Build static libraries in libjava. The default is to only build shared
+libraries.
+
+@table @code
+@item ansi
+Use the single-byte @code{char} and the Win32 A functions natively,
+translating to and from UNICODE when using these functions. If
+unspecified, this is the default.
+
+@item unicows
+Use the @code{WCHAR} and Win32 W functions natively. Adds
+@code{-lunicows} to @file{libgcj.spec} to link with @samp{libunicows}.
+@file{unicows.dll} needs to be deployed on Microsoft Windows 9X machines
+running built executables. @file{libunicows.a}, an open-source
+import library around Microsoft's @code{unicows.dll}, is obtained from
+@uref{http://libunicows.sourceforge.net/}, which also gives details
+on getting @file{unicows.dll} from Microsoft.
+
+@item unicode
+Use the @code{WCHAR} and Win32 W functions natively. Does @emph{not}
+add @code{-lunicows} to @file{libgcj.spec}. The built executables will
+only run on Microsoft Windows NT and above.
+@end table
+@end table
+
+@subsubheading AWT-Specific Options
+
+@table @code
+@item --with-x
+Use the X Window System.
+
+@item --enable-java-awt=PEER(S)
+Specifies the AWT peer library or libraries to build alongside
+@samp{libgcj}. If this option is unspecified or disabled, AWT
+will be non-functional. Current valid values are @option{gtk} and
+@option{xlib}. Multiple libraries should be separated by a
+comma (i.e.@: @option{--enable-java-awt=gtk,xlib}).
+
+@item --enable-gtk-cairo
+Build the cairo Graphics2D implementation on GTK@.
+
+@item --enable-java-gc=TYPE
+Choose garbage collector. Defaults to @option{boehm} if unspecified.
+
+@item --disable-gtktest
+Do not try to compile and run a test GTK+ program.
+
+@item --disable-glibtest
+Do not try to compile and run a test GLIB program.
+
+@item --with-libart-prefix=PFX
+Prefix where libart is installed (optional).
+
+@item --with-libart-exec-prefix=PFX
+Exec prefix where libart is installed (optional).
+
+@item --disable-libarttest
+Do not try to compile and run a test libart program.
+
+@end table
+
@subsubheading Overriding @command{configure} test results
Sometimes, it might be necessary to override the result of some
@@ -2945,6 +3204,13 @@ native compiler. You can then use the native GCC compiler to build the
cross compiler. The installed native compiler needs to be GCC version
2.95 or later.
+If the cross compiler is to be built with support for the Java
+programming language and the ability to compile .java source files is
+desired, the installed native compiler used to build the cross
+compiler needs to be the same GCC version as the cross compiler. In
+addition the cross compiler needs to be configured with
+@option{--with-ecj-jar=@dots{}}.
+
Assuming you have already installed a native copy of GCC and configured
your cross compiler, issue the command @command{make}, which performs the
following steps:
@@ -3143,8 +3409,8 @@ on a simulator as described at @uref{https://gcc.gnu.org/simtest-howto.html}.
In order to run sets of tests selectively, there are targets
@samp{make check-gcc} and language specific @samp{make check-c},
@samp{make check-c++}, @samp{make check-d} @samp{make check-fortran},
-@samp{make check-ada}, @samp{make check-objc}, @samp{make check-obj-c++},
-@samp{make check-lto}
+@samp{make check-java}, @samp{make check-ada}, @samp{make check-objc},
+@samp{make check-obj-c++}, @samp{make check-lto}
in the @file{gcc} subdirectory of the object directory. You can also
just run @samp{make check} in a subdirectory of the object directory.
@@ -3250,6 +3516,19 @@ supported in the @file{gcc} subdirectory. (To see how this works, try
typing @command{echo} before the example given here.)
+@section Additional testing for Java Class Libraries
+
+The Java runtime tests can be executed via @samp{make check}
+in the @file{@var{target}/libjava/testsuite} directory in
+the build tree.
+
+The @uref{http://sourceware.org/mauve/,,Mauve Project} provides
+a suite of tests for the Java Class Libraries. This suite can be run
+as part of libgcj testing by placing the Mauve tree within the libjava
+testsuite at @file{libjava/testsuite/libjava.mauve/mauve}, or by
+specifying the location of that tree when invoking @samp{make}, as in
+@samp{make MAUVEDIR=~/mauve check}.
+
@section How to interpret test results
The result of running the testsuite are various @file{*.sum} and @file{*.log}
@@ -3334,7 +3613,7 @@ you specified with the @option{--prefix} to configure (or
@file{/usr/local} by default). (If you specified @option{--bindir},
that directory will be used instead; otherwise, if you specified
@option{--exec-prefix}, @file{@var{exec-prefix}/bin} will be used.)
-Headers for the C++ library are installed in
+Headers for the C++ and Java libraries are installed in
@file{@var{prefix}/include}; libraries in @file{@var{libdir}}
(normally @file{@var{prefix}/lib}); internal parts of the compiler in
@file{@var{libdir}/gcc} and @file{@var{libexecdir}/gcc}; documentation
@@ -3967,9 +4246,9 @@ The version of binutils installed in @file{/usr/bin} probably works
with this release of GCC@. Bootstrapping against the latest GNU
binutils and/or the version found in @file{/usr/ports/devel/binutils} has
been known to enable additional features and improve overall testsuite
-results. However, it is currently known that boehm-gc may not configure
-properly on FreeBSD prior to the FreeBSD 7.0 release with GNU binutils
-after 2.16.1.
+results. However, it is currently known that boehm-gc (which itself
+is required for java) may not configure properly on FreeBSD prior to
+the FreeBSD 7.0 release with GNU binutils after 2.16.1.
@html
<hr />
@@ -4067,7 +4346,8 @@ with the one implemented under HP-UX 11 using secondary definitions.
GCC 3.0 and up support HP-UX 11. GCC 2.95.x is not supported and cannot
be used to compile GCC 3.0 and up.
-The libffi library haven't been ported to 64-bit HP-UX@ and doesn't build.
+The libffi and libjava libraries haven't been ported to 64-bit HP-UX@
+and don't build.
Refer to @uref{binaries.html,,binaries} for information about obtaining
precompiled GCC binaries for HP-UX@. Precompiled binaries must be obtained
@@ -4080,7 +4360,11 @@ unbundled compiler, or a binary distribution of GCC@.
It is possible to build GCC 3.3 starting with the bundled HP compiler,
but the process requires several steps. GCC 3.3 can then be used to
-build later versions.
+build later versions. The fastjar program contains ISO C code and
+can't be built with the HP bundled compiler. This problem can be
+avoided by not building the Java language. For example, use the
+@option{--enable-languages="c,c++,f77,objc"} option in your configure
+command.
There are several possible approaches to building the distribution.
Binutils can be built first using the HP tools. Then, the GCC
@@ -4836,8 +5120,8 @@ you can install a pre-built GCC to bootstrap and install GCC. See the
@uref{binaries.html,,binaries page} for details.
The Solaris 2 @command{/bin/sh} will often fail to configure
-@samp{libstdc++-v3}. We therefore recommend using the
-following initial sequence of commands
+@samp{libstdc++-v3}, @samp{boehm-gc} or @samp{libjava}. We therefore
+recommend using the following initial sequence of commands
@smallexample
% CONFIG_SHELL=/bin/ksh
@@ -4891,6 +5175,9 @@ on x86 when the Solaris assembler is used, but can be enabled by
configuring with @option{--enable-libphobos}. Also, GDC 9.4.0 is
required on x86, while GDC 9.3.0 is known to work on SPARC.
+GNU @command{make} version 3.81 or later is required to build libjava
+with the Solaris linker.
+
The versions of the GNU Multiple Precision Library (GMP), the MPFR
library and the MPC library bundled with Solaris 11.3 and later are
usually recent enough to match GCC's requirements. There are two
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 330da6eb5d4..a49608b875e 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1587,6 +1587,12 @@ D interface file.
@item @var{file}.dd
D documentation code (Ddoc).
+@c FIXME: Descriptions of Java file types.
+@c @var{file}.java
+@c @var{file}.class
+@c @var{file}.zip
+@c @var{file}.jar
+
@item @var{file}.ads
Ada source code file that contains a library unit declaration (a
declaration of a package, subprogram, or generic, or a generic
@@ -1633,6 +1639,7 @@ ada
d
f77 f77-cpp-input f95 f95-cpp-input
go
+java
@end smallexample
@item -x none
@@ -4825,7 +4832,7 @@ accomplished via the comm page.
@item -fobjc-exceptions
@opindex fobjc-exceptions
Enable syntactic support for structured exception handling in
-Objective-C, similar to what is offered by C++. This option
+Objective-C, similar to what is offered by C++ and Java. This option
is required to use the Objective-C keywords @code{@@try},
@code{@@throw}, @code{@@catch}, @code{@@finally} and
@code{@@synchronized}. This option is available with both the GNU
@@ -17625,7 +17632,7 @@ of these is when the application wishes to throw and catch exceptions
across different shared libraries. In that case, each of the libraries
as well as the application itself should use the shared @file{libgcc}.
-Therefore, the G++ driver automatically adds @option{-shared-libgcc}
+Therefore, the G++ and GCJ drivers automatically add @option{-shared-libgcc}
whenever you build a shared library or a main executable, because C++
programs typically use exceptions, so this is the right thing to do.
@@ -17641,7 +17648,8 @@ propagate through such shared libraries, without incurring relocation
costs at library load time.
However, if a library or main executable is supposed to throw or catch
-exceptions, you must link it using the G++ driver, or using the option
+exceptions, you must link it using the G++ or GCJ driver, as appropriate
+for the languages used in the program, or using the option
@option{-shared-libgcc}, such that it is linked with the shared
@file{libgcc}.
@@ -17964,7 +17972,8 @@ results in @option{-ftrapv} being effective.
This option instructs the compiler to assume that signed arithmetic
overflow of addition, subtraction and multiplication wraps around
using twos-complement representation. This flag enables some optimizations
-and disables others.
+and disables others. This option is enabled by default for the Java
+front end, as required by the Java language specification.
The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
@option{-ftrapv} @option{-fwrapv} on the command-line results in
@option{-fwrapv} being effective. Note that only active options override, so
diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index d0a71ecbb80..62e35c1e22b 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -7435,7 +7435,8 @@ function.
@cindex @code{trap} instruction pattern
@item @samp{trap}
This pattern, if defined, signals an error, typically by causing some
-kind of signal to be raised.
+kind of signal to be raised. Among other places, it is used by the Java
+front end to signal `invalid array index' exceptions.
@cindex @code{ctrap@var{MM}4} instruction pattern
@item @samp{ctrap@var{MM}4}
diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index ffe69d6fcb9..73f495e608d 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -89,7 +89,7 @@ The C preprocessor library.
The Decimal Float support library.
@item libffi
-The @code{libffi} library, used as part of the Go runtime library.
+The @code{libffi} library, used as part of the Go and Java runtime libraries.
@item libgcc
The GCC runtime library.
@@ -113,6 +113,9 @@ about this library.
@item libitm
The runtime support library for transactional memory.
+@item libjava
+The Java runtime library.
+
@item libobjc
The Objective-C and Objective-C++ runtime library.
@@ -144,8 +147,9 @@ Plugin used by the linker if link-time optimizations are enabled.
Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
@item zlib
-The @code{zlib} compression library, used for compressing and
-uncompressing GCC's intermediate language in LTO object files.
+The @code{zlib} compression library, used by the Java front end, as
+part of the Java runtime library, and for compressing and uncompressing
+GCC's intermediate language in LTO object files.
@end table
The build system in the top level directory, including how recursion
@@ -911,6 +915,7 @@ here; FIXME: document the others.
* Test Directives:: Directives used within DejaGnu tests.
* Ada Tests:: The Ada language testsuites.
* C Tests:: The C language testsuites.
+* libgcj Tests:: The Java library testsuites.
* LTO Testing:: Support for testing link-time optimizations.
* gcov Testing:: Support for testing gcov.
* profopt Testing:: Support for testing profile-directed optimizations.
@@ -3588,6 +3593,29 @@ Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
test cases and magic comments more.
+@node libgcj Tests
+@section The Java library testsuites.
+
+Runtime tests are executed via @samp{make check} in the
+@file{@var{target}/libjava/testsuite} directory in the build
+tree. Additional runtime tests can be checked into this testsuite.
+
+Regression testing of the core packages in libgcj is also covered by the
+Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project}
+develops tests for the Java Class Libraries. These tests are run as part
+of libgcj testing by placing the Mauve tree within the libjava testsuite
+sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
+the location of that tree when invoking @samp{make}, as in
+@samp{make MAUVEDIR=~/mauve check}.
+
+To detect regressions, a mechanism in @file{mauve.exp} compares the
+failures for a test run against the list of expected failures in
+@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
+Update this file when adding new failing tests to Mauve, or when fixing
+bugs in libgcj that had caused Mauve test failures.
+
+We encourage developers to contribute test cases to Mauve.
+
@node LTO Testing
@section Support for testing link-time optimizations
diff --git a/gcc/doc/standards.texi b/gcc/doc/standards.texi
index f878615ca30..3a83794ed8b 100644
--- a/gcc/doc/standards.texi
+++ b/gcc/doc/standards.texi
@@ -334,3 +334,6 @@ conformance and compatibility of the Ada compiler.
@xref{Standards,,Standards, gfortran, The GNU Fortran Compiler}, for details
of standards supported by GNU Fortran.
+
+@xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
+for details of compatibility between @command{gcj} and the Java Platform.
\ No newline at end of file
--
2.38.1
