[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)
Log:
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.
Members:
ChangeLog:1.4689->1.4690
FAQ/FAQ.awt:INITIAL->1.15
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
+screenshot:
+ 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
+ LD_LIBRARY_PATH.
+
+ 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
+
+Troubleshooting
+---------------
+
+* 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
+decorations.
+
+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/2002-December/028462.html
+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.
+
+Projects
+--------
+
+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