Embedding distribution information

## Introduction

This is the Embedding distribution of Mozilla. It serves as a reference and smoketest distribution to demonstrate a typical subset of Mozilla needed to embed it into another application. The distribution contains sample applications for testing and development purposes.

Please note the phrase typical subset! If you want to use a different subset then see the customizing the embedding distribution section below.

## Where can I find more information about embedding?

Mozilla.org - http://www.mozilla.org/.

The Embedding project page - http://www.mozilla.org/projects/embedding/. This page should serve as your main point of information for learning how to embed Mozilla in your own applications.

The Embedding Frequently Asked Questions (FAQ) page - http://www.mozilla.org/projects/embedding/faq.html.

The Embedding newsgroup - news:netscape.public.mozilla.embedding.

The Embedding QA page - http://www.mozilla.org/quality/embed/.

Instructions for building Mozilla (including Embedding) - http://www.mozilla.org/build/.

Instructions for fetching Mozilla source code (including Embedding) - http://www.mozilla.org/source.html.

## Contents

The distribution contains, libraries, resources and chrome. All of this is a subset of Mozilla, repackaged for embedding. The layout follows the usual Mozilla directory, i.e.

- ./ - Test applications, launch scripts and core libraries (xpcom, nspr etc.)
- ./components/ - XPCOM components (network, graphics, layout, content, etc.).
- ./chrome/ - chrome files. In embedding most of the chrome has been re-packaged into a single embed.jar file to make it more manageable.
- ./res/ - miscellaneous rendering and parser files.
- ./defaults/ - default preference settings

### Unix

#### TestGtkEmbed

A simple browser application built using the GTK+ Browser Widget.

#### GTK+ Browser Widget

A GTK+ widget for embedding Mozilla into GTK+/GNOME applications such as Galeon. More information about the widget may be found here http://www.mozilla.org/unix/gtk-embedding.html.

### Windows

#### MFCEmbed

A complete browser application written in MFC and the Gecko embedding APIs. This application demonstrates and exercises the functionality necessary to put together a fully featured browser using Gecko.

#### Mozilla ActiveX Control

An ActiveX browser control built with the embedding APIs. You may use the control to embed a browser inside applications written in VB, Delphi etc. More information about the control including installation instructions may be found at http://www.iol.ie/~locka/mozilla/mozilla.htm.

### Macintosh

PPEmbed is built as part of the standard Mac embedding build. Work on Fizilla Mach may also yield a Mac embedding distribution in the future.

## Installation and Usage

### Unix

1. Untar the embedding distribution into an empty directory of your choice.
2. From the command-line, cd into the directory and type './run-mozilla.sh ./TestGtkEmbed'

### Windows

1. Unzip the embedding distribution into an empty directory of your choice.
2. Double-click on mfcembed.exe

## Customizing the embedding distribution

The embedding distribution is produced by first building the full Mozilla source and cherry picking files and chrome into a separate embedding directory. Basically the steps are:

1. Build Mozilla as usual
2. cd mozilla/embedding/config
3. make

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

The embedding distribution will appear in mozilla/dist/Embed.

The build process works by reading a file called basebrowser-win (or basebrowser-unix, basebrowser-mac-macho etc.) and copying the listed files from mozilla/dist/bin into mozilla/dist/Embed. It then reads a file called embed-jar.mn and repackages the specified chrome files and directories into a single embed.jar.

This process can be customized in one of two ways:

1. Edit basebrowser-foo (where foo = win, unix etc.) and remove/add the items you require
2. Create a new file called client-foo and add the items you require. This file is detected by the build process and will be run after the contents of basebrowser-foo have been copied.

The latter is the best probably approach to take since the embedder can maintain these files without modifying ones in Mozilla. The client-foo file allows embedders to specify files to be added or removed from the default embedding distribution. A minus sign in front of a filename deletes that file.

For example if you wanted a distribution containing extra character converters, but not the ActiveX control and not XMLExtras you might define a client-win like this:

    [Embed]
    components\ucvja.dll
    components\ucvko.dll
    components\ucvcn.dll
    components\ucvtw.dll
    components\ucvtw2.dll
    components\ucvibm.dll
    -mozctl.dll
    -mozctlx.dll
    -components\xmlextras.dll
    -components\xmlextras.xpt