GTK Sudoku 0.3 released and lessons learned

[ramsdell@... (John D. Ramsdell)]

GTK Sudoku 0.3 has been released on LuaForge.  GTK Sudoku is a puzzle
solving aid.  A Sodoku logic puzzle is solved by filling each cell in
a board so that every row, column, and 3x3 square contains the digits
one through nine.  This program eliminates much of the drudgery of
solving a puzzle and provides educational tips should the path to the
solution become obscured.  It is different from most other programs in
this category, because users specify the rule that justifies each
change to the Sudoku board.  The program will fail to apply a rule if
its preconditions are not met, thus detecting silly mistakes early.

I thank LuaForge for hosting the GTK Sudoku project at
<http://luaforge.net/projects/gtksudoku>.  As I expect most people
downloading GTK Sudoku will be unfamiliar with Lua, its nice to have a
place that allows browsers to see what else Lua can do.

Before I list the lessons learned from this project, let me set the
context.  GTK Sudoku was constructed by wrapping a GUI around a
formerly text-based interactive Lua script.  I've been using and
tinkering with the script for over a year, but there aren't too many
other people who are willing to type Lua function calls for each game
interaction.

The criterion for selecting a GUI framework were four in number.  (1)
The framework had to support cross-platform development.  (2) The
framework had to be one that I have never used, otherwise, I wouldn't
learn as much.  This eliminated FLTK and wxWidgets.  (3) C is
preferred over C++.  (4) GTK Sudoku was to be scalable in the sense
that size of the default font determines the size of each window and
widget, not the resolution of the display.

The GIMP Toolkit <http://www.gtk.org> was selected.  As of version
2.8.0, GTK+ includes Cairo, a vector graphics library, which was used
to make GTK Sudoku scalable.  It's a very nice part of GTK+.

Embedding the Lua script was quick and easy.  It was naturally
encapsulated in a C module that exports four functions and imports
three.  The major change to the Lua script was a help system that was
unnecessary when I was the only user.

The only tricky section of the GUI was the part that displays the
board.  A Sudoku board is a 9x9 array of cells grouped into 3x3
squares.  The boundaries of the 3x3 squares are drawn with thicker
lines to distinguish them from the other cell boundaries.

The board is implemented as a 9x9 table of cells of equal size, and no
space between cells.  The boundary lines drawn by each cell depends on
the position of the cell in the table.  Cairo is used to make the
board dynamically resizable.

GTK Sudoku was developed on GNU/Linux with Emacs.  I had trouble
finding documentation on versions of GTK+ that include Cairo.  There
were three steps that resolved this issue.  (1) I found, and carefully
studied Davyd Madeley's article on writing widgets using Cairo.

http://gnomejournal.org/article/34/writing-a-widget-using-cairo-and-gtk28

(2) I book marked and frequently referred to the HTML documents in
/usr/share/gtk-doc/html.  (3) The key step was to expand the three
source tarballs that make up GTK+, and create an Emacs tags file for
all the C source and header files.  You will find the sources adhere
to a consistent style, which helps one navigate them.

GTK Sudoku is built using the GNU Build Tools, and about all you have
to do to make your system aware of GTK+ is add the following to your
configure.ac file

AM_PATH_GTK_2_0(2.8.0,, [AC_MSG_ERROR([Cannot find GTK+])])

and then add @GTK_CFLAGS@ to ones CFLAGS, and @GTK_LIBS@ to ones
LDFLAGS.

The use of the GNU Build Tools made it trivial to move GTK Sudoku to
different GNU/Linux distributions, however, building GTK Sudoku with
MinGW and MSYS on Windows was more difficult than moving an FLTK or
wxWindows application to that platform.

If you follow the recommendations in the FLTK and wxWidgets
documentation, your build system will work unmodified on all systems,
including MSYS.  On only MSYS, the link command requires the -mwindows
option, which is added by the GUI framework's configure script.

The GTK+ configure script omits the -mwindows option on MSYS, and when
I reported it as a bug, Tor Lillqvist asserted it is desirable to omit
option on MSYS.  You can read his defense of the omission here:

http://mail.gnome.org/archives/gtk-list/2006-September/thread.html

under the subject: pkg-config --libs gtk+-2.0 omits -mwindows on
Windows.

Packaging GTK Sudoku for Windows was the real challenge.  For Windows,
there is an installer for GTK+ version 2.8.18, which places a
collection of DLLs and support files in "C:\Program Files\Common
Files\GTK\2.0".  The current Windows development environment provides
version 2.8.20.  It turns out you can run a GTK Sudoku binary created
with GTK+ 2.8.20 using a GTK+ 2.8.18 runtime if you add to your source
file a definition of the function g_type_register_static_simple, a
function added to GTK+ after version 2.8.18.  What a hack, no?

The GTK Sudoku Windows installer is close to the LuaForge 10MB limit
in file size.  This is because I had to include all the files in the
GTK+ 2.8.18 installer into the GTK Sudoku installer.  If you install
GTK+ 2.8.18 into the Common File area, applications such GAIM stop
working. 

It was easy to compile GTK Sudoku on an Intel Mac.  I installed the
X11 that came with the machine, and used DarwinPorts to install with
the portfile gtk2.  GTK Sudoku then builds as it does on GNU/Linux.
Writing ones own porfile is also quite easy.  In addition to filing in
the required fields, one only need add:

depends_lib		port:gtk2

In summary, I was very impressed with GTK+, and especially with Cairo,
however porting the GTK+ application to Windows proved challenging,
but not impossible.

John