Developing and using Qt based applications written in Java
==========================================================

This document explains how to develop and use Qt based programs
written in Java.  This is what the Qt java bindings from the package
libqt3-java are designed to accomplish.

Firstly, the bindings should work with any java compiler and VM
properly implementing the JNI interface, but they have only been
tested with the GCJ compiler and GIJ interpreter from the GCC suite.
Note that the bindings are not compiled to native code, using GCJ's
unique capability to do this, they are simply compiled to .class
files, and interpreted, in the classical Java manner.

Secondly, when compiling and running apps using the Qt Java bindings,
you need to add "/usr/share/java/qtjava.jar" to the CLASSPATH.  E.g.

	export CLASSPATH="/usr/share/java/qtjava.jar:/usr/share/java:."
	javac Whatever.java
	java Whatever

And, that's basically the hard part of it all.  For the rest,
developing Qt Java apps is much like Qt C++ apps, except that working
with slots is easier, and compiles may be faster as well.  The API
should be completely similar to the Qt C++ API, so the standard Qt
docs should translate pretty easily.  There are a lot of Qt Java usage
examples in /usr/share/doc/libqt3-java/examples.

If you're interested in developing KDE applications using Java, look
at the libtrinity-java package.


Generating native executables
-----------------------------

It is also possible to produce native executables with the following gcj
invocation:

	export CLASSPATH="/usr/share/java/qtjava.jar:/usr/share/java:."
	gcj -fjni Somefile.java /usr/share/java/qtjava.jar --main=Somefile
	LD_LIBRARY_PATH=/usr/lib/jni ./a.out

As this will compile the full qtjava.jar into native code, the resulting
executable will be rather large. If you plan on having several of these
executables, it may be worth creating a shared qtjava library, like
this:

	gcj -fjni -shared /usr/share/java/qtjava.jar -o libqtjava-shared.so

And then, after you put libqtjava-shared.so in /usr/lib or similar, you
can go like:

	gcj -fjni Somefile.java --main=Somefile -lqtjava-shared
	LD_LIBRARY_PATH=/usr/lib/jni ./a.out

In the future, I'll investigate the possibility of shipping the
qtjava-shared library in the Debian packages.

Also, in order to avoid the necessity of setting the LD_LIBRARY_PATH
environment variable, the option -Djava.library.path=/usr/lib/jni can be
passed to the gcj invocation. There is, however, a bug [1] in gcj that
prevents this from working, and it's only fixed in gcj-4.0.

    [1] http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18234