Re: New module decisions for 3.0

[Colin Walters <walters verbum org>]

On Wed, Jun 2, 2010 at 3:46 AM, Andy Wingo <wingo pobox com> wrote:
> Hi Vincent,
>
> On Wed 02 Jun 2010 01:38, Vincent Untz <vuntz gnome org> writes:
>
>>  + gjs (desktop)
>>    => approved, but with other bindings (not desktop)
>
> Does this mean that gjs will follow API/ABI stability guarantees of
> other parts of the GNOME platform, or of the old Bindings releases?

That's a somewhat complex topic.  There are multiple layers, I think
of them like this:

LABI - the C library's ABI
IABI - Introspection ABI for given library, what appears in the typelib
BABI - Binding ABI, how it processes the IABI to present a language-specific API

It's possible for the IABI to break even if the LABI doesn't, when an
annotation is added.  The best example of this is the (out)
annotation.

/**
 * clutter_color_from_pixel:
 * @color: (out): return location for a #ClutterColor
 * @pixel: a 32 bit packed integer containing a color
 *
 * Converts @pixel from the packed representation of a four 8 bit channel
 * color to a #ClutterColor.
 */
void
clutter_color_from_pixel (ClutterColor *color,
			  guint32       pixel);

Without the (out) annotation, there's no way for introspection to know
that the desired GScript API would look like:

Clutter.Color.from_pixel(0xff0000ff);

Without the annotation though, the function is still *usable*:

var color = new Clutter.Color();
color.from_pixel(0xff0000ff);

The above is exactly the same as you do in C.

For almost all of the introspection annotations though, adding them
simply makes functions usable that weren't before; e.g.  (element-type
Foo) on lists.  It's almost really only the (out) case on structures
that we need to watch out for.  A few others like (type) are used in
relatively rare cases such as when an enumeration is *really* an
integer.

I think what we should say is that after 3.0, libraries should avoid
breaking IABI.  We need better tools for this, to detect when it's
broken.

I also suggest to GI-based binding maintainers that the BABI should be
treated as frozen after 3.0.