/[classpath]/classpath/doc/hacking.texinfo
ViewVC logotype

Diff of /classpath/doc/hacking.texinfo

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.10 by cbj, Mon Jun 25 04:43:56 2001 UTC revision 1.11 by cbj, Sat Sep 28 14:45:25 2002 UTC
# Line 24  Copyright (C) 1998-2001 Free Software Fo Line 24  Copyright (C) 1998-2001 Free Software Fo
24    
25  @page  @page
26  @vskip 0pt plus 1filll  @vskip 0pt plus 1filll
27  Copyright @copyright{} 1998-2001 Free Software Foundation, Inc.  Copyright @copyright{} 1998-2002 Free Software Foundation, Inc.
28  @sp 2  @sp 2
29  Permission is granted to make and distribute verbatim copies of  Permission is granted to make and distribute verbatim copies of
30  this document provided the copyright notice and this permission notice  this document provided the copyright notice and this permission notice
# Line 89  operating system can ship with Java incl Line 89  operating system can ship with Java incl
89  implementation have already been written, including free Java virtual  implementation have already been written, including free Java virtual
90  machines (JVM's) such as @uref{http://www.kaffe.org/,Kaffe} and  machines (JVM's) such as @uref{http://www.kaffe.org/,Kaffe} and
91  @uref{http://www.hungry.com/products/japhar/,Japhar}, and Java compilers  @uref{http://www.hungry.com/products/japhar/,Japhar}, and Java compilers
92  such as @uref{http://www.cs.berkeley.edu/~engberg/guavac/,Guavac}.  such as @uref{http://www.jikes.org/, Jikes} and
93    @uref{http://gcc.gnu.org/java/, GCJ}.
94  However, there is currently no free replacement for Sun's proprietary  However, there is currently no free replacement for Sun's proprietary
95  libraries.  This Classpath project aims to correct this problem by  libraries.  The Classpath project aims to correct this problem by
96  supplying a free class library implementation that will allow a 100%  supplying a free class library implementation that will allow a 100%
97  free Java platform to be distributed.  Note that Kaffe now ships with a  free Java platform to be distributed.  Note that Kaffe now ships with a
98  partial class library that is also free, so there is more than one group  partial class library that is also free, so there is more than one group
# Line 104  working towards a common goal. Line 105  working towards a common goal.
105  Although Classpath is following an open development model where input  Although Classpath is following an open development model where input
106  from developers is welcome, there are certain base requirements that  from developers is welcome, there are certain base requirements that
107  need to be met by anyone who wants to contribute code to this project.  need to be met by anyone who wants to contribute code to this project.
108  They are mostly unfortunately dictated by legal requirements and are not  They are mostly dictated by legal requirements and are not arbitrary
109  arbitrary restrictions chosen by the Classpath team.  restrictions chosen by the Classpath team.
110    
111  You will need to adhere to the following things if you want to donate  You will need to adhere to the following things if you want to donate
112  code to the Classpath project:  code to the Classpath project:
# Line 196  to a complete and robust product.  Writi Line 197  to a complete and robust product.  Writi
197  than going back at the end and adding them.  We use the Mauve testsuite, see  than going back at the end and adding them.  We use the Mauve testsuite, see
198  @uref{http://sources.redhat.com/mauve/,Mauve}.  There is always room for  @uref{http://sources.redhat.com/mauve/,Mauve}.  There is always room for
199  improvement when testing software and there is plenty of headroom left  improvement when testing software and there is plenty of headroom left
200  before Mauve becomes close to complete.  before Mauve becomes close to complete.  
201    
202  @node Project Goals, Programming Tools, Volunteering, Top  @node Project Goals, Programming Tools, Volunteering, Top
203  @comment node-name, next, previous, up  @comment node-name, next, previous, up
# Line 234  probably incomplete list is below. Line 235  probably incomplete list is below.
235    
236  @enumerate  @enumerate
237  @item  @item
238    @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}
239    @item
240  @uref{http://www.japhar.org/,Japhar}  @uref{http://www.japhar.org/,Japhar}
241  @item  @item
242  @uref{http://www.kaffe.org/,Kaffe}  @uref{http://www.kaffe.org/,Kaffe}
243  @item  @item
244  @uref{http://www.sablevm.org/,SableVM}  @uref{http://www.sablevm.org/,SableVM}
 @item  
 @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}  
245  @item  @item
246  @uref{http://www.mozilla.org/projects/ef,Electrical File}  @uref{http://kissme.sourceforge.net/,Kissme}
247  @item  @item
248  @uref{http://latte.snu.ac.kr/,LaTTe}  @uref{http://latte.snu.ac.kr/,LaTTe}
249  @item  @item
# Line 252  Other JNI Compliant JVM's. Line 253  Other JNI Compliant JVM's.
253  As with OS platform support, this priority list could change if a  As with OS platform support, this priority list could change if a
254  volunteer comes forward to port, maintain, and test releases for a  volunteer comes forward to port, maintain, and test releases for a
255  particular JVM.  Kaffe is now developing its own class library, so the  particular JVM.  Kaffe is now developing its own class library, so the
256  priority of supporting that platform is not as high as for Japhar or any  priority of supporting that platform is not as high as for other free VMs.
 other free VM.  
257    
258  The initial target version for Classpath is Java 1.1.  Java 1.2 can be  The initial target version for Classpath is Java 1.1.  Java 2 can be
259  implemented if desired, but please do not create classes that depend on  implemented if desired, but please do not create classes that depend on
260  1.2 features in other packages.  Java 2 features in other packages unless Classpath already contains
261    those features.
262    
263  @node Programming Tools, Programming Standards, Project Goals, Top  @node Programming Tools, Programming Standards, Project Goals, Top
264  @comment node-name, next, previous, up  @comment node-name, next, previous, up
# Line 274  automake 1.4 Line 275  automake 1.4
275  @item  @item
276  autoconf 2.13  autoconf 2.13
277  @item  @item
278  libtool 1.3.5  libtool 1.4.2
279  @item  @item
280  GNU m4 1.4  GNU m4 1.4
281  @item  @item
282  perl 5.6  perl 5.6
 @item  
 GNU MP 2.0.2  
283  @end itemize  @end itemize
284    
285  All of these tools are available from  All of these tools are available from
# Line 342  For Java code, please follow the Line 341  For Java code, please follow the
341  @uref{http://www.fsf.org/prep/standards_toc.html,GNU Coding Standards},  @uref{http://www.fsf.org/prep/standards_toc.html,GNU Coding Standards},
342  with the exception of naming conventions.  Please follow  with the exception of naming conventions.  Please follow
343  @uref{http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html,Sun's  @uref{http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html,Sun's
344  naming conventions}.  naming conventions}.  There are a number of exceptions to the GNU
345    Coding Standards that we make for GNU Classpath and these will be
346    documented soon as well as hopefully providing developers with a code
347    formatting tool that closely matches those rules.
348    
349  For documentation comments, please follow  For documentation comments, please follow
350  @uref{http://java.sun.com/products/jdk/javadoc/writingdoccomments.html,How  @uref{http://java.sun.com/products/jdk/javadoc/writingdoccomments.html,How
# Line 386  Right now the only supported platform is Line 388  Right now the only supported platform is
388  version stabilizes and we begin the effort to port to many other  version stabilizes and we begin the effort to port to many other
389  platforms.  platforms.
390    
391    Sun has produced documentation concerning much of the information
392    needed to make Classpath serializable compatible with Sun
393    implementations.  Part of doing this is to make sure that every class
394    that is Serializable actually defines a field named serialVersionUID
395    with a value that matches the output of serialver on Sun's
396    implementation.  The reason for doing this is below.
397    
398    If a class has a field (of any accessibility) named serialVersionUID
399    of type long, that is what serialver uses. Otherwise it computes a
400    value using some sort of hash function on the names of all method
401    signatures in the .class file. I'm not sure whether the methods are
402    sorted first, or what the hash function is.  The fact that different
403    compilers create different synthetic method signatures, such as
404    access$0() if an inner class needs access to a private member of an
405    enclosing class, make it impossible for two distinct compilers to
406    reliably generate the same serial #, because their .class files
407    differ. However, once you have a .class file, its serial # is unique,
408    and the computation will give the same result no matter what platform
409    you execute on.
410    
411  @node Robustness, Java Efficiency, Portability, Top  @node Robustness, Java Efficiency, Portability, Top
412  @comment node-name, next, previous, up  @comment node-name, next, previous, up
413  @chapter Robustness  @chapter Robustness
# Line 412  Check for null values of jclasses before Line 434  Check for null values of jclasses before
434  JNI does not behave nicely when you pass a null class to it: it  JNI does not behave nicely when you pass a null class to it: it
435  terminates Java with a "JNI Panic."  terminates Java with a "JNI Panic."
436    
437  In general, try to use functions in native/lib/jcl.h.  They check  In general, try to use functions in native/jni/classpath/jcl.h.  They
438  exceptions and return values and throw appropriate exceptions.  check exceptions and return values and throw appropriate exceptions.
439    
440  @node Java Efficiency, Native Efficiency, Robustness, Top  @node Java Efficiency, Native Efficiency, Robustness, Top
441  @comment node-name, next, previous, up  @comment node-name, next, previous, up
# Line 465  A final problem is efficiency of native Line 487  A final problem is efficiency of native
487  like method calls, fields, finding classes, etc.  Generally you should  like method calls, fields, finding classes, etc.  Generally you should
488  cache things like that in static C variables if you're going to use them  cache things like that in static C variables if you're going to use them
489  over and over again.  GetMethodID(), GetFieldID(), and FindClass() are  over and over again.  GetMethodID(), GetFieldID(), and FindClass() are
490  *slow*.  *slow*.  Classpath provides utility libraries for caching methodIDs
491    and fieldIDs in native/jni/classpath/jnilink.h.  Other native data can
492    be cached between method calls using functions found in
493    native/jni/classpath/native_state.h.
494    
495  Here are a few tips on writing native code efficiently:  Here are a few tips on writing native code efficiently:
496    
# Line 495  state fairly efficiently.  Japhar now su Line 520  state fairly efficiently.  Japhar now su
520  native state get and set calls as fast as accessing a C variable  native state get and set calls as fast as accessing a C variable
521  directly.  directly.
522    
523    If you are using native libraries defined outside of Classpath, then
524    these should be wrapped by a Classpath function instead and defined
525    within a library of their own.  This makes porting Classpath's native
526    libraries to new platforms easier in the long run.  It would be nice
527    to be able to use Mozilla's NSPR or Apache's APR, as these libraries
528    are already ported to numerous systems and provide all the necessary
529    system functions as well.
530    
531  @node Specification Sources, Naming Conventions, Native Efficiency, Top  @node Specification Sources, Naming Conventions, Native Efficiency, Top
532  @comment node-name, next, previous, up  @comment node-name, next, previous, up
533  @chapter Specification Sources  @chapter Specification Sources
# Line 583  classpath Line 616  classpath
616   |   |
617   |---->native   |---->native
618           |           |
619           |-->java.io           |-->jni
620           |-->java.lang           |    |-->classpath
621           |-->java.net           |    |-->gtk-peer
622           |-->java.util.jar           |    |-->java-io
623           |-->etc           |    |-->java-lang
624             |    |-->java-net
625             |    |-->java-util
626             |    |-->etc
627             |-->cni
628        
629  @end example  @end example
630    
# Line 601  class library.  Because this is the publ Line 638  class library.  Because this is the publ
638  important that the public classes, interfaces, methods, and variables  important that the public classes, interfaces, methods, and variables
639  are exactly the same as specified in Sun's documentation.  The directory  are exactly the same as specified in Sun's documentation.  The directory
640  structure is laid out just like the java package names.  For example,  structure is laid out just like the java package names.  For example,
641  the class java.util.zip would be in the directory java/util/zip.  the class java.util.zip would be in the directory java-util.
642    
643  @item gnu/java  @item gnu/java
644  Internal classes (roughly analogous to Sun's sun.* classes) should go  Internal classes (roughly analogous to Sun's sun.* classes) should go
# Line 616  appropriate name and see what everybody Line 653  appropriate name and see what everybody
653  This directory holds native code needed by the public Java packages.  This directory holds native code needed by the public Java packages.
654  Each package has its own subdirectory, which is the ``flattened'' name  Each package has its own subdirectory, which is the ``flattened'' name
655  of the package.  For example, native method implementations for  of the package.  For example, native method implementations for
656  java.util.zip should go in native/java.util.zip.  java.util.zip should go in native/classpath/java-util.  Classpath
657    actually includes an all Java version of the zip classes, so no native
658    code is required.
659    
660  @end table  @end table
661    
# Line 628  general guidelines above, the following Line 667  general guidelines above, the following
667    
668  @item  @item
669  Classes that need to load native code should load a library with the  Classes that need to load native code should load a library with the
670  same name as the flattened package name, with all periods removed.  For  same name as the flattened package name, with all hyphens removed.  For
671  example, the native library name specified in LoadLibrary for  example, the native library name specified in LoadLibrary for
672  java.util.zip would be ``javautilzip''.  java-util would be ``javautil''.
673    
674  @item  @item
675  Each package has its own shared library for native code (if any).  The  Each package has its own shared library for native code (if any).
 actual library name to be built will depend on the target JVM.  
676    
677  @item  @item
678  The main native method implementation for a given method in class should  The main native method implementation for a given method in class should
679  go in a file with the same name as the class with a ``.c'' extension.  go in a file with the same name as the class with a ``.c'' extension.
680  For example, the implementation of the native methods in  For example, the JNI implementation of the native methods in
681  java.util.InetAddress would go in native/java.net/InetAddress.c.  java.net.InetAddress would go in native/jni/java-net/InetAddress.c.
682  ``Internal'' native functions called from the main native method can  ``Internal'' native functions called from the main native method can
683  reside in files of any name.  reside in files of any name.
684  @end itemize  @end itemize

Legend:
Removed from v.1.10  
changed lines
  Added in v.1.11

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26