The Chromium Projects

Search this site

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license, and examples are licensed under the BSD License.
For Developers‎ > ‎

Contributing to WebKit

Note: This page is deprecated thanks to the introduction of the Blink project. Please see the Blink Conversion Cheatsheet for the most up-to-date instructions.

Chromium uses the WebKit rendering engine.  Instead of building Chromium-specific implementations, we prefer to contribute as much code as possible upstream to improve all WebKit-based browsers.  WebKit has a number of tools that make contributing patches easier.  To use those tools, you might want to have a complete checkout of WebKit inside your Chromium source tree.

Who Should Use this Configuration?

The easiest way to contribute to the WebKit project is to use a separate, standalone WebKit checkout.  The webkit.org site has some great documentation for getting started with that configuration.  If you are working on Linux, you may want to build the Chromium WebKit port.


However, if you often contribute to both WebKit and Chromium, or you work on pieces of WebKit that are Chromium-specific, you might consider using the hybrid setup explained below.  This setup lets you have a single source tree that contains both a full Chromium checkout and a full WebKit checkout.  The net result is something of a "turducken."  You end up with a full Chromium checkout that contains a full WebKit checkout that contains a partial Chromium checkout!  Good times.

Pulling Top-of-Tree WebKit

By default, a Chromium checkout includes only a subset of the upstream WebKit repository.  To get the full repository, you'll need to edit your .gclient file and add the following lines to your custom deps:

"custom_deps" : {
  "src/third_party/WebKit": "http://svn.webkit.org/repository/webkit/trunk",
  "src/third_party/WebKit/LayoutTests": None,
  "src/third_party/WebKit/Source": None,
  "src/third_party/WebKit/Tools/DumpRenderTree": None,
  "src/third_party/WebKit/Tools/Scripts": None,
  "src/third_party/WebKit/Tools/gdb": None,
  "src/third_party/WebKit/Tools/TestWebKitAPI": None,
  "src/third_party/WebKit/WebKitLibraries": None,
}
 
This instructs gclient to pull the latest revision of WebKit from svn.webkit.org.  Before running gclient sync, you might want to check the webkit.org canary builders to ensure that the latest revision of WebKit is compatible with the latest revision of Chromium.
  • Before syncing for the first time, you should delete any .gclient_entries lines about directories inside third_party/WebKit, or you will get complaints about directories no longer being part of your checkout.
  • You should run update-webkit (you don't need the --chromium flag) at least once before building as it will download and install some libraries into your checkout.
  • You'll probably want to do a clean build to avoid strange dependency issues when switching to these custom deps.

Configuring Your Environment

WebKit has a bunch of useful tools for automating various tasks.  You can make use of these tools by configuring your environment as follows:
  1. Add third_party/WebKit/Tools/Scripts to your path.  This directory has a bunch of awesome tools for managing patches.
  2. When you want to commit WebKit patches to Apple's repository, configure your SVN_EDITOR environment variable to commit-log-editor.  This will turn your ChangeLog entries into a commit message.  Unfortunately, commit-log-editor is a perl script and svn will be running inside a Windows cmd environment, which can't execute it.  To fix this, create a file in your third_party/WebKit dir (assuming that's where you'll be committing patches from) whose contents are:
@e:\cygwin\bin\perl.exe -Ie:\pkasting\svn\trunk\src\third_party\WebKit\Tools\Scripts -w -- e:\pkasting\svn\trunk\src\third_party\WebKit\Tools\Scripts\commit-log-editor %*

(That is a single long line.)  Of course, you should change the paths to match your directory layout.

Note that setting SVN_EDITOR this way will mess up gcl change, so you shouldn't do things like this all the time.

Once you've set up your environment, you should be able to use your WebKit checkout just like a normal checkout from webkit.org.  For example, you might want to update, build, and test the Chromium port:
  • Tools/Scripts/update-webkit --chromium
  • Tools/Scripts/build-webkit --chromium
  • Tools/Scripts/new-run-webkit-tests --chromium
Note, you'll need to run update-webkit --chromium at least once before building in order to download the version of the Chromium sources specified in Source/WebKit/Chromium/DEPS.  To learn more about how to contribute code to WebKit, head over to the Contributing Code page on webkit.org.

Windows Note: As you're probably aware from hacking on Chromium, you have at least two copies of SVN on your machine: the Cygwin version and the depot_tools version.  Generally things should work OK as long as you checkout and update with the same version at all times.  If you're using a hybrid checkout, it's probably easiest to do this by having the depot_tools svn first on your PATH.

Tips and Tricks

There are a number of tricks that can save you a good deal of time when contributing to WebKit.
  • How to run WebKit LayoutTests inside a Chromium build.
  • After you've made your change to WebKit and added your LayoutTests (you did add a LayoutTest, right?), try webkit-patch upload to upload your patch to bugs.webkit.org.
  • When you sync, it's likely you'll have conflicts in ChangeLogs.  Try using the resolve-ChangeLogs script to resolve these conflicts.
  • When converging to top-of-tree before landing a patch, try using the update-webkit script.  This will automagically resolve your ChangeLog conflicts.
  • If you're landing a patch for someone else, try webkit-patch apply-attachment ATTACHMENT_ID to download the patch from bugs.webkit.org and apply it to your working copy.
  • If you're into Git, see the docs on using Git for Webkit.
  • If you aren't a WebKit committer, remember to mark r? and cq? on the patch to request a review and let reviewers know you would like it to go through the commit queue when it is ready.

Troubleshooting

These instructions are currently a work in progress.  If you have any trouble, track down abarth or pkasting on IRC, gchat, or email and we'll try to figure out what's going wrong.
Comments