[[PageOutline]]

= Successful Port How To =

This page describes how to establish and maintain a port that lives in the [http://webkit.org/building/checkout.html main Subversion repository] of the WebKit project, as well as the benefits to doing so.

Obviously you are free to create your own external repository, but if it's publicly available, please consider creating a wiki page for it under the "WebKit Ports" section of the [wiki:"WikiStart" start page].

== What is a Port? ==

A port of WebKit is a unique combination of platform technologies that run the WebKit engine.

The most common difference between ports is the operating system that they run on (e.g., Apple's Mac OS X and Windows ports), but in other cases two ports may run on the same operating system but use different graphics (or other) platform technologies (e.g., the Qt and GTK+ ports on Linux).

== Recommended Porting Steps ==

 1. `JavaScriptCore` building and `Tools/Scripts/run-javascriptcore-tests` running.
  a. This may require modifications to the `JavaScriptCore` and `JavaScriptCore/wtf` source code.
  a. If you're using a new build system you will need to modify `Tools/Scripts/webkitdirs.pm` and `Tools/Scripts/build-jsc`. 
 1. Consider setting up a webkit BuildBot at this time.  Your buildbot request may not be honored until you actually have `run-webkit-tests` running, but it's good to start the process.  Read the BuildBot page.
 1. `WebCore` building.
  a. New build systems will require more modifications to `build-webkit`.
  a. This will likely require writing many port-specific files in `WebCore/platform`.  This is the bulk of the work.
  a. Submitting patches to WebKit should be done in small chunks, with individual bugs and ChangeLogs for each patch.  Each patch should be ideally < 20k in size.
 1. `DumpRenderTree` building.  DumpRenderTree is required to run the LayoutTests (`run-webkit-tests`).
 1. `run-webkit-tests` passing.  Modify `LayoutTests/platform/YOURPLATFORM/TestExpectations` lists to skip any tests you fail.
 1. If you do not already have a BuildBot running, it is imperative that you set one up at this point.  Otherwise your port will break every week. :)
 1. Once you are this far you likely already have at least one person in your porting team with [http://webkit.org/coding/commit-review-policy.html committer rights].  If not, that should be your next goal.  

== TBD ==

NOTE: This document is a work-in-progress.  Add more information as needed!
..