IDL language

[David Zeuthen]

Hey,

It has often come up that it would be nice to have an IDL language to
describe D-Bus interface. I've been working on this for a few days this
week. It's still early in development, but I thought I'd send a note
anyway.

Sidebar:

  I know some people think that D-Bus should be used in a way where you
  introspect your program and then, bingo, stuff is automatically
  exported on the bus. I think that is a nice way to do things
  (especially for small services) and I don't think it's incompatible
   with having an IDL.

  E.g. you still need _some_ way of documenting your D-Bus API (unless
  it's private) and I know from first-hand experience that just pointing
  at the code or telling people to introspect via dbus-send(1) isn't
  really a satisfying answer (for example Marina spent a lot of time
  documenting the online-desktop D-Bus APIs by reverse-engineering via
  dbus-send(1)).

Anyway, to kick off the discussion, here is the proposed IDL format

http://cgit.freedesktop.org/~david/dbus-idl/tree/src/org.freedesktop.DBus.Idl.Tests1.didl

Notes

 o  We force D-Bus structures to be declared, e.g. you can't do

     SomeMethod (struct<int32, int32> is_this_a_pair_or_a_point);

    you will have to declare the structure. This is mainly to help
    high-level languages so it's easier to map into native types and
    classes.

 o  There's a way to declare "dynamic structs". These are always encoded
    as (sa{sv}) and, thus, allow you to dynamically add elements without
    breaking the ABI on the wire. The first element of the struct MUST
    be "dynamic_struct:org.project.NameOfDynamicStruct".

 o  We allow simple annotations with a few well-known ones

      @Deprecated
      @Deprecated("With a reason string")
      @Version("1.2β")
      @Since("1.2α")
      @NoReply
      @DocString("A documentation string")
      @Flags (to hint that an enum is a flag enumeration cf. GEnum vs.
              Flags)

 o  There's a simple API for accessing the parsed tree
    http://cgit.freedesktop.org/~david/dbus-idl/tree/src/dbusidl.h

Remaining work

 o  Print warnings if e.g. docs are missing

 o  Right now the only dep is libglib-2.0 - it's not too hard to get rid
    of that dep, but maybe not worth the effort (ok, we depend on lex
    and yacc but that doesn't incur any run-time deps).   

 o  dbus-idl-to-docbook - a tool to generate docbook docs like I'm doing
    with EggDBus here:
    http://people.freedesktop.org/~david/eggdbus-HEAD/example-dbus.html

 o  dbus-idl-install - to validate and install the IDL into
    /usr/share/dbus-idl-1/idl/

 o  "import org.project.SomeNameSpace;" - to import interfaces and
    declarations from an existing IDL file already installed into
    /usr/share/dbus-idl-1/idl/

 o  Maybe we want a flag_enum to make things clearer.

 o  Test suite

 o  Proper documentation

 o  Support gtkdoc style comments to automatically set well-known
    annotations.

    /**
     *  SomeMethod:
     *  @stuff: Docs for the stuff parameter.
     *  @bikes: The bikes to use @stuff on.
     *  @vehichles: The #Vehicle structs returned.
     *
     *  Take a set of #Bike structs in @bikes and return a list
     *  of #Vehicle structures in @vehichle.
     *
     *  Since: 1.1
     *  Deprecated: 1.3: Use #SomeOtherMethod instead.
     */
    SomeMethod (string stuff,
                array<Bike> bikes,
                array<Vehichle> vehichles);


So, yeah, a lot of work remaining until it's 1.0-ish material but,
still, it's already useful right now (it's ~3500 LOC and I don't expect
it to be much bigger than 8-10K LOC).

At this point I'm mostly interested in feedback about the IDL language
itself and how the proposed "import" stuff should work (maybe we don't
even want a system-wide IDL directory, I don't know).

Discuss.

     David