Embedding Gecko

  • Revision slug: Mozilla_Embedding_FAQ/Embedding_Gecko
  • Revision title: Embedding Gecko
  • Revision id: 64901
  • Created:
  • Creator: trevorh
  • Is current revision? No
  • Comment ActiveX build has been removed; 8 words added

Revision Content

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 {{ Source("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 {{ Source("embedding/config/readme.html", "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 {{ Source("xpinstall/packager/xptlink.pl", "here") }}.

How do I keep up with Gecko interface changes?

If you want to be protected against changes in the Gecko, you should only use interfaces and API that are clearly marked FROZEN in their idl description. This query will find most of the frozen interfaces: {{ LXRSearch("search", "string", "us+FROZEN", "Frozen Interface and APIs") }}. Interfaces are being reviewed and frozen all the time and cover most things embedders will want to do.

You can still use unfrozen interfaces (hey it's open source and we can't stop you!) and even reach into the guts of the code but you do so at your own risk. Subsequent releases of Mozilla may well change these interfaces and your source and binary will break as a result.

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?

As long as you use frozen interfaces, the answer is: "Almost." Unfortunately vtable layout can vary from compiler to compiler. This mostly affects Linux compilers such as gcc which have changed their vtable layout more than once in the past few years. 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 (95? definitely 98 and later)
  • Linux (and probably most other X-windows based *nix variants)
  • Macintosh OS X. MacOS 8.6 and 9 support is now deprecated to the ports section of the Mozilla project and are not being actively worked on.

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:

{{ languages( { "fr": "fr/FAQ_de_Mozilla_embarqu\u00e9/Embarquer_Gecko", "ja": "ja/Mozilla_Embedding_FAQ/Embedding_Gecko" } ) }}

Revision Source

<p>
</p>
<h2 name="Section_2:_Embedding_Gecko"> Section 2: Embedding Gecko </h2>
<h3 name="What_files_do_I_need_in_order_to_embed.3F"> What files do I need in order to embed? </h3>
<p>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.
</p>
<h3 name="How_do_I_make_an_embedding_build.3F"> How do I make an embedding build? </h3>
<p>First <a href="en/Build_Documentation">build Mozilla</a>, then type:
</p>
<pre>cd mozilla/embedding/config
make
</pre>
<p>Note: When using an objdir, cd into mozilla/&lt;objdir&gt;/embedding/config instead, and run make there.
</p><p>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 <code>MFCEmbed</code> on Win32. To run <code>TestGtkEmbed</code> on Unix type:
</p>
<pre>cd mozilla/dist/Embed
./run-mozilla.sh ./TestGtkEmbed
</pre>
<h3 name="How_is_the_embedding_distribution_made.3F"> How is the embedding distribution made? </h3>
<p>Look in {{ Source("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.
</p><p>Note that this sample only contains a <i>typical</i> 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.
</p><p>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.
</p><p>The embedding distribution {{ Source("embedding/config/readme.html", "readme file") }} provides more information.
</p><p><small>Todo: provide a more complete map of features &lt;-&gt; files</small>
</p>
<h3 name="Why_do_I_need_to_distribute_XPT_files_with_my_application.3F"> Why do I need to distribute XPT files with my application? </h3>
<p>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.
</p><p>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 {{ Source("xpinstall/packager/xptlink.pl", "here") }}.
</p>
<h3 name="How_do_I_keep_up_with_Gecko_interface_changes.3F"> How do I keep up with Gecko interface changes? </h3>
<p>If you want to be protected against changes in the Gecko, you should only use interfaces and API that are clearly marked FROZEN in their idl description. This query will find most of the frozen interfaces: {{ LXRSearch("search", "string", "us+FROZEN", "Frozen Interface and APIs") }}. Interfaces are being reviewed and frozen all the time and cover most things embedders will want to do.
</p><p>You can still use unfrozen interfaces (hey it's open source and we can't stop you!) and even reach into the guts of the code but you do so at your own risk. Subsequent releases of Mozilla may well change these interfaces and your source and binary will break as a result.
</p><p>See the <a class="external" href="http://www.mozilla.org/projects/embedding/embedapiref/embedapiTOC.html">Embedding API Reference</a> for more information
</p>
<h3 name="Does_this_mean_my_compiled_product_will_work_with_all_future_versions_of_the_GRE_.2F_Gecko_.2F_Mozilla.3F"> Does this mean my compiled product will work with all future versions of the GRE / Gecko / Mozilla? </h3>
<p>As long as you use frozen interfaces, the answer is: "Almost." Unfortunately vtable layout can vary from compiler to compiler. This mostly affects Linux compilers such as gcc which have changed their vtable layout more than once in the past few years. See the document on <a href="en/Binary_compatibility">Binary compatibility</a>.
</p>
<h3 name="What_platforms_are_supported.3F"> What platforms are supported? </h3>
<p>Short answer is anything Mozilla can run on, then Gecko can too. However, the embedding is concentrating on three primary platforms:
</p>
<ul><li> Windows (95? definitely 98 and later)
</li><li> Linux (and probably most other X-windows based *nix variants)
</li><li> Macintosh OS X. MacOS 8.6 and 9 support is now deprecated to the ports section of the Mozilla project and are not being actively worked on. </li></ul>
<h3 name="Does_the_embedded_build_support_secure_protocols_like_HTTPS.3F"> Does the embedded build support secure protocols like HTTPS? </h3>
<p>Yes, psm is supported in embedding.
</p>
<h3 name="How_does_my_application_communicate_with_Gecko.3F"> How does my application communicate with Gecko? </h3>
<p>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.
</p><p><small>Todo: insert jud's picture here?</small>
</p>
<h3 name="Can_I_embed_without..."> Can I embed without... </h3>
<p>(Some of the more common questions)
</p>
<ul><li> FTP support? Yes.
</li><li> HTTPS support? Yes.
</li><li> Network support? No, maybe someday
</li><li> XUL support? No, but someday yes.
</li><li> JavaScript support? No, maybe someday.
</li><li> CSS support? No, never.
</li><li> DOM support? No, probably never.
</li><li> XML support? No, probably never.
</li><li> International Characters Sets? Yes.
</li><li> Java support? Yes. </li></ul>
<h3 name="Can_I_embed_Mozilla.27s_HTML_editor.3F"> Can I embed Mozilla's HTML editor? </h3>
<p>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).
</p><p>Documentation is lacking, mostly because of pending API changes. Check out the <a href="en/Embedding_the_Editor">Embedding the Editor</a> page for more info.
</p>
<h3 name="What_widget_toolkit_does_Mozilla_use.3F"> What widget toolkit does Mozilla use? </h3>
<p>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.
</p><p>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.
</p><p>In the future, widgets may be defined with XBL.
</p>
<h3 name="Does_the_embedded_Mozilla_have_Java_support.3F"> Does the embedded Mozilla have Java support? </h3>
<p>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.
</p>
<h3 name="Can_I_embed_Mozilla_in_any_other_way.3F">Can I embed Mozilla in any other way?</h3>
<p>Aside from programming direct to the embedding API you may also embed Mozilla:</p>
<ul> <li>In GTK applications using the <a class="external" href="http://www.mozilla.org/unix/gtk-embedding.html">Gtk Mozilla Embedding Widget</a>.</li> <li>In Win32 ActiveX applications using the <a class="external" href="http://www.iol.ie/%7Elocka/mozilla/mozilla.htm">Mozilla ActiveX Control</a>. {{ obsoleteGeneric("inline","gecko7.0") }}</li> <li>In Microsoft .NET (2.0 or higher) applications using the <a class="external" href="http://www.skybound.ca/projects/">GeckoFX Control</a>.</li> <li>In Mac applications using {{ Source("embedding/browser/powerplant/", "PPEmbed") }}.</li> <li>In a Java Application using <a class="external" href="http://www.mozilla.org/projects/blackwood/webclient/">Webclient</a> (Here is the wiki home page <a href="/en/Mozilla_Webclient" title="en/Mozilla_Webclient">Mozilla Webclient</a>, which is under construction).</li>
</ul>

<p>{{ languages( { "fr": "fr/FAQ_de_Mozilla_embarqu\u00e9/Embarquer_Gecko", "ja": "ja/Mozilla_Embedding_FAQ/Embedding_Gecko" } ) }}</p>
Revert to this revision