Embedding Gecko

Obsolete
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

Warning: Embedding of Gecko is no longer supported. If you currently embed Gecko, you should use an alternate solution, because you will not be able to pick up new security improvements. Do not use the techniques covered on this page; this material is retained for historical purposes only.

Section 2: Embedding Gecko

What files do I need in order to embed?

Today you must download and build the entire mozilla browser source tree, and then choose the binary files which you will use in your embedding application. The nightly embedding builds are produced automatically from file manifests so that would be a good place to start looking.

How do I make an embedding build?

First build Mozilla, then type:

cd mozilla/embedding/config
make

Note: When using an objdir, cd into mozilla/<objdir>/embedding/config instead, and run make there.

This creates a directory called mozilla/dist/Embed containing the files and chrome specified by the sample manifests. You can test the sample build by running the test applications TestGtkEmbed on Unix or MFCEmbed on Win32. To run TestGtkEmbed on Unix type:

cd mozilla/dist/Embed
./run-mozilla.sh ./TestGtkEmbed

How is the embedding distribution made?

Look in embedding/config/ to see a the embedding build process. The basebrowser-win (or basebrowser-unix etc.) file determines which files need to be copied. The embed-jar.mn specifies what chrome is required.

Note that this sample only contains a typical subset of files. You may wish to add or remove files from basebrowser-foo (where foo is win, unix or mach as appropriate) depending on the capabilities you need in your product, or supplement these files by writing your own client-foo file which will be read in addition to basebrowser-foo.

For instance, you can remove the "necko2" library if you do not need FTP, but you will need to add the "appcomps" and "mork" libraries in order to use the Mozilla browser's global history implementation.

The embedding distribution readme file provides more information.

Todo: provide a more complete map of features <-> files

Why do I need to distribute XPT files with my application?

XPT files are XPCOM type libraries and contain binary definitions of interfaces used by cross-thread marshalling routines and JavaScript to call objects. In other words they are as vital as DLLs to ensure Gecko functions properly.

XPT files can be concatenated together using the xpt_link tool to reduce clutter and improve startup performance. There is a special perl script for this purpose, that you can see here.

For details on how to create an XPT file on Windows, see Generating XPT on Windows.

How do I keep up with Gecko interface changes?

Your best bet is to try, whenever possible, to use interfaces that are well-established whenever possible, to avoid interfaces that are the most likely to change. However, interfaces are no longer frozen, so they can change (this applies even to interfaces that were, in the past, frozen). However, the MDN wiki posts a list of changes likely to affect developers with each release. Although these lists are written with Firefox add-on developers in mind, the details about changes to interfaces will certainly apply to embedders as well.

See the Embedding API Reference for more information

Does this mean my compiled product will work with all future versions of the GRE / Gecko / Mozilla?

Sort of. You will need to recompile your product for each version of Gecko, since binary compatibility is not only no longer assured, but is specifically prevented for safety reasons. See the document on Binary compatibility.

What platforms are supported?

Short answer is anything Mozilla can run on, then Gecko can too. However, the embedding is concentrating on three primary platforms:

Windows 2000 and later
Linux (and probably most other X-windows based *nix variants)
Mac OS X 10.5 and later

Does the embedded build support secure protocols like HTTPS?

Yes, psm is supported in embedding.

How does my application communicate with Gecko?

The Embedding API provides a set of interfaces and to control the embedded application, and another set of interfaces that the containing application must implement in order to receive asynchronous notifications from the embedded browser.

Todo: insert jud's picture here?

Can I embed without...

(Some of the more common questions)

FTP support? Yes.
HTTPS support? Yes.
Network support? No, maybe someday
XUL support? No, but someday yes.
JavaScript support? No, maybe someday.
CSS support? No, never.
DOM support? No, probably never.
XML support? No, probably never.
International Characters Sets? Yes.
Java support? Yes.

Can I embed Mozilla's HTML editor?

Sort of. The latest word is that you can embed an editor in a native app, and do command handling and updating via the command handling APIs. There is some lacking functionality (e.g. controlling editor types, inserting and extracting HTML). In addition, the command handling APIs are soon going to change, when Mike Judge lands a long-standing patch (which missed the 1.0 change, and bas been delayed way too long).

Documentation is lacking, mostly because of pending API changes. Check out the Embedding the Editor page for more info.

What widget toolkit does Mozilla use?

Mozilla makes its own cross-platform widgets for HTML forms, and does not use a 3rd-party cross platform toolkit, nor the native widgets that a platform provides. The widgets are drawn using GFX, Mozilla's abstraction of a drawing toolkit. They are styled with CSS, including minor per-platform tweaks to allow them to look like the native platform's native widgets. This allows full CSS and DOM support of all HTML widgets across all platforms, without requiring each platform to separately support every part of CSS and DOM.

There have been a number of requests for native widget support but at this time there are no plans to support a second widget set beyond the cross-platform widgets.

In the future, widgets may be defined with XBL.

Does the embedded Mozilla have Java support?

We provide Java support through the OJI plugin API. The Java plugin from Sun takes ~7Mb of disk space (Linux). If you want Java support you should edit the basebrowser-win / basebrowser-unix etc. file and uncomment the OJI section or copy those files manually after an embedding dist has been created.

Can I embed Mozilla in any other way?

Aside from programming direct to the embedding API you may also embed Mozilla:

In GTK applications using the Gtk Mozilla Embedding Widget.
In Win32 ActiveX applications using the Mozilla ActiveX Control. Obsolete since Gecko 7.0
In Microsoft .NET (2.0 or higher) applications using the GeckoFX Control.
In Mac applications using PPEmbed.
In a Java Application using Webclient (Here is the wiki home page Mozilla Webclient, which is under construction).