Subversion Repositories scarts

#!wml --include=..

#include "include/layout.wml"

##

#

# Special Tags

#

#

# 
         

#       answer

#       answer

# 

#

# the section counter

#

{#FAQINDEX#:

                . 

:#FAQINDEX#}

        . 

        %body

{#FAQINDEX#:

:#FAQINDEX#}

{#FAQINDEX#:

        . 

:#FAQINDEX#}

        
. 

        %body

{#FAQINDEX#}

GNU Classpath is a set of essential libraries for supporting

the Java programming language.

Classpath serves the same role that 

href="http://www.gnu.org/software/libc/libc.html">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.

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.

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” 

href="http://www.gnu.org/licenses/license-list.html#SunCommunitySourceLicense">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.

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:

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

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.

Please check the FSF FAQ on the GNU GPL: .

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.

Direct such questions to licensing@gnu.org. The FSF is the

official copyright holder of Classpath and sets the distribution terms

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.

See the 

href="docs/">documentation page, especially the 

href="docs/hacking.html">GNU

Classpath Hacker’s Guide, and pick up a  from the list!

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,

   )

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 

url="http://www.gnu.org/prep/standards/html_node/Reading-Non_002dFree-Code.html">.

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.

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 http://www.gnu.org/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 .

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.

gdk-pixbuf

For building the documentation you will need:

texinfo

Install from CVS

Install a release

">

  Download the current release

  unpack

  make sure you have all pre-requirements

  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.

password is anoncvs

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

Edit the script 'batch_runner' to set the variable COMPILER correctly

  (there are a couple of example settings)

Edit script 'runner' to set the variable RUNTIME correctly

  (there are a couple of example settings)

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)

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

Use CVS import and CVS update as explained in  of the CVS manual. This works well for minor changes, but has the disadvantage of a limited control on the update / merge of the sources. In fact, most of the developers prefer merging the changes by hand.

libgcj, which is almost always trying to be

as synchronized as possible with GNU Classpath CVS, has a script

that runs daily which produces a (colored) differences overview

(including patch/diffs). They also put in special markers into the

source for gcj specific changes that the script recognizes.

Script can be found at:

Daily updated result:

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.

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

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:

Update ChangeLog

Commit your changes in module Classpath to the CVS

cd doc/www.gnu.org

make

copy the modified / new pages to the website module

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.

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.

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."

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.

set the CVS_RSH environment variable to ssh

install gcj 3.3.2 (or higher)

gjdoc CVS :ext:anoncvs@savannah.gnu.org:/cvsroot/cp-tools module gjdoc

install libxmlj

libxmlj CVS :ext:anoncvs@savannah.gnu.org:/cvsroot/classpathx module libxmlj

make && make install

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");

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

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 $*

Configure classpah with --enable-gjdoc.

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

$(GJDOC) -public -use \

        -sourcepath "$(sourcepath)" \

        -encoding UTF-8 \

        -breakiterator \

        -licensetext \

        -linksource \

        -splitindex \

        -d html \

        -doctitle "GNU Classpath $(VERSION)" \

        -windowtitle "GNU Classpath $(VERSION) Documentation" \

        -header $(classpathbox) -footer $(classpathbox) \

        -subpackages java:javax:org