WebKit porting tips: The good, the bad, and the ugly

I thought I’d post this article from our newsletter for those of you don’t get it. And if you don’t get our newsletter you can sign up for it here.


When porting WebKit to a new platform, there are numerous factors to consider—here’s the good, the bad, and the ugly of WebKit porting.

There are a great number of open source projects based on WebKit with many repositories to pull from. Because the decisions you make at the beginning of the porting process can end up causing you trouble later, you’ll find these tips of high value.

Where do I get my source?

The main repository for WebKit is http://www.webkit.org and it contains all of the mainstream ports. If you want to be on the bleeding edge of WebKit, this is the place to be. While this tree has many branches, by using the site you’ll always stay up to date. Keep in mind that when you pull from the trunk, you might not get a stable source code base, nor will you necessarily be getting what others are releasing—just because Apple has a great iPhone browser doesn’t mean the head branch of WebKit will give the same browser.

Another option is to use an alternate repository such as the Origyn Web Browser (OWB) at http://www.sand-labs.org/owb. This is a port of WebKit using the OWB abstraction layer. This tree is kept fairly up to date using a mirroring and automated merge strategy. It’s an attractive option based on its ease of porting since using the OWB abstraction layer means a good deal of the hard work has already been done for you. However, it’s possible that this repository might not be kept up to date. Also, the OWB source code hasn’t been merged back into the main WebKit branch, so if you wish to have your changes pushed back into the WebKit tree, this may not be your best option.

Building it

Once you’ve selected the repository, the next step is to get a working build. Crank Software recommends building a Linux or Windows version no matter what your platform. This’ll allow you to get familiar with the code and build the system on a functional target. You can play with build options and compiler settings. Also, WebKit requires many other open source libraries to build and function on a target. These include sqlite, cURL, XML, XSLT, etc. Doing this build will allow you to determine which of these’ll be required for your port. Once it’s time to work on your own build, we find it easiest to select a similar platform and start from there. Next, look for all the ifdefs for that platform in Makefiles and source code. This’ll give you an indication of how many things will have to change for the new platform.

The port

There are many areas which will require porting to a new platform. We’re now going to go through the platform layers.

OS level services

The native OS must provide core functionality to WebKit, including filesystem and network access, timer facilities, date/time services, and so on. If your system has a POSIX API, then existing code can be leveraged in this area. One area that should be scrutinized is the SharedTimer interface, which creates a common usage one-shot timer. This code has caused problems in every port the Crank Software Embedded Development Consulting Services team has ever been involved.

WebView and Chrome

Your port will have to implement its version of the WebView class and associated Frame loader and ChromeClient. These pieces are the basic building blocks of a WebKit port and Crank Software recommends starting with another port’s version to get a feel for things. The WebView will provide a client API to your system and allow loading of URLs and manipulating pages and content. Most of the callback and notification mechanisms come from these areas including NewWindow requests, progress notifications, security status, and so on.


The native platform must give WebKit a way to render content to an area of the screen. This includes setting up an area of the screen—or a surface to render to—and provide all of the rendering primitives such as rectangles, lines, and polygons. WebKit renders in a way that’ll benefit from a vector graphics API, but a generic 2D API will suffice. If your platform has a port of the common rendering API such as Cairo, this can easily be leveraged by your port. Consider skipping the more advanced features to get the port off the ground. Ignore scaling and alpha blending until your port is rendering basic pages.


The native platform will have to load and render images. WebKit provides a common set of image loaders based on open source image libraries including libpng and libjpeg. These are generic and may not give the performance that you need. The native system can use these built-in loaders or implement their own. Also, the port must provide a way of rendering images along with scaling and tile support.


The native platform must implement a font layer. This includes font loading, caching, and rendering. Don’t underestimate this portion of the port. Most times the font layer can require more time than all of the other layers combined. If your system has Freetype support, this can be leveraged from other ports as this is a commonly used library. Keep in mind that ill configured helper libraries; such as fontconfig, can cause significant performance problems.


WebKit makes heavy use of Unicode strings and requires a native system implementation. Many ports use the ICU library for this functionality. This is a good choice to start with, but tends to be very large and bloated. It can be reduced in size, but a single latin support shim can get the port off the ground quickly.

Render theme

Rendering of form elements and scrollbars must be implemented for each port. Usually, this means drawing buttons to match the underlying native controls for the port’s UI. If you’re porting to a system without a UI, then you must still implement the rendering for controls including buttons, text fields, toggle/radio buttons, and scrollbars. Start with another port, such as the Google Chrome Skia version. This’ll give you a feel for what is required for rendering. To get the initial version running, don’t get bogged down making a button look great—a rectangle looks fine to get the inital port running and demo-worthy.


In order to display and interact with web pages, you’ll have to create a custom launcher application. This application will configure the graphics system or native UI. It’s responsible for ceating the WebView and sending mouse and keyboard events to the WebKit core. Start with a very basic launcher similar to most other ports to get started.

That’s it. We’ve got a lot of WebKit experience. If you’ve got questions, contact us.