This guide explains how to build XPCOM components in C++ using the Gecko SDK.
Introduction
It is assumed that you already know something about XPCOM component development. (More information on XPCOM is available at the XPCOM project page.) The intent of this guide is to help you build your components "the right way" such that they will remain compatible with future versions of Mozilla. For information on how to retrieve and install the Gecko SDK, see here.
An XPCOM component will be compatible with future versions of Mozilla if it only makes use of frozen Gecko APIs. A frozen Gecko API is one that is included in the Gecko and marked frozen with the text <tt>@status FROZEN</tt> (with NSPR as the exception to the rule).
The frozen Gecko API consists of a set of component interfaces (C++ vtables) and <tt>extern "C"</tt> symbols exported from the XPCOM library and the NSPR libraries. The ABI of the component interfaces depends on the C++ ABI of the host compiler (i.e., the vtable format and calling conventions of the virtual methods may vary from compiler to compiler). The Gecko ABI is therefore compiler sensitive. (<tt>about:buildconfig</tt> can be loaded in Mozilla to reveal details about the compiler that was used.)
For the remainder of this guide, we'll assume you are developing components under Linux. (Ports of this guide are welcome.)
A "frozen" interface or function is guaranteed to be supported by future versions
of same major version of the platform. The SDK contains headers for all of the frozen interfaces and
functions, and it also contains headers for classes and functions defined in the
glue libraries. When those classes or functions are used, the component must link
with the corresponding static library. Every frozen interface or function will
be labeled as such in the IDL or header file with "@status FROZEN". (NOTE: NSPR is the one exception to this rule. All NSPR functions are frozen by default and are not marked as such in the respective
header files.)
The glue library exists to make common tasks easier. For example, the
nsCOMPtr class is defined in the XPCOM glue library. If your
component does not use any of the glue classes or functions, then you do
not need to link against the glue library.
Work in progress...
Linking
(Link line, version script to only expose NSGetModule, etc.)