Re: Providing an API reference

[Andreas Rottmann]

address@hidden (Ludovic Courtès) writes:

> Hi,
>
> I've started augmenting the doc with an API reference.  I believe that
> this could complement what's already written since the doc is currently
> closer to a tutorial than to a reference.
>
Indeed!

> Writing an API reference may sound ambitious given the amount of work
> there is to document everything, and given that parts of the API are
> still in flux.  Anyway, my guess is that the most important parts of the
> `-cg' API are relatively stable, and the high-level `wrap-' API will not
> change much.
>
Yeah, that's the basic idea.

> Given these (optimistic?) assumptions, I'm trying to document both the
> high-level API (the `wrap-' interface) and the code-generation API (the
> `-cg'), or at least the its most important parts---the rest can
> hopefully easily be inferred once you've got a feel of how it works.
> The point in documenting the code-generation interface is that it's what
> makes G-Wrap so flexible compared to pure declarative wrapper
> generators.
>
> Everything is in my archive located at
> http://www.laas.fr/~lcourtes/software/address@hidden , in
> `g-wrap--devo--1.9.6--patch-9'.  Obviously, this is just the beginning
> of the story...
>
I've merged that patch now into the development branch.

> I'd be glad to hear comments about what I've done so far.
>
I greatly appreciate your involvement. Sorry for being a bit slow to
comment on the patches not merged yet, instead here are some random
notes about my ideas about G-Wraps future and C-binding helpers for
Scheme in general:

I'm not at all convinced my effort to make G-Wrap support Scheme 48
makes much sense at all, for these reasons:

* Most of G-Wraps complexity stems from C code generation, which is
  not necessary with a Scheme-level FFI, such as Scheme 48 and PLT
  Scheme provide. It seems a different, more simple tool, with the
  different features would be much more suitable:

  With a Scheme-level FFI, you can conviniently bind a given C API
  by writing Scheme code; it seems backwards to use a code
  generator, as you have one in Scheme itself in the form of
  macros. The problem is a different one: extracting certain
  information from the C API that is not (convieniently) available
  without invoking a compiler, such as the values of C macros and
  enumerations. With the code-generation approach, this knowledge is
  compiled into wrapper functions (and thus hidden away). With a
  tool I envision, that knowledge would be _extracted_ at the tools
  run time, by generating simple C programs that print those values
  in S-expression form, invoking the compiler on the C code, and
  running the resulting executable. This is quite different from
  what G-Wrap does, and retrofitting such functionality into G-Wrap
  would make it even more complex.

  I can really recommend reading the paper about the PLT FFI, linked
  from [0], to see how expressive a Scheme-Level FFI is; hiding it
  below a code generator only takes away from that.

  [0] http://community.schemewiki.org/?ffi

* Now that my focus has shifted from Guile to Scheme 48, and
  portable Scheme in general, I view my rewrite using GOOPS
  ambivalently; the rewrite has certainly made G-Wrap more flexible
  and extensible, and probably given it a clearer structure,
  however, due to GOOPS' use of keywords (while they are
  R5RS-compatible and supported by some other implementations),
  GOOPS is fundamentally non-standard, without touching the core of
  implementations that don't provide #:foo-style keywords it isn't
  possible to implement it on other Schemes. IMO, G-Wrap supporting
  multiple back-ends only makes sense when it also is able to run on
  these implementations, or else it probably won't get much usage.

So in short: G-Wrap's future looks brightest when staying a Guile
(-only) tool; a much more simple, portable C-binding tool can be
achieved by:

  * Implementing a PLT-style FFI. This already goes a long way towards
    easing the work of creating bindings; I wrote a simple mysql
    binding for Scheme 48 in 135 lines of pure Scheme. Actually, the
    RTI (run time information) layer in G-Wrap can be seen as a
    half-implementation of that approach; implementing a subset of the
    PLT FFI for Guile based on that part of G-Wrap would be not very
    hard (speaking from my experience on doing the same thing for
    Scheme 48).

  * Supplement that with tools that can extract the low-level C API
    information from headers, by parsing and compilation (as outlined
    above). Also G-Wrap could profit from a C header parser, as
    writing the declarations for the wrappers is quite tedious if more
    than a few functions are involved. I haven't really looked at it,
    but scheffig[1] is a tool that looks similiar to G-Wrap on a
    superficial level (generates C wrapper functions) and leverages
    the FCC C parser written by Mike Sperber, which probably is quite
    portable.

    [1] http://blogs.macbay.de/unspecific/stories/5261/

  * The low-level API information, as extracted in the above step still
    doesn't contain enough information for useful Scheme bindings, as
    part of the information needed for binding a C library are only
    available in its documentation, for example the semantics of memory
    allocation, for example whether a "double *" function argument in
    fact an array of a certain size, specified by another argument of
    that function, or a output argument. This information would be
    encapsulated in hand-written high-level bindings that make use of
    the automatically generated low-level bindings that result from
    header parsing.

Regards, Rotty
-- 
Andreas Rottmann         | address@hidden      | address@hidden | address@hidden
http://yi.org/rotty      | GnuPG Key: http://yi.org/rotty/gpg.asc
Fingerprint              | DFB4 4EB4 78A4 5EEE 6219  F228 F92F CFC5 01FD 5B62
v2sw7MYChw5pr5OFma7u7Lw2m5g/l7Di6e6t5BSb7en6g3/5HZa2Xs6MSr1/2p7 hackerkey.com

Always be wary of the Software Engineer who carries a screwdriver.
  -- Robert Paul