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.

The XRE project, which means "XUL Runtime Environment", has been replaced by XULRunner.

Mozilla Suite: the old GRE

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: the new GRE

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

Finding and using a GRE from application code

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.dll/libxpcom.so (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

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 XPCOM_GLUE defined.
• Link with xpcomglue.lib (not 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 XPCOMGlueShutdown().

Dependent libraries and environment variables

The XULRunner GRE is designed so that the embedder does not need to set any environment variables such as PATH or 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.