[kaffe] CVS kaffe (robilad): added information on peerless AWT switches to FAQ.awt

Kaffe CVS cvs-commits at kaffe.org
Sat Mar 25 05:25:46 PST 2006

PatchSet 7171 
Date: 2006/03/25 13:16:11
Author: robilad
Branch: HEAD
Tag: (none) 
added information on peerless AWT switches to FAQ.awt

2006-03-25  Dalibor Topic  <robilad at kaffe.org>

        * FAQ/FAQ.awt: Added information on runtime switches to use
        the peerless AWT implementations.


Index: kaffe/ChangeLog
diff -u kaffe/ChangeLog:1.4689 kaffe/ChangeLog:1.4690
--- kaffe/ChangeLog:1.4689	Fri Mar 24 22:36:45 2006
+++ kaffe/ChangeLog	Sat Mar 25 13:16:11 2006
@@ -1,3 +1,8 @@
+2006-03-25  Dalibor Topic  <robilad at kaffe.org>
+	* FAQ/FAQ.awt: Added information on runtime switches to use
+	the peerless AWT implementations.
 2006-03-24  Dalibor Topic  <robilad at kaffe.org>
 	* README, configure.ac: bumped up version to 1.1.7-rc2.
Checking out kaffe/FAQ/FAQ.awt
RCS:  /home/cvs/kaffe/kaffe/FAQ/FAQ.awt,v
VERS: 1.15
--- /dev/null	Sun Aug  4 19:57:58 2002
+++ kaffe/FAQ/FAQ.awt	Sat Mar 25 13:25:45 2006
@@ -0,0 +1,310 @@
+FAQ for the AWT
+AWT Implementations
+Since Kaffe 1.1.5, we have successfully merged the peerful AWT implementation
+based on GTK+ from GNU Classpath, and the old one, peerless lightweight AWT,
+is renamed as kaffe-awt. The so-called peerful AWT implementation intends to
+map Java AWT peers into the corresponding widget set of specific environment,
+and that is GTK+ for the case of current GNU Classpath development. In other
+side, the original peerless kaffe-awt is lightweight, which means that it
+only makes use few necessary dependencies for basic requirements, such as 
+window creation, drawing operation, color allocation, etc. You could find
+that peerless AWT implementations look alike among different backends, while
+the peerful AWT implementations differ a lot. Jim Huang prepares a compre-
+hensive comparisons of existing AWT implementations as the following
+  http://www.kaffe.org/~jserv/awt-implementations.png
+Selection among different AWT implementations in Kaffe is very easy, just
+use "kaffe -help" to dump help message. For example pass -Xkaffe-xlib-awt 
+to force KaffeVM to use Xlib-based AWT backend, while GNU Classpath's AWT
+is selected by default.
+GNU Classpath AWT implementation
+GNU Classpath AWT implementation is enabled in default build process, but
+the original peerless AWT ones are turned off. We attempt to merge AWT/Swing
+implementation from recent GNU Classpath cvs repository. To build this, make
+sure if GTK+ 2.4 and its development packages are available. Optionally, you
+might need Cairo Graphics framework (http://www.cairographics.org/) to enable
+the new Graphics2D implementation, which is reported to let many complex AWT
+and Swing applications, such as JFreeChart, run well. Tell configure script
+with --enable-gtk-cairo to enable new Graphics2D, and drive your Java startup
+command with -Dgnu.java.awt.peer.gtk.Graphics=Graphics2D to use Cairo-based
+Graphics2D implementation.
+GNU Classpath AWT is very excellent to meet the specifications of Sun JDK,
+and you can look into the latest comparison from [Results of comparison 
+between jdk14 and classpath]:
+  http://www.kaffe.org/~stuart/japi/htmlout/h-jdk14-classpath.html
+Peeless AWT implementations
+[= 1.0.2 Event Model / Deprecated methods =]
+We do support the old 1.0.2 event model and all 1.0.2 deprecated methods,
+[= Swing =]
+We completely support Swing. The version that works best with kaffe is
+the JFC 1.1 with Swing 1.1.1, which is labeled as EOL (End-Of-Life), and
+you might have to browse Sun's web page to seek for archive download:
+  http://java.sun.com/products/archive/index.html
+Note: Later versions may or may not run. Patches to get them to run are 
+welcome. It would be in general preferable to help out GNU Classpath to 
+implement SWING, though.
+Whatever Sun may tell you about Swing being 100% pure Java - just don't
+believe them.  Swing make a number of assumptions about the underlying AWT
+implementation and makes calls to a number of "banned" methods - oh and it
+makes extensive use of deprecates.
+[= Selecting an peerless AWT implementation =]
+Currently, the peerless AWT implementations are disabled in default build,
+and you have to pass --with-kaffe-x-awt to configure script. Also, there 
+are different peerless AWT backends for Kaffe. You can configure it to
+use a specific one, by using the --with-awt option of the configure script.
+So far, you have the following choices:
+* --with-kaffe-x-awt
+  an X lib based AWT backend. It is the default AWT backend if the X
+  Window system is detected by the configure script.
+  The X lib based AWT backend has been written by Peter Mehlitz from
+  Transvirtual.
+  See http://www.x.org for information on X Window System.
+  You need to run kaffe with -Xkaffe-xlib-awt option, in order for it
+  to load the correct classes for this AWT. So you should run your
+  code with
+  kaffe -Xkaffe-xlib-awt YourClass
+* --with-kaffe-qt-awt
+  a Qt based AWT backend. It uses Trolltech's cross-platform graphical
+  library. It works with Qt 3 and Qt 2, Qt/Embedded or Qt/X11 version. 
+  It should also work with Qtopia. 
+  It may work with other versions of Qt 3 or Qt 2 (Win32, OS X), but
+  it has not been tested in such configurations. If you can test it in
+  such configurations, please report your experiences to the Kaffe
+  Mailing List, kaffe at kaffe.org.
+  If you are developing against a dynamically linked version of Qt,
+  you need to compile kaffe with dynamically linked libraries. If you
+  are developing against a static version of Qt, you need to compile
+  kaffe with statically linked libraries. In general, you should try
+  to match linking types of libraries.
+  In order to compile the Qt based AWT backend, you need to have an
+  installation of Qt libraries including the moc compiler and the Qt
+  header files. You have to pass the full path to the directory of
+  your Qt installation to the configure script using the --with-qtdir
+  option. 
+  You also have to make sure the moc compiler is in your $PATH. It can
+  usually be found in the bin directory of your Qt installation. If
+  you can not find it, you need to install the developer version of the
+  Qt libraries. How to do that is system dependent, on Linux you may
+  have to get a libqt3-developer package for your distribution, or
+  compile Qt from scratch.
+  Finally, in order to be able to dynamically link Kaffe's AWT backend
+  with the Qt libraries, you may have to add the lib directory of your
+  Qt installation to your native linker's library lookup path. On
+  Linux, that means you may have to add the lib directory to
+  The initial Qt based AWT backend was written by Murphy Chen and Ken-Hao
+  Liu from Dialogue Technologies, Inc.
+  More information on Qt is available from http://www.trolltech.com.
+  You need to run kaffe with -Xkaffe-qt-awt option, in order for it
+  to load the correct classes for this AWT. So you should run your
+  code with
+  kaffe -Xkaffe-qt-awt YourClass
+* --with-kaffe-nanox-awt
+  a Nano-X based AWT backend. It uses famous Nano-X library provided
+  by Nano-X Window System (formly known as MicroWindows, the project 
+  has been renamed to The Nano-X Window System, due to conflicts with 
+  the Windows trademark registered by Microsoft.)
+  The latest version of Nano-X we developed with is 0.9.0, and it 
+  should be API-compatible with earlier versions.
+  The initial Nano-X based AWT backend was written by Exor International 
+  Inc. and Sinby Corporatin in 2001, and we have reviewed their design
+  and implementation to merge in.
+  To enable Nano-X based AWT backend, you should also pass the extra
+  two options to configure script, --with-nanox-include and 
+  --with-nanox-library, to specify the the corresponding Nano-X path.
+  See http://www.microwindows.org/ for informations on Nano-X.
+  You need to run kaffe with -Xkaffe-nanox-awt option, in order for it
+  to load the correct classes for this AWT. So you should run your
+  code with
+  kaffe -Xkaffe-nanox-awt YourClass
+* Qt-based AWT backend
+  * Compilation problems
+    Make sure that either QTDIR is set, or that you passed a
+    --with-qtdir flag to the configure sript. Don't use relative
+    paths to specify directories.
+  * Moc trouble
+    Make sure that the build system picks up the right moc for the
+    version of qt you are compiling against. So if you have several
+    versions of qt installed on your system, put QTDIR/bin to the
+    front of your PATH before you start configuring and building
+    kaffe.
+  * Linker complains about missing symbols
+    That could be an instance of moc trouble above, but more often
+    it's a problem between C++ ABIs of the compiler used to build qt
+    you want to link against, and the compiler you used to build
+    kaffe's Qt-based AWT with.
+    The GNU C++ compiler g++ had a short period where the ABI changed
+    with almost every release, so if you are using a Qt library
+    compiled with one of those 'interim' versions, your best bet is to
+    rebuild Qt frim scratch with your current compiler.
+  * QTDIR, QTEDIR, QPEDIR is pointing to the wrong directory.
+    Qt uses QTDIR to find its fonts, and may use the other environment
+    variables to locate other crucial bits for execution. Make sure
+    that you've got them pointing to the right directories, i.e. the
+    versions you compiled against. Read Qt toolkits installation
+    description for more information on those environment variables.
+  * Dynamical linking fails 
+    Make sure that you've linked to correct versions of Qt
+    library. Use ldd to check if KAFFE_HOME/jre/lib/your-cpu/libawt.so
+    links to it.
+    Other that that, you should make sure that the Qt libraries can be
+    found by the linker. Putting QTDIR/lib in LD_LIBRARY_PATH might
+    help.
+  * Qt AWT backend can't show GIF images
+    Currently, Qt AWT backend handles all images routines via Qt
+    toolkit, and this behavior is totolly different to X AWT backend.
+    The GIF support is disabled by Qt's default configuration, and
+    you need to reconfigure to enable the feature if you would like
+    to let Qt AWT backend support it.
+  * Qt/Embedded AWT doesn't work in console
+    You need to redirect the stdout and stderr streams so that they
+    don't interfere with the framebuffer. The Qt based AWT
+    implementation is still rather rough, so it prints a lot of
+    debugging output which confuses the framebuffer, apparently.
+  * Qt AWT backend crashes, how can I help?
+    First, Qt AWT backend in Kaffe is still buggy, so any feedback 
+    is important to developers for improving. You may attempt to 
+    enable the debug option in Kaffe (configure as --enable-debug 
+    support, read FAQ/FAQ.debugging), and execute a Java AWT 
+    application like:
+      kaffe -vmdebug AWT -cp <CLASSPATH> <CLASSNAME>
+    Qt AWT backend will dump debug messages in stderr, and you could
+    redirect to text file. To specify the Qt AWT native part, you
+    pass some arguments, such AWT_EVT, AWT_CLR, etc. to -vmdebug 
+    option.
+  Finally, try to figure out what's wrong using a debugger according
+  to the debugging messages you obtain. Good luck and please keep in
+  touch with the kaffe mailing list kaffe at kaffe.org.
+Other AWT backends
+The source code for the PocketLinux version of Kaffe includes AWT
+backends for many other graphical toolkits. If you are interested in
+helping the Kaffe developers merge them with the Kaffe.org sources,
+contact us on the Kaffe Mailing List kaffe at kaffe.org.
+The list of backends from PocketLinux includes Gtk1, grx, peg, Allegro
+and a few others. The major difference in native AWT implementation
+between Kaffe.org's and PocketLinux's is that PocketLinux's AWT 
+depends on more native functions from graphics toolkit / widget set 
+for the advanced usage. For example, PocketLinux's AWT implementation
+even supports the dynamic theme switching feature with more 
+There are other AWT backends written by third party developers that
+haven't been merged in yet:
+* DirectFB
+See the following posts for more information:
+http://www.kaffe.org/pipermail/kaffe/2005-February/101410.html .
+If you are interested in merging them in, contact the Kaffe Mailing
+List on kaffe at kaffe.org.
+If you want to contribute to kaffe's AWT developement, you could
+* Write documentation
+  Document the workings of kaffe's AWT to make life easier for porters
+  and mergers.
+* Refactor current AWT implementation
+  The AWT implementations share some common native code that should be
+  in a common AWT library. Take a look at Pocketlinux for an idea.
+  Kaffe's AWT doesn't follow Sun's peer concepts, and makes it hard to
+  'override' the default AWT implementation. Refactor kaffe's AWT to
+  allow alternative AWT implementations (like PJA) to be plugged in
+  easily, and to allow multiple native AWT backends to be built and
+  selected at runtime.
+* Merge in another AWT implementation
+  Pick one of the Pocketlinux AWT implementations, and merge it in.
+* Write another AWT implementation
+  If your platform has a native graphical library, then the presumably
+  fastest AWT implementation would use the native toolkit.
+  Or go the other way around, and write an AWT implementation for a
+  cross platform graphical toolkit, like wxWidgets, or SDL, bringing
+  AWT to platforms where no Qt or X11 are available.

More information about the kaffe mailing list