Skip to content

Commit cbfbe7f

Browse files
donny-dontdonny-dont
authored
Update README.md (#367)
1 parent 5723eb4 commit cbfbe7f

File tree

1 file changed

+102
-65
lines changed

1 file changed

+102
-65
lines changed

‎README.md‎

Lines changed: 102 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,117 @@
11
# docker-webkit-dev
2-
Docker images for doing WebKit development
3-
4-
[![Build Status](https://internal.cloud.drone.ci/api/badges/WebKitForWindows/docker-webkit-dev/status.svg)](https://internal.cloud.drone.ci/WebKitForWindows/docker-webkit-dev)
5-
6-
## Windows development
7-
8-
The `webkitdev` images contain the tools necessary to build WebKit on Windows.
9-
To run the images follow the instructions for [Docker for Windows]
10-
(https://docs.docker.com/docker-for-windows/). After installation Docker will
11-
be able to run Linux containers. To switch over to Windows containers follow
12-
[this visual]
13-
(https://stefanscherer.github.io/run-linux-and-windows-containers-on-windows-10/).
14-
15-
Currently 1.13.1 is the tested version. The beta channel has not been tested.
16-
17-
### Building WinCairo
18-
2+
Docker images for local WebKit development and CI/CD on Windows.
3+
4+
[![Build Status](https://dev.azure.com/donjolmstead/Docker%20WebKit%20Dev/_apis/build/status%2FWebKitForWindows.docker-webkit-dev?branchName=main)](https://dev.azure.com/donjolmstead/Docker%20WebKit%20Dev/_build/latest?definitionId=1&branchName=main)
5+
6+
## Host Setup
7+
Using the `webkitdev` Docker images requires a Windows host, ideally Windows 11
8+
or Windows Server 2022 but Windows 10 and Windows Server 2019 can also be used,
9+
with [Docker](https://www.docker.com/) installed and targeting Windows
10+
containers. For new installs follow the latest documentation to setup
11+
[Windows for containers](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment).
12+
13+
## Images
14+
The `webkitdev` Docker images include the required software to build WebKit on
15+
Windows. Docker images can descend from each other, following a single
16+
inheritance model like in Object-Oriented Programming (OOP). The images in the
17+
table below are organized by purpose and include all components of the previous
18+
image. In practice users will likely only ever need the `msbuild-2022` one for
19+
local builds or `buildbot-worker` for [running CI/CD](BUILDBOT.md) within the
20+
WebKit infrastructure.
21+
22+
| Image | Description |
23+
|---|---|
24+
| [base](https://hub.docker.com/r/webkitdev/base) | The base image (depends on the tag) |
25+
| [scripts](https://hub.docker.com/r/webkitdev/scripts) | Powershell modules to install the software needed |
26+
| [scm](https://hub.docker.com/r/webkitdev/scm) | Contains the Source Control Management (SCM) used for WebKit, e.g. git |
27+
| [tools](https://hub.docker.com/r/webkitdev/tools) | Contains build tools for WebKit, e.g. python, cmake, etc. |
28+
| [msbuild-2022](https://hub.docker.com/r/webkitdev/msbuild-2022) | Contains Visual Studio Build Tools and LLVM |
29+
| [buildbot-worker](https://hub.docker.com/r/webkitdev/buildbot-worker) | Contains Buildbot and scripts to connect to WebKit CI/CD infrastructure |
30+
31+
Docker images support tagging. For Windows images the tag references the version
32+
of the container base image, Windows Server 2022 and Windows Server 2019.
33+
Compatibility depends on what the host OS is. In general Windows 11 needs to
34+
target 2022 tags and Windows 10 needs to target 2019 tags. For the latest
35+
information on Windows container version compatibility see the
36+
[documentation](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility).
37+
38+
| Tag | Automated | Win 11 | Win 10 | Description |
39+
|---|:---:|:---:|:---:|---|
40+
| 2022 | :white_check_mark: | :white_check_mark: | :x: | A Windows 2022 server container |
41+
| windows-2022 | :x: | :white_check_mark: | :x: | A Windows container, used for Layout Tests |
42+
| 1809 | :x: | :white_check_mark: | :white_check_mark: | A Windows 2019 server container |
43+
| windows-1809 | :x: | :white_check_mark: | :white_check_mark: | A Windows container, used for Layout Tests |
44+
45+
The `windows-<version>` have a larger base image containing more Windows OS
46+
components making them ideal for testing WebKit. The other tags use Windows
47+
Server Core and are suitable for building WebKit.
48+
49+
### Building locally
50+
> [!IMPORTANT]
51+
> Windows 11 and Windows Server 2022 users should pull the images directly from
52+
> DockerHub rather than building locally. The only exception is when
53+
> [updating the images](UPDATING.md).
54+
55+
Run the `Build-All.ps1` PowerShell script to build the images. It expects a
56+
single argument `-Tag` which specifies the tag to build. Use the :point_up:
57+
table to determine what value to use.
58+
59+
After the script completes run `docker images` and verify the images are present
60+
and tagged. The created time should be within the time frame the script was
61+
executing in.
62+
63+
## Building the Windows WebKit port
1964
With the `webkitdev/msbuild-2022` image everything is there to do a build of
20-
WinCairo. To start run the following command replacing `X` with the number of
21-
CPUs you'd like to have running the build, and `Y` with the number of GBs that
22-
should be available for the build. The defaults for the container are not enough
23-
to build WinCairo successfully.
65+
the Windows WebKit port. Start out by doing a local checkout of the
66+
[WebKit repository](https://github.com/WebKit/WebKit). The `docker run` command
67+
needs to be populated with the following fields.
2468

25-
As an example with 8 logical cores setting `cpu-count` to `6` and `memory` to
26-
`16g` can successfully build WinCairo. To be safe you can give more memory and
27-
CPU to make sure the build completes.
69+
| Field | Description |
70+
|---|---|
71+
| tag | The tag to use |
72+
| cpu-count | The number of CPUs to dedicate to the container (optional on a Windows Server host) |
73+
| [memory](https://docs.docker.com/reference/cli/docker/container/run/#memory) | The memory limit for the container (optional on a Windows Server host) |
74+
| [volume](https://docs.docker.com/reference/cli/docker/container/run/#volume) | A local path containing the WebKit checkout, use `/` over `\` |
2875

2976
```powershell
30-
# Pulls the latest image
31-
docker pull webkitdev/msbuild-2022
32-
33-
# Runs an interactive shell which will remove itself when completed
34-
docker run --name build --rm -it --cpu-count=X --memory=Yg webkitdev/msbuild-2022 cmd
77+
docker run --name build --rm -it `
78+
--cpu-count=<cpu-count> --memory=<memory> `
79+
--volume <volume>:C:/webkit `
80+
webkitdev/msbuild-2022:<tag> powershell
3581
```
3682

37-
Once the command is run it will place you into a Windows Command Prompt.
38-
From there run the following.
39-
40-
```cmd
41-
:: Checkout WebKit
42-
svn checkout -q https://svn.webkit.org/repository/webkit/trunk WebKit
43-
44-
:: WebKit looks for files on disk to identify the IDE. It is currently
45-
:: unable to determine when MS Build Tools are installed. So to get
46-
:: around this we pretend that we have Visual Studio Professional
47-
:: installed on the machine by doing a "touch" on its location
48-
type nul > "C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\devenv.com"
49-
50-
:: Build WinCairo
51-
::
52-
:: The output is currently being redirected to a file as there is an
53-
:: outstanding bug on Docker for Windows where too much console output
54-
:: will cause the container to break.
55-
::
56-
:: https://github.com/docker/for-win/issues/199
57-
cd WebKit
58-
perl Tools\Scripts\build-webkit --wincairo --64-bit
59-
```
60-
61-
The build shouldn't take more than an hour. If at any point you want to check
62-
the progress you can run the following to gain access to the container.
83+
As an example a Windows 11 host having 8 logical cores and 32GB of memory
84+
containing a checkout of WebKit at `C:\GitHub\webkit` would run the container
85+
like this :point_down:.
6386

6487
```powershell
65-
docker exec -it build powershell
88+
docker run --name build --rm -it `
89+
--cpu-count=6 --memory=16g `
90+
--volume C:/GitHub/webkit:C:/webkit `
91+
webkitdev/msbuild-2022:2022 powershell
6692
```
6793

68-
Then to check the output of the file do the following where `X` is the number of
69-
lines at the end of the file to display.
94+
Once the command is run it will place you into a Powershell session. From there
95+
execute the following to build the Windows WebKit port.
7096

7197
```powershell
72-
Get-Content .\WebKit\output.txt | Select-Object -last X
98+
Select-VSEnvironment
99+
$env:CC = 'clang-cl.exe'
100+
$env:CXX = 'clang-cl.exe'
101+
cd C:\webkit
102+
perl Tools\Scripts\build-webkit
73103
```
74104

75-
### Troubleshooting
76-
77-
Currently the only issue I've had with the setup is that the build
78-
requires a large amount of memory. If you see in the build logs that the
79-
compiler needs more memory then exit out of the container and start it again
80-
with additional memory.
105+
> [!NOTE]
106+
> Building in a container in Hyper-V isolation, the default for Windows 11 and
107+
> 10, will take longer than a local build. Building in a container in process
108+
> mode, the default for Windows Server 2022 and 2019, will build in a similar
109+
> time as a local build.
110+
>
111+
> Ideally dedicate a large amount of resources when running in Hyper-V to reduce
112+
> build time.
113+
114+
After completion the artifacts end up in the `WebKitBuild` directory within the
115+
checkout. The Buildbots for the Windows WebKit port use these Docker containers
116+
so they should build WebKit without issue. However if there any problems with
117+
the images feel free to open an issue.

0 commit comments

Comments
 (0)