hacking.texinfo

gcc的组建

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.

@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

@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 judgment, 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
* Writing ChangeLogs::          
@end menu

@node Writing ChangeLogs,  , Hacking Code, 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

@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 captital 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