Sunday, April 20, 2008

Building XULRunner and WinEmbed using Visual Studio 2005

Lately I have been searching around for ways to properly embed a Mozilla browser into my software and noticed that there is a huge community out there trying to do exactly the same. Unfortunately this is a tricky issue and documentation about it really hard to find and often ambiguous.
I created this brand new blog, to post as a first contribution a description of how to build XULRunner and a nice little test project called WinEmbed under windows and using Visual Studio 2005.
Please note, that none of the source code was written by me. It all comes from the Mozilla guys. I have merely gone to the hassle of compiling information from a million diverse sources, making things build and blogging all that in one location. So let's get started.

1. Some considerations before we start
There are several ways to embed a mozilla browser into your own software, some are better, some are worse but all of them greatly depend on what you actually want to achieve. As for me, I wanted to have a browser window embedded into my own GUI. Somethting that nicely renders web pages, can handle flash and javascript and is extensible and free.
In the beginning I tried embedding Firefox, meaning that I checked out the source code, built it and tried to figure out how to change it so that it would fit my needs. Not a very good choice!
But there is a better one: XULRunner. XULRunner is a kind of runtime environment that allows you to run XUL applications. These XUL applications are packaged pieces of software with descriptors that tell the XULRunner runtime, where to find resources and how to display them.
More than that, XULRunner can also be used for embedding the Mozilla browser engine (Gecko) into your own software. WinEmbed - a test project from Mozilla, and part of the CVS checkout - demonstrates how that is done.
The basic idea behind it is, that you write your embedding code in such a way that at startup of your software, the embedded browser components are loaded dynamically from a XULRunner installation on your system.
This means that when you want to deploy your software you will have to deploy a XULRunner installation along side with it. One of the many benefits of this solution is that you can use clean interfaces to the XULRunner components and don't have to change any browser code to fit it your needs.

2. Getting the Source Code
As posted on http://www.nathanm.com/building-xulrunner/, you have to get XULRunner and build it. You can either get a packaged version of the sources or you ceckout the sources from Mozilla's CVS.
In this walkthrough we will checkout the sources from CVS.

2.1 Checkout Mozilla Sources from CVS
You need a CVS client (e.g. WinCVS or Tortoise CVS) and you need to access it with the following parameters:
Protocol: pserver
Server: "cvs-mirror.mozilla.org"
Port: default (2401 or leave blank)
Repository folder: "/cvsroot"
User name: "anonymous"
Your client will have to use a CVSROOT of :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot
This is specified also on the Mozilla web site.
If your CVS client supports it, select that you want to checkout using UNIX-like line endings. Otherwise you will have to run a python script over the checked out sources to convert line endings to UNIX format.

Checkout the module "mozilla" to your local disk.

2.2 Getting the Mozilla Build Tools
To build XULRunner you will need
  1. Visual Studio 2008 installed
  2. The Mozilla Build Tools installed and configured
See Mozilla's Build Prerequisites for the build tools and their setup.

2.3 Preparing the XULRunner build

Note: For the rest of this walkthrough, we assume that you have checked out the mozilla sources to MOZILLA_HOME

To build XULRunner, you need to create a .mozconfig.mk file in your MOZILLA_HOME folder. The file should have the following contents:
mk_add_options MOZ_CO_PROJECT=xulrunner
mk_add_options MOZ_OBJDIR=@topsrcdir@/obj-xulrunner
ac_add_options --enable-application=xulrunner
#to avoid problems on a non-vista system:
ac_add_options --disable-parental-controls
#Uncomment the following line if you
#don't want to build JavaXPCOM:

#ac_add_options --disable-javaxpcom
It may be best if you replace @topsrcdir@ with your MOZILLA_HOME directory path, since otherwise the built binaries may end up in a different place than you expect.
The .mozconfig.mk from above will make sure that the built binaries are placed in a folder called obj-xulrunner.

2.4 Building XULRunner
To build XULRunner, you will have to run "start-msvc8.bat" from the mozilla build tools. This will open a UNIX-like shell in which you can change directory to your MOZILLA_HOME. E.g. if your MOZILLA_HOME is E:\mozillacheckout, then you cd to: cd /e/mozillacheckout/mozilla
If you checked out without the UNIX-like line endings option, you have to convert the files in the source tree first by entering
python build/win32/mozilla-dos2unix.py
This will dos2unix the source tree.

After that you can start the build process by typing
make -f client.mk build
This can take a while and it will build XULRunner, the SDK, all the libraries and tests including WinEmbed.
The following important locations will be created by the build process:
  1. XULRunner: MOZILLA_HOME/mozilla/obj-xulrunner/dist/bin
  2. XULRunner Headers : MOZILLA_HOME/mozilla/obj-xulrunner/dist/include
  3. XULRunner Libraries: MOZILLA_HOME/mozilla/obj-xulrunner/dist/lib
  4. WinEmbed:MOZILLA_HOME/mozilla/obj-xulrunner/embedding/
    tests/winEmbed
2.5 Testing the XULRunner build with WinEmbed
After XULRunner was successfully built, you can test it with WinEmbed. For that you first have to register XULRunner to your system. For that
  1. open a windows command line shell
  2. cd to your MOZILLA_HOME\mozilla\obj-xulrunner\dist\bin folder
  3. type xulrunner --register-global
After that XULRunner will be registered to your system and the dynamically loaded libraries will be found at startup of WinEmbed.

To start WinEmbed, do as follows:
  1. open a windows command line shell
  2. cd to your MOZILLA_HOME\mozilla\obj-xulrunner\embedding\
    tests\winEmbed folder
  3. execute winEmbed.exe
You should see some output like "You are embedded man" and a window should open up which displays the mozilla home page in the embedded browser.

Note: If you did not register XULRunner properly, the window with the embedded browser will not show up.

3. Visual Studio 2005 Project for WinEmbed
I created a Visual Studio 2005 Solution and Project files that allow you to build and debug WinEmbed. All you have to do is download the first file below and unzip the contents to your MOZILLA_HOME\embedding\tests\winEmbed directory. Then you can open WinEmbedVS2005.sln. Make sure you study the included Readme.txt in detail.

Download Visual Studio 2005 Project Files
Download Visual Studio 2005 Project Files and Sources of WinEmbed


Resources
  • http://www.mozilla.org/projects/embedding/
  • http://developer.mozilla.org/en/docs/VC8_Build_Instructions
  • http://lxr.mozilla.org/seamonkey/
  • http://developer.mozilla.org/en/docs/XPCOM
  • http://www.mozilla.org/projects/embedding/embedapiref/embedapiTOC.html
  • http://www.mozilla.org/projects/xpcom/glue/Component_Reuse.html
  • http://developer.mozilla.org/en/docs/XPCOM_Glue#Using_Mozilla_internal_linkage
  • http://starkravingfinkle.org/blog/2006/10/mozilla-platform-xpcom-in-c/

5 comments:

Unknown said...

Hi.

I downloaded your source code which is pretty good for discovering the embedding api, I can't get WebBrowserChrome::SetDimensions to be called when moving the window or resizing it, could you give a tip?

Thanks

Yeti

Rajneesh said...

great work!! Saved my time..This link has been added to my blog :
http://mytechknow.blogspot.com/

dimplex said...

Open source help always good for beginners.

Android developer said...

Interesting blog and i actually enjoyed to arrangement your blog and i ahead best of the peoples are cast your brawl blog because they get able activity to apprehend your information.

Android app developers said...

This is one of the Important and useful post.I like your blog clarity.This is one of the nice post.