SWIGification status

[Chris Shoemaker]

Devs,
        The swigify branch has a business-module with no g-wrap
generated wrappers.  I believe it's functionally equivalent to trunk.
(Please let me know if you find any differences.)

        The process took about twice as long as I'd hoped, but I
learned some valuable lessons along the way.  First off, I'm very
impressed with SWIG.  It's got good docs, a helpful mailing list, and
reasonably intuitive behavior.  It's quite flexible and I was able to
adapt it to several different organizational structures.

        Functionally, it seems to do everything g-wrap does, but with
much less code, if you follow the conventions.

        One lesson is that the swig wrappers use SCM_NULLP() to
represent NULL, while the g-wrap wrappers use !SCM_NFALSEP().  That
means that some representations of null objects in guile code has to
be changed from #f to '().

        Probably the most important thing I learned is that you can do
the conversion one module at a time.  The key is to provide typemaps
for the not-yet-swigified types that convert to/from g-wrapped C
pointers.  E.g.:

// Temporary SWIG<->G-wrap converters 
%typemap(in) QofBook * {
  $1 = (QofBook *)gw_wcp_get_ptr($input);
}

%typemap(out) QofBook * {
  $result = gw_wcp_assimilate_ptr($1, scm_c_eval_string("<gnc:Book*>"));
}

        Using that technique, I think it would have been possible to
accomplish the business module conversion without any changes to
src/engine.

        There are a few minor outstanding issues that I'd rather be
solved with more consensus/input.  E.g. 
1) circular Makefile deps, 
2) maybe converting macro functions to real functions, 
3) xacc vs. gnc in function names, 
4) underscores-automatically-converted-to-dashes vs. gncStudlyCaps, 
5) how to best wrap enum values, 
6) runtime mangled type names,
7) wrapping entire headers vs. just the used functions.

        My recommendation would be to abandon the swigify branch,
which contains several false-starts and missteps, and export a
cleaned-up version of the branch's diff into a new branch.  I think
the entire conversion process for a module can be characterized into 6
to 8 logical commits.  That's probably about 1 hour's work for the
already-converted business module (which really contains 3 wrapped
modules but only one significant one).

After that, there remains (in appropriate order, and with my estimate
of amount of work involved):

Hours     Module
1 ./gnome/gw-gnc-spec.scm
1 ./register/register-core/gw-register-core-spec.scm
2 ./report/report-gnome/gw-report-gnome-spec.scm
1 ./report/report-system/gw-report-system-spec.scm
3 ./gnome-utils/gw-gnome-utils-spec.scm
2 ./app-utils/gw-app-utils-spec.scm
2 ./engine/gw-engine-spec.scm
3 ./engine/gw-kvp-spec.scm
1 ./gnc-module/gw-gnc-module-spec.scm
1 ./core-utils/gw-core-utils-spec.scm

Plus some work to convert the runtime C code from g-wrap to swig,
which isn't quite as automated.  Bottom line is that even though I've
only converted one major module, I think about 75% of the work is
done.  However, this was a vacation project for me, and vacation is
over, so it's unlikely I'd be able to finish this in the next month.
I'll work on redoing the branch and see if some solutions to the open
issues fall out.  After that, it's basically busy-work (sed is your
friend) to convert the modules one at a time.  If anyone else is
interested taking it over, speak up any at point in the process.

-chris