Standardizing FFI based wrappers

[Luc Heinrich]

Greetings,

Back in november, when FFI 0.1.1 was released, there was a beginning
of an interesting discussion about "standardizing" the way FFI based
wrappers should be named, organized and packaged, in order to create a
clean and useful (and hopefully growing) FFI "ecosystem" (yeah, I
know, but I couldn't find a better word for it). Some good suggestions
were made but I don't think anything was really settled. I think it
would be good to continue this discussion now and decide on a set of
guidelines, maybe illustrated by a sample wrapper.

Here's what I could gather so far:

- About organization:
Sean O'Halpin wondered "if it would be useful to have these FFI-
enabled libs under an ffi/ namespace, e.g. you'd require 'ffi/ncurses'
and possibly include FFI::NCurses. We could put shared structs,
constants, etc. under ffi/include."

- About packaging:
Sean O'Halpin thinks "it's better to provide a thin bridge and then
abstract on top of that. [...] Thin wrapper in a single gem. Any
abstractions should be separate gems."
Luis Lavena agreed: "Yeah, first layer of implementation and then
abstraction (Rubify)"
Nit Khair then suggested that "some of these conversions/wrappers
would be "approved" and sort of become a standard, so we don't have a
plethora of them. Then they could be placed in one repo (after some
sort of review)."

- About naming:
Tom Enebo suggested "just naming them the library name, as in
libncurses, libtommath, whatever."
Sean O'Halpin thinks that it's "a little *nix-centric".
I would personnally suggest to name them "ffi-{LIBNAME}", like ffi-
zlib or ffi-ncurses, etc, this makes it obvious what it is and makes
it easier to search for all ffi based wrappers in rubygems repositories.


If you have something to add or any comment on all this, please speak
out

 

[Sean O'Halpin]

Greetings,

Back in november, when FFI 0.1.1 was released, there was a beginning of an
interesting discussion about "standardizing" the way FFI based wrappers
should be named, organized and packaged, in order to create a clean and
useful (and hopefully growing) FFI "ecosystem"

I'm also interested in feedback. I'm working on an FFI wrapper for
ncurses. I haven't released a gem yet though the project is on github
if anyone's interested in work-in-progress:
http://github.com/seanohalpin/ffi-ncurses/tree/master. This is how I'm
planning to address the issues raised by Luc:

= Organisation

The gem will be called ffi-ncurses and will live in its own directory
rather than under ffi/ncurses.

I would like to call the module FFI::NCurses but would appreciate some
feedback as to whether people think this is a good idea. Would it be
polluting the FFI namespace?

= Packaging

No change here - thin wrapper only.

The only really tricky decision is what to do about macros. For
example, in ncurses there are macros to return the yx coordinates,
like this:

#define getyx(win,y,x) (y = getcury(win), x = getcurx(win))

used like this:

int x, y;
getyx(win, y, x);

i.e. it directly updates the variables passed in. They are convenience
wrappers to obviate the fact that C cannot return multiple values.
I've translated them to work like this:

y, x = getyx(win)

Not a literal translation, but certainly (IMHO) in the spirit of the
macro. (But as they say in Italian: traduttore, traditore

Again, any feedback here would be welcome.

= Naming

As mentioned above, I'm going to call the gem ffi-ncurses (and version
0.1.0 will be out real soon now).

= Other issues

- Do we want to distinguish operating system specific libraries, e.g.
ffi-win32-console, ffi-darwin-growl_plugin?

Regards,
Sean

 

[Charles Oliver Nutter]

- About organization:
Sean O'Halpin wondered "if it would be useful to have these FFI-enabled
libs under an ffi/ namespace, e.g. you'd require 'ffi/ncurses' and
possibly include FFI::NCurses. We could put shared structs, constants,
etc. under ffi/include."

I agree with ffi/ path prefix. I agree with FFI:: prefix since there
will already exist conflicts (built-in readline's "Readline" for example).

It will also be very nice to know they'll be prefixed with ffi/ and
FFI:: in all cases.

- About packaging:
Sean O'Halpin thinks "it's better to provide a thin bridge and then
abstract on top of that. [...] Thin wrapper in a single gem. Any
abstractions should be separate gems."
Luis Lavena agreed: "Yeah, first layer of implementation and then
abstraction (Rubify)"
Nit Khair then suggested that "some of these conversions/wrappers would
be "approved" and sort of become a standard, so we don't have a plethora
of them. Then they could be placed in one repo (after some sort of
review)."

I agree with making them thin and am neutral on the "one repo" thing. We
could certainly use the ruby-ffi project for that purpose, if storing
them in a common repo was desirable.

- About naming:
Tom Enebo suggested "just naming them the library name, as in
libncurses, libtommath, whatever."
Sean O'Halpin thinks that it's "a little *nix-centric".
I would personnally suggest to name them "ffi-{LIBNAME}", like ffi-zlib
or ffi-ncurses, etc, this makes it obvious what it is and makes it
easier to search for all ffi based wrappers in rubygems repositories.

I like ffi- prefix for all "simple" ffi wrapper gems.

- Charlie

 

[Beoran]

This proposal looks fine, I like FI::SDL, FFI:SDL_ttf, FFI::Opengl, etc.

However I have some questions with regards to the practical implementation.
First of all, what to do with C libaries that consist of several
physical .so (or .dll)
libraries but only have on C interface? Gnome/GTK comes to mind.

Also, what to do with forks or competing implementations? I know in an
ideal
world people should work together, but perhaps they won't. Ruby alone has
four C based wrappers for SDL, namely RubySDL, Rubygame, RUDL and Gosu.
What to do in case two people wrap the same library?

Kind Regards,

Bjorn.

 

[Luc Heinrich]

I like ffi- prefix for all "simple" ffi wrapper gems.

I haved pushed a basic wrapper of zlib to GitHub, it's pretty simple =20
and not fully tested yet, but if you guys want to use it as an example =20=

for more discussions, feel free

<http://github.com/lucsky/ffi-zlib/tree/master>

One thing I noticed while doing this, for example, is that you still =20
have to refer to the original zlib header(s) to figure out what the =20
function parameters are exactly, since the attach_function calls only =20=

mention the types. You would probably still have to check the =20
documentation for behavior explanations but if the parameter names =20
would at least be available somewhere it would probably make things =20
easier.

So is it ok to simply redirect the wrapper user to the library =20
headers ? Or do we want a standard way to comment the function =20
wrappers too ?

--=20
Luc Heinrich - (e-mail address removed)

 

[Sean O'Halpin]

One thing I noticed while doing this, for example, is that you still have to
refer to the original zlib header(s) to figure out what the function
parameters are exactly, since the attach_function calls only mention the
types. You would probably still have to check the documentation for behavior
explanations but if the parameter names would at least be available
somewhere it would probably make things easier.

So is it ok to simply redirect the wrapper user to the library headers ? Or
do we want a standard way to comment the function wrappers too ?

Surely one of the ideas behind providing thin wrappers is that the
existing C-oriented documentation will suffice with a little
translation.

Better to put effort into documenting common C to Ruby FFI idioms to
help in that translation across all FFI wrappers IMHO.

So perhaps FFI docs could contain pointers to original docs plus notes
on any significant departures from a straight transliteration and how
to handle tricky arguments?

Regards,
Sean

 

[Julian Raschke]

Ruby alone has

four C based wrappers for SDL, namely RubySDL, Rubygame, RUDL and Gosu.
What to do in case two people wrap the same library?

Gosu has no connection to the SDL, it is actually a pretty thin layer
around the C++ version of the same library I am also not sure if it
makes sense to rubify game libraries which need every bit of
performance, but if so, I think the Rubygame and RUDL libraries could
very well be wrappers on top of Ruby/SDL.

Julian

 

[Beoran]

Gosu has no connection to the SDL, it is actually a pretty thin layer
around the C++ version of the same library I am also not sure if it
makes sense to rubify game libraries which need every bit of
performance, but if so, I think the Rubygame and RUDL libraries could
very well be wrappers on top of Ruby/SDL.

Julian

Gosu does make use of SDL(indirectly) at least on Linux.

And performance is not a big problem. I feel I need to stress is that
wrapping SDL or other C game libraries with Ruby does make a lot of
sense, since most of the blitting, etc happens on the C side of things
anyway. Pygame proves that this approach works well for Python, and I'm
convinced it woks well for Ruby, at the very least for 2D games. A
two-language approach makes a lot of sense, with the low level stuff in
the C libraries and the high level stuff in Ruby.

Kind Regards,

Beoran.