Personal tools
You are here: Home / cmgui / Zinc / Writing XPCOM components for zinc

Writing XPCOM components for zinc

Introduction

Caveat: this guide was written assuming you are working on a linux machine. It is also possible to develop XPCOM components under windows or on a mac.

XPCOM (Cross Platform Component Object Model) is a cross platform component model from Mozilla. XPCOM components provide an interface which can be accessed from various different programming languages (eg JavaScript). The components themselves can also be written in various different languages (eg Java, C++, Python, JavaScript). I have used Javascript as my implementation language.

Some understanding of the basic concepts can be gained by reading the first few paragraphs from this link:

http://www.builderau.com.au/program/javascript/soa/Creating_XPCOM_components_with_JavaScript/0,339028434,339206503,00.htm

This guide is designed to expand on the material found here: http://developer.mozilla.org/en/docs/How_to_Build_an_XPCOM_Component_in_Javascript

You should open this link up and refer to it after/while reading this page. Using it you should be able to get a Hello world XPCOM component working very quickly.

Basic Steps

I aim to clarify a few things so you can move through the guide even faster. Assuming you have firefox installed the steps are as follows:

  1. Install the gecko sdk (see notes below)
  2. Generate a GUID (see notes below)
  3. Write an .idl file to define your interface
  4. Compile your .idl file into an .xpt (type lib file) using tools from the gecko sdk
  5. Create your component by writing a .js javascript file (or use Java, C++ or Python)
  6. Install your component
  7. Use your component

Installing the gecko sdk

Before beginning you should download and install the gecko sdk (standard development kit) for creating XPCOM objects. You will be using various tools provided by the gecko sdk to create and install your component. To download the sdk choose a version appropriate for your operating system available from here: http://developer.mozilla.org/en/docs/Gecko_SDK#Downloading

If you download the linux version installing is a simple matter of extracting the zipped tar to the appropriate directory. To extract it in the directory your downloaded tar ball file is in use:

bunzip2 gecko-sdk-i686-pc-linux-gnu-1.8.0.4.tar.bzip2
tar -xvf gecko-sdk-i686-pc-linux-gnu-1.8.0.4.tar

You can run the various tools by specifying the full path name to their binary executables. Note you do not need to build the gecko sdk to use it. For more information on the gecko sdk see: http://developer.mozilla.org/en/docs/Gecko_SDK

Generating GUIDs

For every component you write you will need a GUID (Globally Unique IDentifier). A GUID is a pseudo-random number that is computed in order to identify any component in the computer that requires a unique number. There are a number of tools available to generate a GUID. Here is a nice online tool which only requires one click to generate a GUID: http://www.somacon.com/p113.php Just cut and paste the generated number into your code.

For more information and other tools for generating GUIDS see http://developer.mozilla.org/en/docs/Generating_GUIDs

Generate a GUID and you are ready to go.

General Tips

Use incremental development. It is very difficult to debug an XPCOM component as the error messages are not particularly helpful. Simple typos can take a long time to find. I recommend getting a hello world example up and running to begin with or starting with a copy of a component that already works. Make sure you can install it and check that you can access your component from the calling javascript without an error.

Add a little bit of functionality at at time, always checking that your component still compiles and is still accessable from your javascript. DO NOT be tempted to write lots of code before testing as this will cost you time in the long run.

Common Errors

Below are listed a number of mistakes I have made when developing XPCOM components. The error messages are often very unhelpful so it is good to be aware of a few of the more common mistakes.

  1. Forgetting to compile the xpt file. Your idl file must be compiled to an xpt file before the component can be used. If you are not doing this manually remember to edit the appropriate makefile to ensure compilation takes place. You can check the xpt file exists/is up to date by looking at a directory listing of the directory containing your idl file.
  2. Forgetting to install the xpcom components. It is not enough to compile the xpt file, the components must also be installed into the browser. If you are building components as part of an extension make sure you reinstall the extension.
  3. Omitting a comma after a function defintion within a class prototype. The class defintion in javascript is given in terms of a prototype. The prototype contains a comma separated list of properties and functions. It is easy to forget to put a comma after a function definition which will result in your component not working.