Creating XPCOM Components:Setting up the Gecko SDK

From MDC

This chapter provides basic setup information for the Gecko Software Development Kit (SDK) used to build the WebLock component in this tutorial. The following four sections tell the developer how to download and organize the Gecko SDK and create a new project in which components like WebLock can be created.

Contents 1 Downloading and Setting the SDK 2 Building a Microsoft Visual Cpp Project 2.1 Creating a New Project 2.2 Adding the Gecko SDK to the Project Settings 3 A Makefile for Unix

[edit] Downloading and Setting the SDK

The Gecko SDK provides all of the tools, headers, and libraries that you need to build XPCOM Components. The SDK is available for Windows, Linux, and Mac operating systems, and versions for other operating systems are being developed, and can be retrieved from as a single archive from the following platform-specific locations:

• Linux: http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/1.8.0.4/sdk/gecko-sdk-i686-pc-linux-gnu-1.8.0.4.tar.bz2
• Windows: http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/1.8.0.4/sdk/gecko-sdk-win32-msvc-1.8.0.4.zip
• Mac: http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/1.8.0.4/sdk/gecko-sdk-mac-1.8.0.4.zip

Note that the version number for the archives above is 1.8. The WebLock component was built with version 1.4a, which is no longer available. You may want to check for newer versions at

• Gecko versions prior to 1.7: http://releases.mozilla.org/pub/mozilla.org/mozilla/releases/
• Gecko versions after 1.8: http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/

Once you download the SDK, you can expand it into any convenient location. In this appendix, we set up the Windows Gecko SDK in c:\gecko-sdk\. If you choose some other location, remember to adjust the settings described here (e.g., in the Building a Microsoft Visual Cpp Project section below) to point to this new location.

When you extract the SDK, it should have the layout seen below:

Layout of the Extracted SDK

The directories represent different modules in the SDK. For example, the headers for networking are all located in the necko directory, and the headers that XPCOM requires are in the XPCOM directory. This directory structure makes build scripts slightly more complicated (since there will be many different include paths), but it helps to organize the parts of the SDK meaningfully.

The two top level header files are special. The file mozilla-config.h lists all of the defines used in the SDK. Including this header file in your project ensures that the component you create uses the same defines as the Gecko libraries themselves. Note that mozilla-config.h may be need to be included before other includes in your component's source code.

Each module directory is divided into three subdirectories:

Module Subdirectories

The bin directory contains static libraries, dynamic libraries, and in some cases tools that may be useful in development. The idl directory contains the public IDL files exported by the module. The includes directory contains C++ header files used by your component.

XPCOM exports a number of binaries that should be mentioned at this point. The table below refers to the Windows file names for the executables.

Application Name	Description of functionality
regxpcom.exe	Registers or Unregisters components with XPCOM
xpidl.exe	Generates typelib and C++ headers from XPIDL
xpt_dump.exe	Prints out information about a given typelib
xpt_link.exe	Combines multiple typelibs into a single typelib

Library Name	Description of functionality
xpcomglue.lib	XPCOM Glue library to be used by xpcom components.

[edit] Building a Microsoft Visual Cpp Project

Once you set up the Gecko SDK, you can create a Microsoft Visual C++ project to handle component development with the SDK.

[edit] Creating a New Project

After launching Visual C++, select New from the File menu. Then, from the New dialog, select "Win32 Dynamic-Link Library". Use the fields to the right of the dialog to name your project and set its location. (This example uses "SampleGeckoProject" as the project name and C:\ as its location.).

New Dialog

Select OK. In the Win32 Dynamic-Link Library dialog that displays (see below), you can choose the default selection "An Empty DLL Project" as the type of DLL.

In this dialog, click Finish. Microsoft Studio creates a new project per your specification and presents you with the standard Project view.

[edit] Adding the Gecko SDK to the Project Settings

In order to build anything that uses Gecko, you have to further modify the project so that it knows where to find the Gecko SDK on the disk. To edit project settings, select Settings from the Project menu (or press Alt-F7).

Most of the changes you make in the following steps apply to all configurations of the project (both Debug and Optimized), so select "All Configurations" from the Settings For dropdown menu:

On the C/C++ tab, select the Preprocessor category. This window is where you add the include paths to the Gecko SDK as well as two preprocessor defines:

• XPCOM_GLUE
• MOZILLA_STRICT_API

At a minimum, you must include the nspr, the embedstring and string include directories, and the xpcom include subdirectory. If your component will use other parts of the SDK (e.g., necko), you will have to add these include directories to this field as well.

Assuming you are using the example location for your project, these paths are the following:

• c:\gecko-sdk\embedstring\include
• c:\gecko-sdk\xpcom\include
• c:\gecko-sdk\nspr\include
• c:\gecko-sdk\string\include

Under the C++ language category, disable exception handling. As described in the section Exceptions in XPCOM, exception handling isn't supported across interface boundaries, so setting this option may catch problems during development.

The WebLock component needs to link against the appropriate libraries to uses XPCOM Glue. To add these libraries, select the Link tab, then choose the Input category. In this panel, instead of linking to the include subdirectories of the nspr, embedstring, and xpcom directories, add the paths to the bin subdirectories.

We also link against a number of libraries in the Object/library modules line:

• nspr4.lib
• plds4.lib
• plc4.lib
• embedstring.lib
• xpcomglue.lib

Both of these settings are shown below:

The last change you need to make to set up the Gecko SDK in your project is to change the "Use run-time library" setting to "Multithreaded DLL." Since this change is configuration dependent, you must make set the Release configuration run-time library to the release multithreaded DLL runtime and the Debug configuration to the debug multithreaded dll runtime (this needs clarification):

After making these changes, press OK. This finalizes the project settings and gives you a project that will hold and compile XPCOM Components.

[edit] A Makefile for Unix

On Linux, the equivalent project settings are typically handled in a Makefile. The Makefile allows you to specify any number of options for your build environment, including the path and configuration updates you need to build with the Gecko SDK.

Below is a listing for a Makefile that configures your compiler to work with the SDK. Explaining the details of the Makefile is outside the scope of this appendix, but it modifies the same properties that are configured in the Visual C++ project (see Building a Microsoft Visual Cpp Project). For a listing of the commands that appear in this listing, see the Make manual.

Sample Makefile for the Gecko SDK

CXX   = c++

CPPFLAGS +=     -fno-rtti              \
                -fno-exceptions        \
                -shared

# Change this to point at your Gecko SDK directory.
GECKO_SDK_PATH = /home/dougt/gecko-sdk

# GCC only define which allows us to not have to #include mozilla-config
# in every .cpp file.  If your not using GCC remove this line and add
# #include "mozilla-config.h" to each of your .cpp files.
GECKO_CONFIG_INCLUDE = -include mozilla-config.h

GECKO_DEFINES  = -DXPCOM_GLUE -DMOZILLA_STRICT_API

GECKO_INCLUDES = -I $(GECKO_SDK_PATH)                    \
                 -I $(GECKO_SDK_PATH)/xpcom/include      \
                 -I $(GECKO_SDK_PATH)/nspr/include       \
                 -I $(GECKO_SDK_PATH)/string/include     \
                 -I $(GECKO_SDK_PATH)/embedstring/include

GECKO_LDFLAGS =  -L $(GECKO_SDK_PATH)/xpcom/bin -lxpcomglue \
                 -L $(GECKO_SDK_PATH)/nspr/bin -lnspr4      \
                 -L $(GECKO_SDK_PATH)/nspr/bin -lplds4      \
                 -L $(GECKO_SDK_PATH)/embedstring/bin/ -lembedstring

build:
        $(CXX) -o MozShim.so $(GECKO_CONFIG_INCLUDE) $(GECKO_DEFINES) $(GECKO_INCLUDES) $(GECK\
O_LDFLAGS) $(CPPFLAGS) $(CXXFLAGS) MozShim.cpp
        chmod +x MozShim.so

clean:
        rm MozShim.so