hacking.texinfo change committed

[Steven Augart]

This is nearly identical to the proposed patch I posted here on May 26:

2004-06-04  Steven Augart  <address@hidden>

        * doc/hacking.texinfo: Formatting fixes.
        (Utility Classes) New TeXinfo node.

Index: doc/hacking.texinfo
===================================================================
RCS file: /cvsroot/classpath/classpath/doc/hacking.texinfo,v
retrieving revision 1.27
diff -I*.class -u -r1.27 hacking.texinfo
--- doc/hacking.texinfo 3 Jun 2004 15:25:25 -0000       1.27
+++ doc/hacking.texinfo 4 Jun 2004 20:51:43 -0000
@@ -11,7 +11,7 @@
 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 Free Software Foundation, 
Inc.
+Copyright (C) 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
 
 @ifnotplaintext
 @dircategory GNU Libraries
@@ -88,6 +88,7 @@
 Programming Goals
 
 * Portability::                 Writing Portable Software                
+* Utility Classes::             Reusing Software
 * Robustness::                  Writing Robust Software               
 * Java Efficiency::             Writing Efficient Java            
 * Native Efficiency::           Writing Efficient JNI          
@@ -140,10 +141,10 @@
 
 @itemize @bullet
 @item
address@hidden under any circumstances refer to proprietary code while
address@hidden 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 @samp{src.zip} file
+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
@@ -157,7 +158,7 @@
 someday in court.  Please don't let that happen.
 
 @item
address@hidden decompile proprietary class library implementations.}  While
address@hidden 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
@@ -256,7 +257,7 @@
 BSDs.
 
 @item
-Other UNIX-like operating systems.
+Other Unix-like operating systems.
 
 @item
 Platforms which currently have no Java support at all.
@@ -389,7 +390,7 @@
 to build shared libraries.
 
 @item m4
-The free GNU replacement for the standard UNIX macro processor.
+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.
@@ -765,8 +766,8 @@
 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 NEWS file.  If it
-changes the VM interface you must mention that in both the NEWS file
+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
@@ -887,13 +888,14 @@
 
 @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
 
address@hidden Portability, Robustness, Programming Goals, Programming Goals
address@hidden Portability, Utility Classes, Programming Goals, Programming 
Goals
 @comment node-name, next, previous, up
 @section Portability
 
@@ -916,9 +918,30 @@
 
 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.
+platforms.  Jikes RVM runs Classpath on AIX, and generally the Jikes
+RVM team fixes Classpath to work on that platform. 
 
address@hidden Robustness, Java Efficiency, Portability, Programming Goals
address@hidden Utility Classes, Robustness, Portability, Programming Goals
address@hidden  node-name,  next,  previous,  up
address@hidden 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
address@hidden/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.
+
address@hidden Robustness, Java Efficiency, Utility Classes, Programming Goals
 @comment node-name, next, previous, up
 @section Robustness
 
@@ -936,22 +959,22 @@
 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 JCL_ThrowException.  This guarantees that if
+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 jclasses before you send them to JNI functions.
+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 native/jni/classpath/jcl.h.  They
+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 NullPointerException when an
+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:
 
@@ -997,10 +1020,10 @@
 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
-*slow*.  Classpath provides utility libraries for caching methodIDs
-and fieldIDs in native/jni/classpath/jnilink.h.  Other native data can
address@hidden  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
-native/jni/classpath/native_state.h.
address@hidden/jni/classpath/native_state.h}.
 
 Here are a few tips on writing native code efficiently:
 
@@ -1012,13 +1035,15 @@
 methods directly from your native code and not incur the overhead of a
 method call from Java to C.
 
-Cache methodIDs and fieldIDs wherever you can.  String lookups are
-expensive.  The best way to do this is to use the 
native/jni/classpath/jnilink.h
-library.  It will ensure that jmethodIDs are always valid, even if the
+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 
address@hidden/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
-NewGlobalRef() to the method's underlying class; however, when 1.2 comes
address@hidden()} 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 jmethodID the next time it is used.
+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
@@ -1250,10 +1275,10 @@
 
 @item gnu/java
 Internal classes (roughly analogous to Sun's sun.* classes) should go
-under the gnu/java directory.  Classes related to a particular public
+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
-gnu/java/util/zip.  Sub-packages under the main package name are
address@hidden/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.
 
@@ -1261,7 +1286,7 @@
 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 native/classpath/java-util.  Classpath
+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.
 
@@ -1286,7 +1311,7 @@
 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 native/jni/java-net/InetAddress.c.
+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
@@ -1483,7 +1508,7 @@
 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 
address@hidden/java/locale/LocaleInformation_en} as an example.
address@hidden/java/locale/LocaleInformation_en} as an example.
 
 @node String Collation, Break Iteration, Localization, Localization
 @comment node-name, next, previous, up