code in cvs is broken

Rob Browning rlb@defaultvalue.org
Wed, 14 Nov 2001 18:07:45 -0600


Derek Atkins <warlord@MIT.EDU> writes:

> Ok, I've read through the design.txt file a number of times.  It
> unfortunately doesn't describe in enough detail (at least for a newbie
> like myself) how C code, g-wrap specifications, and scheme code all
> fit together to create a gnc-module.  Looking at the engine as an
> example, why do there appear to be two modules, "gnucash engine" and
> "gnucash gw-engin" and how do they relate to each other?  I still
> haven't grokked this part yet.

g-wrap was written to wrap *existing* C code, so if you have a given C
lib, say libfoo.so, then if you write a g-wrap -spec.scm file for
libfoo, say gw-foo-spec.scm, g-wrap will generate C code to wrap the
functions in libfoo.  g-wrap will generate gw-foo.scm gw-foo.c
gw-foo.h and gw-foo.html.  

Then, if gw-foo.scm is in a directory named g-wrapped in your
GUILE_LOAD_PATH or %load-path, and if you build a library from
gw-foo.c named libgw-foo.so, and it's in your LD_LIBRARY_PATH, you
will be able to say (use-modules (g-wrapped gw-foo)) from guile and
load the guile bindings for libfoo.

So libgnc-engine is the code for the engine, and libgw-engine is the
code for the wrappers which has to be linked against the engine or the
dynamic-link in gw-engine.scm will fail.  Similarly, libgnc-engine has
to be linked against everything it depends on at build time, or when
guile's dynamic-link (which bottoms out in dlopen) opens libgw-engine
and starts trying to recursively patch up all the symbol references in
there, it'll go on to libgnc-engine and then fail because
libgnc-engine isn't fully linked.

> I do, at least, seem to understand the "use-modules"
> vs. "gnc:module-load" thing, although it appears that "use-modules" is
> still used within modules.  So I guess I'm still confused about where
> and when to use these two functions.

If you're writing a schme-only module, you probably only need a
standard guile module -- see price-quotes.scm for an example.

If you need to write a module that includes any .c files, you should
use a gnc-module which may depend on other gnc-modules and may load
other guile-only modules.

gnc-modules support several things above and beyond a normal guile
module.  In addition to handling C code, you can:

  1) add the public functions from several other 

> As I mentioned earlier, there isn't enough documentation to help
> someone build a module.  For example, I had to learn by
> experimentation that I had to (export ...) all my symbols...  Isn't
> there some way g-wrap can do this automatically?

You don't have to do that.  If you're trying to make a given
guile-module's functions available to the other code *within* a given
gnc-module, then you need to put the use-modules statement inside the
gnc-module's .scm file, i.e. app-utils.scm.

If you're trying to make all the symbols from a given guile module
available to other code that loads your gnc-module, then you need to
use-modules the module in your gnc-module's gncmod-foo.c file, in the
init function -- see gncmod-app-utils.c.

Hope this helps.

-- 
Rob Browning
rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
Previously @cs.utexas.edu
GPG=1C58 8B2C FB5E 3F64 EA5C  64AE 78FE E5FE F0CB A0AD