hacking.texinfo

linux下建立JAVA虚拟机的源码KAFFE

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.  But finishing, polishing up, documenting, testing and
debugging current functionality is of higher priority then adding new
functionality.

@node Needed Tools and Libraries, Programming Standards, 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.  Although 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 GCC 3.3+ (plus a free VM from the list above
and the libraries listed below) is needed.  The other tools are only
needed when working directly on the CVS version.

@itemize @bullet
@item
GCC 3.3+
@item
CVS 1.11+
@item
automake 1.7+
@item
autoconf 2.59+
@item
libtool 1.4.2+
@item
GNU m4 1.4
@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}.  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 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 gcj version 3.3 or higher.  If
that version is not available for your platform you can try the
@uref{http://www.jikes.org/, jikes compiler}.  We try to keep all code
compilable with both gcj and jikes at all times.

@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 Makefile.in files from Makefile.am
files.  The Makefile.in is turned into a Makefile by autoconf.  Why
use this?  Because it automatically generates every makefile target
you would ever want (clean, install, 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 compiling the native AWT libraries you need to have the following
libraries installed:

@table @b
@item GTK+ 2.2.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.
@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 easiest.  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 GNU jaxp
Can be found in @file{external/jaxp}.  Provides javax.xml, org.w3c and
org.xml packages.  Upstream is
@uref{http://www.gnu.org/software/classpathx/,GNU ClasspathX}.

@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 Programming Standards, Hacking Code, Needed Tools and Libraries, 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 itmakes it a bit easier to distinguish methods in inner and anonymousclasses 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}.