[image of the evil water droplet] (jpeg 3k)

GNU Classpath

1. introduction
1.1 What is GNU Classpath?
1.2 Why Java?
1.3 But isn't Java free already?
1.4 What do we need to make Java free?
1.5 Is GNU Classpath all that is needed for running Java programs?

2. licensing
2.1 Under which licence is GNU Classpath released?
2.2 Where can I find more about the GPL?
2.3 What does the exception allow me to do?
2.4 I have a question about licensing GNU Classpath. Who can I ask?
2.5 How can I be sure that my application does not break the license?

3. Classpath Development
3.1 I would like to contribute, where shall I start?
3.2 Can I look at source code distributed with other implementations to get inspiration?
3.3 I'm tainted by; can I help anyway?
3.4 Why do I have to give the copyright to the FSF?
3.5 How do I install GNU Classpath?
3.6 How do I install Mauve?
3.7 How can I synchronize my sources with GNU Classpath?
3.8 How do I avoid compiling some files or packages?
3.9 How do I change classpath's web pages?
3.10 Is it possible to use Classpath in a proprietary VM?

4. Classpath Implementation
4.1 Why does java.lang.Throwable delay the StackTrace array construction?

5. Varia
5.1 How to generate API Documentation with gjdoc/libxmlj?

1. introduction

1.1 What is GNU Classpath?

GNU Classpath is a set of essential libraries for supporting the Java programming language.

Classpath serves the same role that libc has for C, but is much richer in functionality. The broadness of the standard library is an important reason why Java has been so successful. For example, the library includes frameworks to convert between character encodings, for accessing relational databases, for building Graphical User Interfaces, for encryption, for logging, and for numerous other tasks that are needed to build complex applications.


1.2 Why Java?

On the GNU operating system, we want to run software independent of the programming language in which it was written. Because Java is widespread, and because Java has some nice features, we want to support Java as well.


1.3 But isn't Java free already?

Sun Microsystems, the company who has created Java, currently distributes the “Java Development Kit” and “Java Runtime Environment” at no cost. The former even comes with the source code of the standard class library. However, the “Sun Community Source License” does not grant essential freedoms, for example the right to distribute a modified version of the code.

Therefore, Sun’s implementation does not qualify as Free Software.


1.4 What do we need to make Java free?

Though it would be helpful if Sun would open their sources, this is not the most important step toward a free Java. Even more important for a free Java are:

  • Access to the TCK (Technology Compatibility Kits) on acceptable terms
  • Involvement in the JCP without contamination or other unacceptable constraints
  • Easing of the requirements on subsetting. The free software community doesn't work well with the "one big perfect release" model that Sun seems to want.

There was already a lot of discussions around this topic on other sites:


1.5 Is GNU Classpath all that is needed for running Java programs?

GNU Classpath is a free implementation of Java’s standard library. To execute Java programs, it is also necessary to have a Java Virtual Machine (JVM). This component manages memory, enforces security restrictions, compiles Java bytecodes to the instruction set of your computer, and provides other runtime services. There exist several projects for free JVMs . Most use GNU Classpath as the up-stream source for their library.

Java programs can also be compiled “ahead of time,” like C++ or other compiled languages. The GNU Compiler Collection (GCC) does this, and its Java library is mostly derived from GNU Classpath.


2. licensing

2.1 Under which licence is GNU Classpath released?

GNU Classpath is licensed under the GPL plus a special exception:

Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination.

As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.


2.2 Where can I find more about the GPL?

Please check the FSF FAQ on the GNU GPL: http://www.fsf.org/licenses/gpl-faq.html .

2.3 What does the exception allow me to do?

If you combine GNU Classpath with independent modules to produce an executable you can copy and distribute the resulting executable under terms of your choice.

So you can use and distribute GNU Classpath as is in your program without changing the license of your software.


2.4 I have a question about licensing GNU Classpath. Who can I ask?

Direct such questions to licensing@gnu.org. The FSF is the official copyright holder of Classpath and sets the distribution terms

2.5 How can I be sure that my application does not break the license?

The FSF has a GPL-compliance lab which offers consulting services for companies who are working to develop products that incorporate Free Software so that they can do so in ways that comply with the terms of the GPL and other Free Software licenses. If you are interested in this service, please write to compliance-lab@fsf.org.
3. Classpath Development

3.1 I would like to contribute, where shall I start?

See the documentation page, especially the GNU Classpath Hacker’s Guide, and pick up a task from the list!

3.2 Can I look at source code distributed with other implementations to get inspiration?

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 or other companies in regard with java technology that might cover the core class libaries or tools. The reason for this requirement is that we want to make sure that Sun or any other company cannot rightfully claim that GNU Classpath infringes their copyright. You are therefore questioned about your experience with other implementations of similar source code and any agreements with companies you might have signed when you request to contribute to GNU Classpath.

Please note that this does not mean you cannot help GNU Classpath at all in such a case. Here is a list of things you can do instead:

  • write Mauve test cases
  • write example applications demonstrating the usage of the packages
  • writing/fixing helper programs (like japitools) and scripts
  • report bugs
  • help fixing the documentation
  • help in other related Free software projects (e.g. virtual machine development, GUMP )

Here are some rough guidelines for deciding whether or not it would be wise to accept a contribution from someone that studied source code for another implementation of the core libraries or is under contract with some company covering implementations of core library classes.

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!)

This isn't a GNU Classpath project specific issue. See GNU: Reading Non-Free Code .

3.3 I'm tainted by; can I help anyway?

Even if you have seen Sun's source and you cannot contribute code to GNU Classpath, there are still many way you can help us. Here's a few examples of contributions you can make that would greatly help us:
  • Mauve test cases
  • Example programs for GNU Classpath
  • Documentation fixes
  • Help programs (e.g. japitools) and scripts
In general, if you 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. In case of doubt, please refer to FSF legal.

3.4 Why do I have to give the copyright to the FSF?

Some contributors of Classpath might be annoyed if their work was being used under conditions that are not according to the terms of the license. However, enforcing the license in court (if this was ever needed) would be easier if the Free Software Foundation can claim to speak in the name of all authors. For this reason, and for others that are specific to the intellectual property system of the United States, GNU projects tend to be a bit picky about getting signatures from all contributors. Please do not see this as a personal offence.

Giving the copyright to the FSF also gives us a clear paper trail where changes come from, which confirms our clean-room status.

The assignment contract commits the foundation to setting distribution terms that permit free redistribution.

The assignment contract we normally use has a clause that permits you to use your code in proprietary programs, on 30 days' notice. (The 30 days' notice is there because, through a legal technicality, it would improve our position in a suit against a hoarder.) Although we believe that proprietary software is wrong, we include this clause because it would serve no purpose to ask you to promise not to do it. You're giving us a gift in the first place.

You don't need to invoke this clause in order to distribute copies as free software under the GNU GPL, since everyone is allowed to do that.

See also /licenses/why-assign.html.

For getting the assignment form, please send an e-mail with your name (as it appears in your passport) and your current postal address to the maintainer of GNU Classpath, Mark Wielaard .


3.5 How do I install GNU Classpath?

Follow these steps to install GNU Classpath. Please note that you need this only if you want to work directly with it; usually JVMs contain a pre-packaged version of GNU Classpath. Prerequisites Please check the exact version of the prerequisites from your release's INSTALL file. In every case, you need:

  • GNU gmake
  • GNU autoconf
  • GNU automake
  • GNU libtool
For building the Java bytecode (.class files), one of these compilers are required. You can select which compiler using --with-jikes, --with-gcj or --with-kjc as argument to configure; the present default is gcj.
  • GCJ (part of GNU GCC)
  • IBM Jikes
For building the JNI native libraries, the following are required unless --disable-gtk-peer is used as an argument to configure. For building the documentation you will need:
  • texinfo
Install from CVS
    cvs checkout
    ./autogen.sh
    ./configure
    make
Install a release
    ftp://ftp.gnu.org/gnu/classpath/ Download the current release
    tar zxf classpath-version.tar.gz unpack
    cd classpath-version
    more INSTALL make sure you have all pre-requirements
    ./configure configure the distribution; use --help to get the list of options: you will usually need --prefix=dest/dir/for/classpath; use --disable-gtk-peer if you don't use gtk+/gnome.
    make; make install

3.6 How do I install Mauve?

    export CVSROOT=:ext:anoncvs@bogus.example.com:/cvs/mauve
    cvs loginpassword is anoncvs
    cvs checkout mauve
    cd mauve
    ./configure The main thing this does is creating the gnu/testlet/config.java. You could also do this by hand from the config.java.in file
    vi batch_runner Edit the script 'batch_runner' to set the variable COMPILER correctly (there are a couple of example settings)
    vi runner Edit script 'runner' to set the variable RUNTIME correctly (there are a couple of example settings)
    ./batch_run run ./batch_run and look at the results. You can also run individual tests with
    - echo gnu.testlet.java.lang.String.getBytes | jamvm gnu.testlet.SimpleTestHarness
    (Option flags are -verbose and -debug)

3.7 How can I synchronize my sources with GNU Classpath?

When developing a JVM that uses GNU Classpath, a copy of GNU Classpath local to the JVM is often used. To keep the Classpath sources synchronized with the main development, a few approaches are possible (we assume here that you are keeping the local copy of Classpath in your JVM revision control software):

3.8 How do I avoid compiling some files or packages?

The file lib/standard.omit controls which files are omitted from the compilation. Add a regex with the files to be omitted and rebuild classpath.

3.9 How do I change classpath's web pages?

To modify and upload GNU Classpath's web pages, you need write access to the CVS. First, checkout the modules "classpath" and "website".

The web pages are stored in doc/www.gnu.org and are written in wml (Web Meta Language, see http://thewml.org/ ).

A typical page usually looks like this:

#include "include/layout.wml"

<subject "here goes the page title">

<box>

<boxtitle>Section 1 Title<\boxtitle>
<boxitem>
  section 1 contents
<\boxitem>

....

<\box>

Invoking "make" creates the html pages in the same directory. To copy those pages to another directory, use

> export CLASSPATH_WEBROOT=...destination...
> make publish

The steps to publish the pages are:

  1. Update ChangeLog
  2. Commit your changes in module Classpath to the CVS
  3. cd doc/www.gnu.org
  4. make
  5. copy the modified / new pages to the website module
  6. commit the changes in the website module

Note that it takes up to an hour for the pages to appear on the GNU website after an upload.

3.10 Is it possible to use Classpath in a proprietary VM?

Only the proprietary VM's vendor can make it work with GNU Classpath, by the nature of the VM being proprietary. GNU Classpath provides well documented and widely used interfaces for interfacing with runtimes. It's up to proprietary VM vendors to make their products work with GNU Classpath, if they wish to do so. If you, as a customer, want the runtime to use GNU Classpath, please talk to your proprietary software vendor.

You can also try using a free runtime that supports GNU Classpath out-of-the-box instead.

4. Classpath Implementation

4.1 Why does java.lang.Throwable delay the StackTrace array construction?

Well consider what happens in a VM. VMThrowable.fillInStackTrace() is very fast -- it's just a chain of addresses. VMThrowable.getStackTrace() is very slow, because it has to convert all those addresses into StackTraceElements. I suspect that you can get the trace for the whole stack in less time than it takes to create a single StackTraceElement. For this reason, the vmState is stored and lazily converted to a StackTraceElement[]. (Andrew Haley)

A particular problem is posed by OutOfMemoryException: throwing it shouldn't require any memory (there's none anyway). Some propose that the VM should preallocate it at bootstrap, but this doesn't solve the problem. In Chris Gray's words "if several threads throw OOME at the same time, the stack traces can get mixed up [...snip...] This situation is less improbable than you might think, since if one thread encounters an OOM situation, all other threads should encounter one too. With some forms of co-operative multi-threading you may get away with it, but in the general pre-emptive case you could be living dangerously."


5. Varia

5.1 How to generate API Documentation with gjdoc/libxmlj?

Beware: generating the complete API Documentation non-trivial and the generation of a full tree takes more then one and half hour (on a 1.4 Ghz Athlon), 150+ MB of memory, at least 25MB of tmp storage, and at least twice so much in your obj build dir.

  1. set the CVS_RSH environment variable to ssh

  2. install gcj 3.3.2 (or higher)
    gjdoc CVS :ext:anoncvs@savannah.gnu.org:/cvsroot/cp-tools module gjdoc
  3. install libxmlj
    libxmlj CVS :ext:anoncvs@savannah.gnu.org:/cvsroot/classpathx module libxmlj
    make && make install

  4. For gjdoc add at the start of gnu/classpath/tools/gjdoc/Main.java (main):
    System.setProperty("javax.xml.transform.TransformerFactory", "gnu.xml.libxmlj.transform.TransformerFactoryImpl");
  5. There is a ant build.xml file, but you can also compile it all by hand together with the external/jaxp/source files from Classpath which can be copied in the src direcrory as follows:
    find * -name \*.java | xargs gcj -O2 -g -o gjdoc \
    --main=gnu.classpath.tools.gjdoc.Main

  6. Create a simple gjdoc script and put it in your PATH:
    #!/bin/sh
    CLASSPATH=/home/mark/src/libxmlj:/home/mark/src/gjdoc/src/resources \
    LD_LIBRARY_PATH=/usr/local/libxmlj/lib \
    /home/mark/src/gjdoc/src/gjdoc $*

  7. Configure classpah with --enable-gjdoc.
  8. Type make and go get yourself some coffe, take a shower and do some work in the garden.

There is one catch. The above setup is completely broken for some HTML entities (see [bugs #4823] HTML entities such as auml and nbsp should be put back in the API doc). So if you have spectacular and mysterious crashes then make sure that your java source files don't contain such entities.

Alternatively, you may also try the following command (the one used to generate the doc on http://developer.classpath.org/doc/ ):

    $(GJDOC) -public -use \
    -sourcepath "" \
    -encoding UTF-8 \
    -breakiterator \
    -licensetext \
    -linksource \
    -splitindex \
    -d html \
    -doctitle "GNU Classpath " \
    -windowtitle "GNU Classpath Documentation" \
    -header -footer \
    -subpackages java:javax:org




Return to GNU's home page.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

Please send comments on these web pages to webmasters@www.gnu.org, send other questions to gnu@gnu.org.

Copyright © 1999-2006 Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Updated: $Date: 2018/04/02 11:18:27 $ $Author: th_g $