hacking.texinfo

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

\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename 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 Free Software Foundation, Inc.

@ifnotplaintext
@dircategory GNU Libraries
@direntry
* Classpath Hacking: (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
* 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 a 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 build.  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 URL's.  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 JVM's that provide
JNI or CNI support.  However, the top priority is free JVM's.  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://kissme.sourceforge.net/,Kissme}
@item
@uref{http://www.ibm.com/developerworks/oss/jikesrvm/,Jikes RVM}
@item
@uref{http://www.sablevm.org/,SableVM}
@item
@uref{http://www.kaffe.org/,Kaffe}
@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 currently not the easiest
target.  When hacking on GNU Classpath the easiest is to use
compilers and runtime environments that that work out of the box with
it, such as the jikes compiler and the runtime environments jamvm and
kissme.  But you can also work directly with targets like gcj and
kaffe that have their own copy of GNU Classpath currently.  In that
case changes have to be merged back into GNU Classpath proper though,
which is sometimes more work.  SableVM is starting to migrate from an
integrated GNU Classpath version to being usable with GNU Classpath
out of the box.


The initial target version for Classpath is the 1.1 spec.  Higher
versions can be implemented (and have been implemented, including lots
of 1.4 functionality) if desired, but please do not create classes
that depend on features in those packages unless GNU Classpath already