Table Of Contents
=================

- What's this?
- Rationale
- Status & Issues
- Installing on the iLiad
- Compiling from sources
- Future
- Thanking
- Links


What's this?
============
This is an initial port of Lua gtk+ bindings from [1] for the iLiad ereader,
back-ported to work with iLiad's gtk+ v2.6. 

WARNING: this is alpha quality. It needs more work to be fully useful.
It's my first iLiad port as well.


Rationale
=========
iLiad ereader is a fascinating platform, not just a marvelous ereader.
Trying to find different approaches to develop applications for it,
python - my language of choice - was not a proper option because of the
poor performance it shows on the iLiad.
So we were looking at other languages, there lua looks like the natural
choice then, even more thanks to hansen's lua package [4].

As the iLiad uses gtk+ platform as default, I tried the canonical gtk+
bindings for Lua language in [2], but they are very difficult to compile,
even in my desktop machine, so they aren't good candidates for the iLiad.

There are other GUI options, like iup [3], but it doesn't have the
expected performance while writing complex applications either.

After all this frustration I found another gtk+ bindings [1].
They look modern, clean and the building process is quite easy.
The main problem here is that they require gtk+ version >= 2.12 and iLiad
includes v2.6. So some work was in order to make them run on the iLiad.


Status & Issues
===============
It mainly works in this initial port, but there are some problems.

The most obvious one is that, with no apparent reason, they don't use
the high-contrast theme, a must with the 16-gray colors palette in the
iLiad. So there is not enough contrast in the widgets.


Things that don't work:

- libglade
  It crashes by now, I think is due to I used a different libglade library
  that the one present on the iLiad. This problem should disappear 
  compiling these bindings in the same environment that used other people
  in their ports

- sqlite binding
  same problem than with libglade

- every gtk+ widget or feature introduced after version 2.6, as iLiad
  includes glib v2.6.6 and gtk+ v2.6.7
  . For example:
    . glib / gobject: checksum, gio
    . gdk window attribute: iscomposite
    . gtk+ widgets: assistant, builder, print, recent, statusicon, tooltip
    . gtk+ about widget attribute: program-name

- Gtktooltips
  As this widget is obsolete after gtk+ v2.6, is not included into lgui
  package in [1], so if we need tooltips widget we would need to write
  bindings for it


Anyway, with help of the community we can solve the most important issues:

1. lgui should use the high-contrast theme by default... how?

2. It looks like the other lua packages available have been linked with
static liblua.a. I've linked these with a dynamic liblua.so, so I need
to include and install it here.
Are performance benefits compiling static vs. dynamic? 

3. Could anyone (hansel? ;-) build these packages and provide an installer?
We'd need to unify packages in order to not duplicate libraries, even different
versions of them. F.e. libglade and libsqlite3 are good examples here.


Once these problems are solved, maybe we could include lobj, lgui and ldbi with
hansen's lua package. Or perhaps build different packages: lua-base, lua-gui-iup,
lua-gui-gtk, lua-sqlite, lua-extras (lfs, lxp, etc)...?


Installing on the iLiad
=======================

Of course, first of all, you need to install lua package on your iLiad
(start here [4]).

Copy next files into specified directories on the iLiad:

* file "liblua.so" (in package "bin/_lib")
  into /usr/local/lib

* dir "ldbi" and files "_lgui.so", "_lobj.so" (in package "bin/_lib/lua/5.1")
  into /usr/local/lib/lua/5.1

* dir "ldbi" and files "lgui.lua", "lobj.lua" (in package "bin/_share/lua/5.1")
  into /usr/local/share/lua/5.1

Optionally, copy the examples to the iLiad to test the bindings.
Note that some examples won't work as they are writing for gtk+ v2.12.


Compiling from sources
======================

0. Use your cross-compile environment of choice.
   I've used Adam B.'s iLiad Development VMWare image from [5]
   Note that I've needed to build glib, pango, gtk, libglade, ncurses, readline,
   lua and sqlite (IN THAT SAME ORDER) from sources.
   Versions: glib v2.6.6, pango v1.8.1, gtk+ v2.6.7, libglade v2.4.2,
             ncurses v5.4, readline v5.2, lua v5.1.4, sqlite amalgamation v3.6.10
   I've downloaded original sources from their respective home sites.

1. Get packages lobj-0.9.0.tar.bz2, lgui-0.21.0.tar.bz2 and ldbi-0.2.0.tar.bz2
   from [1]

2. Uncompress and change directories name to end with ".iliad"

3. Apply patches from src directory in this package

4. Build the binaries
   a) lobj: run "make", then "make install"
   b) lgui: run "make USE_GLADE=1", then "make install"
   c) ldbi: run "make _sqlite.so", then "male install-sqlite" 

5. install files to the iLiad (consult previous section)


Future
======

- Near
  . Fix theme issue
  . Push hansen to build and package against their libsqlite and libglade
  . Write gtk-tooltips binding from gtk+ v2.6

- Far
  . Once iLiadOS is released, and glib/gtk+ stack upgraded to last versions
    we could use original lgui packages in [1], so this backport won't be
    needed anymore.
    Also, we could include other new software: gio, cairo, gstreamer...
 

Thanking
========
Thanks for Irex Technologies for their marvelous device and for opening it.
Also to the whole iLiad community; specially Adam B, jharker, scotty1024, yokos,
antartica, nekonami, hansel, ericshliao... and many others I probably forget.


Links
=====
[1] http://oproj.tuxfamily.org/wiki/doku.php?id=projects
[2] http://luaforge.net/projects/lua-gtk/
[3] http://sourceforge.net/projects/iup
[4] http://www.mobileread.com/forums/showthread.php?t=36483
[5] http://www.mobileread.com/forums/showthread.php?s=2fb2fd35ce0f0812dcae2cf5a5ed35b2&t=10200


---- Iñigo Serna <mailto:inigoserna@gmail.com> -- Sat Feb 14 17:43:06 2009
