Getting WebKit (the web engine the powers Safari) up and running is super easy, but some aspects are not super well documented. But once you get all the bits in place, getting a custom build of WebKit up and running on MacOS is a breeze.
Note: webkit.org provides a detailed getting started guide. It provides a bunch of additional/useful details, so please go there for authoritative information.
Getting the code
Getting the code for WebKit is easy (but please see WebKit’s instructions in case this blog post is out of date).
Note: WebKit is quite a few gigabytes… don’t expect a quick download!
git clone git://git.webkit.org/WebKit-https.gitcdwebkitwebkit
Building
Thanks to the provided scripts, building is also straight forward:
./Tools/Scripts/build-webkit --debug
On my 16″ MacBook Pro, this takes about 20 minutes. Note, if you have ccache installed, you can add the --use-ccache. That may improve re-compile times.
Tip: if you are doing a fair bit of hacking on WebKit, it’s useful to add /Path/To/WebKit/Tools/Scripts/ to your PATH.
Running WebKit in Safari
Running a freshly compiled WebKit in Safari (i.e., it uses your locally built WebKit as the rendering/JS engine for the system’s Safari installation) can sometimes fail when WebKit’s version gets out of sync with the installed version of Safari.
This happened to me, when I updated to Safari 14. Regardless, it’s worth a shot because it’s nice to see WebKit running in Safari proper:
./Tools/Scripts/run-safari --debug
As expected, the --debug flag compiles a debuggable (unoptimized) version for WebKit.
If you get a bunch of permission errors creating directories, you might need to “sudo” – but obviously, don’t then go to random websites. Alternatively, you can also try adding a --no-saved-state flag, which won’t write to so many directories.
Running “Mini browser”
What seems to be the preferred way to run WebKit by the WebKit community is to use what is called the “minibrowser”. As the name implies, the minibrowser is just a little browser chrome shell with stripped down functionality:
./Tools/Scripts/run-minibrowser --debug
As expected, the --debug flag tells the running which build to use. Don’t forget to add the --debug that, or it won’t work.
The minibrowser is good enough that you can run your WebKit build and do whatever testing or debugging you need to do.
Now you are up and running. Happy hacking!