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.
Check out the code:
You can also use the WebKit checked out inside an existing git Chromium tree, whose origin is
For login, the scripts will automatically use your system keychain (GNOME Keyring on Linux, Keychain on Mac OS X), which is most secure, though it can be fiddly.
On Linux, first running webkit-patch without anything stored in git configuration and logging in manually stores username and password in the keyring, and then adding username only to git configuration gives automatic sign-in (if you initially log in with username set in git, it won't store all the information correctly and you'll still need to key in username).
Alternatively, you can store your password in plain text, which is easier, but insecure:
Next we setup some environment variables. You can put these in
If you also want to use goma on Mac, you'll also need
On Linux goma only requires the usual goma setup.
If you want to use clang on Linux, you'll need
Now we're ready to pull in the Chromium dependencies
First, update your checkout
Then create a branch to work on:
When you want to update your branch, update master as described above, and then rebase your branch on master:
The merge driver you configured above will take care of merging the ChangeLog files.
Then you do the actual development. Keep in mind that WebKit uses a different coding style than Chromium: WebKit Coding Style Guidelines
You can compile WebKit like this (the --makeargs parameter is only required when you use goma, otherwise ninja will use a reasonable default)
And run tests like this:
Note that currently (when?) Linux baselines are for Ubuntu Lucid, Mac baselines for Mac 10.6, and Windows baselines for Win XP. If you don't have these operating systems available, you can try to pass --no-pixel-tests and hope that the text dumps are enough to catch regressions. On Ubuntu, you can setup a chroot as described here: Using a chroot.
If you added a new file, you'll need to rerun gyp
If you added a file to WebCore, you will need register it with all build systems used in WebKit which is surprisingly difficult and beyond this simple guide.
If you change the WebCore API, you will need to update exported symbol lists for various platforms as described here: Exporting Symbols
Once you're happy with your change, you can upload it to Bugzilla, either manually via the web page, or by using
There are many configuration options, which you can list with the help command via:
To post a patch to a new bug, without requesting review (such as for a WIP), use:
This will prompt you for a one line description of your change, which will be used to create a bug on http://bugs.webkit.org/. It will also run some basic style checks on your patch, open an editor with ChangeLog entries, and show you the diff before uploading the patch. This will also store the URL https://bugs.webkit.org/show_bug.cgi?id=BUGID in the ChangeLogs, which will be used automatically determine the bug number on subsequent uploads. (It can also be stored in git commit messages, for instance, where it will also be picked up.)
You'll need EditBugs permission for the script to work properly (namely to assign the bug to you), else you'll get an error. You can request this (from anyone with EditUser permission) on the mailing list webkit-committers at lists.webkit.org or on #webkit on IRC (freenode).
There are a few conventions for the description/summary, such as using [WIP], or indicating subcomponents with [SubComponentName] or the like, and regressions with REGRESSION -- see Bug Reporting Guidelines.
There are various other fields you can fill in about the bug, detailed at Bug Reporting Guidelines. If you need to set these, it's easiest to use the web page. Of these, the most significant (and only one that can be set via the script) is the component, which you can set via --component=COMPONENT -- it may be useful to include this in a script if you generally work on a single component. You can also specify if it is only for a given platform, etc.
For subsequent uploads, you can just run this again (it will automatically determine the bug number). You likely want to automatically update the ChangeLogs (new date, revised bug description, touched files/functions), via:
Depending on the files you've touched, some people will get automatically cc'd on the issue. Otherwise, you can look at the files you've changed and try to find a good reviewer yourself, and cc them on the issue, or run
Once your patch looks good to you and is ready for review, request review by setting the r? flag:
You can also set or clear the r (review) and cq (commit queue) flags on Bugzilla by clicking on the "Details" link next to the patch, and using the relevant drop-down.
On the bug tracker, the EWS (Early Warning System) will pick up your patch and check whether it compiles on a number of different configurations. The cr-linux bot will also execute tests. If anything breaks or there's anything wrong with the patch, substantively or stylistically you will likely get r- (review rejected) from a reviewer; if it's approved, you will get r+ and proceed to committing (see below).
If you want to upload your patch to an existing bug, you can specify the bug number on the command line, or manually include the URL https://bugs.webkit.org/show_bug.cgi?id=BUGID in the ChangeLog (or git commit message):
You can specify a one-line Description for the patch, and a multi-line Comment, further describing the patch and changes.
To get from git log (making sure you've committed, so it's not the previous, unrelated git message):
To enter interactively:
Alternatively, you can use webkit-patch post-commits which does automatically get from git.
There are various git workflows, almost always starting by creating a local branch and switching to it. However, committing style varies.
If you want webkit-patch upload to pick up the bug number from the git commit message (it should pick it up from the ChangeLogs, however), use a message such as:
Instead of using webkit-patch upload you can alternatively use webkit-patch post-commits for slightly different behavior. post-commits is fundamentally for uploading a branch as a sequence of patches, and thus generates multiple attachments. For simple uses you don't want this behavior and thus must be using the "amend a single commit" workflow to get a single patch, or hack around this (if using multiple revisions on a local branch) by specifying the commitish appropriately, though this is tricky. One advantage is that post-commits will automatically set the Description (and optionally Comment) from the git commit, without needing the auxiliary scripts above. If using
If using the "amend a single commit" workflow, diff against HEAD via:
To only set the Description (no Comment), use:
You can manually run the scripts that webkit-patch runs via:
The first checks style; the second creates an updated structure for your ChangeLog entries, though you will still need to merge the old and new entries manually. You will need to update the ChangeLog entries for various reasons, such as the date changing, the bug description changing, adding tests, or change additional files or methods; this can be tedious to do this manually, hence the script
It's best to use the commit queue for landing patches. To get on the commit queue, you need to set the cq? flag on the patch (click on Details and set commit-queue to ?) or pass the
When you get a r+/cq+ on your patch, it will be automatically landed, and the commit queue will replace "Reviewed by nobody (OOPS)!" in the ChangeLogs with the respective reviewer.
Sometimes, you will get a r+/cq- (LGTM with nits). In that case, you can address the nits, and then you need to manually replace "Reviewed by nobody (OOPS)!" in the ChangeLogs with "Reviewed by Foo Bar", and upload that patch with cq? (but not requesting another review).
Once you're a committer, you can then set cq+ yourself, otherwise, any other committer can grant you cq+.
There's a number of situations where you can't use the commit queue, e.g. you might want to roll the chromium DEPS file:
or you want to commit new baselines you created with garden-o-matic:
or commit a patch from a reviewed bug:
Once your patch lands, you need to clean up by deleting your local branch. This is necessary because patches are committed outside the git flow (you don't git push them), so git doesn't know that they've been committed. You may want to wait a day or two after landing to make sure the patch didn't break anything and isn't reverted.
If you have deleted your branch and need to revise the patch, just create a new branch, download the patch from Bugzilla, and apply it. This is also automated; note that you can download reviewed patches from a bug, or a specific attachment.
webkit-patch apply-from-bug BUGID
webkit-patch apply-attachment ATTACHMENT_ID
There are two ways to test how chromium does with your change: You can either patch your patch into the WebKit checkout in chromium:
Build Chromium as usual then.
Or you can build content_shell from within WebKit and test your change there: Running layout tests using the content shell