Announcing the merge of the kdelibs4-dbus branch

[Thiago Macieira]

Thiago Macieira wrote:
>I'll prepare an email with the porting highlights. But, right now, you
> can refer to the wiki
>(http://wiki.kde.org/tiki-index.php?page=Porting%20KDELibs%20to%20D-Bus)
>for porting instructions.

Ok, as promised, the highlights needed for porting:

1) you need the CVS version of D-BUS library. The one that your 
distribution installed, even if it's 0.61, probably won't be enough to 
compile QtDBus. Apparently the D-BUS developers forgot to install one 
header (dbus-signature.h) for a long time and no one noticed.

There's also the issue that a bug in the dbus-daemon program prevented 
calls with interface="" from being delivered. So if you want to use KDE 
programs that make calls with empty interface names, you need to upgrade 
your dbus daemon to the CVS version as well.

2) you need the Subversion or CVS version of QtDBus. It's official home is 
now in trunk/kdesupport in our Subversion server, with CMake as its 
primary build system. I merged all changes yesterday to the 
freedesktop.org CVS, so what you compile with --enable-qt in the dbus CVS 
will be the same code as our Subversion repository.

3) QtDBus has lot of debugging enabled by default. So you see every 
message sent or received being dumped to your stdout. If you want a quiet 
build, you need to add -DQT_NO_DEBUG -DQT_NO_DEBUG_STREAM to the 
preprocessor flags.

4) There is no Windows port of libdbus-1 yet -- at least, nothing that I 
have seen. Ralf can be more specific about this, but unless the port is 
made working by tomorrow, KDE on Win32 will stop building tomorrow.

5) QtDBus finds libdbus-1 through pkg-config and KDE finds QtDBus through 
pkg-config as well. The QtDBus .pc file contains dependency info on Qt, 
so Qt must be found using pkg-config as well. Make sure your 
PKG_CONFIG_PATH contains $QTDIR/lib then, as well as wherever you 
installed D-BUS and QtDBus to.

The buildsystem guys can probably change my FindQtDBus.cmake script if 
they want to, in order to find the library in another way.

6) Every module has to add to their top-level CMakeLists.txt:
	add_definitions( ${QDBUS_DEFINITIONS} )

7) The proper way of including the QtDBus classes is through:
	#include <dbus/qdbus.h>
This is the D-BUS way of doing things. Now that we're separating from the 
core and moving to kdesupport, I'll probably provide a more Qt-way of 
including (i.e., #include <QtDBus/QDBusInterface> etc.)

8) The code generator program equivalent to dcopidl2cpp is called 
dbusidl2cpp, but that's a misnomer: it does not read IDL code. It reads 
XML and outputs C++. The program could use some improvement in its usage, 
but basically, it boils down to:
	dcopidl2cpp -m -a myclassadaptor -p myclassinterface org.kde.MyClass.xml

This will generate files called myclassadaptor.cpp, myclassadaptor.h, 
myclassinterface.cpp and myclassinterface.h (the -m option is used to add 
a #include "xxxx.moc" to the bottom of the .cpp files). The Adaptor files 
are meant to be changed by the developer, so they should be checked in to 
Subversion. The interface ones are not.

Since I have no working CMake macro to generate the interface files during 
compilation, I and the others have been committing the interface files to 
Subversion as well. The qt-dbus/examples directory contains one attempt 
at such macro, but if you watch closely, you'll notice that the interface 
file is unnecessarily built at every "make".

9) The .xml file should either be written by hand or, as an alternative, 
you can use the dbuscpp2xml tool. This tool parses a .h that contains one 
or more QObject-derived classes and prints a XML representation of the 
class' signals, slots and properties.

In fact, you may notice that if you run the XML through dbusidl2cpp again, 
the Adaptor class that is generated is quite similar to the original 
class.

I thought of writing a real IDL parser at this point, but I figured that I 
could use one parser I know everyone to have installed already: moc. So 
that's why it reads C++ code.

The GUI tool to build interfaces is in qt-dbus/builder, but it's not 
complete yet. It loads interfaces, but it doesn't let you modify any yet.

10) For an interface called org.kde.Phonon.MixerIface (one example I found 
in Phonon), the dbusidl2cpp will generate the following class names:

MixerIfaceAdaptor - the adaptor
OrgKdePhononMixerIfaceInterface - the interface
org::kde::Phonon::MixerIface - typedef to OrgKdePhononMixerIfaceInterface

none of those classes are exported or meant to be exported.

So don't name your interfaces with something ending in Iface. It just 
makes the name uglier. (It's my fault for choosing that name for a Phonon 
existing class)

Most of the methods in the interface class are inline, except for the 
constructor and the destructor. As I noted on the wiki, interfaces are 
QObjects, so they are way more expensive to create than DCOPRef. If you 
can and if you make repeated calls to the same remote object, cache the 
pointer in your class. If you cannot do that, then at least use a 
non-empty interface name when creating a QDBusInterfacePtr.

11) All applications should properly set the organizationDomain and 
applicationName properties in QCoreApplication. We should modify 
KApplication and KAboutData to contain that information.

12) Interface contents cannot change during the session of one 
application. This means you cannot have one application exporting 
org.kde.Interface with one set of functions and another application 
exporting the same interface with another set of functions.

Interfaces are a contract that you make with 3rd party applications. 
Therefore, interfaces are subject to "binary compatibility" guidelines 
once released: you may not remove methods/signals/properties from 
interfaces, you may not change the signature of existing methods/signals 
or the type of properties. In special, if your interface is meant to 
interoperate with other bindings (Java bindings, Python bindings, glib 
bindings), you should not create overloads either.

However, I think we should clearly mark which interfaces are public (i.e., 
script-writers and other, external applications can use) and which ones 
are meant for our own, internal use. For the latter ones, we could "break 
binary compatibility" as often as we'd like.

-- 
Thiago Macieira  -  thiago (AT) macieira.info - thiago (AT) kde.org
  thiago.macieira (AT) trolltech.com     Trolltech AS
    GPG: 0x6EF45358                   |  Sandakerveien 116,
    E067 918B B660 DBD1 105C          |  NO-0402
    966C 33F5 F005 6EF4 5358          |  Oslo, Norway
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20060530/5f97c5a9/attachment.sig>