• ClasspathFirstSteps

This page lists issues that summarize the result/outcome of decisions that been made on the mailing list or IRC (#classpath at irc.freenode.org). If you add new issues please file them respectively under Programming or Non-Programming related.

Index

Non-Programming related

Tainted developer

• Last edit: 2005-01-16 rschuster
• Description:
  • If you are going to contribute source code to GNU Classpath we must make sure that you have not studied the source code of the JDK/JRE or decompiled any of its classes. Furthermore you must not have signed any non-disclosure agreements with Sun in regard with Java technology. The reason for this requirement is that we want to make sure that Sun or any other firm cannot rightfully claim that GNU Classpath infringes their copyright. You are therefore questioned about your experience with Sun's source code and agreements with the firm when you request the FSF copyright assignment. Please note that being tainted does not mean you cannot help GNU Classpath at all. Here is a list of things you can do instead:
    • write Mauve test cases
    • write example applications demonstrating the usage of the API
    • writing/fixing helper programs (like japitools) and scripts
    • report bugs
    • help fixing the documentation

    • help in other Java-related Free software projects (e.g. virtual machine development, GUMP)

    We take this topic very seriously and had a discussion on the mailing list about that. Please read this statement by GNU Classpath's maintainer Mark Wielaard:
    • [Can someone who has seen Sun source code for a particular part of the core libraries contribute to GNU Classpath?]

      Depends. (I will forward a copy of this answer to FSF legal so they can check what I say.)
      

      If the developer got access to the source code by signing some contract (like the SCSL) with Sun then it would be best to examine that contract (by FSF legal) before deciding.
      

      If the developer just accidentally saw some of the source code and had no intention (and didn't actually) study the implementation (with the intention of contributing to GNU Classpath) there is no problem.
      

      Studying a proprietary implementation with the intention of implementing it (better) for GNU Classpath is a clear no-no. The general rule is that if you have looked at or studied any (proprietary) implementation of a package you should not work on that package for GNU Classpath. That is because it would be difficult to proof that you really did an independent implementation. Since what you create might look very similar (which is not unlikely). Working on something completely unrelated is OK (as long as there are no contractual obligations with Sun or some other company to not do this of course).
      

      The important thing is that we want to be clear on the fact that we created an independent implementation. We don't want to get into tricky legal situations. We want to avoid risking to go to court over reverse engineering or clean room situation questions if not absolutely necessary. That is why we in general just say "please don't contribute if you looked at other implementations". If someone thinks that their actions might be explained as copying directly or indirectly another (proprietary) implementation then that could be a problem that we want to avoid.
      

      FSF Legal will always advise not to take any unnecessary risks that might endanger the (perceived) free software status of a GNU project. (If we might need to go to court to proof that what we did was OK, then don't!)
      

• References:

  • GNU: Reading Non-Free Code

  • Statement I from Mark

  • Statement II from Mark (quoted above)

Copyright assignment

• Last edit: 2005-01-10 rschuster
• Description:

  • I you want to contribute a substantial amount of code (more than 10 to 15 lines) to GNU Classpath an assignment of your copyright to the Free Software Foundation is neccessary. The reasons for the assignment are explained in GNU Classpath's FAQ and on http://www.gnu.org (see references). This issue will therefore tell more about its effects and how the assignment is done.
    

    The procedure starts by writing an email to either Classpath's discussion mailing list or the project's maintainer directly, where you clearly state that you have are not a tainted developer (see respective issue). The project maintainer will then forward you an electronic assignment form which has to be filled out and send to the FSF (and a copy goes back to Mark). The subject line of that email has to be your name as it is written in your passport. After a couple of days you will receive a letter from the Free Software Foundation containing the assignment paper which you have to sign and send back. If nothing goes wrong you will receive an email saying that your assignment has been completed. From now on your patches can go in. (Later on another letter will arive at your doorstep containing a copy of the signed assignment paper.)
    You may used to give copyright to yourself in source files when you have helped in projects where no copyright assignment is neccessary. However for GNU Classpath you have to write this line instead:

     Copyright (C) <comma separated list of years> Free Software Foundation, Inc.

    in each source file. The assignment paper clearly states that you are allowed to make any other use of your contributed code. That means that the assignment does not impose any restrictions on your contribution.
    The GNU Classpath development team is aware of the fact that the assignment process is considered tedious. Occasional developers which stumble on a problem and send a patch are often surprised, when they receive an answer saying that they have to fill out a written paper to have their patch applied. Other developers disagree with the assignment process at all. The development team therefore highly appreciate if you go through the hassles. Though there are other ways to contribute which require no copyright assignment:

    • write Mauve test cases
    • writing/fixing helper programs (like japitools) and scripts
    • report bugs

    • help in other Java-related Free software projects (e.g. virtual machine development, GUMP)

• References:

  • GNU Classpath FAQ - Why do I have to give the copyright to the FSF?

  • Why the FSF gets copyright assignments from contributors

  • GNU Contribution Policy

  • Mark telling about the amount of code lines that qualifies a substantial contribution

  • Dalibor telling about the copyright assignemt and alternative ways to contribute

GNU Classpath coding style

• Last edit: 2005-01-11 rschuster
• Description:

  • GNU Classpath as an official GNU project adheres to its coding style. However we have our own hacker's guide for stuff that is not covered by the former document.
    

    Furthermore when it comes to inner classes the language allows you to access the  private  members between the outer and the inner class directly. However the runtime has to generate a so-called trampoline method to make this access possible. This decreases performance and can be avoided if you declare such a member as package-private instead. The usage of package-privateness is a bit against object oriented philosophy, that is why you are encouraged to document when a  private  statement was removed in favor of execution speed. Here is an example from one of Tom's patches:

    -  private DeleteFileHelper()
    +  // Package-private to avoid a trampoline constructor.
    +  DeleteFileHelper()
       {
       }
        

• References:

  • GNU Coding Style

  • GNU Classpath Hacker's Guide

  • Tom telling how to avoid trampoline methods

GNU Classpath release schedule

• Last edit: 2006-09-01 rschuster
• Description:
  • Since 0.09 GNU Classpath follows a two month schedule on which a new snapshot version is released. 0.09 was released on 2004-05-02. 0.10 was released on 2004-07-12. 0.11 was released on 2004-09-13. 0.12 was released on 2004-11-15. 0.13 was released on 2005-01-07. 0.14 was released on 2005-02-25. 0.15 was released on 2005-05-01. 0.16 was released on 2005-06-30. 0.17 was released on 2005-07-15 in order to fix some problems which came up after the 0.16 release. 0.18 was released on 2005-09-06. 0.19 was released on 2005-11-02. 0.20 was released on 2006-01-13. 0.90 was released on 2006-03-06. (It was decided that '0.90' more closely matched the state of development.) 0.91 was released on 2006-05-15. 0.92 was released on 2006-08-09. 0.93 was released on 2006-12-11. 0.95 was released on 2007-04-23.
• References:

  • Answer on request for a faster release schedule in 2003

  • Latest comment from Mark about a two month schedule

  • GNU Classpath News including release announcements

How to Prepare a Release

• Last edit: 2007-09-18 gnu_andrew
• Description:
  • Mark wrote a description of the release process prior to releasing 0.91.
• References:

  • ClasspathReleaseProcess

Getting write access for Mauve CVS

• Last edit: 2005-09-19 rschuster
• Description:

  • If you are going to write test cases for the free Java test suite Mauve send your patches to the [mauve-patches_AT_sources.redhat.com] mailing list. Write access will be given to regular contributors or GNU Classpath developers. Drop a line to Tom Tromey and he will set it up for you. Usually he can be reached via Classpath' IRC channel, too: #classpath on irc.gnu.org

    Note: Mauve is not part of the GNU project, that means that no copyright assignment is needed!

Getting developer access for GNU Classpath' BugZilla

• Last edit: 2005-09-19 rschuster
• Description:

  • If you are a Classpath developer and need proper BugZilla access privileges (everyone needs this ) ask Mark Wielaard (mjw on #classpath) or Andrew Pinski (pinskia on #classpath) for this and it will be set up for you.

• References:

  • GNU Classpath bugs page

Nightly Snapshots

• Last edit: 2007-09-19 dalibor
• Description:
  • Some people can't access the CVS repository easily, and prefer downloading nightly snapshots instead.

    Snapshots can be found at the builder.classpath.org web site.

Programming related

Dealing with performance regressions

• Last edit: 2005-02-01 rschuster
• Description:

  • If you rework existing code it its possible that your change affects execution speed of the modified method in a negative way. This is called a performance regression.
    

    As a Free software project GNU Classpath strives for being the best implementation of the Java API. Besides feature completeness and API conformance, achieving a high runtime performance is a major goal. For this to become true we expect patches which modify existing code introduce no performance regressions.
    

    In the future we want to have specialized test cases which will check performance and warn if neccessary.
    

    However if you add a new API we do not force you to write the best performing version in the first place. If you have a vague feeling of what could be done to make your implementation faster, adding a FIXME or TODO comment explaining that is always a good idea.

• References:

  • Thoughts on performance regression tests

GNU Classpath specific documentation tags

• Last edit: 2005-01-19 rschuster
• Description:

  • GNU Classpath introduces the @specnote tag which you can use to describe what the implementation state of a class and/or method. The specnote is meant to describe binary compatible API changes like changing an access modifier from protected to public. As an example here is a code snippet of our java.beans.PropertyEditorSupport implementation:

    * @since 1.5
    * @specnote this was <code>protected</code> prior to 1.5
    */
    public PropertyEditorSupport()
    {
        

    Another tag you can use is @status which describes to which official JDK version this class should be compatible. As an example from the same class:

     * @status updated to 1.5
     */
    public class PropertyEditorSupport implements PropertyEditor
    {
        

    Furthermore you will meet an @version tag on some classes which is used as a developer specific way of versioning a class. You should avoid its usage and delete it from classes you modify because we regard the tag as not being useful anymore.

    When you are using the @author tag you may add your email address enclosed in round parentheses ( ). You will find older author tags where the address is enclosed in < > brackets which you are encouraged to update to the new format. Keep in mind that each author has its own @author tag, do not generate a list of comma separated names. Here is an example:

     * @author John Keiser
     * @author Eric Blake (ebb9@email.byu.edu)
     * @author Tom Tromey (tromey@cygnus.com)
     * @since 1.0
     * @see ClassLoader
     */
    public final class Class implements Serializable
    
        

    Finally you should add the @since to every class and method which has it in the official documentation. We have not yet agreed on our own policy to the tag.

• References:

  • Already closed bug entry that requested special handling for @author tag

  • Complaint that the @specnote usage is not documented

  • Michael Koch about @version tag

  • Meaning of @status and @specnote

  • Tom Tromey about the tags

Hacking GNU Classpath with GNU Emacs

• Last edit: 2005-08-01 tromey
• Description:
  • This issue describes how to hack on GNU Classpath using Emacs IDE.

• If you add this code to your .emacs, it will prompt you about updating copyrights. Note that the copyright code in Emacs has a known bug where it won't recognize copyright years on the next line -- so you must be sure to check that the results are sane.

  (defun fp-copyright-update () 
    (and (not (eq major-mode 'fundamental-mode))
         (copyright-update)))
  
  (and (fboundp 'copyright-update)
       (add-hook 'write-file-hooks 'fp-copyright-update))

• The "GNU" coding style in Emacs is essentially what Classpath uses. You can set this up by invoking (c-set-style "GNU") in your .emacs. But, since most people work on multiple projects, you may want code like this, which sets the style depending on the file name:

  (defun tjt-set-c-style () 
    (if (buffer-file-name)
        (cond
         ((or
           (string-match "/org\\.eclipse\\..*\\.java$" (buffer-file-name))
           (string-match "/com\\.redhat\\..*\\.java$" (buffer-file-name)))
          (progn
            (c-set-style "BSD")
            (set (make-local-variable 'c-basic-offset) 4)
            (set (make-local-variable 'tab-width) 4)))
         (t
          (progn
            (c-set-style "GNU")
            (c-set-offset 'inline-open 0))))
      (c-set-style "GNU")))
  
  (add-hook 'c-mode-common-hook 'tjt-set-c-style)

• It is also handy to be able to jump from a source file in Classpath to the corresponding javadoc on the web. Here is some code to do this.

  (defun tjt-java-class-help () 
    "Get help on the current Java class."
    (interactive)
    (let ((found nil))
      ;; Use initial `.*' to suck up as much leading text as possible.
      (cond
       ((string-match "^.*\\(libjava\\|classpath/external/[a-z0-9_]*\\|classpath\\)/\\(.*\\)\\.java$"
                      buffer-file-name)
        (setq found
              (substring buffer-file-name (match-beginning 2) (match-end 2))))
       ((string-match "^.*libjava/\\(.*\\)/nat\\(.*\\)\\.cc$"
                      buffer-file-name)
        (setq found
              (concat (substring buffer-file-name (match-beginning 1)
                                 (match-end 1))
                      "/"
                      (substring buffer-file-name (match-beginning 2)
                                 (match-end 2))))))
      (if found
          (funcall browse-url-browser-function
                   (concat
                    "http://java.sun.com/j2se/1.5.0/docs/api/"
                    found
                    ".html"))
        (message "Doesn't look like Java buffer"))))
  
  (add-hook 'java-mode-hook 
            (function 
             (lambda ()
               (local-set-key "\C-hx" 'tjt-java-class-help)
               )))

Hacking GNU Classpath with Eclipse

• Last edit: 2005-12-21 mjw
• Description:
  • This issue describes how to hack on GNU Classpath using the Eclipse (3) IDE.

    See for a full description (inculding a screenshot walkthrough) ClasspathHackingWithEclipse.

• References:

  • Hacking GNU Classpath with Eclipse

  • Compilation instructions for generics-branch

Implementation of equals() and hashCode()

• Last edit: 2005-01-21 rschuster
• Description:

  • If you are using the JAPITools comparisons to find out methods which have to be implemented you will realize that the tool does not track implementations of  equals()  and  hashCode() . The reason for this is that we consider the functionality of these methods as an implementation detail which we do not have to follow in the way Sun did.
    

    Imagine that it is theoretically possible to implement  Object.equals()  in a way that it supports all known classes (e.g. using  instanceof  and explicit casts). If we had done it this way there is no need for any overridden implementation of that method in the whole class tree. Now if JAPITools would strictly requiring an implementation of  equals()  in  ArrayList  for example, then an error would be reported although our behaviour matches that of the Sun API already.
    

    However we suggest finding out which classes need proper  equals()  and  hashCode()  behavior and write mauve tests for this. After that we should implement that behavior in the most effective way.
    

• References:

  • Stuart Ballard about JAPITools and equals/hashCode detection

Hacking on native methods

• Last edit: 2005-05-02 rschuster
• Description:

  • A couple of classes in GNU Classpath directly depends on features which are provided by the operating system and/or other native libraries. To access these features a mechanism known as Java Native Interface (JNI) is used. Hacking on JNI is considered advanced. You should have used it at least once for your own project's purposes and read an introduction about it.
    

    This issue explains how JNI is used in GNU Classpath and what you have to know to hack on classes depending on JNI. This is no introduction on JNI and I assume that you know the general terms and definitions of that mechanism. Furthermore I expect that you have read the GNU Classpath Hacker's Guide which has several sections concerning JNI. However I have added some external links to documentation and tutorials about the topic.
    

    Generally compile your native code with --enable-Werror and comply with the GNU Coding Style rules. Please do not use C++-style comments (// foo) in native code.
    

    Header files have to be created from class files using gcjh4 which is part of the GCC version 4. You can now use the version which is part of GCC's 4.0.0 .
    

    Any class that had no native methods before needs a suitable rule in include/Makefile.am to automatically create its header file at build time. You can use the other entries in that file as an example. When a header file has changed or is added do not forget to commit the changes/additions to the CVS.
    Note:

    JNI is extraordinarily verbose and error prone. Therefore you are encouraged to read about common traps and pitfalls of JNI. If you are doing the noble job of transforming code from GCJ's CNI to JNI take extra care about the exception statements: In CNI this will leave the method immediately, where in the JNI version you need an explicit return statement (any value given to it is discarded).
    

    Please keep in mind that adding of new native methods to GNU Classpath without providing the ability to avoid JNI via the VM interface is considered contrary to our long-term goal of becoming JNI independent. The solution for a class Foo is to let it rely upon functionalilty of a class named VMFoo. The latter class may then use native methods and is meant to be implemented different on non-JNI capable systems.
    

References:

• GNU Classpath Programming Goals

• GNU Classpath Directory and File Naming Conventions

• Sun's JNI tutorial

• Sun's documentation about the JNI

• IBM DeveloperWorks article about JNI

• JNI Pitfalls page

• GNU Classpath JNI independence

Patch submission guide

• Last edit: 2005-10-18 rschuster
• Description:
  • Although GNU Classpath has not yet official contribution rules here is a tentative list how the patch commitment process should work:
  • Make sure you are not a tainted developer (at least for the part you are working on) and have a copyright assignment for larger patches.
  • Please use our coding style.
  • Please separate stylistic (indenting) and documentation changes from algorithmic ones. This is very important for the review process because a patch is very hard to read if it contains both kinds of changes.

  • Write factual ChangeLog entries. That means write what you have done not why. Look at the examples given in the GNU Hacker Guide on ChangeLog entries.

  • Send an email in the following format to classpath-patches@gnu.org:

    • Subject: Describes the change. Starting with FYI: says you are committing the patch without comments, where RFC: means you expect input from others before applying the patch. If you wrote a patch for any other branch than HEAD include the branch's name in bracket, eg. [generics]].

    • Body: Put the ChangeLog entry for you patch here. If you feel the need for additional clarification then add some sentences.

    • Attachment: The patch in unified diff format (cvs diff -uN). If the size exceeds the list's limit tar.gz the patch. New files may be attached plainly. (Hint: Add "diff -uN" to ~/.cvsrc to make unified diff generation automatic.)

      • For new files you must have added them with cvs add first, otherwise they will not show up in the patch!

      • Do not include the ChangeLog entry in the patch itself. Patches for GNU Classpath have to be merged to other projects as well which have different ChangeLog files. Separating the entry from the patch makes the integration work much easier.

  • If no one complains for a couple of days commit your patch to the CVS.

    Finally: Do not take critics on coding style personally. We appreciate your work for GNU Classpath and are very thankful for your contribution to our community. We know that it is cumbersome at first to adopt a coding style that is not your own. However GNU Classpath is a large project and consistency in our codebase is very important for the future work on it.
    

  • In case your patch fixed a bug in GNU Classpath' BugZilla you should mark it fixed and set the target milestone to the next release. By adhering to this one can check the bugs closed for one version

    If you have the impression that the email conversation about a particular patch takes too much time, you may show up on IRC (#classpath at irc.freenode.org) and discuss the problem face to face and in real-time.

• References:

  • Mark Wielaard about proper ChangeLog entries

  • GNU ChangeLog guide

Building GNU Classpath from CVS

• Last edit: 2005-03-15 rschuster
• Description: This issue describes how to fetch and build GNU Classpath from CVS.
  • Why?

    Building GNU Classpath from CVS can be used to test the latest features and ensure that VMs are still compatible with it. Please note that not all VMs can use Classpath from CVS yet. Though work is focussed on this. You find a detailed description how to get JamVM to run with GNU Classpath from CVS in another issue below.
    

  • Requirements and configure options:

    A detailed description of the requirements and the configuration options is always available via Classpath's INSTALL file. On Debian-based system you need to install the following packages:

    • libgtk2.0-dev, ecj (recommended over Jikes), make, gcc, libxtst-dev, libgconf2-dev, mozilla-dev
  • Fetch the sources

    cvs -z3 -d:pserver:anoncvs@cvs.savannah.gnu.org:/cvsroot/classpath co classpath
    

  • Generate Autotools support files

    cd classpath
    ./autogen.sh
    cd ..
    

  • Configuration For developers we recommend building GNU Classpath not inside the source directory.

    mkdir cp-obj
    cd cp-obj
    ../classpath/configure --prefix=<prefixdir>

    <prefixdir> is the directory where you want to install GNU Classpath. The default prefix directory is /usr/local. Append any configure options you need.

  • Build & installation

    make
    make install
    

    Congratulations, you now have a Free software Java class library.

• References:

  • GNU Classpath API documentation

  • Home of the GTK+ library

  • Home of libxml and libxslt

  • Home of the Jikes compiler

Building and running GNU Classpath on Cygwin

• Last edit: 2005-07-01 smeslin-weber
• Description: This issue describes the steps required for getting started with GNU Classpath on Cygwin. It includes instructions for installing the required packages, building GNU Classpath and running a test program using either JamVM or SableVM.
• References:

  • ClasspathOnCygwin