[PATCH] for Review: Java configure options in install.texi

[Mohan Embar <gnustuff at thisiscool dot com>]

Hi All,

>Mohan> I didn't know where to put it and it ended up concluding
>Mohan> that the proper place was gcc/doc/install.texi, but
>Mohan> there are so many libgcj configure options that aren't
>Mohan> docunmented there that it isn't even funny. (Of course,
>Mohan> two wrongs don't make a right....)

>Yeah, if you're up to it, write a patch for all the missing options
>for install.texi.  I think that's where this belongs: I assume
>install.texi is meant to have an exhaustive list, and that's
>presumably where people will start when trying to build gcc.

Here is my first stab at this. I documented "my" libgcj options
and basically pasted the rest of the stuff straight from
configure --help, with a couple of exceptions. I've also attached
the gccinstall.html which Ranjit showed me how to generate.

Most of the options are pretty terse and could stand to be
elaborated upon. Here are some examples that are sure to win some
literary award somewhere:

--enable-interpreter
Enable the Java interpreter.

--disable-java-net
Disable java.net.

--disable-jvmpi
Disable JVMPI support.

Nevertheless, it's better than nothing.

I know I need to submit this to gcc-patches, but I wanted to give us
a chance to look at things here first. In particular, I'm looking for
feedback on the way I formatted the new section as well as more elaborate
documentation for most of the options. You can also send these to me
in a plain text email and I'll incorporate them.

If I don't here from anyone soon, I'll submit this to gcc-patches. I'm
assuming doc fixes like this can still go into 3.4, but what do I know?

-- Mohan
http://www.thisiscool.com/
http://www.animalsong.org/

ChangeLog
2004-01-19  Mohan Embar  <gnustuff@thisiscool.com>

	* doc/install.texi: Add section on Java-specific options.

Index: doc/install.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/install.texi,v
retrieving revision 1.248.4.3
diff -u -2 -r1.248.4.3 install.texi
--- doc/install.texi	18 Jan 2004 11:59:06 -0000	1.248.4.3
+++ doc/install.texi	20 Jan 2004 03:24:09 -0000
@@ -546,4 +546,8 @@
 work and should not normally be used.

+Note that each @option{--enable} option has a corresponding
+@option{--disable} option and that each @option{--with} option has a
+corresponding @option{--without} option.
+
 @table @code
 @item --prefix=@var{dirname}
@@ -1011,16 +1015,4 @@
 language sub-directories might not have been configured!

-@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.in} so that @samp{libgcj} is enabled by default on this platform,
-you may use @option{--enable-libgcj} to override the default.
-
 @item --with-dwarf2
 Specify that the compiler should
@@ -1116,8 +1108,4 @@
 libiconv library files in @file{@var{dir}/lib}.

-@item --with-system-zlib
-Use installed zlib rather than that included with GCC@.  This option
-only applies if the Java front end is being built.
-
 @item --enable-obsolete
 Enable configuration for an obsoleted system.  If you attempt to
@@ -1179,7 +1167,127 @@
 @end table

-Note that each @option{--enable} option has a corresponding
-@option{--disable} option and that each @option{--with} option has a
-corresponding @option{--without} option.
+@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.in} 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 --disable-getenv-properties
+Don't set system properties from @env{GCJ_PROPERTIES}.
+
+@item --enable-hash-synchronization
+Use a global hash table for monitor locks.
+
+@item --enable-interpreter
+Enable the Java interpreter.
+
+@item --disable-java-net
+Disable java.net.
+
+@item --disable-jvmpi
+Disable JVMPI support.
+
+@item --with-ecos
+Enable runtime eCos target support.
+
+@item --without-libffi
+Don't use libffi.
+
+@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 @code{builtin_setjmp} for exceptions.
+
+@item --with-system-zlib
+Use installed zlib rather than that included with GCC@.
+
+@item --with-win32-nlsapi=ansi, unicows or unicode
+Indicates how MinGW libgcj translates between UNICODE
+characters and the Win32 API.
+@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 libunicows.
+@file{unicows.dll} needs to be deployed on 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 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
+Indicates the AWT peer type. Valid values are @option{gtk} and
+@option{xlib}. If unspecified, AWT will be non-functional in
+the built @samp{libgcj}.
+
+@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

 @html

Attachment: gccinstall.html.bz2
Description: application/bzip2