summaryrefslogtreecommitdiff
path: root/libjava/classpath/doc/cp-hacking.texinfo
diff options
context:
space:
mode:
Diffstat (limited to 'libjava/classpath/doc/cp-hacking.texinfo')
-rw-r--r--libjava/classpath/doc/cp-hacking.texinfo2081
1 files changed, 2081 insertions, 0 deletions
diff --git a/libjava/classpath/doc/cp-hacking.texinfo b/libjava/classpath/doc/cp-hacking.texinfo
new file mode 100644
index 000000000..2914c5be5
--- /dev/null
+++ b/libjava/classpath/doc/cp-hacking.texinfo
@@ -0,0 +1,2081 @@
+\input texinfo @c -*-texinfo-*-
+
+@c %**start of header
+@setfilename cp-hacking.info
+@settitle GNU Classpath Hacker's Guide
+@c %**end of header
+
+@setchapternewpage off
+
+@ifinfo
+This file contains important information you will need to know if you
+are going to hack on the GNU Classpath project code.
+
+Copyright (C) 1998,1999,2000,2001,2002,2003,2004,2005,2007,2009 Free Software Foundation, Inc.
+
+@ifnotplaintext
+@dircategory GNU Libraries
+@direntry
+* Classpath Hacking: (cp-hacking). GNU Classpath Hacker's Guide
+@end direntry
+@end ifnotplaintext
+@end ifinfo
+
+@titlepage
+@title GNU Classpath Hacker's Guide
+@author Aaron M. Renn
+@author Paul N. Fisher
+@author John Keiser
+@author C. Brian Jones
+@author Mark J. Wielaard
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
+@sp 2
+Permission is granted to make and distribute verbatim copies of
+this document provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+document under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Free Software Foundation.
+
+@end titlepage
+
+@ifinfo
+@node Top, Introduction, (dir), (dir)
+@top GNU Classpath Hacker's Guide
+
+This document contains important information you'll want to know if
+you want to hack on GNU Classpath, Essential Libraries for Java, to
+help create free core class libraries for use with virtual machines
+and compilers for the java programming language.
+@end ifinfo
+
+@menu
+* Introduction:: An introduction to the GNU Classpath project
+* Requirements:: Very important rules that must be followed
+* Volunteering:: So you want to help out
+* Project Goals:: Goals of the GNU Classpath project
+* Needed Tools and Libraries:: A list of programs and libraries you will need
+* Installation:: Installation instructions
+* Building and running with the X AWT peers:: Building and running with the X AWT peers
+* Misc. Notes:: Miscellaneous notes
+* Programming Standards:: Standards to use when writing code
+* Hacking Code:: Working on code, Working with others
+* Programming Goals:: What to consider when writing code
+* API Compatibility:: How to handle serialization and deprecated methods
+* Specification Sources:: Where to find class library specs
+* Naming Conventions:: How files and directories are named
+* Character Conversions:: Working on Character conversions
+* Localization:: How to handle localization/internationalization
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Programming Standards
+
+* Source Code Style Guide::
+
+Working on the code, Working with others
+
+* Branches::
+* Writing ChangeLogs::
+
+Working with branches
+
+* Writing ChangeLogs::
+
+Programming Goals
+
+* Portability:: Writing Portable Software
+* Utility Classes:: Reusing Software
+* Robustness:: Writing Robust Software
+* Java Efficiency:: Writing Efficient Java
+* Native Efficiency:: Writing Efficient JNI
+* Security:: Writing Secure Software
+
+API Compatibility
+
+* Serialization:: Serialization
+* Deprecated Methods:: Deprecated methods
+
+Localization
+
+* String Collation:: Sorting strings in different locales
+* Break Iteration:: Breaking up text into words, sentences, and lines
+* Date Formatting and Parsing:: Locale specific date handling
+* Decimal/Currency Formatting and Parsing:: Local specific number handling
+
+@end detailmenu
+@end menu
+
+@node Introduction, Requirements, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+
+The GNU Classpath Project is dedicated to providing a 100% free,
+clean room implementation of the standard core class libraries for
+compilers and runtime environments for the java programming language.
+It offers free software developers an alternative core library
+implementation upon which larger java-like programming environments
+can be built. The GNU Classpath Project was started in the Spring of
+1998 as an official Free Software Foundation project. Most of the
+volunteers working on GNU Classpath do so in their spare time, but a
+couple of projects based on GNU Classpath have paid programmers to
+improve the core libraries. We appreciate everyone's efforts in the
+past to improve and help the project and look forward to future
+contributions by old and new members alike.
+
+@node Requirements, Volunteering, Introduction, Top
+@comment node-name, next, previous, up
+@chapter Requirements
+
+Although GNU Classpath is following an open development model where input
+from developers is welcome, there are certain base requirements that
+need to be met by anyone who wants to contribute code to this project.
+They are mostly dictated by legal requirements and are not arbitrary
+restrictions chosen by the GNU Classpath team.
+
+You will need to adhere to the following things if you want to donate
+code to the GNU Classpath project:
+
+@itemize @bullet
+@item
+@strong{Never under any circumstances refer to proprietary code while
+working on GNU Classpath.} It is best if you have never looked at
+alternative proprietary core library code at all. To reduce
+temptation, it would be best if you deleted the @file{src.zip} file
+from your proprietary JDK distribution (note that recent versions of
+GNU Classpath and the compilers and environments build on it are
+mature enough to not need any proprietary implementation at all when
+working on GNU Classpath, except in exceptional cases where you need
+to test compatibility issues pointed out by users). If you have
+signed Sun's non-disclosure statement, then you unfortunately cannot
+work on Classpath code at all. If you have any reason to believe that
+your code might be ``tainted'', please say something on the mailing
+list before writing anything. If it turns out that your code was not
+developed in a clean room environment, we could be very embarrassed
+someday in court. Please don't let that happen.
+
+@item
+@strong{Never decompile proprietary class library implementations.} While
+the wording of the license in Sun's Java 2 releases has changed, it is
+not acceptable, under any circumstances, for a person working on
+GNU Classpath to decompile Sun's class libraries. Allowing the use of
+decompilation in the GNU Classpath project would open up a giant can of
+legal worms, which we wish to avoid.
+
+@item
+Classpath is licensed under the terms of the
+@uref{http://www.fsf.org/copyleft/gpl.html,GNU General Public
+License}, with a special exception included to allow linking with
+non-GPL licensed works as long as no other license would restrict such
+linking. To preserve freedom for all users and to maintain uniform
+licensing of Classpath, we will not accept code into the main
+distribution that is not licensed under these terms. The exact
+wording of the license of the current version of GNU Classpath can be
+found online from the
+@uref{http://www.gnu.org/software/classpath/license.html, GNU
+Classpath license page} and is of course distributed with current
+snapshot release from @uref{ftp://ftp.gnu.org/gnu/classpath/} or by
+obtaining a copy of the current CVS tree.
+
+@item
+GNU Classpath is GNU software and this project is being officially sponsored
+by the @uref{http://www.fsf.org/,Free Software Foundation}. Because of
+this, the FSF will hold copyright to all code developed as part of
+GNU Classpath. This will allow them to pursue copyright violators in court,
+something an individual developer may neither have the time nor
+resources to do. Everyone contributing code to GNU Classpath will need to
+sign a copyright assignment statement. Additionally, if you are
+employed as a programmer, your employer may need to sign a copyright
+waiver disclaiming all interest in the software. This may sound harsh,
+but unfortunately, it is the only way to ensure that the code you write
+is legally yours to distribute.
+@end itemize
+
+@node Volunteering, Project Goals, Requirements, Top
+@comment node-name, next, previous, up
+@chapter Volunteering to Help
+
+The GNU Classpath project needs volunteers to help us out. People are
+needed to write unimplemented core packages, to test GNU Classpath on
+free software programs written in the java programming language, to
+test it on various platforms, and to port it to platforms that are
+currently unsupported.
+
+While pretty much all contributions are welcome (but see
+@pxref{Requirements}) it is always preferable that volunteers do the
+whole job when volunteering for a task. So when you volunteer to write
+a Java package, please be willing to do the following:
+
+@itemize @bullet
+@item
+Implement a complete drop-in replacement for the particular package.
+That means implementing any ``internal'' classes. For example, in the
+java.net package, there are non-public classes for implementing sockets.
+Without those classes, the public socket interface is useless. But do
+not feel obligated to completely implement all of the functionality at
+once. For example, in the java.net package, there are different types
+of protocol handlers for different types of URLs. Not all of these
+need to be written at once.
+
+@item
+Please write complete and thorough API documentation comments for
+every public and protected method and variable. These should be
+superior to Sun's and cover everything about the item being
+documented.
+
+@item
+Please write a regression test package that can be used to run tests
+of your package's functionality. GNU Classpath uses the
+@uref{http://sources.redhat.com/mauve/,Mauve project} for testing the
+functionality of the core class libraries. The Classpath Project is
+fast approaching the point in time where all modifications to the
+source code repository will require appropriate test cases in Mauve to
+ensure correctness and prevent regressions.
+@end itemize
+
+Writing good documentation, tests and fixing bugs should be every
+developer's top priority in order to reach the elusive release of
+version 1.0.
+
+@node Project Goals, Needed Tools and Libraries, Volunteering, Top
+@comment node-name, next, previous, up
+@chapter Project Goals
+
+The goal of the Classpath project is to produce a
+@uref{http://www.fsf.org/philosophy/free-sw.html,free} implementation of
+the standard class library for Java. However, there are other more
+specific goals as to which platforms should be supported.
+
+Classpath is targeted to support the following operating systems:
+
+@enumerate
+@item
+Free operating systems. This includes GNU/Linux, GNU/Hurd, and the free
+BSDs.
+
+@item
+Other Unix-like operating systems.
+
+@item
+Platforms which currently have no Java support at all.
+
+@item
+Other platforms such as MS-Windows.
+@end enumerate
+
+While free operating systems are the top priority, the other priorities
+can shift depending on whether or not there is a volunteer to port
+Classpath to those platforms and to test releases.
+
+Eventually we hope the Classpath will support all JVMs that provide
+JNI or CNI support. However, the top priority is free JVMs. A small
+list of Compiler/VM environments that are currently actively
+incorporating GNU Classpath is below. A more complete overview of
+projects based on GNU classpath can be found online at
+@uref{http://www.gnu.org/software/classpath/stories.html,the GNU
+Classpath stories page}.
+
+@enumerate
+@item
+@uref{http://gcc.gnu.org/java/,GCJ}
+@item
+@uref{http://jamvm.sourceforge.net/,jamvm}
+@item
+@uref{http://www.cacaojvm.org/,cacao}
+@item
+@uref{http://jikesrvm.org,Jikes RVM}
+@item
+@uref{http://www.kaffe.org/,Kaffe}
+@item
+@uref{http://www.ikvm.net/,IKVM}
+@end enumerate
+
+As with OS platform support, this priority list could change if a
+volunteer comes forward to port, maintain, and test releases for a
+particular JVM@. Since gcj is part of the GNU Compiler Collective it
+is one of the most important targets. But since it doesn't currently
+work out of the box with GNU Classpath it is not the easiest
+target. When hacking on GNU Classpath the easiest solution is to use
+compilers and runtime environments that work out of the box with
+it, such as the Eclipse compiler, ecj, and the runtime environments jamvm and
+cacao. Both Jikes RVM and Kaffe use an included version of GNU Classpath by
+default, but Kaffe can now use a pre-installed version and Jikes RVM supports
+using a CVS snapshot as well as the latest release. Working directly with
+targets such as Jikes RVM, gcj and IKVM is possible but can be a little more
+difficult as changes have to be merged back into GNU Classpath proper,
+which requires additional work. Due to a recent switch to the use of 1.5 language
+features within GNU Classpath, a compiler compatible with these features is required.
+At present, this includes the Eclipse compiler, ecj, and the OpenJDK compiler.
+
+GNU Classpath currently implements the majority of the 1.4 and 1.5 APIs
+(binary compatibility is above 95% for both, but does not take into account
+internal implementations of features such as graphic and sound support). There
+is support for some 1.6 APIs but this is still nascent. Please do not create classes
+that depend on features in other packages unless GNU Classpath already
+contains those features. GNU Classpath has been free of any
+proprietary dependencies for a long time now and we like to keep it
+that way. Finishing, polishing up, documenting, testing and
+debugging current functionality is of higher priority then adding new
+functionality.
+
+@node Needed Tools and Libraries, Installation, Project Goals, Top
+@comment node-name, next, previous, up
+@chapter Needed Tools and Libraries
+
+If you want to hack on Classpath, you should at least download and
+install the following tools and try to familiarize yourself with
+them. In most cases having these tools installed will be all
+you really need to know about them. Also note that when working on
+(snapshot) releases only a 1.5 compiler (plus a free VM from the list above
+and the libraries listed below) is required. The other tools are only
+needed when working directly on the CVS version.
+
+@itemize @bullet
+@item
+GNU make 3.80+
+@item
+GCC 2.95+
+@item
+Eclipse Compiler for Java 3.1+
+@item
+CVS 1.11+
+@item
+automake 1.11+
+@item
+autoconf 2.64+
+@item
+libtool 1.5+
+@item
+GNU m4 1.4.6
+@item
+texinfo 4.2+
+@end itemize
+
+All of these tools are available from
+@uref{ftp://gnudist.gnu.org/pub/gnu/,gnudist.gnu.org} via anonymous
+ftp, except CVS which is available from
+@uref{http://www.cvshome.org/,www.cvshome.org} and the Eclipse
+Compiler for Java, which is available from
+@uref{http://www.eclipse.org/jdt/core,www.eclipse.org/jdt/core}.
+
+Except for the Eclipse Compiler for Java, they are fully documented
+with texinfo manuals. Texinfo can be browsed with the Emacs editor,
+or with the text editor of your choice, or transformed into nicely
+printable Postscript.
+
+Here is a brief description of the purpose of those tools.
+
+@table @b
+
+@item make
+GNU make ("gmake") is required for building Classpath.
+
+@item GCC
+The GNU Compiler Collection. This contains a C compiler (gcc) for
+compiling the native C code and a compiler for the java programming
+language (gcj). You will need at least gcc version 2.95 or higher
+in order to compile the native code. There is currently no
+released version of gcj that can compile the Java 1.5 programming
+language used by GNU Classpath.
+
+@item ecj
+The Eclipse Compiler for Java. This is a compiler for the Java 1.5
+programming language. It translates source code to bytecode. The
+Eclipse Foundation makes ``ecj.jar'' available as the JDT Core Batch
+Compiler download.
+
+@item CVS
+A version control system that maintains a centralized Internet
+repository of all code in the Classpath system.
+
+@item automake
+This tool automatically creates @file{Makefile.in} files from
+@file{Makefile.am} files. The @file{Makefile.in} is turned into a
+@file{Makefile} by @command{autoconf}.
+
+Why use this? Because it automatically generates every makefile
+target you would ever want (@option{clean}, @option{install},
+@option{dist}, etc) in full compliance with the GNU coding standards.
+It also simplifies Makefile creation in a number of ways that cannot
+be described here. Read the docs for more info.
+
+@item autoconf
+Automatically configures a package for the platform on which it is
+being built and generates the Makefile for that platform.
+
+@item libtool
+Handles all of the zillions of hairy platform specific options needed
+to build shared libraries.
+
+@item m4
+The free GNU replacement for the standard Unix macro processor.
+Proprietary m4 programs are broken and so GNU m4 is required for
+autoconf to work though knowing a lot about GNU m4 is not required to
+work with autoconf.
+
+@item perl
+Larry Wall's scripting language. It is used internally by automake.
+
+@item texinfo
+Manuals and documentation (like this guide) are written in texinfo.
+Texinfo is the official documentation format of the GNU project.
+Texinfo uses a single source file to produce output in a number of formats,
+both online and printed (dvi, info, html, xml, etc.). This means that
+instead of writing different documents for online information and another
+for a printed manual, you need write only one document. And when the work
+is revised, you need revise only that one document.
+
+@end table
+
+For any build environment involving native libraries, recent
+versions of @command{autoconf}, @command{automake}, and @command{libtool}
+are required if changes are made that require rebuilding @file{configure},
+@file{Makefile.in}, @file{aclocal.m4}, or @file{config.h.in}.
+
+When working from CVS you can run those tools by executing
+@command{autogen.sh} in the source directory.
+
+For building the Java bytecode (.class files), you can select
+which compiler should be employed using @option{--with-javac} or
+@option{--with-ecj} as an argument to @command{configure};
+the present default is @command{ecj} if found.
+
+Instead of @command{ecj}, you can also use @command{javac}, which is
+available at
+@uref{https://openjdk.dev.java.net/compiler, openjdk.dev.java.net/compiler}.
+
+For compiling the native AWT libraries you need to have the following
+libraries installed (unless @option{--disable-gtk-peer} is used as an argument
+to @command{configure}):
+
+@table @b
+@item GTK+ 2.8.x
+@uref{http://www.gtk.org/,GTK+} is a multi-platform toolkit for
+creating graphical user interfaces. It is used as the basis of the
+GNU desktop project GNOME.
+
+@item gdk-pixbuf
+@uref{http://www.gnome.org/start/,gdk-pixbuf} is a GNOME library for
+representing images.
+
+@item XTest
+@uref{http://www.x.org,www.x.org} hosts the XTest Extension (libXtst).
+It is necessary for GdkRobot support in java.awt.
+
+@end table
+
+There is a bug in earlier versions of at-spi, atk, and gail, which are
+used for GNOME accessibility. Prior to version 1.18.0 of these packages,
+gtk graphical applications should be run without accessibility (clear the
+GTK_MODULES environment variable).
+
+For building the Qt AWT peer JNI native libraries you have to
+specify @option{--enable-qt-peer} and need the following library:
+
+@table @b
+@item Qt
+@uref{http://www.trolltech.com/products/qt,Qt} version 4.0.1 or higher.
+The Qt library is a cross-platform graphics toolkit.
+
+@end table
+
+Please note that at the moment most operating systems do not
+ship Qt version 4.0.1 by default. We recommend using GNU Classpath' Qt
+support only for its developers and bug reporters. See
+@uref{http://developer.classpath.org/mediation/ClasspathShowcase, the wiki}
+for details on how to get it to work.
+
+For building the X AWT peers you have to specify where to find the
+Escher library on your system using the @option{--with-escher=ABS.PATH} option.
+You will need the following library:
+
+@table @b
+@item Escher
+@uref{http://escher.sourceforge.net,Escher} version 0.2.3 or higher.
+The Escher library is an implementation of X protocol and associated
+libraries written in the Java programming language.
+
+@end table
+
+For building the ALSA midi provider code you will need
+the following library:
+
+
+@table @b
+@item ALSA
+@uref{http://www.alsa-project.org,ALSA} libraries.
+
+The ALSA project provides sound device drivers and associated
+libraries for the Linux kernel.
+
+@end table
+
+Building the ALSA midi provider code can be disabled by passing
+@option{--disable-alsa} to @command{configure}.
+
+For building the DSSI midi synthesizer provider code you will
+need the following libraries:
+
+@table @b
+@item DSSI
+@uref{http://dssi.sourceforge.net,DSSI} library for audio
+processing plugins.
+
+@item liblo
+@uref{http://plugin.org.uk/liblo/,liblo}, the Lightweight OSC
+implementation.
+
+@item LADSPA
+@uref{http://www.ladspa.org,LADSPA}, the Linux Audio Developer's
+Simple Plugin API.
+
+@item JACK
+@uref{http://jackit.sourceforge.net,JACK}, a low latency audio
+server.
+
+@item libsndfile
+@uref{http://www.mega-nerd.com/libsndfile/,libsndfile}, an audio
+file I/O library.
+
+@item fluidsynth
+@uref{http://www.fluidsynth.org/,fluidsynth}, a real-time SoundFont
+2 based soft-synth.
+
+@end table
+
+The GConf-based backend for java.util.prefs needs the following
+library headers:
+
+@table @b
+@item GConf
+@uref{http://www.gnome.org/projects/gconf/,GConf} version 2.11.2
+(or higher). GConf is used for storing desktop and application
+configuration settings in GNOME.
+
+@end table
+
+The GStreamer backend for javax.sound.sampled (The Java Sound API, not
+including the MIDI portion) needs the following library headers:
+
+@table @b
+@item GStreamer
+@uref{http://gstreamer.freedesktop.org/,GStreamer} version 0.10.10
+(or higher). You will also need at least gstreamer-base and
+gstreamer-plugins-base. More plugins can be used to allow streaming of
+different sound types but are not a compile time requirement. See
+README.gstreamer in the source distribution for more informations.
+
+@end table
+
+For building @command{gcjwebplugin} you'll need the Mozilla plugin
+support headers and libraries, which are available at
+@uref{http://www.mozilla.org,www.mozilla.org}.
+
+For enabling the com.sun.tools.javac support in tools.zip you
+will need a jar file containing the Eclipse Java Compiler.
+Otherwise com.sun.tools.javac will not be included in @file{tools.zip}.
+
+For building the xmlj JAXP implementation (disabled by default,
+use @command{configure --enable-xmlj}) you need the following libraries:
+
+@table @b
+@item libxml2
+@uref{http://www.xmlsoft.org/,libxml2} version 2.6.8 or higher.
+
+The libxml2 library is the XML C library for the Gnome desktop.
+
+@item libxslt
+@uref{http://www.xmlsoft.org/XSLT/,libxslt} version 1.1.11 or higher.
+
+The libxslt library if the XSLT C library for the Gnome desktop.
+@end table
+
+GNU Classpath comes with a couple of libraries included in the source
+that are not part of GNU Classpath proper, but that have been included
+to provide certain needed functionality. All these external libraries
+should be clearly marked as such. In general we try to use as much as
+possible the clean upstream versions of these sources. That way
+merging in new versions will be easier. You should always try to get
+bug fixes to these files accepted upstream first. Currently we
+include the following 'external' libraries. Most of these sources are
+included in the @file{external} directory. That directory also
+contains a @file{README} file explaining how to import newer versions.
+
+@table @b
+
+@item JSR166 concurrency support
+Can be found in @file{external/jsr166}. Provides java.util.concurrent
+and its subpackages. Upstream is
+@uref{http://g.oswego.edu/dl/concurrency-interest/,Doug Lea's Concurrency Interest Site}.
+
+@item RelaxNG Datatype Interfaces
+Can be found in @file{external/relaxngDatatype}. Provides org.relaxng.datatype
+and its subpackages. Upstream is
+@uref{http://www.oasis-open.org/committees/relax-ng/}.
+
+@item Simple API for XML (SAX)
+Can be found in @file{external/sax}. Provides org.xml.sax and its subpackages.
+Upstream is
+@uref{http://www.saxproject.org}.
+
+@item Document Object Model (DOM) bindings
+Can be found in @file{external/w3c_dom}. Provides org.w3c.dom and its subpackages.
+Upstream locations are listed in @file{external/w3c_dom/README}.
+
+@item fdlibm
+Can be found in @file{native/fdlibm}. Provides native implementations
+of some of the Float and Double operations. Upstream is
+@uref{http://gcc.gnu.org/java/,libgcj}, they sync again with the
+'real' upstream @uref{http://www.netlib.org/fdlibm/readme}. See also
+java.lang.StrictMath.
+
+@end table
+
+@node Installation, Building and running with the X AWT peers, Needed Tools and Libraries, Top
+@comment node-name, next, previous, up
+@chapter Installation instructions
+
+This package was designed to use the GNU standard for configuration
+and makefiles. To build and install do the following:
+
+@enumerate
+@item Configuration
+
+Run the @command{configure} script to configure the package. There are
+various options you might want to pass to @command{configure} to control how the
+package is built. Consider the following options, @command{configure --help}
+gives a complete list.
+
+@table @option
+@item --enable-java
+
+compile Java source (default=@option{yes}).
+
+@item --enable-jni
+
+compile JNI source (default=@option{yes}).
+
+@item --enable-gtk-peer
+
+compile GTK native peers (default=@option{yes}).
+
+@item --enable-qt-peer
+
+compile Qt4 native peers (default=@option{no}).
+
+@item --enable-default-toolkit
+
+fully qualified class name of default AWT toolkit (default=@option{no}).
+
+@item --enable-xmlj
+
+compile native libxml/xslt library (default=@option{no}).
+
+@item --enable-load-library
+
+enable to use JNI native methods (default=@option{yes}).
+
+@item --enable-local-sockets
+
+enable build of local Unix sockets.
+
+@item --with-glibj
+define what to install @option{(zip|flat|both|none)} (default=@option{zip}).
+
+@item --with-escher=/path/to/escher
+
+enable build of the X/Escher peers, with
+the escher library at @file{/path/to/escher}, either
+in the form of a JAR file, or a directory
+containing the .class files of Escher.
+
+@item --enable-Werror
+
+whether to compile C code with @option{-Werror} which turns
+any compiler warning into a compilation failure
+(default=@option{no}).
+
+@item --with-gjdoc
+
+generate documentation using @command{gjdoc} (default=@option{no}).
+
+@item --with-jay
+
+Regenerate the parsers with @command{jay}, must be given the
+path to the @command{jay} executable
+
+@item --with-glibj-zip=ABS.PATH
+
+use prebuilt glibj.zip class library
+
+@item --with-ecj-jar=ABS.PATH
+
+specify jar file containing the Eclipse Java Compiler
+
+@item --with-gstreamer-peer
+
+build the experimental GStreamer peer (see @file{README.gstreamer})
+
+@end table
+
+For more flags run @command{configure --help}.
+
+@item Building
+
+Type @command{gmake} to build the package. There is no longer a
+dependency problem and we aim to keep it that way.
+
+@item Installation
+
+Type @command{gmake install} to install everything. This may require
+being the superuser. The default install path is /usr/local/classpath
+you may change it by giving @command{configure} the
+@option{--prefix=<path>} option.
+
+@end enumerate
+
+Report bugs to @email{classpath@@gnu.org} or much better to the
+GNU Classpath bug tracker at
+@uref{http://savannah.gnu.org/support/?func=addsupport&group=classpath,Savannah}.
+
+Happy Hacking!
+
+Once installed, GNU Classpath is ready to be used by any VM that supports
+using the official version of GNU Classpath. Simply ensure that
+@file{/usr/local/classpath/share/classpath} is in your @env{CLASSPATH} environment
+variable. You'll also have to set your @env{LD_LIBRARY_PATH}
+variable (or similar system configuration) to include the Classpath
+native libraries in @file{/usr/local/classpath/lib/classpath}.
+
+*NOTE* All example paths assume the default prefix is used with @command{configure}.
+If you don't know what this means then the examples are correct.
+
+@example
+LD_LIBRARY_PATH=/usr/local/classpath/lib/classpath
+CLASSPATH=/usr/local/classpath/share/classpath/glibj.zip:.
+export LD_LIBRARY_PATH CLASSPATH
+@end example
+
+More information about the VMs that use GNU Classpath can be found in the
+@file{README} file.
+
+@node Building and running with the X AWT peers, Misc. Notes, Installation, Top
+@comment node-name, next, previous, up
+@chapter Building and running with the X AWT peers
+
+In order build the X peers you need the Escher library version 0.2.3
+from @uref{http://escher.sourceforge.net,escher.sourceforge.net}.
+Unpack (and optionally build) the
+Escher library following the instructions in the downloaded
+package. Enable the build of the X peers by passing
+@option{--with-escher=/path/to/escher} to @command{configure} where @file{/path/to/escher}
+either points to a directory structure or JAR file containing the
+Escher classes. For Unix systems it is preferable to also build local
+socket support by passing @option{--enable-local-sockets}, which accelerates
+the network communication to the X server significantly.
+
+In this release you have to enable the X peers at runtime by
+setting the system property awt.toolkit=gnu.java.awt.peer.x.XToolkit
+by passing @option{-Dawt.toolkit=gnu.java.awt.peer.x.XToolkit} to the @command{java}
+command when running an application.
+
+@node Misc. Notes, Programming Standards, Building and running with the X AWT peers, Top
+@comment node-name, next, previous, up
+@chapter Misc. Notes
+
+Compilation is accomplished using a compiler's @@file syntax. For our
+part, we avoid placing make style dependencies as rules upon the
+compilation of a particular class file and leave this up to the Java
+compiler instead.
+
+The @option{--enable-maintainer-mode} option to @command{configure} currently does very
+little and shouldn't be used by ordinary developers or users anyway.
+
+On Windows machines, the native libraries do not currently build, but
+the Java bytecode library will. GCJ trunk is beginning to work under
+Cygwin.
+
+@node Programming Standards, Hacking Code, Misc. Notes, Top
+@comment node-name, next, previous, up
+@chapter Programming Standards
+
+For C source code, follow the
+@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}.
+The standards also specify various things like the install directory
+structure. These should be followed if possible.
+
+For Java source code, please follow the
+@uref{http://www.gnu.org/prep/standards/,GNU Coding
+Standards}, as much as possible. There are a number of exceptions to
+the GNU Coding Standards that we make for GNU Classpath as documented
+in this guide. We will hopefully be providing developers with a code
+formatting tool that closely matches those rules soon.
+
+For API documentation comments, please follow
+@uref{http://java.sun.com/products/jdk/javadoc/writingdoccomments.html,How
+to Write Doc Comments for Javadoc}. We would like to have a set of
+guidelines more tailored to GNU Classpath as part of this document.
+
+@menu
+* Source Code Style Guide::
+@end menu
+
+@node Source Code Style Guide, , Programming Standards, Programming Standards
+@comment node-name, next, previous, up
+@section Java source coding style
+
+Here is a list of some specific rules used when hacking on GNU
+Classpath java source code. We try to follow the standard
+@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}
+for that. There are lots of tools that can automatically generate it
+(although most tools assume C source, not java source code) and it
+seems as good a standard as any. There are a couple of exceptions and
+specific rules when hacking on GNU Classpath java source code however.
+The following lists how code is formatted (and some other code
+conventions):
+
+
+@itemize @bullet
+
+@item
+Java source files in GNU Classpath are encoded using UTF-8. However,
+ordinarily it is considered best practice to use the ASCII subset of
+UTF-8 and write non-ASCII characters using \u escapes.
+
+@item
+If possible, generate specific imports (expand) over java.io.* type
+imports. Order by gnu, java, javax, org. There must be one blank line
+between each group. The imports themselves are ordered alphabetically by
+package name. Classes and interfaces occur before sub-packages. The
+classes/interfaces are then also sorted alphabetical. Note that uppercase
+characters occur before lowercase characters.
+
+@example
+import gnu.java.awt.EmbeddedWindow;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+import javax.swing.JFrame;
+@end example
+
+@item
+Blank line after package statement, last import statement, classes,
+interfaces, methods.
+
+@item
+Opening/closing brace for class and method is at the same level of
+indent as the declaration. All other braces are indented and content
+between braces indented again.
+
+@item
+Since method definitions don't start in column zero anyway (since they
+are always inside a class definition), the rational for easy grepping
+for ``^method_def'' is mostly gone already. Since it is customary for
+almost everybody who writes java source code to put modifiers, return
+value and method name on the same line, we do too.
+
+@c fixme Another rational for always indenting the method definition is that it makes it a bit easier to distinguish methods in inner and anonymous classes from code in their enclosing context. NEED EXAMPLE.
+
+@item
+Implements and extends on separate lines, throws too. Indent extends,
+implements, throws. Apply deep indentation for method arguments.
+
+@c fixme Needs example.
+
+@item
+Don't add a space between a method or constructor call/definition and
+the open-bracket. This is because often the return value is an object on
+which you want to apply another method or from which you want to access
+a field.
+
+Don't write:
+
+@example
+ getToolkit ().createWindow (this);
+@end example
+
+But write:
+@example
+ getToolkit().createWindow(this);
+@end example
+
+@item
+The GNU Coding Standard it gives examples for almost every construct
+(if, switch, do, while, etc.). One missing is the try-catch construct
+which should be formatted as:
+
+@example
+ try
+ @{
+ //
+ @}
+ catch (...)
+ @{
+ //
+ @}
+@end example
+
+@item
+Wrap lines at 80 characters after assignments and before operators.
+Wrap always before extends, implements, throws, and labels.
+
+@item
+Don't put multiple class definitions in the same file, except for
+inner classes. File names (plus .java) and class names should be the
+same.
+
+@item
+Don't catch a @code{NullPointerException} as an alternative to simply
+checking for @code{null}. It is clearer and usually more efficient
+to simply write an explicit check.
+
+For instance, don't write:
+
+@example
+try
+ @{
+ return foo.doit();
+ @}
+catch (NullPointerException _)
+ @{
+ return 7;
+ @}
+@end example
+
+If your intent above is to check whether @samp{foo} is @code{null},
+instead write:
+
+@example
+if (foo == null)
+ return 7;
+else
+ return foo.doit();
+@end example
+
+@item
+Don't use redundant modifiers or other redundant constructs. Here is
+some sample code that shows various redundant items in comments:
+
+@example
+/*import java.lang.Integer;*/
+/*abstract*/ interface I @{
+ /*public abstract*/ void m();
+ /*public static final*/ int i = 1;
+ /*public static*/ class Inner @{@}
+@}
+final class C /*extends Object*/ @{
+ /*final*/ void m() @{@}
+@}
+@end example
+
+Note that Jikes will generate warnings for redundant modifiers if you
+use @code{+Predundant-modifiers} on the command line.
+
+@item
+Modifiers should be listed in the standard order recommended by the
+JLS@. Jikes will warn for this when given @code{+Pmodifier-order}.
+
+@item
+Because the output of different compilers differs, we have
+standardized on explicitly specifying @code{serialVersionUID} in
+@code{Serializable} classes in Classpath. This field should be
+declared as @code{private static final}. Note that a class may be
+@code{Serializable} without being explicitly marked as such, due to
+inheritance. For instance, all subclasses of @code{Throwable} need to
+have @code{serialVersionUID} declared.
+@c fixme index
+@c fixme link to the discussion
+
+@item
+Don't declare unchecked exceptions in the @code{throws} clause of a
+method. However, if throwing an unchecked exception is part of the
+method's API, you should mention it in the Javadoc. There is one
+important exception to this rule, which is that a stub method should
+be marked as throwing @code{gnu.classpath.NotImplementedException}.
+This will let our API comparison tools note that the method is not
+fully implemented.
+
+@item
+When overriding @code{Object.equals}, remember that @code{instanceof}
+filters out @code{null}, so an explicit check is not needed.
+
+@item
+When catching an exception and rethrowing a new exception you should
+``chain'' the Throwables. Don't just add the String representation of
+the caught exception.
+
+@example
+ try
+ @{
+ // Some code that can throw
+ @}
+ catch (IOException ioe)
+ @{
+ throw (SQLException) new SQLException("Database corrupt").setCause(ioe);
+ @}
+@end example
+
+@item
+Avoid the use of reserved words for identifiers. This is obvious with those
+such as @code{if} and @code{while} which have always been part of the Java
+programming language, but you should be careful about accidentally using
+words which have been added in later versions. Notable examples are
+@code{assert} (added in 1.4) and @code{enum} (added in 1.5). Jikes will warn
+of the use of the word @code{enum}, but, as it doesn't yet support the 1.5
+version of the language, it will still allow this usage through. A
+compiler which supports 1.5 (e.g.@: the Eclipse compiler, ecj) will simply
+fail to compile the offending source code.
+
+@c fixme Describe Anonymous classes (example).
+@c fixme Descibe Naming conventions when different from GNU Coding Standards.
+@c fixme Describee API doc javadoc tags used.
+
+@end itemize
+
+Some things are the same as in the normal GNU Coding Standards:
+
+@itemize @bullet
+
+@item
+Unnecessary braces can be removed, one line after an if, for, while as
+examples.
+
+@item
+Space around operators (assignment, logical, relational, bitwise,
+mathematical, shift).
+
+@item
+Blank line before single-line comments, multi-line comments, javadoc
+comments.
+
+@item
+If more than 2 blank lines, trim to 2.
+
+@item
+Don't keep commented out code. Just remove it or add a real comment
+describing what it used to do and why it is changed to the current
+implementation.
+@end itemize
+
+
+@node Hacking Code, Programming Goals, Programming Standards, Top
+@comment node-name, next, previous, up
+@chapter Working on the code, Working with others
+
+There are a lot of people helping out with GNU Classpath. Here are a
+couple of practical guidelines to make working together on the code
+smoother.
+
+The main thing is to always discuss what you are up to on the
+mailinglist. Making sure that everybody knows who is working on what
+is the most important thing to make sure we cooperate most
+effectively.
+
+We maintain a
+@uref{http://www.gnu.org/software/classpath/tasks.html,Task List}
+which contains items that you might want to work on.
+
+Before starting to work on something please make sure you read this
+complete guide. And discuss it on list to make sure your work does
+not duplicate or interferes with work someone else is already doing.
+Always make sure that you submit things that are your own work. And
+that you have paperwork on file (as stated in the requirements
+section) with the FSF authorizing the use of your additions.
+
+Technically the GNU Classpath project is hosted on
+@uref{http://savannah.gnu.org/,Savannah} a central point for
+development, distribution and maintenance of GNU Software. Here you
+will find the
+@uref{https://savannah.gnu.org/projects/classpath/,project page}, bug
+reports, pending patches, links to mailing lists, news items and CVS.
+
+You can find instructions on getting a CVS checkout for classpath at
+@uref{https://savannah.gnu.org/cvs/?group=classpath}.
+
+You don't have to get CVS commit write access to contribute, but it is
+sometimes more convenient to be able to add your changes directly to
+the project CVS@. Please contact the GNU Classpath savannah admins to
+arrange CVS access if you would like to have it.
+
+Make sure to be subscribed to the commit-classpath mailinglist while
+you are actively hacking on Classpath. You have to send patches (cvs
+diff -uN) to this list before committing.
+
+We really want to have a pretty open check-in policy. But this means
+that you should be extra careful if you check something in. If at all
+in doubt or if you think that something might need extra explaining
+since it is not completely obvious please make a little announcement
+about the change on the mailinglist. And if you do commit something
+without discussing it first and another GNU Classpath hackers asks for
+extra explanation or suggests to revert a certain commit then please
+reply to the request by explaining why something should be so or if
+you agree to revert it. (Just reverting immediately is OK without
+discussion, but then please don't mix it with other changes and please
+say so on list.)
+
+Patches that are already approved for libgcj or also OK for Classpath.
+(But you still have to send a patch/diff to the list.) All other
+patches require you to think whether or not they are really OK and
+non-controversial, or if you would like some feedback first on them
+before committing. We might get real commit rules in the future, for
+now use your own judgement, but be a bit conservative.
+
+Always contact the GNU Classpath maintainer before adding anything
+non-trivial that you didn't write yourself and that does not come from
+libgcj or from another known GNU Classpath or libgcj hacker. If you
+have been assigned to commit changes on behalf of another project or
+a company always make sure they come from people who have signed the
+papers for the FSF and/or fall under the arrangement your company made
+with the FSF for contributions. Mention in the ChangeLog who actually
+wrote the patch.
+
+Commits for completely unrelated changes they should be committed
+separately (especially when doing a formatting change and a logical
+change, do them in two separate commits). But do try to do a commit of
+as much things/files that are done at the same time which can
+logically be seen as part of the same change/cleanup etc.
+
+When the change fixes an important bug or adds nice new functionality
+please write a short entry for inclusion in the @file{NEWS} file. If it
+changes the VM interface you must mention that in both the @file{NEWS} file
+and the VM Integration Guide.
+
+All the ``rules'' are really meant to make sure that GNU Classpath
+will be maintainable in the long run and to give all the projects that
+are now using GNU Classpath an accurate view of the changes we make to
+the code and to see what changed when. If you think the requirements
+are ``unworkable'' please try it first for a couple of weeks. If you
+still feel the same after having some more experience with the project
+please feel free to bring up suggestions for improvements on the list.
+But don't just ignore the rules! Other hackers depend on them being
+followed to be the most productive they can be (given the above
+constraints).
+
+@menu
+* Branches::
+* Writing ChangeLogs::
+@end menu
+
+@node Branches, Writing ChangeLogs, Hacking Code, Hacking Code
+@comment node-name, next, previous, up
+@section Working with branches
+
+Sometimes it is necessary to create branch of the source for doing new
+work that is disruptive to the other hackers, or that needs new
+language or libraries not yet (easily) available.
+
+After discussing the need for a branch on the main mailinglist with
+the other hackers explaining the need of a branch and suggestion of
+the particular branch rules (what will be done on the branch, who will
+work on it, will there be different commit guidelines then for the
+mainline trunk and when is the branch estimated to be finished and
+merged back into the trunk) every GNU Classpath hacker with commit
+access should feel free to create a branch. There are however a couple
+of rules that every branch should follow:
+
+@itemize @bullet
+
+@item All branches ought to be documented in the developer wiki at
+@uref{http://developer.classpath.org/mediation/ClasspathBranches}, so
+we can know which are live, who owns them, and when they die.
+
+@item Some rules can be changed on a branch. In particular the branch
+maintainer can change the review requirements, and the requirement of
+keeping things building, testing, etc, can also be lifted. (These
+should be documented along with the branch name and owner if they
+differ from the trunk.)
+
+@item Requirements for patch email to classpath-patches and for paperwork
+@strong{cannot} be lifted. See @ref{Requirements}.
+
+@item A branch should not be seen as ``private'' or
+``may be completely broken''. It should be as much as possible
+something that you work on with a team (and if there is no team - yet
+- then there is nothing as bad as having a completely broken build to
+get others to help out). There can of course be occasional breakage, but
+it should be planned and explained. And you can certainly have a rule
+like ``please ask me before committing to this branch''.
+
+@item Merges from the trunk to a branch are at the discretion of the
+branch maintainer.
+
+@item A merge from a branch to the trunk is treated like any other patch.
+In particular, it has to go through review, it must satisfy all the
+trunk requirements (build, regression test, documentation).
+
+@item There may be additional timing requirements on merging a branch to
+the trunk depending on the release schedule, etc. For instance we may
+not want to do a branch merge just before a release.
+
+@end itemize
+
+If any of these rules are unclear please discuss on the list first.
+
+@menu
+* Writing ChangeLogs::
+@end menu
+
+@node Writing ChangeLogs, , Branches, Hacking Code
+@comment node-name, next, previous, up
+@section Documenting what changed when with ChangeLog entries
+
+To keep track of who did what when we keep an explicit ChangeLog entry
+together with the code. This mirrors the CVS commit messages and in
+general the ChangeLog entry is the same as the CVS commit message.
+This provides an easy way for people getting a (snapshot) release or
+without access to the CVS server to see what happened when. We do not
+generate the ChangeLog file automatically from the CVS server since
+that is not reliable.
+
+A good ChangeLog entry guideline can be found in the Guile Manual at
+@uref{http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html}.
+
+Here are some example to explain what should or shouldn't be in a
+ChangeLog entry (and the corresponding commit message):
+
+@itemize @bullet
+
+@item
+The first line of a ChangeLog entry should be:
+
+@example
+[date] <two spaces> [full name] <two spaces> [email-contact]
+@end example
+
+The second line should be blank. All other lines should be indented
+with one tab.
+
+@item
+Just state what was changed. Why something is done as it is done in
+the current code should be either stated in the code itself or be
+added to one of the documentation files (like this Hacking Guide).
+
+So don't write:
+
+@example
+ * java/awt/font/OpenType.java: Remove 'public static final'
+ from OpenType tags, reverting the change of 2003-08-11. See
+ Classpath discussion list of 2003-08-11.
+@end example
+
+Just state:
+
+@example
+ * java/awt/font/OpenType.java: Remove 'public static final' from
+ all member fields.
+@end example
+
+In this case the reason for the change was added to this guide.
+
+@item
+Just as with the normal code style guide, don't make lines longer then
+80 characters.
+
+@item
+Just as with comments in the code. The ChangeLog entry should be a
+full sentence, starting with a capital and ending with a period.
+
+@item
+Be precise in what changed, not the effect of the change (which should
+be clear from the code/patch). So don't write:
+
+@example
+ * java/io/ObjectOutputStream.java : Allow putFields be called more
+ than once.
+@end example
+
+But explain what changed and in which methods it was changed:
+
+@example
+ * java/io/ObjectOutputStream.java (putFields): Don't call
+ markFieldsWritten(). Only create new PutField when
+ currentPutField is null.
+ (writeFields): Call markFieldsWritten().
+@end example
+
+@end itemize
+
+The above are all just guidelines. We all appreciate the fact that writing
+ChangeLog entries, using a coding style that is not ``your own'' and the
+CVS, patch and diff tools do take some time to getting used to. So don't
+feel like you have to do it perfect right away or that contributions
+aren't welcome if they aren't ``perfect''. We all learn by doing and
+interacting with each other.
+
+
+@node Programming Goals, API Compatibility, Hacking Code, Top
+@comment node-name, next, previous, up
+@chapter Programming Goals
+
+When you write code for Classpath, write with three things in mind, and
+in the following order: portability, robustness, and efficiency.
+
+If efficiency breaks portability or robustness, then don't do it the
+efficient way. If robustness breaks portability, then bye-bye robust
+code. Of course, as a programmer you would probably like to find sneaky
+ways to get around the issue so that your code can be all three ... the
+following chapters will give some hints on how to do this.
+
+@menu
+* Portability:: Writing Portable Software
+* Utility Classes:: Reusing Software
+* Robustness:: Writing Robust Software
+* Java Efficiency:: Writing Efficient Java
+* Native Efficiency:: Writing Efficient JNI
+* Security:: Writing Secure Software
+@end menu
+
+@node Portability, Utility Classes, Programming Goals, Programming Goals
+@comment node-name, next, previous, up
+@section Portability
+
+The portability goal for Classpath is the following:
+
+@enumerate
+@item
+native functions for each platform that work across all VMs on that
+platform
+@item
+a single classfile set that work across all VMs on all platforms that
+support the native functions.
+@end enumerate
+
+For almost all of Classpath, this is a very feasible goal, using a
+combination of JNI and native interfaces. This is what you should shoot
+for. For those few places that require knowledge of the Virtual Machine
+beyond that provided by the Java standards, the VM Interface was designed.
+Read the Virtual Machine Integration Guide for more information.
+
+Right now the only supported platform is Linux. This will change as that
+version stabilizes and we begin the effort to port to many other
+platforms. Jikes RVM runs Classpath on AIX, and generally the Jikes
+RVM team fixes Classpath to work on that platform.
+
+@node Utility Classes, Robustness, Portability, Programming Goals
+@comment node-name, next, previous, up
+@section Utility Classes
+
+At the moment, we are not very good at reuse of the JNI code. There
+have been some attempts, called @dfn{libclasspath}, to
+create generally useful utility classes. The utility classes are in
+the directory @file{native/jni/classpath} and they are mostly declared
+in @file{native/jni/classpath/jcl.h}. These utility classes are
+currently only discussed in @ref{Robustness} and in @ref{Native
+Efficiency}.
+
+There are more utility classes available that could be factored out if
+a volunteer wants something nice to hack on. The error reporting and
+exception throwing functions and macros in
+@file{native/jni/gtk-peer/gthread-jni.c} might be good
+candidates for reuse. There are also some generally useful utility
+functions in @file{gnu_java_awt_peer_gtk_GtkMainThread.c} that could
+be split out and put into libclasspath.
+
+@node Robustness, Java Efficiency, Utility Classes, Programming Goals
+@comment node-name, next, previous, up
+@section Robustness
+
+Native code is very easy to make non-robust. (That's one reason Java is
+so much better!) Here are a few hints to make your native code more
+robust.
+
+Always check return values for standard functions. It's sometimes easy
+to forget to check that malloc() return for an error. Don't make that
+mistake. (In fact, use JCL_malloc() in the jcl library instead--it will
+check the return value and throw an exception if necessary.)
+
+Always check the return values of JNI functions, or call
+@code{ExceptionOccurred} to check whether an error occurred. You must
+do this after @emph{every} JNI call. JNI does not work well when an
+exception has been raised, and can have unpredictable behavior.
+
+Throw exceptions using @code{JCL_ThrowException}. This guarantees that if
+something is seriously wrong, the exception text will at least get out
+somewhere (even if it is stderr).
+
+Check for null values of @code{jclass}es before you send them to JNI functions.
+JNI does not behave nicely when you pass a null class to it: it
+terminates Java with a "JNI Panic."
+
+In general, try to use functions in @file{native/jni/classpath/jcl.h}. They
+check exceptions and return values and throw appropriate exceptions.
+
+@node Java Efficiency, Native Efficiency, Robustness, Programming Goals
+@comment node-name, next, previous, up
+@section Java Efficiency
+
+For methods which explicitly throw a @code{NullPointerException} when an
+argument is passed which is null, per a Sun specification, do not write
+code like:
+
+@example
+int
+strlen (String foo) throws NullPointerException
+@{
+ if (foo == null)
+ throw new NullPointerException ("foo is null");
+ return foo.length ();
+@}
+@end example
+
+Instead, the code should be written as:
+
+@example
+int
+strlen (String foo) throws NullPointerException
+@{
+ return foo.length ();
+@}
+@end example
+
+Explicitly comparing foo to null is unnecessary, as the virtual machine
+will throw a NullPointerException when length() is invoked. Classpath
+is designed to be as fast as possible -- every optimization, no matter
+how small, is important.
+
+@node Native Efficiency, Security, Java Efficiency, Programming Goals
+@comment node-name, next, previous, up
+@section Native Efficiency
+
+You might think that using native methods all over the place would give
+our implementation of Java speed, speed, blinding speed. You'd be
+thinking wrong. Would you believe me if I told you that an empty
+@emph{interpreted} Java method is typically about three and a half times
+@emph{faster} than the equivalent native method?
+
+Bottom line: JNI is overhead incarnate. In Sun's implementation, even
+the JNI functions you use once you get into Java are slow.
+
+A final problem is efficiency of native code when it comes to things
+like method calls, fields, finding classes, etc. Generally you should
+cache things like that in static C variables if you're going to use them
+over and over again. GetMethodID(), GetFieldID(), and FindClass() are
+@emph{slow}. Classpath provides utility libraries for caching methodIDs
+and fieldIDs in @file{native/jni/classpath/jnilink.h}. Other native data can
+be cached between method calls using functions found in
+@file{native/jni/classpath/native_state.h}.
+
+Here are a few tips on writing native code efficiently:
+
+Make as few native method calls as possible. Note that this is not the
+same thing as doing less in native method calls; it just means that, if
+given the choice between calling two native methods and writing a single
+native method that does the job of both, it will usually be better to
+write the single native method. You can even call the other two native
+methods directly from your native code and not incur the overhead of a
+method call from Java to C.
+
+Cache @code{jmethodID}s and @code{jfieldID}s wherever you can. String
+lookups are
+expensive. The best way to do this is to use the
+@file{native/jni/classpath/jnilink.h}
+library. It will ensure that @code{jmethodID}s are always valid, even if the
+class is unloaded at some point. In 1.1, jnilink simply caches a
+@code{NewGlobalRef()} to the method's underlying class; however, when 1.2 comes
+along, it will use a weak reference to allow the class to be unloaded
+and then re-resolve the @code{jmethodID} the next time it is used.
+
+Cache classes that you need to access often. jnilink will help with
+this as well. The issue here is the same as the methodID and fieldID
+issue--how to make certain the class reference remains valid.
+
+If you need to associate native C data with your class, use Paul
+Fisher's native_state library (NSA). It will allow you to get and set
+state fairly efficiently. Japhar now supports this library, making
+native state get and set calls as fast as accessing a C variable
+directly.
+
+If you are using native libraries defined outside of Classpath, then
+these should be wrapped by a Classpath function instead and defined
+within a library of their own. This makes porting Classpath's native
+libraries to new platforms easier in the long run. It would be nice
+to be able to use Mozilla's NSPR or Apache's APR, as these libraries
+are already ported to numerous systems and provide all the necessary
+system functions as well.
+
+@node Security, , Native Efficiency, Programming Goals
+@comment node-name, next, previous, up
+@section Security
+
+Security is such a huge topic it probably deserves its own chapter.
+Most of the current code needs to be audited for security to ensure
+all of the proper security checks are in place within the Java
+platform, but also to verify that native code is reasonably secure and
+avoids common pitfalls, buffer overflows, etc. A good source for
+information on secure programming is the excellent HOWTO by David
+Wheeler,
+@uref{http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html,Secure
+Programming for Linux and Unix HOWTO}.
+
+@node API Compatibility, Specification Sources, Programming Goals, Top
+@comment node-name, next, previous, up
+@chapter API Compatibility
+
+@menu
+* Serialization:: Serialization
+* Deprecated Methods:: Deprecated methods
+@end menu
+
+@node Serialization, Deprecated Methods, API Compatibility, API Compatibility
+@comment node-name, next, previous, up
+@section Serialization
+
+Sun has produced documentation concerning much of the information
+needed to make Classpath serializable compatible with Sun
+implementations. Part of doing this is to make sure that every class
+that is Serializable actually defines a field named serialVersionUID
+with a value that matches the output of serialver on Sun's
+implementation. The reason for doing this is below.
+
+If a class has a field (of any accessibility) named serialVersionUID
+of type long, that is what serialver uses. Otherwise it computes a
+value using some sort of hash function on the names of all method
+signatures in the .class file. The fact that different compilers
+create different synthetic method signatures, such as access$0() if an
+inner class needs access to a private member of an enclosing class,
+make it impossible for two distinct compilers to reliably generate the
+same serial #, because their .class files differ. However, once you
+have a .class file, its serial # is unique, and the computation will
+give the same result no matter what platform you execute on.
+
+Serialization compatibility can be tested using tools provided with
+@uref{http://www.kaffe.org/~stuart/japi/,Japitools}. These
+tools can test binary serialization compatibility and also provide
+information about unknown serialized formats by writing these in XML
+instead. Japitools is also the primary means of checking API
+compatibility for GNU Classpath with Sun's Java Platform.
+
+@node Deprecated Methods, , Serialization, API Compatibility
+@comment node-name, next, previous, up
+@section Deprecated Methods
+
+Sun has a practice of creating ``alias'' methods, where a public or
+protected method is deprecated in favor of a new one that has the same
+function but a different name. Sun's reasons for doing this vary; as
+an example, the original name may contain a spelling error or it may
+not follow Java naming conventions.
+
+Unfortunately, this practice complicates class library code that calls
+these aliased methods. Library code must still call the deprecated
+method so that old client code that overrides it continues to work.
+But library code must also call the new version, because new code is
+expected to override the new method.
+
+The correct way to handle this (and the way Sun does it) may seem
+counterintuitive because it means that new code is less efficient than
+old code: the new method must call the deprecated method, and throughout
+the library code calls to the old method must be replaced with calls to
+the new one.
+
+Take the example of a newly-written container laying out a component and
+wanting to know its preferred size. The Component class has a
+deprecated preferredSize method and a new method, getPreferredSize.
+Assume that the container is laying out an old component that overrides
+preferredSize and a new component that overrides getPreferredSize. If
+the container calls getPreferredSize and the default implementation of
+getPreferredSize calls preferredSize, then the old component will have
+its preferredSize method called and new code will have its
+getPreferredSize method called.
+
+Even using this calling scheme, an old component may still be laid out
+improperly if it implements a method, getPreferredSize, that has the
+same signature as the new Component.getPreferredSize. But that is a
+general problem -- adding new public or protected methods to a
+widely-used class that calls those methods internally is risky, because
+existing client code may have already declared methods with the same
+signature.
+
+The solution may still seem counterintuitive -- why not have the
+deprecated method call the new method, then have the library always call
+the old method? One problem with that, using the preferred size example
+again, is that new containers, which will use the non-deprecated
+getPreferredSize, will not get the preferred size of old components.
+
+@node Specification Sources, Naming Conventions, API Compatibility, Top
+@comment node-name, next, previous, up
+@chapter Specification Sources
+
+There are a number of specification sources to use when working on
+Classpath. In general, the only place you'll find your classes
+specified is in the JavaDoc documentation or possibly in the
+corresponding white paper. In the case of java.lang, java.io and
+java.util, you should look at the Java Language Specification.
+
+Here, however, is a list of specs, in order of canonicality:
+
+@enumerate
+@item
+@uref{http://java.sun.com/docs/books/jls/clarify.html,Clarifications and Amendments to the JLS - 1.1}
+@item
+@uref{http://java.sun.com/docs/books/jls/html/1.1Update.html,JLS Updates
+- 1.1}
+@item
+@uref{http://java.sun.com/docs/books/jls/html/index.html,The 1.0 JLS}
+@item
+@uref{http://java.sun.com/docs/books/vmspec/index.html,JVM spec - 1.1}
+@item
+@uref{http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/jniTOC.doc.html,JNI spec - 1.1}
+@item
+@uref{http://java.sun.com/products/jdk/1.1/docs/api/packages.html,Sun's javadoc - 1.1}
+(since Sun's is the reference implementation, the javadoc is
+documentation for the Java platform itself.)
+@item
+@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jvmdi/jvmdi.html,JVMDI spec - 1.2},
+@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html,JNI spec - 1.2}
+(sometimes gives clues about unspecified things in 1.1; if
+it was not specified accurately in 1.1, then use the spec
+for 1.2; also, we are using JVMDI in this project.)
+@item
+@uref{http://java.sun.com/products/jdk/1.2/docs/api/frame.html,Sun's javadoc - 1.2}
+(sometimes gives clues about unspecified things in 1.1; if
+it was not specified accurately in 1.1, then use the spec
+for 1.2)
+@item
+@uref{http://developer.java.sun.com/developer/bugParade/index.html,The
+Bug Parade}: I have obtained a ton of useful information about how
+things do work and how they *should* work from the Bug Parade just by
+searching for related bugs. The submitters are very careful about their
+use of the spec. And if something is unspecified, usually you can find
+a request for specification or a response indicating how Sun thinks it
+should be specified here.
+@end enumerate
+
+You'll notice that in this document, white papers and specification
+papers are more canonical than the JavaDoc documentation. This is true
+in general.
+
+
+@node Naming Conventions, Character Conversions, Specification Sources, Top
+@comment node-name, next, previous, up
+@chapter Directory and File Naming Conventions
+
+The Classpath directory structure is laid out in the following manner:
+
+@example
+classpath
+ |
+ |---->java
+ | |
+ | |-->awt
+ | |-->io
+ | |-->lang
+ | |-->util
+ | | |
+ | | |--->zip
+ | | |--->jar
+ | |-->net
+ | |-->etc
+ |
+ |---->gnu
+ | |
+ | |-->java
+ | |
+ | |-->awt
+ | |-->lang
+ | |-->util
+ | | |
+ | | |-->zip
+ | |-->etc
+ |
+ |---->native
+ |
+ |-->jni
+ | |-->classpath
+ | |-->gtk-peer
+ | |-->java-io
+ | |-->java-lang
+ | |-->java-net
+ | |-->java-util
+ | |-->etc
+ |-->cni
+
+@end example
+
+Here is a brief description of the toplevel directories and their contents.
+
+@table @b
+
+@item java
+Contains the source code to the Java packages that make up the core
+class library. Because this is the public interface to Java, it is
+important that the public classes, interfaces, methods, and variables
+are exactly the same as specified in Sun's documentation. The directory
+structure is laid out just like the java package names. For example,
+the class java.util.zip would be in the directory java-util.
+
+@item gnu/java
+Internal classes (roughly analogous to Sun's sun.* classes) should go
+under the @file{gnu/java} directory. Classes related to a particular public
+Java package should go in a directory named like that package. For
+example, classes related to java.util.zip should go under a directory
+@file{gnu/java/util/zip}. Sub-packages under the main package name are
+allowed. For classes spanning multiple public Java packages, pick an
+appropriate name and see what everybody else thinks.
+
+@item native
+This directory holds native code needed by the public Java packages.
+Each package has its own subdirectory, which is the ``flattened'' name
+of the package. For example, native method implementations for
+java.util.zip should go in @file{native/classpath/java-util}. Classpath
+actually includes an all Java version of the zip classes, so no native
+code is required.
+
+@end table
+
+Each person working on a package get's his or her own ``directory
+space'' underneath each of the toplevel directories. In addition to the
+general guidelines above, the following standards should be followed:
+
+@itemize @bullet
+
+@item
+Classes that need to load native code should load a library with the
+same name as the flattened package name, with all hyphens removed. For
+example, the native library name specified in LoadLibrary for
+java-util would be ``javautil''.
+
+@item
+Each package has its own shared library for native code (if any).
+
+@item
+The main native method implementation for a given method in class should
+go in a file with the same name as the class with a ``.c'' extension.
+For example, the JNI implementation of the native methods in
+java.net.InetAddress would go in @file{native/jni/java-net/InetAddress.c}.
+``Internal'' native functions called from the main native method can
+reside in files of any name.
+@end itemize
+
+@node Character Conversions, Localization, Naming Conventions, Top
+@comment node-name, next, previous, up
+@chapter Character Conversions
+
+Java uses the Unicode character encoding system internally. This is a
+sixteen bit (two byte) collection of characters encompassing most of the
+world's written languages. However, Java programs must often deal with
+outside interfaces that are byte (eight bit) oriented. For example, a
+Unix file, a stream of data from a network socket, etc. Beginning with
+Java 1.1, the @code{Reader} and @code{Writer} classes provide functionality
+for dealing with character oriented streams. The classes
+@code{InputStreamReader} and @code{OutputStreamWriter} bridge the gap
+between byte streams and character streams by converting bytes to
+Unicode characters and vice versa.
+
+In Classpath, @code{InputStreamReader} and @code{OutputStreamWriter}
+rely on an internal class called @code{gnu.java.io.EncodingManager} to load
+translators that perform the actual conversion. There are two types of
+converters, encoders and decoders. Encoders are subclasses of
+@code{gnu.java.io.encoder.Encoder}. This type of converter takes a Java
+(Unicode) character stream or buffer and converts it to bytes using
+a specified encoding scheme. Decoders are a subclass of
+@code{gnu.java.io.decoder.Decoder}. This type of converter takes a
+byte stream or buffer and converts it to Unicode characters. The
+@code{Encoder} and @code{Decoder} classes are subclasses of
+@code{Writer} and @code{Reader} respectively, and so can be used in
+contexts that require character streams, but the Classpath implementation
+currently does not make use of them in this fashion.
+
+The @code{EncodingManager} class searches for requested encoders and
+decoders by name. Since encoders and decoders are separate in Classpath,
+it is possible to have a decoder without an encoder for a particular
+encoding scheme, or vice versa. @code{EncodingManager} searches the
+package path specified by the @code{file.encoding.pkg} property. The
+name of the encoder or decoder is appended to the search path to
+produce the required class name. Note that @code{EncodingManager} knows
+about the default system encoding scheme, which it retrieves from the
+system property @code{file.encoding}, and it will return the proper
+translator for the default encoding if no scheme is specified. Also, the
+Classpath standard translator library, which is the @code{gnu.java.io} package,
+is automatically appended to the end of the path.
+
+For efficiency, @code{EncodingManager} maintains a cache of translators
+that it has loaded. This eliminates the need to search for a commonly
+used translator each time it is requested.
+
+Finally, @code{EncodingManager} supports aliasing of encoding scheme names.
+For example, the ISO Latin-1 encoding scheme can be referred to as
+''8859_1'' or ''ISO-8859-1''. @code{EncodingManager} searches for
+aliases by looking for the existence of a system property called
+@code{gnu.java.io.encoding_scheme_alias.<encoding name>}. If such a
+property exists. The value of that property is assumed to be the
+canonical name of the encoding scheme, and a translator with that name is
+looked up instead of one with the original name.
+
+Here is an example of how @code{EncodingManager} works. A class requests
+a decoder for the ''UTF-8'' encoding scheme by calling
+@code{EncodingManager.getDecoder("UTF-8")}. First, an alias is searched
+for by looking for the system property
+@code{gnu.java.io.encoding_scheme_alias.UTF-8}. In our example, this
+property exists and has the value ''UTF8''. That is the actual
+decoder that will be searched for. Next, @code{EncodingManager} looks
+in its cache for this translator. Assuming it does not find it, it
+searches the translator path, which is this example consists only of
+the default @code{gnu.java.io}. The ''decoder'' package name is
+appended since we are looking for a decoder. (''encoder'' would be
+used if we were looking for an encoder). Then name name of the translator
+is appended. So @code{EncodingManager} attempts to load a translator
+class called @code{gnu.java.io.decoder.UTF8}. If that class is found,
+an instance of it is returned. If it is not found, a
+@code{UnsupportedEncodingException}.
+
+To write a new translator, it is only necessary to subclass
+@code{Encoder} and/or @code{Decoder}. Only a handful of abstract
+methods need to be implemented. In general, no methods need to be
+overridden. The needed methods calculate the number of bytes/chars
+that the translation will generate, convert buffers to/from bytes,
+and read/write a requested number of characters to/from a stream.
+
+Many common encoding schemes use only eight bits to encode characters.
+Writing a translator for these encodings is very easy. There are
+abstract translator classes @code{gnu.java.io.decode.DecoderEightBitLookup}
+and @code{gnu.java.io.encode.EncoderEightBitLookup}. These classes
+implement all of the necessary methods. All that is necessary to
+create a lookup table array that maps bytes to Unicode characters and
+set the class variable @code{lookup_table} equal to it in a static
+initializer. Also, a single constructor that takes an appropriate
+stream as an argument must be supplied. These translators are
+exceptionally easy to create and there are several of them supplied
+in the Classpath distribution.
+
+Writing multi-byte or variable-byte encodings is more difficult, but
+often not especially challenging. The Classpath distribution ships with
+translators for the UTF8 encoding scheme which uses from one to three
+bytes to encode Unicode characters. This can serve as an example of
+how to write such a translator.
+
+Many more translators are needed. All major character encodings should
+eventually be supported.
+
+@node Localization, , Character Conversions, Top
+@comment node-name, next, previous, up
+@chapter Localization
+
+There are many parts of the Java standard runtime library that must
+be customized to the particular locale the program is being run in.
+These include the parsing and display of dates, times, and numbers;
+sorting words alphabetically; breaking sentences into words, etc.
+In general, Classpath uses general classes for performing these tasks,
+and customizes their behavior with configuration data specific to a
+given locale.
+
+@menu
+* String Collation:: Sorting strings in different locales
+* Break Iteration:: Breaking up text into words, sentences, and lines
+* Date Formatting and Parsing:: Locale specific date handling
+* Decimal/Currency Formatting and Parsing:: Local specific number handling
+@end menu
+
+In Classpath, all locale specific data is stored in a
+@code{ListResourceBundle} class in the package @code{gnu/java/locale}.
+The basename of the bundle is @code{LocaleInformation}. See the
+documentation for the @code{java.util.ResourceBundle} class for details
+on how the specific locale classes should be named.
+
+@code{ListResourceBundle}'s are used instead of
+@code{PropertyResourceBundle}'s because data more complex than simple
+strings need to be provided to configure certain Classpath components.
+Because @code{ListResourceBundle} allows an arbitrary Java object to
+be associated with a given configuration option, it provides the
+needed flexibility to accomodate Classpath's needs.
+
+Each Java library component that can be localized requires that certain
+configuration options be specified in the resource bundle for it. It is
+important that each and every option be supplied for a specific
+component or a critical runtime error will most likely result.
+
+As a standard, each option should be assigned a name that is a string.
+If the value is stored in a class or instance variable, then the option
+should name should have the name name as the variable. Also, the value
+associated with each option should be a Java object with the same name
+as the option name (unless a simple scalar value is used). Here is an
+example:
+
+A class loads a value for the @code{format_string} variable from the
+resource bundle in the specified locale. Here is the code in the
+library class:
+
+@example
+ ListResourceBundle lrb =
+ ListResourceBundle.getBundle ("gnu/java/locale/LocaleInformation", locale);
+ String format_string = lrb.getString ("format_string");
+@end example
+
+In the actual resource bundle class, here is how the configuration option
+gets defined:
+
+@example
+/**
+ * This is the format string used for displaying values
+ */
+private static final String format_string = "%s %d %i";
+
+private static final Object[][] contents =
+@{
+ @{ "format_string", format_string @}
+@};
+@end example
+
+Note that each variable should be @code{private}, @code{final}, and
+@code{static}. Each variable should also have a description of what it
+does as a documentation comment. The @code{getContents()} method returns
+the @code{contents} array.
+
+There are many functional areas of the standard class library that are
+configured using this mechanism. A given locale does not need to support
+each functional area. But if a functional area is supported, then all
+of the specified entries for that area must be supplied. In order to
+determine which functional areas are supported, there is a special key
+that is queried by the affected class or classes. If this key exists,
+and has a value that is a @code{Boolean} object wrappering the
+@code{true} value, then full support is assumed. Otherwise it is
+assumed that no support exists for this functional area. Every class
+using resources for configuration must use this scheme and define a special
+scheme that indicates the functional area is supported. Simply checking
+for the resource bundle's existence is not sufficient to ensure that a
+given functional area is supported.
+
+The following sections define the functional areas that use resources
+for locale specific configuration in GNU Classpath. Please refer to the
+documentation for the classes mentioned for details on how these values
+are used. You may also wish to look at the source file for
+@file{gnu/java/locale/LocaleInformation_en} as an example.
+
+@node String Collation, Break Iteration, Localization, Localization
+@comment node-name, next, previous, up
+@section String Collation
+
+Collation involves the sorting of strings. The Java class library provides
+a public class called @code{java.text.RuleBasedCollator} that performs
+sorting based on a set of sorting rules.
+
+@itemize @bullet
+@item RuleBasedCollator - A @code{Boolean} wrappering @code{true} to indicate
+that this functional area is supported.
+@item collation_rules - The rules the specify how string collation is to
+be performed.
+@end itemize
+
+Note that some languages might be too complex for @code{RuleBasedCollator}
+to handle. In this case an entirely new class might need to be written in
+lieu of defining this rule string.
+
+@node Break Iteration, Date Formatting and Parsing, String Collation, Localization
+@comment node-name, next, previous, up
+@section Break Iteration
+
+The class @code{java.text.BreakIterator} breaks text into words, sentences,
+and lines. It is configured with the following resource bundle entries:
+
+@itemize @bullet
+@item BreakIterator - A @code{Boolean} wrappering @code{true} to indicate
+that this functional area is supported.
+@item word_breaks - A @code{String} array of word break character sequences.
+@item sentence_breaks - A @code{String} array of sentence break character
+sequences.
+@item line_breaks - A @code{String} array of line break character sequences.
+@end itemize
+
+@node Date Formatting and Parsing, Decimal/Currency Formatting and Parsing, Break Iteration, Localization
+@comment node-name, next, previous, up
+@section Date Formatting and Parsing
+
+Date formatting and parsing is handled by the
+@code{java.text.SimpleDateFormat} class in most locales. This class is
+configured by attaching an instance of the @code{java.text.DateFormatSymbols}
+class. That class simply reads properties from our locale specific
+resource bundle. The following items are required (refer to the
+documentation of the @code{java.text.DateFormatSymbols} class for details
+io what the actual values should be):
+
+@itemize @bullet
+@item DateFormatSymbols - A @code{Boolean} wrappering @code{true} to indicate
+that this functional area is supported.
+@item months - A @code{String} array of month names.
+@item shortMonths - A @code{String} array of abbreviated month names.
+@item weekdays - A @code{String} array of weekday names.
+@item shortWeekdays - A @code{String} array of abbreviated weekday names.
+@item ampms - A @code{String} array containing AM/PM names.
+@item eras - A @code{String} array containing era (i.e., BC/AD) names.
+@item zoneStrings - An array of information about valid timezones for this
+locale.
+@item localPatternChars - A @code{String} defining date/time pattern symbols.
+@item shortDateFormat - The format string for dates used by
+@code{DateFormat.SHORT}
+@item mediumDateFormat - The format string for dates used by
+@code{DateFormat.MEDIUM}
+@item longDateFormat - The format string for dates used by
+@code{DateFormat.LONG}
+@item fullDateFormat - The format string for dates used by
+@code{DateFormat.FULL}
+@item shortTimeFormat - The format string for times used by
+@code{DateFormat.SHORT}
+@item mediumTimeFormat - The format string for times used by
+@code{DateFormat.MEDIUM}
+@item longTimeFormat - The format string for times used by
+@code{DateFormat.LONG}
+@item fullTimeFormat - The format string for times used by
+@code{DateFormat.FULL}
+@end itemize
+
+Note that it may not be possible to use this mechanism for all locales.
+In those cases a special purpose class may need to be written to handle
+date/time processing.
+
+@node Decimal/Currency Formatting and Parsing, , Date Formatting and Parsing, Localization
+@comment node-name, next, previous, up
+@section Decimal/Currency Formatting and Parsing
+
+@code{NumberFormat} is an abstract class for formatting and parsing numbers.
+The class @code{DecimalFormat} provides a concrete subclass that handles
+this is in a locale independent manner. As with @code{SimpleDateFormat},
+this class gets information on how to format numbers from a class that
+wrappers a collection of locale specific formatting values. In this case,
+the class is @code{DecimalFormatSymbols}. That class reads its default
+values for a locale from the resource bundle. The required entries are:
+
+@itemize @bullet
+@item DecimalFormatSymbols - A @code{Boolean} wrappering @code{true} to
+indicate that this functional area is supported.
+@item currencySymbol - The string representing the local currency.
+@item intlCurrencySymbol - The string representing the local currency in an
+international context.
+@item decimalSeparator - The character to use as the decimal point as a
+@code{String}.
+@item digit - The character used to represent digits in a format string,
+as a @code{String}.
+@item exponential - The char used to represent the exponent separator of a
+number written in scientific notation, as a @code{String}.
+@item groupingSeparator - The character used to separate groups of numbers
+in a large number, such as the ``,'' separator for thousands in the US, as
+a @code{String}.
+@item infinity - The string representing infinity.
+@item NaN - The string representing the Java not a number value.
+@item minusSign - The character representing the negative sign, as a
+@code{String}.
+@item monetarySeparator - The decimal point used in currency values, as a
+@code{String}.
+@item patternSeparator - The character used to separate positive and
+negative format patterns, as a @code{String}.
+@item percent - The percent sign, as a @code{String}.
+@item perMill - The per mille sign, as a @code{String}.
+@item zeroDigit - The character representing the digit zero, as a @code{String}.
+@end itemize
+
+Note that several of these values are an individual character. These should
+be wrappered in a @code{String} at character position 0, not in a
+@code{Character} object.
+
+@bye
+