Debugging WebKit

To debug from within Xcode, you can use the WebKit workspace. Ensure that the Products and Intermediates locations for the workspace match those used by build-webkit by choosing File > Workspace Settings and clicking the Advanced button, selecting Custom, Relative to Workspace, and entering WebKitBuild both for Products and for Intermediates. Note that if you have specified a custom build location in Xcode preferences, then you don’t need to do this.

iOS Simulator

Debugging UIProcess or WebProcess
Run Safari with the WebKit version you built.

Execute xcrun --sdk iphonesimulator lldb --attach-name MobileSafari in the Terminal to debug the UIProcess.

Use for the value of --attach-name to debug the WebProcess:

xcrun --sdk iphonesimulator lldb --attach-name


Internal Debug Menu

There is a Debug menu that can be enabled in Safari, and it supplies many useful options to help with debugging. To enable it, run the following in your terminal:

defaults write IncludeInternalDebugMenu 1

Debugging UIProcess

  1. Open the WebKit2 Xcode project
Note: the Xcode project file depends on the build location specified in the project itself. Choose Xcode > Preferences > Locations, click Locations, click the Advanced button, and ensure that the build location is Legacy.
  1. Set the project’s build products location

    To find the WebKit you built, Xcode needs to know the build products location that build-webkit used. You can set the build products location in the project’s build settings editor.

  2. Set the project’s active scheme

    Xcode also needs to know the build configuration you used. You can set the active scheme from the workspace window.

  3. Add Safari to the project’s active scheme

    Choose Edit Scheme from scheme pop-up menu. In the leftmost pane of the window, choose Run. In the Info pane, choose Other from the Executable pop-up menu. Then select /Applications/

  4. Launch the debugger

    In the workspace window, click the Run button.

  5. See the Xcode Debugging Guide for more information on using Xcode to debug software on OS X.

Debugging WebProcess

Current versions of Safari use a process for each tab, so it is easy to end up with a new WebProcess and have to reattach. If you enable the Internal Debug Menu as outlined above, you can have Safari display the Process ID of the WebProcess for each tab. Simply go to Debug > Miscellaneous Flags and select Show Web Process IDs In Page Titles. You should now see something like [WP 60737] in the title of every web page you navigate to, and 60737 is the Process ID of the WebProcess backing that tab.

  • From the command line:
    Execute the debug-safari or debug-minibrowser script with the –target-web-process option. It will start the debugger with WebProcess as the target and with command-line arguments that will make WebProcess run Safari or MiniBrowser as its client. At the debugger prompt, enter run to start the process.
  • From Xcode:
    Open the WebKit workspace and choose “All Source (target WebProcess)” from the Scheme pop-up menu in the toolbar, then choose Product > Run. If WebKit is already built, it is quicker to choose Product > Perform Action > Run Without Building