The framework for embedding Mozilla technologies was at one point called the GRE (Gecko Runtime Environment). This embedding framework allows applications to locate a compatible Gecko runtime and embed it without knowing in advance where that runtime will be installed. This document describes how embedders should dynamically link to a GRE. To understand how GREs are registered, see GRE Registration.
There are two different forms for the GRE: the "old" GRE was part of the Mozilla application suite. It was installed with the Windows installer of Mozilla 1.4 through 1.7.x. There was never an official GRE shipped for Linux, but various distributors such as Red Hat have registered Mozilla installations as if they were a GRE. The Mozilla suite never supported a GRE on Mac.
XULRunner is the new version of the GRE, which not only allows embedding but is capable of bootstrapping entire XUL applications such as Firefox. XULRunner supports or is planned to support embedding on all three major platforms (Windows, Mac, and Linux).
Avoid linking directly against xpcom.dll
If an application wishes to use the GRE, it must take careful steps to ensure that it links against the proper libraries. If you link directly against
xpcom.lib import lib), your application will not launch unless xpcom.dll is in your
PATH. This prevents dynamically finding a compatible GRE at runtime.
Find a compatible GRE
Note: Support for locating a standalone glue was removed in Gecko 6.0.
To find a compatible GRE, you should use the function
GRE_GetGREPathWithProperties() (declared in
xpcom/glue/standalone/nsXPCOMGlue.h). This allows the embedder to specify what version(s) of GRE are appropriate, and to specify any special features the GRE must have (currently there are no special features defined).
Statically link to xpcomglue.lib (the "standalone glue")
The solution is to statically link against
xpcomglue.lib, also known as the "standalone glue" (see XPCOM Glue). This library provides a layer of indirection between embedding code and XPCOM. To use the XPCOM glue, you must follow these steps:
- Compile your code with
- Link with
xpcomglue_s.lib!). Don't link against the NSPR libs.
- Find a compatible GRE (see above).
- Dynamically link to that GRE using the
XPCOMGlueStartup()function. See environment variables below.
- Initialize XPCOM and do your work; when finished, shut down XPCOM.
- Unlink XPCOM with
Dependent libraries and environment variables
The XULRunner GRE is designed so that the embedder does not need to set any environment variables such as
LD_LIBRARY_PATH before calling
XPCOMGlueStartup(), because it dynamically loads the correct dependent libraries. Unfortunately, the Mozilla suite-based GRE is not as forgiving, especially on Linux. Embedders will need to set the
LD_LIBRARY_PATH environment variable and start a new process in order to embed a suite-based GRE correctly.