Distribute introspection XML (WasRe: glib bindings (Was Re: [patch] gobject sender and pid))

[David Zeuthen]

Hey Havoc,

(sorry for the long mail; no need to reply to all my points)

On Tue, 2006-03-14 at 13:38 -0500, Havoc Pennington wrote:
> Some starting points:
>  - when do you use the dynamic introspection data vs. the files?

 - languages like C

 - when you want build-time checking and manually generate stubs
   in the Java and C#'s of the world

 - when the service is not available or you are not privileged to
   get at the data - things like code assist in e.g. Eclipse comes to
   mind

>  - what if they differ? several cases:
>    - same interface is different dynamically vs. in the file
>      (can it happen? how?)

Sure, it happens when 

 - something breaks; we check this in C at build-time; you would
   only notice it in e.g. Python at run-time

 - the interface is extended in a way that doesn't break ABI [1]

[1] We probably need to define excactly what "ABI breakage" means wrt.
D-BUS services; as argued elsewhere I regard adding new exceptions as
breaking ABI, you may not.. we can probably not be as relaxed as the ABI
rules projects like e.g. GTK+ use for C though..

Btw, we don't even need to define what "ABI breakage" is, however D-BUS
becomes less useful if there is no "blessed" definition of ABI breakage
and any discussion of "versioning" thus becomes pointless.

>    - interface only available dynamically (why?)

Because we don't mandate that introspection data needs to be shipped nor
do we specify where to install and whether it needs to be installed if,
and only if, the main executable is available (e.g. put it in hal or
hal-devel).

>    - interface only available statically (why?)

Service is not available, not running, you are not privileged to get at
it.

>  - if I'm providing an interface, how do I generate the introspection
>    file?

Good question because sometimes you need to full service up and running
and this is not easily achievable in an automated build environment. So
some projects probably needs the developer to "manually" [2] generate it
and include it in CVS and the distribution tarball. 

I suggest to punt this to bindings; they should provide a tool that does
this for the source code they handle - for example for C# or whatever
you could invoke the compiler and even extract things like what
exceptions to throw from annotations and/or doc snippets. Sure, tools
like this takes time to write but that doesn't mean we shouldn't be
aiming high.

[2] : can be automated through a script and dbus-send

>  - if I'm consuming an interface, how do I ask for the file?

We use the rules

 - introspection data is one XML file per interface

 - well-defined naming rules for XML file, e.g. <interfacename>.xml, for
   example HAL would export org.fredesktop.Hal.Manager.xml, 
   org.fredesktop.Hal.Device.xml and so forth.

 - XML files installed into a well-defined location

We can probably put pkg-config to use here.

Conclusion: 

 - Yes, it's useful to have the introspection data per interface,
   available in a well-known location, under a well-known name.

 - Yes, we should require applications to provide install these and
   distributors (e.g. Fedora, Debian, ..) are encouraged to provide
   these in the development sub-package, e.g. hal-devel for hal.

> Some thoughts:
> 
>  - ideally the canonical "interface definition" remains the code, i.e. 
>    I'd rather just write the GObject or QObject, maybe with some inline
>    annotations, maintaining a separate xml file sucks - so the installed
>    xml would be a generated file where the generation is 
>    binding-specific

Yea.

>  - ideally an interface can be asked for by name, like:
>    "dbus-tool --print-interface org.freedesktop.DBus > foo.xml"
>    and foo.xml would include only the requested interface, not 
>    any other stuff that might have been in the same original file

Yep.

>  - tools could also go directly, 
>    "dbus-tool --generate-c-header org.freedesktop.DBus > foo.h"

Well, we have dbus-binding-tool so use shell redirection etc.

>  - I think it'd be fine, or even good, to distribute the xml file 
>    with the app using it; i.e. it's like Makefile.in, not like 
>    Makefile - generated by the original developer. Not sure 
>    this changes much but maybe it does.

I think we should require this; not just encourage it.

>  - on Windows, you can get a COM typelib in C++ like:
>    #import "iTunes.exe"
>   (or something like that), which in effect includes the header
>    file for that typelib. Would be cool to appriximate the same 
>    effect...

...

>  - this emphasizes the "if you break an interface you must rename"
>    kind of deal (we continue to punt on the interface versioning 
>    question, though I thought we had some good consensus on how that 
>    could work, nobody coded it)

With a precise definition of what "ABI breakage" means (at least from a
syntactical point of view)  we would even provide tools that would catch
the cases where the syntax changes. Of course, we can't catch ABI
busters for when the semantics changes...

How do we move on? If we're not disagreeing too much I can write a patch
to our docs / spec that incorporate these requirements. Even if it's "an
app is never required to ship introspection data" that's fine too; I
just feel we need to resolve this before 1.0.

    David