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 |
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 |
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: |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
|
|
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 |
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 |
|
|
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 |
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 |
|
|
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 |