[[PageOutline]]

WinCairo port is a WebKit port for Windows, which is fully Open Source and redistributable unlike AppleWin port.
It is using [https://www.cairographics.org/ Cairo] for the graphics backend, [https://curl.se/libcurl/ libcurl] for the network backend.
It supports only 64 bit.

= Installing Development Tools =

You need CMake, Perl, Python, Ruby, gperf, the latest Windows 10 SDK and Visual Studio 2022 to build WinCairo port.
The easiest way to install some tools is using [https://chocolatey.org/ Chocolatey], 

{{{
choco install -y ActivePerl python ruby git gperf
}}}

`choco install cmake` doesn't configure your PATH. A switch is needed.

{{{
choco install -y cmake --installargs 'ADD_CMAKE_TO_PATH=System'
}}}


WinCairo supports CMake Ninja generator and CMake Visual Studio generator.
Ninja is optional.

{{{
choco install -y ninja
}}}


You might need more tools if you want to develop WebKit.

{{{
choco install -y svn patch diffutils
}}}

Or, you can follow the part of [https://webkit.org/webkit-on-windows/#installing-development-tools AppleWin port's instructions] to install the necessary developer tools, and check out the WebKit code.


= WinCairo command prompt =

To compile, run programs and run tests, you need to set some environment variables.
For ease of development, it's recommended to create a batch file to set environment variables and open powershell.
Create a batch file with the following content and put it in the top source directory, and double-click it to open powershell.

{{{
@echo off
cd %~dp0

path C:\xampp\apache\bin;%path%
path C:\Program Files\CMake\bin;%path%
path %ProgramFiles(x86)%\Microsoft Visual Studio\Installer;%path%
for /F "usebackq delims=" %%I in (`vswhere.exe -latest -property installationPath`) do set VSPATH=%%I

set RC_PROJECTSOURCEVERSION=0.0.0.0.0
set WEBKIT_LIBRARIES=%~dp0WebKitLibraries\win
set WEBKIT_OUTPUTDIR=%~dp0WebKitBuild
set WEBKIT_TESTFONTS=%~dp0Tools\WebKitTestRunner\fonts

set DUMPRENDERTREE_TEMP=%TEMP%

rem set http_proxy=http://your-proxy:8080
rem set https_proxy=%http_proxy%

rem set JSC_dumpOptions=1
rem set JSC_useJIT=0
rem set JSC_useDFGJIT=0
rem set JSC_useRegExpJIT=0
rem set JSC_useDOMJIT=0

rem set WEBKIT_SHOW_FPS=1

call "%VSPATH%\VC\Auxiliary\Build\vcvars64.bat"
cd %~dp0
start powershell
}}}

You can replace `powershell` with `cmd` or `wt` (Windows Terminal) if you like.

`WebKitLibraries\win` directory is the default library directory of WinCairo, but it's  a source directory and AppleWin is also using this directory.
You can change it to other directory. For example,
{{{
set WEBKIT_LIBRARIES=%~dp0WebKitLibraries\wincairo
}}}


= Building WinCairo =

In the WinCairo command prompt, invoke build-webkit to start building.
{{{
perl Tools/Scripts/build-webkit --wincairo --release
}}}

Ensure you don't have GCC in your PATH, otherwise CMake is going to use GCC and builds will fail.

build-webkit automatically downloads the latest WebKitRequirements from GitHub.
It checks the latest WebKitRequirements every time you invoke.
I'd like to recommend to use --skip-library-update for incremental build to speed up.

{{{
python Tools\Scripts\update-webkit-wincairo-libs.py
perl Tools\Scripts\build-webkit --wincairo --release --skip-library-update
}}}

The build succeeded if you got `WebKit is now built` message. Run your `MiniBrowser`.

{{{
WebKitBuild/Release/bin64/MiniBrowser.exe
}}}

== Building from within Visual Studio ==

In the WinCairo command prompt, 

{{{
perl Tools/Scripts/build-webkit --wincairo --release --no-ninja --generate-project-only
}}}

Open the generated solution file by devenv.

{{{
devenv WebKitBuild\Release\WebKit.sln
}}}

Build "MiniBrowser" project.

= Debugging WinCairo =

* [wiki:"Debugging With Visual Studio"].
* [https://github.com/WebKit/WebKit/blob/main/Introduction.md#logging-in-webkit Logging in WebKit]

= Required Libraries =

You will get required libraries downloaded automatically when you perform a {{{build-webkit --wincairo}}}.
The source code is hosted in: https://github.com/WebKitForWindows/WebKitRequirements


= Running the tests =

Install XAMPP.
XAMPP should be installed in the default install path (c:\xampp).

{{{
choco install -y XAMPP-74
}}}

Install required Python and Ruby modules.

{{{
pip install pywin32
gem install webrick
}}}


If Apache service is running, stop it.
{{{
net stop apache2.4
}}}


Some extensions need to be registered as CGI. Modify the following commands for your Perl an Python paths, and run them as administrator.

{{{
reg add HKEY_CLASSES_ROOT\.pl\Shell\ExecCGI\Command /ve /d "c:\xampp\perl\bin\perl.exe -T"
reg add HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command /ve /d "c:\xampp\perl\bin\perl.exe -T"
reg add HKEY_CLASSES_ROOT\.py\Shell\ExecCGI\Command /ve /d "c:\Python39\python.exe -X utf8"
}}}

You need openssl.exe in your PATH to run wpt server.
XAMPP contains openssl.exe in C:\xampp\apache\bin directory. Append the directory to your PATH.

Open the WinCairo command prompt as administrator because http tests need to run Apache service.

Invoke run-webkit-tests.

{{{
# for WebKit1
python Tools/Scripts/run-webkit-tests --release --wincairo -1
# for WebKit2
python Tools/Scripts/run-webkit-tests --release --wincairo
}}}

You can use Docker to run LayoutTests by mounting the host directory.

{{{
docker run -it --rm --cpu-count=8 --memory=16g -v %cd%:c:\repo -w c:\repo webkitdev/msbuild
}}}

If you are using Japanese Windows, some layout tests fails due to form control size differences.
`GetStockObject(DEFAULT_GUI_FONT)` returns `MS UI Gothic` on it. Remove `GUIFont.Facename` of `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\GRE_Initialize`. 
And, replace `MS UI Gothic` with `Microsoft Sans Serif` in `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\FontSubstitutes\MS Shell Dlg`.

If http tests fail as flaky failures due to the socket count limit, increase the user port range. See [https://bugs.webkit.org/show_bug.cgi?id=224523 Bug 224523]
{{{
netsh int ipv4 set dynamicport tcp start=1025 num=64511
}}}


= Download build artifacts from Buildbot =

* Go to [https://build.webkit.org/#/builders/27 WinCairo-64-bit-WKL-Release-Build Buildbot builder page].
* Click any "Build #" which is green.
* Click "> stdio" of "transfer-to-s3".
* You can find "S3 URL" in the console log.
* Download the zip.
* Download the corresponding release of WebKitRequirements.  https://github.com/WebKitForWindows/WebKitRequirements/releases

* Unpack them, copy all DLL of WinCairoRequirements to the directory of MiniBrowser.exe
* Install the latest [https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist vc_redist.x64.exe] of Microsoft Visual C++ Redistributable for Visual Studio


= Compile WinCairo with Clang =

clang-cl builds isn't supported anymore, see [https://bugs.webkit.org/show_bug.cgi?id=171618 Bug 171618].

clang-cl has a problem for /MP support. https://reviews.llvm.org/D52193
It's recommended to use Ninja with clang-cl.
Install clang-cl and Ninja.

{{{
choco install llvm ninja -y
}}}

Open Visual Studio Command Prompt, and invoke the following commands.

{{{
set CC=clang-cl
set CXX=clang-cl
perl Tools\Scripts\build-webkit --release --wincairo --ninja
}}}

clang-cl builds are experimental, see [https://bugs.webkit.org/show_bug.cgi?id=171618 Bug 171618] for the current status.