[[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.


= Building WinCairo =

Start "x64 Native Tools Command Prompt for VS 2022".

Some environment variables should be set.

{{{
set WEBKIT_LIBRARIES=%cd%\WebKitLibraries\win
set WEBKIT_OUTPUTDIR=%cd%\WebKitBuild
}}}


In the top source directory, use 
{{{
perl Tools/Scripts/build-webkit --wincairo --release
}}}
to start the build. 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 ==

Start "x64 Native Tools Command Prompt for VS 2022".

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

Some environment variables should be propagated to Visual Studio.

{{{
set WEBKIT_LIBRARIES=%cd%\WebKitLibraries\win
set WEBKIT_OUTPUTDIR=%cd%\WebKitBuild
}}}

If you are behind http proxy, you need more environment variables for libcurl.

{{{
set http_proxy=http://proxy.example.com:8080/
set https_proxy=%http_proxy%
set no_proxy=localhost,127.0.0.1
}}}

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 a command prompt as administrator because http tests need to run Apache service.
Set some environment variables.

{{{
set WEBKIT_LIBRARIES=%cd%\WebKitLibraries\win
set WEBKIT_OUTPUTDIR=%cd%\WebKitBuild
set WEBKIT_TESTFONTS=%cd%\Tools\WebKitTestRunner\fonts
set DUMPRENDERTREE_TEMP=%TEMP%
}}}

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.