Contents:

  - Build Instructions for Linux
  - Build Instructions for MingW32


Build Instructions for Linux
============================

My system is Debian/testing, where most of the required libraries are available
as packages.  Prerequisites:

  - Gtk2 (last tested with 2.12.10) with devel files
  - libffi
  - lua5.1, liblua-bit, liblua5.1-expat
  - lua sockets - required for the http/ftp etc. library
  - libcmph (optional, also at http://sf.net/projects/cmph)
  - gccxml
  - gcc, binutils, make, ...

Package names in Debian:

	libgtk2.0-dev
	libffi5-dev
	liblua5.1-0-dev
	liblua5.1-expat0
	liblua5.1-bit0
	liblua5.1-socket-dev
	libcmph-dev
	gccxml
	gcc
	make

Thanks to Enrico Tassi for building all the Lua related packages, including
this one, and even the cmph library.


About the optional cmph library
-------------------------------

  This library can compute a minimal perfect hash function, which means that
for a given set of keys, each key is mapped to an integer in the range 0 to
n-1, n being the number of keys.  There are no hash collisions and no unused
slots.

  At runtime, cmph is not required.  lua-gtk contains the (simple) code to
do hash lookups; the code to compute the hash function is much more complex.

  If this library is not available at build time, a simple hash method is used
instead.  There is probably little runtime difference, both size and speed
wise, although I suppose the cmph generated hash will be faster; it requires
two hash values to be computed, but doesn't have collisions, while the simple
code needs just one hash computation, but has lots of collisions as well as
empty buckets.  The resulting library is about 20 kB smaller with cmph.


Procedure
---------

 - optionally, run ./configure (try --help, and see below)
 - run "make"
 - as root, run "make install".  Alternatively, create symlinks which is
   nice during development:

   /usr/local/lib/lua/5.1/gtk.so --> ..../lua-gtk/build/linux-i386/gtk.so
   /usr/local/share/lua/5.1/gtk --> ..../lua-gtk/lib

Now you should be ready to run the example scripts:

$ lua examples/button.lua
$ lua examples/pixmap.lua


configure options
-----------------

  --debug

	Compile with debugging information and without optimization.  Results
	in a larger and slower binary, but this is useful for testing and
	making sense out of core dumps.

  --no-summary

	Omit the summary and makes configure run silently unless an error
	occurs.  Not recommended.  In case of bug reports in would be useful
	to include this information.

  --diable-debug

	Omit a few debugging functions like gtk.dump_struct, dump_stack,
	set_debug_flags and others.  This reduces the size of the library
	a little.

  --disable-gtkhtml

	The GtkHtml library is optional, but if you have it installed (with
	development headers) but don't want to have support for it, give
	this option.  Note that even if it is enabled, and you have runtime
	linking enabled (default on non windows architectures), no error
	will happen at runtime if the library isn't available - until you try
	to use it.

  --disable-dynlink

	Normally the library (gtk.so) is not linked against any other libaries,
	but loads them dynamically at runtime.  This makes all libraries
	optional, e.g. libgtkhtml; if it's not present, gtk.so will still load
	and simply report an error when unavailable functions are about to
	be called.

  --host [ARCH]

	Specify for what target architecture to compile.  A list of known
	architectures is listed


Cross compiling
===============

  Some attempts have been made to cross compile from i386 to other
architectures, like sparc, mips, hppa and so forth.  On Debian, try the
following steps to get started:

1. Add the following lines to /etc/apt/sources.list:

	deb http://debian.speedblue.org ./
	deb-src http://debian.speedblue.org ./

2. Run aptitude, or your favourite frontend to apt, and install the following
   packages.  Replace "sparc" with whatever architecture(s) you are interested
   in.  Keep in mind that qemu doesn't support all CPUs.

	qemu
	apt-cross
	gcc-4.1-sparc

3. optional - configure the kernel to automatically use qemu to run foreign
   binaries using the binfmt_misc module; execute these as root:

	modprobe binfmt_misc
	script/qemu.sh

4. install the ffi library for the architecture:

	apt-cross -a sparc -i libffi4-dev

5. build the library

	./configure --host linux-sparc
	make

If the build succeeds, you will now have a build/linux-sparc/gtk.so.  This may
or may not work, and in the end you can't test it with qemu, because the
other binaries (lua, gtk etc.) are not there.  I installed them using
apt-cross, but for some reason, maybe libc incompatibility, this fails to run.



Documentation
=============

  The included documentation is partly built directly from the Lua and C
sources.  This requires an improved version of luadoc, not yet publicly
available, but I'm trying to get the changes into the official luadoc.



Build Instructions for MingW32
==============================

To build this package for Windows please use MingW32.  The resulting binaries
run on native Windows.  In other words, you'll be cross-compiling from Linux
to Windows; I don't have a development environment under Windows to build it
natively.  Therefore, install the mingw32 build environment.  For Debian,
install the following packages:

	mingw32			The actual cross compiler.
	gcc-mingw32		The actual cross compiler (alternative).
	wine			To run the cross compiled binaries
	lib32nss-mdns		on amd64, required for Wine.
	libwine-dev		Contains headers like windows.h

Note that the package gcc-mingw32 is smaller and more up-to-date, so you
should probably install that.


Step 1
------

  Please refer to README.win32.txt on instructions on how and where to get the
latest Gtk+2 libraries.  You need quite a few ZIP files for the individual
components.  To make this easier, use the provided script:

	mkdir -p mingw/gtk-zip mingw/gtk
	script/download-gtk-win.lua mingw/gtk-zip
	cd mingw/gtk
	for i in ../gtk-zip/*.zip; do unzip $i; done

  Then install the Gtk runtime (not the -dev packages, just the normal ones)
onto a Windows box.  Again, see README.win32.txt on how to edit the registry
to add the install path to the search path.  It is possible to try it out with
wine, although the fonts are at a huge size, I haven't figured out why, YMMV.

  Interestingly, a few files seem to be missing from gtksourceview-2.2.2.zip,
namely the *.rng files.  You have to copy them from the Linux package!  If
these files are not present, you'll get this error message:

	"could not find the RelaxNG schema file"

  Copy the files styles.rng, language.rng and language2.rng from
/usr/share/gtksourceview-2.0 to the appropriate directories of your Windows
installation.


Step 2
------

Build the library by calling

	./configure --help
	./configure --host win32-i386
	make

If gccxml produces an error, please try configuring with "--without gtkhtml",
this fixes it for me.

This builds the file build/win32-i386/gtk.dll.  To obtain a ZIP file with all
the required files, do this:

	make zip

This will create the tree /tmp/lua-gtk-$(VERSION), along with a suitable
ZIP file.  Copy that to the windows box, and try it out.



[1] http://luabinaries.luaforge.net/packaging.html,
    http://luabinaries.luaforge.net/download.html
    The file to get is lua...._Win32_bin.zip