- current build status

	sparc: builds; all tests fail; gtk.window_new not found.
	powerpc: builds; all tests fail; gtk.window_new not found
	i386: builds; test #11 fails
	amd64: builds; some tests fail
	hppa: builds; all tests fail; gtk.window_new not found
	s390: builds; all testse fail; gtk.window_new not found;
		gtk.GTK_CAN_DEFAULT not found
	mipsel: liblua5.1-bit0 not found

	armel: 0.9 port works thanks to the access to such a box thanks to
	Martin Guy.  The changes have to be ported forward to trunk.

determine .so to link to at configure time, should be /usr/lib/libatk-1.0.so.0
etc.

provide an option to statically link to libffi5



CURRENT
=======

 - add an entry on freshmeat.net, see
   http://freshmeat.net/tags/lua.  search for "gtk repository"

 - failures in tests 016, 018, 023, 030
   due to loading of older versions of modules. Ensure that some kind
   of versioning catches this.
   	1. remove the "hash_method" field of the API.  The core module
	   supports multiple hash methods.
	2. the struct module should say which hash method is used.
	   in lg_register_module check that this is a supported method.
	3. maybe add version numbers to the supported hash methods so
	   that enhancements can be made.

 - when configuring with debug on/off, if changed, the next recompile should
   rebuild all .o files, which doesn't currently happen.

 - cmph has only been tested with the bdz algorithm.  Allow for multiple
   algorithms to be compiled in, selectable at build time of the core module.

 - build on linux-amd64: va_list is not available, because its full_name
   is va_list[0].  script/parse-xml.lua:mark_override() works with the
   full names, though.

 - src/gtk/spec.lua (and others) contain the absolute path to the library
   to load.  This is not correct, it should be retrieved using pkg-config
   or similar methods.

 - make the configure/build process more robust

 	- check for gccxml (maybe only in the core module)
	- modules may have additional flags to configure
	- when changing config, recompile hash/hash-generate-cmph.  If a
	  different cmph version is used, constants may change.
	- don't generate unused .c files in build/gnome: types.c, globals.c.

	- detect non-existant foreign (non-native) types at build time.  This
	  requires the modules that should provide the type to be already
	  built.

 - support cmph 0.9 and its new algorithm CHD, see http://cmph.sf.net/

 - make the use of arg_flags clearer.
 	1. bits 0-3 are reserved by the core module.
	2. a per-module callback handles values with bits set 4-7

 - check the required hash algorithm and method at module load time.  store
   it alphanumerically in the module header.  used for:
	- hashes of fundamental type names
	- hashes of names of non-native types
	- stored again for each hash table
   Does it make sense to compile hash algorithms, methods separately and load
   them on demand?  Probably not.  But anyway the core module should be able
   to provide more than one hash method.

 - test build-time linking

 - test the windows build some more

 - remove overrides for return values and replace with argument flags
   An additional mechanism would be required to replace the "FSO" overrides;
   maybe keep them.



BUGS
====

- some event handler get an event object that contains NIL things for
  ev.key etc., i.e. the aliases don't work.  When garbage collection is
  off, this doesn't seem to happen.  Gdk passes the same events (same
  addresses) in subsequent invocations of the handler, but the Lua program
  must not keep a reference to it I guess, as events have no refcounting.
  So, after a handler has run, the Lua object and all aliases must be
  destroyed?


- x = gtk.hscale_new(nil)
  dump.struct(x)
  --> unresolved type gtk.70, should be defined in gdk.
  This type is GdkColor[4], which is NOT provided by gdk.  Instead, such
  arrays must be a native type, referring to a possibly non-native type.

- x = gtkhtml.view_new()
  x:show()
  --> HtmlView.show not found.  GtkLayout not found (in gtk), as this type
  isn't used there.
  Any "struct *xxx" being defined could, basically, mean that a "struct xxx"
  is also created as a type, or at least registered with its hash value.

- when freeing structures allocated with "new", they must be properly freed,
  e.g. when "char*" fields exist, free them...

- glib.printf("%f\n", 20.0) fails: value pushed as integer, and not as float.
  see src/gnome/types.c(623):lua2ffi_vararg().
  solution: glib.printf("%f\n", gnome.box(20, "double"))

- lua2ffi routines should be called with ar->index == ar->func_arg_nr.
  This way, messages by luaL_checktype etc. would be correct, and
  ar->func_arc_nr can be discarded.

- g_assertion_message is used in GLib starting with 2.15 for the macro
  G_VALUE_COLLECT.  If lua-gtk is compiled for 2.15 or newer, this call
  will be there.  But when used with an older GLib version e.g. 2.14,
  this will fail.  A warning is shown at startup.

- signals connected with GtkBuilder on menu items create a GtkAction object
  which is not freed.  What about that?  See src/gtk/override.c:_connect_func.

- overrides don't do the trace output, which happens in lg_call.

  Solution 1: instead of calling luaL_register() on the override list in
  src/gnome/data.c, add a new closure for each of the functions that
  prints the trace (if enabled), and then calls the actual function.  It could
  get the underlying function's signature?

  Solution 2: explicitely call a tracing function from each override,
  supplying the override name.  This is more work, makes overrides more
  complicated, but may require less memory (no closures to create) and run
  faster (C call instead of Lua call).


  GdkColor...

- The size field for structure elements should not be set if the referenced
  type has this info.  Must be present for bitfields, but max. value should
  be 32 (or 64 on 64 bit archs).

  Interestingly, sometimes the size is set for fundamental types (like struct,
  union) when this type has no fixed size.  This size should be zero!

- maybe check the "const" flag sometimes at runtime for something?  disallow
  writing into such structures.

- g_convert & friends on win32 don't work.  some library component missing?

- GSList.  you have to call g_slist_free() yourself.  what about the
  items pointed to?  

- check refcounting usage, memory leaks
	- valgrind
	- glib memory statistics
	- make sure my reference counting (g_object_ref/_unref) is correct.
	  seems to be ok...
	- refcounting on GIOChannel not OK.  Sometimes in-use channels are
	  freed, which aborts communication. (probably already fixed)
	- GObject documentation on memory management says that when an object
	  is destroyed, the "dispose" handler should release all references
	  it might hold, while finalize really frees the object.  Does this
	  apply to lua-gtk?  Usually GObjects will have just one ref from
	  Lua, while the Lua proxy object may have multiple references.

- running Win executables with wine under Linux, and using glade.lua - font
  sizes are insanely large.

 - memory corruption in examples/raedic.lua: query twice and then exit.
   2008-08-26 doesn't seem to happen anymore.


MISSING FEATURES
================

- socket_co: connect attempts must be asynchronous, otherwise the GUI can be
  blocked (by a slow DNS server, for example).
	getaddrinfo_a in libc.  available in mingw?
		libws2_32.a has _getaddrinfo@16, but not getaddrinfo_w.
  	libc-ares2, 123 kB
	adns -- quite "fat" according to udns description.  160 kB
	write an own non-recursing simple dns resolver?  might be easy.
	http://www.network-research.org/udns.html
	udns
	libunbound1
	libldns1

- handle data type float*, e.g. GtkCurve.ctlpoint

- handle data type "signed char", e.g. GdkEventAny.send_event

- wrapper for gtk_tree_model_get would be nice.

- accept GdkAtom enums in lua2ffi_struct_ptr, or rather make GdkAtom #defines
  behave like struct*.

- more documentation
	- user documentation must be written by hand, the luadoc output
	  is cute but not really helpful.
	- set up a wiki to edit documentation?
	- improve the homepage, add more content, better layout
	- use luadoc tags for all user visible functions in the C modules
	- developer documentation to give pointers for hacking

- call tracing should show the actual values of the arguments; would require
  a new callback for each parameter type, some kind of tostring.

  - implement this entirely in the debug.c file
  - use the CONV_xxx constants, no extra data in type_info
  - alternatively, show the Lua value directly, i.e. before type conversion.
    this is probably not as useful.

- try LuaJIT - should speed everything up.  at least check that it works with
  it because in a larger project, somebody might want to use it.



IMPROVEMENTS
============

 - add basic profiling capability
	- question: what part of the runtime is in Lua, what in the libraries?
	- time calls into the library in lg_call
	- time callbacks
	- time closure invocations

 - use GIR (gobject introspection) to obtain all the data which is now
   generated by parse-xml.lua.  See

	   http://live.gnome.org/GObjectIntrospection
	   Debian Package: libgirepository-1.0-dev
	   Files in /usr/share/gir-1.0 and /usr/lib/girepository-1.0

   The GIR files come in two flavors, XML and binary, which can be converted
   into each other.  Currently, the binary representation has less information:
   some type information is missing, like the "c:type" tags that would be
   necessary to determine the number of indirections.

   As of 02/2010, the data seems still too buggy to replace the current data
   which is extracted from the header files using gccxml.  Another binding
   using GIR already exists, lgob, which has a more object-oriented approach.
   It has a code-generator and therefore has one wrapper function per supported
   library function, leading to a rather heavy binding.

   http://oproj.tuxfamily.org/wiki/doku.php?id=lgob


 - reduce size:
 	Data			Old	New	Delta
	----------------------------------------------
	constants		39711	41190	+1479
	functions		59975	58668	-1307
	structs			98301	113742	+15441
	 - type_list		16624	29432
	 - elem_list
	 - strings_types	25725	22192
	types			1107	1868	+761
	globals			1502	847	-655
	----------------------------------------------
	TOTAL					+15719

 - optimize argument flags: separate into a TYPE part (e.g. ARRAY)
   and FLAG part (e.g. ALLOCATED).  Are all of these flags required?

- would it be possible to adjust the refcount of an object each time the
  Lua proxy object is ref/unref'd?  This would reflect the refcount more
  accurately.  NO: lua_pushvalue(L, i) just copies a pointer, doesn't call
  anything.

- add an argument flag that says "defaults to NIL if missing without error".
  This would make the override for gtk_tree_model_get_value superfluous, and
  maybe other overrides as well.

- can src/boxed.c and src/voidptr.c be merged?  Both wrap a Lua value in a
  C structure.

- reduce the size of struct type_info to 6 bytes instead of 8: possible, would
  save about 4 kB across all current modules - not worth it.

- reduce the size of struct struct_elem - could be reduced to 6 byte (48 bit)
  from the current 64 bit.  Total size currently 26496 bytes (3312 elements),
  would shrink to 19872, saving about 6 kB. - not worth it.

  - Try to reduce
	2. more efficient encoding of enum data?

	3. in production, enum data could be used without hash values; saves
	   about 10k, or just one byte of hash value, saves 5k

	4. More efficient encoding of function prototypes?  try different
	   variants. Current version:

	   	0	invalid
		1-127	this type
		>128	unset high bit, shift right 8 + add next byte

		one byte encoding enough 17500/23100 times = 76%
		total = 17500 + 5600*2 = 28700

		0	invalid (required for something? maybe not)
		1-249	this type
		250	next byte + 250
		251	next byte + 250 + 256
		252	next byte + 250 + 256*2
		253	next byte + 250 + 256*3
		254	next byte + 250 + 256*4
		255	two bytes follow for full range

		one byte enough 19580 times = 85%
		total = 19580 + 3520 = 26620 bytes

		The three byte version is required for > 1530 types, which
		is currently not reached.

		Not much to be gained.

	5. try to combine strings.
		long_some_thing
		some_thing
		thing
		GtkMenu
		GtkMenuBar
		GtkMenuBarButton

		Store 16 bit offset plus 8 bit length
		Strings stored without NUL byte
		Generation:
			- build a list of all strings
			- find common substrings.  maybe descending sort
			  by string length, and search substring before adding
			  for each string.
			- an object might encapsulate this functionality

	6. remove the func_nnnn dummy type names and element names.  Use just
	   "func" or so for all of them.

- Fully support Arrays.  The information is already there, but I think
  it is not possible to access the elements of an array with [].
  
- Substructures and subunions are currently ignored.  Must be supported e.g.
  for GdkEvent.  This has worked before?

  The elements can be accessed, though, e.g.
  dump_struct(gdkevent.grab_broken).  So, in reality, the data is all there.
  Just drop the warning messages?

- use a better module definition, see
  http://lua-users.org/wiki/LuaDesignPatterns

- Additional Library Support.

  Done: Cairo, GLib, GObject, ATK, Pango, gdk-pixbuf, GDK, GTK+, GtkHTML,
  libxml2, gio, GtkSourceView, GtkSpell.

  GNOME Developer Platform Libraries (only non-deprecated):
  glib, gio, gobject, atk, at-spi, gail, pango, gdk-pixbuf, gdk, gtk+,
  libxml2, libxslt, libglade, gconf.

  Still missing:
  at-spi, gail, libxslt, libglade.

  Other non-Gnome libraries that build on GObject:
  vte, webkit, gstreamer, libgtkimageview0, gtask, gtkhotkey

  Other libraries that could also be supported, but are not based on GObject:
  libunique


	gio
		pkg-config gio-2.0 gio-unix-2.0

		#include <gio/gio.h>
		#include <gio/gunixmounts.h>
		#include <gio/gdesktopappinf.h>
		#include <gio/gunixinputstream.h>
		#include <gio/gunixoutputstream.h>
	
	at-spi
		install libatspi-dev, libatspi1.0-0

  - GL
  	libgtkgl2.0-dev
	libgtkglext1-dev

  - GDA
  	libgda3-dev

  - GD2
  	libgd2-xpm-dev
	libfreetype6-dev
	libpng12-dev
	libjpeg62-dev

  - GAIL
  	libgail-dev

  - Gnome Libraries
  	libgnome2-dev
  	libgnomedb3-dev
	libgnomeprint2.2-dev
	libart-2.0-dev

  - libxslt
	libxslt1-dev

  - libglade - maybe not, use GtkBuilder

  - GtkImageView
    libgtkimageview0
    libgtkimageview-dev
  http://trac.bjourne.webfactional.com/

- GCC attributes.  Use when GCC is available.

http://gcc.gnu.org/onlinedocs/gcc-4.1.1/gcc/Function-Attributes.html



How does this compare to the "alien" library?
http://alien.luaforge.net/

 - alien is not designed to support a large number of functions efficiently;
   they have to be declared individually.
 - doesn't know about Gtk's type hierarchy

- Support easy modification of metatables of widgets.  Something like
  gtk.get_metatable "GdkWindow" or similar.  Maybe make it as simple as

  	mt = gtk.get_metatable "GdkWindow"
	mt.__get_xid = function(w) return gdk.gtk_x11_drawable_get_xid(w) end


DOCUMENTATION
=============

  - write some more documentation (on the website), in addition to the
    automatically generated documentation (luadoc).  Interesting topics

  - update the website with current examples; e.g. glade.lua should not
    be used anymore, instead use GtkBuilder.

  - assign more error numbers and document them in src/*/messages-en.html

  - set up a website to translate messages



TRANSLATION
===========

 - convert all messages to use one of the three translation macros.
 	luaL_error, luaL_argerror

 - Lua code that looks through C source files and extracts messages; uploads
   all these messages through a web interface to the translation website.
   needs proper authorization!

	- scan source files, extract messages and locations. (ok)
	- login with challenge/response
	- fetch existing messages: send a module name, retrieve a list of
	  message IDs along with hashes of the message text and the
	  locations. (WIP)
	- upload all changed messages as well as vanished messages (serialized
	  Lua table).  retrieve the answer (error messages etc.) and display
	  them. (missing)
	
	- detect re-use of existing message numbers. (missing)
		- a message already exists
		- the message is different
		- no known location matches the new location (with fuzz)

 - help coders assign new message IDs.  On the website, display the next
   free id. (ok)

 - Descriptions can now only be entered on-line, no text file anymore. (missing)

 - Code to dump the translations into Lua files, which are loaded at runtime on
   demand.  This should work with a remote server and not access a database
   directly. (missing)

 - These translated files should be in CVS too to have them under version
   control.  Now and then check in the changes.  This is a backup of the
   in-database data.  Have code ready to load the DB from the dumped files;
   these should therefore contain all the data (or all relevant data) of the db.

 - Code to dump descriptions into .html.in files for documentation.  This
   should work with a remote server and not access a database directly.
   (missing)

 - Web module to view descriptions of messages on-line. (missing)