View source

From SandboxWiki

You do not have permission to do that, for the following reason:
The action you have requested is limited to users in the group user.
You can view and copy the source of this page:
Contact: Kalle Vahlman <firstname.lastname@movial.com>
----

[[Image:Browser-d-bus-bridge-300px.png‎|right]]

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.1.

==Documentation==

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

The documentation is generated from ''html/dbus.js'' with the [http://code.google.com/p/jsdoc-toolkit/ jsdoc toolkit].

==Roadmap==

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

Current release is 1.1.

===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 [http://pallo.dyndns.org/git/?p=maker.git 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==

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:
* dbus-glib headers installed (libdbus-glib-1-dev)
* xulrunner sdk from ftp://ftp.mozilla.org/pub/mozilla.org/xulrunner/releases/1.9.0.7/sdk
* OR xulrunner source from ftp://ftp.mozilla.org/pub/mozilla.org/xulrunner/releases/1.9.0.7/source

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
[http://developer.mozilla.org/en/Using_XPCOM_in_JavaScript_without_leaking 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 <tt>onReply</tt> outside <tt>foo</tt> or add "method_foo
= null;" to end of <tt>foo</tt>.

==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:

* D-Bus and D-Bus Glib bindings
* [http://trac.webkit.org/wiki/BuildingGtk WebKit GTK+ port] for GTK+ environment
* [http://trac.webkit.org/wiki/QtWebKit QtWebKit] for Qt environment
** Qt version usage requires a [https://sandbox.movial.com/files/browser-dbus-bridge/0001-Added-API-to-extract-the-JavaScript-execution-contex.patch patch to expose the JSCore API from QWebFrame] and a [https://sandbox.movial.com/files/browser-dbus-bridge/0002-Added-support-for-conversion-between-JSObjectRef-and.patch patch to add support for conversion between JSObjectRef and QVariant] (made against qtwebkit-2.0 release branch).

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 <tt>make install</tt>. 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
Return to Browser DBus Bridge.
Retrieved from "http://sandbox.movial.com/wiki/index.php/Browser_DBus_Bridge"
View source

From SandboxWiki

Views

Personal tools

Navigation

Search

Toolbox
