Gecko Embedding Basics

  • Revision slug: Gecko/Gecko_Embedding_Basics
  • Revision title: Gecko Embedding Basics
  • Revision id: 108738
  • Created:
  • Creator: Anguis
  • Is current revision? No
  • Comment /* Getting the Code */

Revision Content

Note: This document is in the process of being migrated. If you would like to help with this migration, please migrate from here.

Given the ever-growing importance of the Web as a source of information, entertainment, and personal connectedness, the ability to access and view data stored in HTML format is becoming more and more important for a wide variety of otherwise highly divergent software applications. Whether it's a matter of a simple HTML page viewer or of a full-fledged web browser, the ability to parse and render HTML-based documents is an increasingly significant function in many, many situations. For the application developer, the problem becomes how to implement this crucial functionality in a way that minimizes development time yet results in an agile and robust product. Embedding Gecko, the rendering engine at the heart of the Netscape and Mozilla browsers, is an outstanding solution to this problem.

Why Gecko

Gecko is the smart embedding choice. It is quick, robust, and highly standards compliant. In its Mozilla and Netscape incarnations, it has been widely distributed and very well reviewed.

It is Open Source. Unlike other embedding choices, all of Gecko's source code is freely available and fully customizable. You can tinker and tweak as much as you need. Yet, depending on the license chosen, it is quite possible to use Gecko as a component in what is otherwise a fully proprietary commercial product.

And because Gecko is associated with the Mozilla project, there are many resources available to assist the embedding effort. The Mozilla web site, mozilla.org, has an embedding project area at mozilla.org/projects/embedding/. There is a newsgroup, netscape.public.mozilla.embedding, focussed on exchanging information among embedders, as well as a number of other related newsgroups. A complete cross-reference for the codebase is available at lxr.mozilla.org/seamonkey/. And filing, following the progress of, and helping to fix any bugs is made simple through the Bugzilla bug database, bugzilla.mozilla.org/.

Gecko is also architected from the ground up to be cross-platform. Directly from mozilla.org, it runs on Wintel, Mac OS 9.0 and OS X, and Linux, and there are third-party ports to a number of other platforms.

Finally, licensing Gecko is royalty-free, even if the final application is an otherwise proprietary commercial product. Very generally, any modifications of the original Mozilla-supplied source code (but not the code in which it is embedded) must be returned to the community, that same original code must be made available to the application's users (often by a link to the mozilla.org website), and the application must indicate in some obvious way (for example, a logo on the box or on the About: page) that the product embeds Gecko. Exact descriptions of the possible licensing arrangements are presented at www.mozilla.org/MPL/, which is the only legally complete source for licensing information.

What You Need to Embed

Once you've decided to embed, there are three main steps that you must take. First you must get the code. Then you must understand some specific technologies used in the manipulation of the Gecko codebase. Finally, you must decide which additional functionalities you may wish to add. This section will guide you through these steps.

Getting the Code

At the moment, the best way to get the files you will need to embed Gecko is to download and build the entire Mozilla source tree. This is actually a fairly simple process. Full instructions and appropriate links are available at http://mozilla.org/source.html. A second, component by component, method is under development, but is still at a beta stage. Information on this project can be found at http://www.mozilla.org/projects/embedding/bootstrap.html. In addition, work is also being done on developing a Gecko Runtime Environment, or GRE, which would support multiple applications built on Mozilla components using a single set of core libraries. This project lives at http://www.mozilla.org/projects/embedding/GRE.html. (If you intend to work component by component you must be particularly aware of issues of versioning and binary compatibility. For help in this area, look at http://mozilla.org/projects/xpcom/glue/Component_Reuse.html.)

First you must acquire some tools (basically a supported compiler, a Perl distribution, and some general purpose utilities). Then you must set up your computer environment. Next you must download the source. Assuming you are going to download the entire tree, there are two ways to do this: you can FTP a tarball of the entire tree (this is the simplest way, and it's guaranteed to compile, but it may not include the most recent additions to the code) or you can use CVS to get the absolutely most recent code or to do incremental updates. Once you have the tree and the tools and your environment is properly set up, all you have to do is run the appropriate provided makefile. There are detailed instructions for each of the supported platforms.

When the build is done, navigate to the mozilla/embedding/config directory. There you will find sample manifest files (all the names begin with "basebrowser") for embedding on each of the different platforms. These are samples only and they may not fit your needs completely, but they are a good place to start. There are also sample embedding projects for each platform that you can use as models. See http://mozilla.org/projects/embedding/examples/index.html

Understanding the Coding Environment

XPCOM

XPIDL

XPConnect and XPT files

String classes

XUL/XBL

Choosing Additional Functionalities

What Gecko Provides

What You Provide

Common Embedding Tasks

Resources

Appendix: Data Flow Inside Gecko

Revision Source

<div class="note"><b>Note</b>: This document is in the process of being migrated.  If you would like to help with this migration, please migrate from <a class="external" href="http://www.mozilla.org/projects/embedding/embedoverview/EmbeddingBasicsTOC.html">here</a>.
</div>
<p>Given the ever-growing importance of the Web as a source of information, entertainment, and personal connectedness, the ability to access and view data stored in HTML format is becoming more and more important for a wide variety of otherwise highly divergent software applications. Whether it's a matter of a simple HTML page viewer or of a full-fledged web browser, the ability to parse and render HTML-based documents is an increasingly significant function in many, many situations. For the application developer, the problem becomes how to implement this crucial functionality in a way that minimizes development time yet results in an agile and robust product. Embedding Gecko, the rendering engine at the heart of the Netscape and Mozilla browsers, is an outstanding solution to this problem.
</p>
<h2 name="Why_Gecko"> Why Gecko </h2>
<p>Gecko is the smart embedding choice. It is quick, robust, and highly standards compliant. In its Mozilla and Netscape incarnations, it has been widely distributed and very well reviewed.
</p><p>It is Open Source. Unlike other embedding choices, all of Gecko's source code is freely available and fully customizable. You can tinker and tweak as much as you need. Yet, depending on the license chosen, it is quite possible to use Gecko as a component in what is otherwise a fully proprietary commercial product.
</p><p>And because Gecko is associated with the Mozilla project, there are many resources available to assist the embedding effort. The Mozilla web site, <a class="external" href="http://www.mozilla.org">mozilla.org</a>, has an embedding project area at <a class="external" href="http://mozilla.org/projects/embedding/">mozilla.org/projects/embedding/</a>. There is a newsgroup, netscape.public.mozilla.embedding, focussed on exchanging information among embedders, as well as a number of other related newsgroups. A complete cross-reference for the codebase is available at <a class="external" href="http://lxr.mozilla.org/seamonkey/">lxr.mozilla.org/seamonkey/</a>. And filing, following the progress of, and helping to fix any bugs is made simple through the Bugzilla bug database, <a class="external" href="http://bugzilla.mozilla.org/">bugzilla.mozilla.org/</a>.
</p><p>Gecko is also architected from the ground up to be cross-platform. Directly from mozilla.org, it runs on Wintel, Mac OS 9.0 and OS X, and Linux, and there are third-party ports to a number of other platforms.
</p><p>Finally, licensing Gecko is royalty-free, even if the final application is an otherwise proprietary commercial product. <i>Very</i> generally, any modifications of the original Mozilla-supplied source code (but not the code in which it is embedded) must be returned to the community, that same original code must be made available to the application's users (often by a link to the mozilla.org website), and the application must indicate in some obvious way (for example, a logo on the box or on the About: page) that the product embeds Gecko. Exact descriptions of the possible licensing arrangements are presented at <a class="external" href="http://www.mozilla.org/MPL/">www.mozilla.org/MPL/</a>, which is the only legally complete source for licensing information.
</p>
<h2 name="What_You_Need_to_Embed"> What You Need to Embed </h2>
<p>Once you've decided to embed, there are three main steps that you must take. First you must get the code. Then you must understand some specific technologies used in the manipulation of the Gecko codebase. Finally, you must decide which additional functionalities you may wish to add. This section will guide you through these steps.
</p>
<h3 name="Getting_the_Code"> Getting the Code </h3>
<p>At the moment, the best way to get the files you will need to embed Gecko is to download and build the entire Mozilla source tree. This is actually a fairly simple process. Full instructions and appropriate links are available at http://mozilla.org/source.html. A second, component by component, method is under development, but is still at a beta stage. Information on this project can be found at http://www.mozilla.org/projects/embedding/bootstrap.html. In addition, work is also being done on developing a Gecko Runtime Environment, or GRE, which would support multiple applications built on Mozilla components using a single set of core libraries. This project lives at http://www.mozilla.org/projects/embedding/GRE.html. (If you intend to work component by component you must be particularly aware of issues of versioning and binary compatibility. For help in this area, look at http://mozilla.org/projects/xpcom/glue/Component_Reuse.html.)
</p><p>First you must acquire some tools (basically a supported compiler, a Perl distribution, and some general purpose utilities). Then you must set up your computer environment. Next you must download the source. Assuming you are going to download the entire tree, there are two ways to do this: you can FTP a tarball of the entire tree (this is the simplest way, and it's guaranteed to compile, but it may not include the most recent additions to the code) or you can use CVS to get the absolutely most recent code or to do incremental updates. Once you have the tree and the tools and your environment is properly set up, all you have to do is run the appropriate provided makefile. There are detailed instructions for each of the supported platforms.
</p><p>When the build is done, navigate to the mozilla/embedding/config directory. There you will find sample manifest files (all the names begin with "basebrowser") for embedding on each of the different platforms. These are samples only and they may not fit your needs completely, but they are a good place to start. There are also sample embedding projects for each platform that you can use as models. See http://mozilla.org/projects/embedding/examples/index.html
</p>
<h3 name="Understanding_the_Coding_Environment"> Understanding the Coding Environment </h3>
<h4 name="XPCOM"> XPCOM </h4>
<h4 name="XPIDL"> XPIDL </h4>
<h4 name="XPConnect_and_XPT_files"> XPConnect and XPT files </h4>
<h4 name="String_classes"> String classes </h4>
<h4 name="XUL.2FXBL"> XUL/XBL </h4>
<h3 name="Choosing_Additional_Functionalities"> Choosing Additional Functionalities </h3>
<h2 name="What_Gecko_Provides"> What Gecko Provides </h2>
<h2 name="What_You_Provide"> What You Provide </h2>
<h2 name="Common_Embedding_Tasks"> Common Embedding Tasks </h2>
<h2 name="Resources"> Resources </h2>
<h2 name="Appendix:_Data_Flow_Inside_Gecko"> Appendix: Data Flow Inside Gecko </h2>
Revert to this revision