code in cvs is broken

[Derek Atkins]

Just to make sure I understand this.....  (please bear with me)

Let's say I have some C-library, foo, that I want to:
	a) turn into a gnc-module, and
	b) g-wrap the interfaces to allow scheme hooks..

To do this, I would create:
	libgnc-foo.so -- the C library plus gnc-module initialization code
			for gnc-module "gnucash/foo".

	libgw-foo.so -- the g-wrap function stub library

	gw-foo{,-spec}.scm  -- the gw-foo guile module that loads the
			libgw-foo shared object and exports the symbols

	foo.scm -- a guile module the gnc-module "gnucash/foo" can
			execute at load-time to auto-load the g-wrapped
			module via (use-modules (g-wrapped gw-foo)).

Then in other scheme code (e.g. extensions.scm), all I need to do is:
	(gnc:module-load "gnucash/foo")
and it will autoload everything above for me, and then I have access
to all my module symbols.

Assuming I'm correct so far, then is it reasonable to have a
gnc-module gnucash/bar (similarly laid out as above), where bar.scm
has (gnc:module-load "gnucash/foo")?

-derek

Rob Browning <rlb@defaultvalue.org> writes:

> 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

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord@MIT.EDU                        PGP key available