Browser DBus Bridge

From SandboxWiki

Jump to: navigation, search

Contact: sandbox-developers at movial.com


The Browser D-Bus Bridge is a JavaScript D-Bus bindings implementation for web browsers. The Bridge allows privileged JavaScript code to talk to the D-Bus, both session and system bus (if not prohibited by the D-Bus configuration).

The bridge currently supports Gecko-based and WebKit-based browsers. Each of these have their own implementation of the Bridge due to technical differences in the integration, but support the same API on the JavaScript side. The Bridge defines and implements a unified API (referred to as "the Bridge API") to access D-Bus. While you can always use the implementation-specific APIs, their stability is not guaranteed. They also might not support extra features of the Bridge API (like introspection).

Current version of Browser D-Bus Bridge is 1.2.

Contents

Documentation

You can find the Browser D-Bus Bridge documentation online at http://sandbox.movial.com/docs/browser-dbus-bridge/1.2

The documentation is generated from html/dbus.js with the jsdoc toolkit.

Roadmap

Here are recorded plans for current and future development for the JS bindings.

Current release is 1.2.

1.x: API for services

The second stage allows JS applications to export an JS object to the message bus.

TBD: plan the API

Source code

Source code browser is available at http://sandbox.movial.com/gitweb?p=browser-dbus-bridge.git

Release tarballs are available from http://sandbox.movial.com/files/browser-dbus-bridge/

Source tree structure

The Browser D-Bus Bridge has two separate implementations, one for XPCOM (the component system used by Gecko) and one for JavaScriptCore (the WebKit javascript engine).

The source tree has the following structure:

  • build/ - This is the Maker build system by Timo Savola
  • Makefile
    • Toplevel makefile, run "make" to get a list of build targets
  • xpcom-debusservice/
    • IDBusService.idl
      • defines the XPCOM interfaces that JS wrapper uses
    • DBusService.cpp
      • service singleton and module
      • getters for signal and method objects
      • DBus messaging for internal usage
    • DBusMarshaling.cpp
      • packs data from nsIVariants to DBus message iterator
      • unpacks data from DBus message iterator to nsIVariants
      • only used internally
    • DBusDataCarrier.cpp
      • Carries certain data types that have no XPCOM equivalent
    • DBusMethod.cpp
      • DBus method object implementation
    • DBusSignal.cpp
      • DBus method object implementation
  • debug/include/IDBusService.h
    • build time generated interface header, includes sample code for C++ implementation
  • jscorebus/
    • jscorebus/jscorebus.c
      • General setup and type classes
    • jscorebus/jscorebus-classfactory.c
      • Simple way to keep track of JS classes
    • jscorebus/jscorebus-marshal.c
      • Type conversion magic
    • jscorebus/jscorebus-method.c
      • Method object implementation
    • jscorebus/jscorebus-signal.c
      • Signal object implementation
    • jscorebus/jscorebus-signature.c
      • Signature autodetection magic
  • tests
    • unit.c
      • A simple unit testing utility
    • jscorebus-webkit.c
      • A simple tester for the jscorebus implementation (WebKit)
    • bdb-xul
      • A simple XUL application to test the XPCOM implementation
  • html
    • dbus.js
      • The Bridge API JavaScript implementation
    • unit.html
      • Unit testing page
    • conversions.html
      • Test page for type conversions
    • signal-emission.html
      • Test page for emitSignal() API

Gecko version notes

NOTE: The current code base is known not to work with Gecko version 1.9.1.5 or later, due to this change: http://hg.mozilla.org/releases/mozilla-1.9.1/rev/ed60afa878e9

The Gecko version is implemented as an XPCOM service (IDBusService) and a JavaScript wrapper. IDBusService API tries to follow the user API, but some things (variable arguments, DBus service object creation, callable DBus method objects) would be difficult to implement with XPCOM. The JavaScript wrapper hides these details.

Setting up development environment

The Bridge uses non-frozen interfaces (eg. nsIVariant seems to be one), so building against distributions of the SDK that only have the frozen interfaces might not work. The use of SDK releases from Mozilla is recommended in such cases.

Requirements:

If building xulrunner from source ($ denotes shell propmpt):

$ tar xfj xulrunner-1.9.0.7-source.tar.bz2
$ cd mozilla
$ cat > .mozconfig <<EOF
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../obj-@CONFIG_GUESS@
ac_add_options --enable-application=xulrunner

# mk_add_options MOZ_MAKE_FLAGS=-j4

# ac_add_options --enable-debug
# ac_add_options --disable-optimize

ac_add_options --disable-tests
ac_add_options --disable-mochitest

ac_add_options --disable-javaxpcom
EOF
make -f client.mk build
cd ../obj-$yourplatform*
make package
make sdk
  • extract xulrunner and xulrunner-sdk from obj-$yourplatform*/dist/

Install instructions

NOTE: You might see errors about ls and /lib/xulrunner if the autodetection of proper paths fails, please ignore that error and use the variables described below to build and install the XPCOM service correctly. We'll try to fix this to be better ASAP.

Build DBus XPCOM service:

cd browser-dbus-bridge
make xpcom

or (if needed)

make xpcom  GECKO_SDK_PATH=...
  • use GECKO_SDK_PATH to point to xulrunner-sdk
make install

or

make install GECKO_COMPONENT_DIR=...
  • use GECKO_COMPONENT_DIR to point to install target location

or to use the tester provided with the Bridge, you do the following:

  • install the Bridge component to the tester's component dir:
make install GECKO_COMPONENT_DIR=tests/bdb-xul/components
  • run the tester:
/path/to/xulrunner/bin/xulrunner tests/bdb-xul/application.ini html/unit.html

Avoiding resource leaks

JavaScript code should be careful not to create reference cycles. See Using XPCOM in JavaScript without leaking for more technical datails.

Example:

function foo() {
  var method_foo = dbus.getMethod( .. );
  method_foo.onReply = function () {
    alert("this will leak");
  }
}

Move the function assigned to onReply outside foo or add "method_foo = null;" to end of foo.

WebKit (JavaScriptCore) version notes

The WebKit version is actually not at all tied to WebKit itself, but rather to the JavaScript engine called JavaScriptCore. The responsibility of injecting the D-Bus functionality into a web document's DOM JS context is on the application. The binding library offers an easy way to do this of course. An example of how to do this is included in the tests/ directory.

Setting up development environment

Requirements:

First install the WebKit as described on the port page. You will also need the development headers for D-Bus and the D-Bus GLib bindings. You can use a versions from your distribution, if available.

Install instructions

To build the JSCoreBus portion of Browser D-Bus Bridge, execute the following command:

$ make jscore

or

$ make jscore-qt

depending on your environment (GTK+ or Qt)

The build system tries to locate the D-Bus and WebKit development headers with pkg-config.

Then you can install the library with make install. This will install the library to /usr/local. If you want to change the installation location, define the PREFIX variable in the invocation of make. For example, if you wish to install the library to /opt/webkit the following command:

$ make install PREFIX=/opt/webkit
Personal tools