1# Running Against ToT WebKit in the Simulator
2
3This is a simplified workflow intended to make it as easy as possible to compile
4and run against ToT WebKit locally. If you intend to do daily development in a
5WebKit tree, you may want to consider an alternate workflow as described
6[here](https://docs.google.com/document/d/1l74JNYr9dniUnT5aKUS1_EswlDmuQghlEfyVCiPh9a4).
7
8A design doc explaining the details behind these steps can be found
9[here](https://docs.google.com/document/d/15HCmvC_yKNpmcrgHaGUA5LWWwROCmOz7qyYnMmhQkBQ)
10
11Note: this only works on Simulator.  At present, we do not have the ability to
12compile WebKit for devices.
13
14## Warning: do this in a new checkout
15
16The changes below will substantially increase compile times, for both clean and
17incremental builds.  No-op builds will jump from ~0s to ~60s, which will
18likely be an unacceptable regression in a daily development checkout.
19
20By pulling a separate, new checkout for WebKit, you sidestep these issues at the
21expense of greater disk usage.
22
23## Updating .gclient to pull WebKit
24
25To start, edit your `.gclient` file to checkout WebKit @HEAD. Both of the custom
26variables are necessary, as by default webkit.git is pinned to a revision in the
27distant past.
28
29```
30solutions = [
31  {
32    "url": "https://chromium.googlesource.com/chromium/src.git",
33    "name": "src",
34
35    "custom_vars": {
36      "checkout_ios_webkit": True,
37      "ios_webkit_revision": "refs/heads/master",
38    },
39
40  },
41]
42target_os = ["ios"]
43target_os_only = "True"
44````
45
46Add the `custom_vars` section as above and re-run `gclient sync`.  After it
47completes, you should have a WebKit checkout in `ios/third_party/webkit/src`.
48
49## Building
50
51WebKit-enabled checkouts expose a `webkit` target via GN/ninja. The WebKit
52libraries will automatically be built as part of the default set of targets, or
53you can build it individually.
54
55```
56# Builds all targets, including webkit.
57ninja -C out/Debug-iphonesimulator
58
59# Builds just the webkit target.
60ninja -C out/Debug-iphonesimulator webkit
61```
62
63The WebKit build output can be found at
64`out/Debug-iphonesimulator/obj/ios/third_party/webkit/`.
65
66### Speeding up clean builds by building WebKit first
67
68We build using a set of scripts provided by WebKit; they set up an environment
69and then invoke xcodebuild directly.  To prevent xcodebuild from competing with
70ninja for CPU/RAM, we limit the WebKit build to four parallel jobs. This is
71generally sufficient for incremental builds, but for clean builds (or after a
72sync) it may be faster to build WebKit without this limitation.
73
74```
75# After a sync, build WebKit first.
76ios/third_party/webkit/build-webkit.py
77
78# Once WebKit is built, invoke ninja as usual to build Chromium.
79ninja -C out/Debug-iphonesimulator
80```
81
82### One-time setup (per machine, per version of Xcode)
83
84If you move to a new machine or install a new version of Xcode, you'll need to
85run a setup script in order to copy some headers from the macOS SDK into the iOS
86SDK.
87
88```
89sudo ios/third_party/webkit/src/Tools/Scripts/configure-xcode-for-ios-development
90```
91
92
93## Running against locally-built libraries
94
95To run against the libraries you've just built, set the `DYLD_FRAMEWORK_PATH`
96environment variable to the directory containing the WebKit build output.  This
97is usually easiest to do in the Xcode UI.
98
99```
100DYLD_FRAMEWORK_PATH = /path/to/out/Debug-iphonesimulator/obj/ios/third_party/webkit/Debug-iphonesimulator/
101```
102
103