Hacker's guide to WebKit/GTK+

Code layout

The GTK+ port targets the cross-platform GLib and GTK+ APIs as well as related libraries. This means that it can be built against any of the windowing systems supported by GTK+ and Cairo without modification -- those tested so far are X11 and DirectFB. Windows should work too.

Code specific to any one backend should be conditionally compiled only when that windowing system is available. One examples of this kind of feature might be direct X11/Win32 use for plugin support. This can be done at configure time or with a switch passed to the build system, or even just using the definitions provided by the gdk headers.

The main components of the port:

Gtk+-specific modules

• Gtk+/Gtk UI platform: ​WebCore/platform/gtk

• GTK+ graphics helpers: ​WebCore/platform/graphics/gtk (this is typically for higher-level graphics functionality built on top of the Cairo graphics backend)

• "Page/Gtk": ​WebCore/page/gtk

• "Loader/Gtk": ​WebCore/loader/gtk

• WebKit Gtk: ​WebKit/gtk
  • ​webkit -- The actual public GObject API and header files
  • ​WebCoreSupport -- These are conceptually partial classes for the implementations in "WebView"
  • ​docs - API documentation
  • ​tests - API unit tests
  • ​po - String localization

• GtkLauncher (example application): ​WebKitTools/GtkLauncher

There may be other gtk-port related directories which have yet to be listed here.

Shared code modules

While the Gtk+ port is the primary consumer of these backends, we aim to keep them portable, avoiding even ifdef'd sections specific to the Gtk+ port:

• libsoup http backend: ​WebCore/platform/network/soup

• cairo graphics backend: ​WebCore/platform/graphics/cairo

• cairo graphics "canvas" element backend: ​WebCore/html/CanvasRenderingContext2D.cpp (and a few other files in WebCore/html)

• GStreamer media backend: ​WebCore/platform/graphics/gtk/MediaPlayerPrivateGStreamer.cpp (has small dependencies on GTK+/Cairo that can be easily abstracted if other ports want to share the GStreamer backend)

Bundled code modules

Bundled code is code checked into WebKit SVN that is developed and maintained primarily in some other source code repository.

• Don't change the coding style of bundled code to match the WebKit guidelines
• Avoid making needless changes to bundled code
• Don't change the copyright headers without permission
• Contribute modifications back to the originating project promptly where relevant

There isn't much bundled code at the moment, since we now use the Cairo, libpng, libjpeg etc. versions installed on the user's system.

These files are bundled from other projects:

• RenderThemeGtk backend (from Mozilla)
  • ​WebCore/platform/gtk/gtk2drawing.c ​remote
  • ​WebCore/platform/gtk/gtkdrawing.h ​remote
• Plugin support (from Mozilla)
  • ​WebCore/plugins/gtk: gtk2xtbin.c, gtk2xtbin.h, xembed.h

Working on WebCore

• The GTK+ elements of WebCore follow the WebKit coding style.

• There is no API stability in this layer. If an abstraction does not fit GTK+/Cairo/GStreamer/Libsoup concepts, feel free to seek advice on how to generalise the abstraction layer. This should not be necessary too often though.

• Documentation is generally avoided in favour of clear, self-explanatory code and good variable names.

Working on the public API

• Follow the precedent set by the Mac and Win ports. There is ​Mac API documentation available for reference.

• Document new additions with ​GtkDoc. It is OK to base GTK+ API documentation on the Objective-C documentation, but remember that "the receiver" will be "@this" or similar in GTK+ terminology, and a "method" translates to a "function" etc.

• If you find mistakes in the Objective-C API documentation, take notes and add them in the comments of your bug report.

• Check function parameters with g_return_if_fail() and g_return_val_if_fail()

• Don't use the abbreviation "URL" or "url" in any public API headers or documentation. Instead, use "URI" or "uri". This is a strong convention in GLib/GTK+ which deviates from the one used in WebCore and other WebKit ports.
  • Recommendation: Internally, relevant gchar* variables to be passed to or from the user should also be named "uri" until parsed into a KURL or WebCore data structure, at which point they should be called "url".

• Try to implement several functions at the same time to get a better understanding of how they work together and to improve consistency. This is more effective than just implementing functions and signals one by one as needed.

• Avoid drawing inspiration from ports other than Mac and Win, since they might have decided to follow their own interpretation. This is like going for the primary sources in a research project.

• If a method looks strange or out of place, ask questions until someone explains why it is the way it is. The Mac port may contain deprecated/bad API that exists only for the sake of compatibility -- we want to learn from those mistakes rather than copying them.

API rationale

The strategy here is to develop a GObject-based interpretation of the Objective-C API combined with experience working with GtkTextView, GtkHtml and gtkmozembed. This allows us to benefit from the maturity of a widely-deployed API, but demands extra caution not to adopt any of the baggage or legacy that might be present for backward compatibility only. The Win port is also a useful resource but is less suitable for direct inspiration since it hasn't been deployed as a stable API yet and has a large API footprint that would be difficult to support in the long term.

WebKitWebView

Formerly named WebKitPage (​http://bugs.webkit.org/show_bug.cgi?id=15691). Name matches GtkTextView, GtkTreeView etc. on the GTK+ side and WebView in the Mac and Win ports of WebKit.

WebKitWebFrame

Formerly WebKitFrame. Currently very similar to Mac WebFrame, this is a headless representation of a browser frame, rather than a GtkWidget like WebKitWebView.

WebKitNetworkRequest

Very limited right now but this can be considered the beginning of a public API to access the underlying HTTP stack.

WebKitWebSettings

The future of WebKitWebSettings is uncertain (​http://bugs.webkit.org/show_bug.cgi?id=16219). We might not want to do settings like this at all.

The build bots

There is a ​build bot available for most ports including GTK+. The ​waterfall view is particularly useful.

This helps keep all the ports buildable. There is also compile output provided which is helpful for understanding the build environments and compiler flags used by other ports and tracking down compiler warnings.

LayoutTests

To run the layout tests you need to have built your WebKitGTK+ with the following command:

./WebKitTools/Scripts/build-webkit --gtk

To run the tests you need to setup your environment, so that the sizes for fonts and widgets match - the render dumps are compared textually, and the sizes must match for the tests to pass. This means you need to install the Ahem true type font, and also guarantee the following output for fc-match:

$ fc-match Times
n021003l.pfb: "Nimbus Roman No9 L" "Regular"
$ fc-match Sans-Serif
Vera.ttf: "Bitstream Vera Sans" "Roman"
$ fc-match Serif
VeraSe.ttf: "Bitstream Vera Serif" "Roman"
$ fc-match Mono
VeraMono.ttf: "Bitstream Vera Sans Mono" "Roman"

This usually means installing the gsfonts-x11 and ttf-bitstream-vera packages in a Debian system. You also need to run the tests inside an X server that has no GTK+ theme set. Xvfb is recommended. So you would do something similar to this:

$ Xvfb -ac :23&
$ env -i DISPLAY=:23 ./WebKitTools/Scripts/run-webkit-tests --gtk --no-launch-safari

Never mind the 'safari' in there. It's just inheritance from the past, when Mac was the only 'port'.

Optimization

See the hacker's guide to optimizing WebKit/GTK+.