Skip to content

Update README.md #367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
donny-dont merged 1 commit into from
Jul 11, 2024
Merged

Update README.md #367

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 102 additions & 65 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,80 +1,117 @@
# docker-webkit-dev
Docker images for doing WebKit development

[![Build Status](https://internal.cloud.drone.ci/api/badges/WebKitForWindows/docker-webkit-dev/status.svg)](https://internal.cloud.drone.ci/WebKitForWindows/docker-webkit-dev)

## Windows development

The `webkitdev` images contain the tools necessary to build WebKit on Windows.
To run the images follow the instructions for [Docker for Windows]
(https://docs.docker.com/docker-for-windows/). After installation Docker will
be able to run Linux containers. To switch over to Windows containers follow
[this visual]
(https://stefanscherer.github.io/run-linux-and-windows-containers-on-windows-10/).

Currently 1.13.1 is the tested version. The beta channel has not been tested.

### Building WinCairo

Docker images for local WebKit development and CI/CD on Windows.

[![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)

## Host Setup
Using the `webkitdev` Docker images requires a Windows host, ideally Windows 11
or Windows Server 2022 but Windows 10 and Windows Server 2019 can also be used,
with [Docker](https://www.docker.com/) installed and targeting Windows
containers. For new installs follow the latest documentation to setup
[Windows for containers](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment).

## Images
The `webkitdev` Docker images include the required software to build WebKit on
Windows. Docker images can descend from each other, following a single
inheritance model like in Object-Oriented Programming (OOP). The images in the
table below are organized by purpose and include all components of the previous
image. In practice users will likely only ever need the `msbuild-2022` one for
local builds or `buildbot-worker` for [running CI/CD](BUILDBOT.md) within the
WebKit infrastructure.

| Image | Description |
|---|---|
| [base](https://hub.docker.com/r/webkitdev/base) | The base image (depends on the tag) |
| [scripts](https://hub.docker.com/r/webkitdev/scripts) | Powershell modules to install the software needed |
| [scm](https://hub.docker.com/r/webkitdev/scm) | Contains the Source Control Management (SCM) used for WebKit, e.g. git |
| [tools](https://hub.docker.com/r/webkitdev/tools) | Contains build tools for WebKit, e.g. python, cmake, etc. |
| [msbuild-2022](https://hub.docker.com/r/webkitdev/msbuild-2022) | Contains Visual Studio Build Tools and LLVM |
| [buildbot-worker](https://hub.docker.com/r/webkitdev/buildbot-worker) | Contains Buildbot and scripts to connect to WebKit CI/CD infrastructure |

Docker images support tagging. For Windows images the tag references the version
of the container base image, Windows Server 2022 and Windows Server 2019.
Compatibility depends on what the host OS is. In general Windows 11 needs to
target 2022 tags and Windows 10 needs to target 2019 tags. For the latest
information on Windows container version compatibility see the
[documentation](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility).

| Tag | Automated | Win 11 | Win 10 | Description |
|---|:---:|:---:|:---:|---|
| 2022 | :white_check_mark: | :white_check_mark: | :x: | A Windows 2022 server container |
| windows-2022 | :x: | :white_check_mark: | :x: | A Windows container, used for Layout Tests |
| 1809 | :x: | :white_check_mark: | :white_check_mark: | A Windows 2019 server container |
| windows-1809 | :x: | :white_check_mark: | :white_check_mark: | A Windows container, used for Layout Tests |

The `windows-<version>` have a larger base image containing more Windows OS
components making them ideal for testing WebKit. The other tags use Windows
Server Core and are suitable for building WebKit.

### Building locally
> [!IMPORTANT]
> Windows 11 and Windows Server 2022 users should pull the images directly from
> DockerHub rather than building locally. The only exception is when
> [updating the images](UPDATING.md).

Run the `Build-All.ps1` PowerShell script to build the images. It expects a
single argument `-Tag` which specifies the tag to build. Use the :point_up:
table to determine what value to use.

After the script completes run `docker images` and verify the images are present
and tagged. The created time should be within the time frame the script was
executing in.

## Building the Windows WebKit port
With the `webkitdev/msbuild-2022` image everything is there to do a build of
WinCairo. To start run the following command replacing `X` with the number of
CPUs you'd like to have running the build, and `Y` with the number of GBs that
should be available for the build. The defaults for the container are not enough
to build WinCairo successfully.
the Windows WebKit port. Start out by doing a local checkout of the
[WebKit repository](https://github.com/WebKit/WebKit). The `docker run` command
needs to be populated with the following fields.

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

```powershell
# Pulls the latest image
docker pull webkitdev/msbuild-2022

# Runs an interactive shell which will remove itself when completed
docker run --name build --rm -it --cpu-count=X --memory=Yg webkitdev/msbuild-2022 cmd
docker run --name build --rm -it `
--cpu-count=<cpu-count> --memory=<memory> `
--volume <volume>:C:/webkit `
webkitdev/msbuild-2022:<tag> powershell
```

Once the command is run it will place you into a Windows Command Prompt.
From there run the following.

```cmd
:: Checkout WebKit
svn checkout -q https://svn.webkit.org/repository/webkit/trunk WebKit

:: WebKit looks for files on disk to identify the IDE. It is currently
:: unable to determine when MS Build Tools are installed. So to get
:: around this we pretend that we have Visual Studio Professional
:: installed on the machine by doing a "touch" on its location
type nul > "C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\devenv.com"

:: Build WinCairo
::
:: The output is currently being redirected to a file as there is an
:: outstanding bug on Docker for Windows where too much console output
:: will cause the container to break.
::
:: https://github.com/docker/for-win/issues/199
cd WebKit
perl Tools\Scripts\build-webkit --wincairo --64-bit
```

The build shouldn't take more than an hour. If at any point you want to check
the progress you can run the following to gain access to the container.
As an example a Windows 11 host having 8 logical cores and 32GB of memory
containing a checkout of WebKit at `C:\GitHub\webkit` would run the container
like this :point_down:.

```powershell
docker exec -it build powershell
docker run --name build --rm -it `
--cpu-count=6 --memory=16g `
--volume C:/GitHub/webkit:C:/webkit `
webkitdev/msbuild-2022:2022 powershell
```

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

```powershell
Get-Content .\WebKit\output.txt | Select-Object -last X
Select-VSEnvironment
$env:CC = 'clang-cl.exe'
$env:CXX = 'clang-cl.exe'
cd C:\webkit
perl Tools\Scripts\build-webkit
```

### Troubleshooting

Currently the only issue I've had with the setup is that the build
requires a large amount of memory. If you see in the build logs that the
compiler needs more memory then exit out of the container and start it again
with additional memory.
> [!NOTE]
> Building in a container in Hyper-V isolation, the default for Windows 11 and
> 10, will take longer than a local build. Building in a container in process
> mode, the default for Windows Server 2022 and 2019, will build in a similar
> time as a local build.
>
> Ideally dedicate a large amount of resources when running in Hyper-V to reduce
> build time.

After completion the artifacts end up in the `WebKitBuild` directory within the
checkout. The Buildbots for the Windows WebKit port use these Docker containers
so they should build WebKit without issue. However if there any problems with
the images feel free to open an issue.