jabxpcom/Documentation

JabXPCOM is an XPCOM component which provides access to Jabber from any programming language with XPCOM bindings (such as C++, Java, JavaScript, Python, or Ruby)--currently, it's just a simple wrapper around the C++ jabberoo library released under the GNU Library General Public License.

Building and Installation

Building XPCOM

You can either choose to use a complete Mozilla build (on Debian/Ubuntu, you can just install the mozilla-dev package), or build a standalone XPCOM/XPConnect.

Because I am using a standalone XPConnect build, I will give a few instructions on how to build it in addition to Mozilla's Standalone XPCOM information. The Mozilla project uses its build system for checking out the required parts of the CVS repository:

export CVSROOT=":pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot"
cvs -z 3 co mozilla/client.mk
cd mozilla
make -f client.mk pull_all BUILD_MODULES=xpconnect MOZ_CO_TAG=MOZILLA_1_0_BRANCH

On a Windows platform you would instead use:

set CVSROOT=":pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot"
cvs -z 3 co mozilla/client.mak
cd mozilla
nmake -f client.mak pull_xpconnect MOZ_CO_TAG=MOZILLA_1_0_BRANCH

If you only want to use XPCOM/XPConnect (and not debug the code yourself), it is a good idea to disable debugging and enable optimisations:

./configure --enable-modules=xpconnect --disable-debug --enable-optimizemake BUILD_MODULES=xpconnect

Again, the build system works a bit differently on a Windows platform:

nmake -f client.mak build_xpconnect

Building PyXPCOM

Your best option is to use my Debian/Ubuntu package from http://cmeerw.org/debian/

Although PyXPCOM packages can be downloaded from ActiveState's Web-site, I don't recommend doing it because the distribution files there are outdated. Better get the current version checked out from the Mozilla CVS repository (see mozilla.org: source code via cvs. You only have to login if you haven't already done so (the password for user anonymous is anonymous):

cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot login
(Logging in to anonymous@cvs-mirror.mozilla.org)
CVS password:

Then change to the directory where your Mozilla sources are and check it out by issuing:

cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot checkout -rMOZILLA_1_7_BRANCH mozilla/extensions/python/xpcom

Before continuing you should probably check the Python related settings in extensions/python/xpcom/src/Makefile.in and extensions/python/xpcom/src/loader/Makefile.in to make sure that they match your setup.

To have the PyXPCOM makefiles integrated into Mozilla's build system, you will also have to apply this patch in Mozilla's home directory: pyxpcom-allmakefiles.diff (via ftp (it is based on this bug report).

In order to build PyXPCOM you have to create the makefiles by running configure in Mozilla's home directoy with --enable-extensions=python/xpcom first. Then you can build it by simply typing make in PyXPCOM's directory:

./configure --enable-modules=xpconnect --enable-extensions=python/xpcom --disable-debug --enable-optimizecd extensions/python/xpcom && make

Building jabberoo

JabXPCOM depends on jabberoo which itself depends on libsigc++. Again, your best option is to use my Debian/Ubuntu package from http://cmeerw.org/debian/

Building JabXPCOM

Edit config.mak
make
Copy the XPCOM components libjabxpcom.so and libtcpstream.so (also libgnutlsstream.so and/or libopensslstream.so if you have built SSL/TLS support) and the type libraries datastream.xpt, jabxpcom.xpt, judoxpcom.xpt and streamconnector.xpt to your Mozilla/XPCOM components directory
Run regxpcom (you might have to call it via run-mozilla.sh and/or set LD_LIBRARY_PATH for your Mozilla environment) in your Mozilla/XPCOM components directory

If you have successfully installed PyXPCOM you can now try out the JabXPCOM test programs.

Setting Up the Environment

Now that you have (hopefully) everything built, you will need to set up the XPCOM environment (because you usually don't want to mess up your Mozilla browser installation).

The best way to set up the environment is to create a directory for XPCOM and symlink all relevant components into it:

mkdir jabrss && cd jabrss
ln -s /usr/lib/xulrunner/libxpcom.so .
ln -s /usr/lib/xulrunner/libxul.so .

mkdir components && cd components
ln -s /usr/lib/xulrunner/components/proxyObjInst.xpt .
ln -s /usr/lib/xulrunner/components/xpcom_base.xpt .
ln -s /usr/lib/xulrunner/components/xpcom_components.xpt .
ln -s /usr/lib/xulrunner/components/xpcom_ds.xpt .
ln -s /usr/lib/xulrunner/components/xpcom_io.xpt .
ln -s /usr/lib/xulrunner/components/xpcom_threads.xpt .
ln -s /usr/lib/xulrunner/components/xpcom_xpti.xpt .

cd ..

Now you have to install JabXPCOM/JabRSS into this directory and proceed with the XPCOM registration:

MOZILLA_FIVE_HOME=. /usr/lib/mozilla/regxpcom

Memory Management

As JabXPCOM is built upon jabberoo, it has to take jabberoo's memory management rules into account.

This isn't any problem at all for non-const elements. But some special care has to be taken for (references to) const elements which are passed to callback functions, because these const elements are managed by jabberoo and are deleted when the callback function returns. But as these elements are wrapped inside XPCOM objects and a callback function might store a reference to an XPCOM object, the jabberoo object has to be copied in this case.

Technically, the callback function wrapper checks if any references to the XPCOM object are still held and calls the detach method of the XPCOM wrapper which then takes care of making a local copy of the jabberoo object.