Skip to content

Latest commit

 

History

History
168 lines (112 loc) · 7.27 KB

build.md

File metadata and controls

168 lines (112 loc) · 7.27 KB

Build Steps

Table of Contents

If you have CMake installed, the included config should work for all platforms.

EdgeHTML (Edge Legacy)

Note: It's highly recommended to choose the new Chromium-based Edge over the EdgeHTML-based Edge Legacy.

Define WEBVIEW_WIN before adding webview.hpp.

In order to target EdgeHTML (Microsoft Edge Legacy), webview uses the new C++/WinRT API.

Requirements

  • Visual Studio 2019
  • At least Windows 10, version 1809 (Build 17763)
    • The C++/WinRT API is fairly new, and its webview was introduced in v1803 (UniversalAPIContract v6). This also uses WebViewControl.AddInitializeScript introduced in v1809. For more information about API contracts, read this blog post by Microsoft.

A few things to note:

  • To debug, install the Microsoft Edge DevTools.

  • Displaying localhost in the webview will only work after adding a loopback exception. A simple way to enable this is to run

    CheckNetIsolation.exe LoopbackExempt -a -n=Microsoft.Win32WebViewHost_cw5n1h2txyewy

    This can then be checked using CheckNetIsolation.exe LoopbackExempt -s. Read more about network loopbacks here.

Build with cl.exe (Edge Legacy)

To use cl.exe directly, you'd need to grab the NuGet packages manually.

  1. Download / clone this repo and navigate to it.
  2. Get the C++/WinRT package either by using the NuGet CLI or downloading them from the NuGet website.
  3. Run .\bin\cppwinrt.exe -in sdk. (Optionally, you can add the -verbose flag.)
    • This should generate a local directory called winrt containing a bunch of headers. These are WinRT projection headers that you can use to consume from C++ code. You will be needing these headers for compilation.
  4. Compile by running cl main.cpp /DWEBVIEW_WIN /EHsc /I "." /std:c++17 /link WindowsApp.lib user32.lib kernel32.lib.

If your winrt directory is located somewhere else, change the /I "." argument above.

Build with Clang (Edge Legacy)

While not officially supported, Microsoft does use Clang internally for testing purposes. If you want to use Clang, they have some basic instructions on their website.

I've gotten clang-cl to compile with the following steps:

  1. Download / clone this repo and navigate to it.
  2. Get the C++/WinRT package either by using the NuGet CLI or downloading them from the NuGet website.
  3. Run .\bin\cppwinrt.exe -in sdk. (Optionally, you can add the -verbose flag.)
  4. Install LLVM 8.0.0. (I've tested it with 8.0.0, but Microsoft says LLVM 6.0.0 should work too.)
    • (Optional) Add LLVM to your PATH, specifically clang-cl.exe.
  5. Compile by running clang-cl main.cpp /DWEBVIEW_WIN /EHsc /I "." -Xclang -std=c++17 -Xclang -Wno-delete-non-virtual-dtor /link "WindowsApp.lib" "user32.lib" "kernel32.lib".

If your winrt directory is located somewhere else, change the /I "." argument above.

Chromium (Edge)

Define WEBVIEW_EDGE before adding webview.hpp.

To target the new Chromium Edge, webview uses the new WebView2 SDK.

Follow the instructions in the official WebView2 docs.

To summarize:

Build with cl.exe (Edge Chromium)

To use cl.exe directly, you'd need to grab the NuGet packages manually.

  1. Download / clone this repo and navigate to it.
  2. Make sure you have the new Edge installed (beta, dev, or canary) or the runtime.
  3. Get the WebView2 package and the Windows Implementation Libraries (WIL) package either by using the NuGet CLI or downloading them from the NuGet website.
    • From WebView2, you need the following files:
      • .\build\native\include\WebView2.h
      • .\build\native\x86\WebView2LoaderStatic.lib.
      • For dynamic linking, use WebView2Loader.dll.lib and make sure WebView2Loader.dll is located with your executable when running.
    • From WIL, you need .\include\wil\.
  4. Compile by running cl main.cpp /DWEBVIEW_EDGE /EHsc /std:c++17 /link WebView2LoaderStatic.lib version.lib.

MacOS

webview depends on the Cocoa and Webkit frameworks. Also, make sure your compiler supports Objective-C++ (g++ and clang++ should both work).

Use the provided CMake config to compile. Otherwise, to manually compile,

  • Define WEBVIEW_MAC
  • Enable Objective-C++ compilation
  • Add frameworks Cocoa and Webkit

For example,

clang++ main.cpp -DWEBVIEW_MAC -ObjC++ -std=c++11 -framework Cocoa -framework Webkit -o my_webview

Linux

webview depends on gtk+-3.0 and webkit2gtk-4.0:

sudo apt-get install libgtk-3-dev libwebkit2gtk-4.0-37 libwebkit2gtk-4.0-dev

Use the provided CMake config to compile. Otherwise, to manually compile,

  • Define WEBVIEW_GTK
  • Add gtk+-3.0 and webkit2gtk-4.0

For example,

g++ main.cpp -DWEBVIEW_GTK `pkg-config --cflags --libs gtk+-3.0 webkit2gtk-4.0` -o my_webview

Unit Tests

To build and run the tests,

mkdir build
cd build
cmake ../test
cmake --build .
ctest --timeout 5

Certain tests will load files from localhost:8080. Before running tests, make sure to locally host the build directory (or wherever CMake is configured). For example,

python3 -m http.server 8080 # Python 3

npm install -g http-server
http-server -p 8080         # Node

Running Headless Tests

  • Windows: Supported only for Chromium Edge (WEBVIEW_EDGE). Make sure to install the Windows 10 SDK and the WebView2 Runtime before running the webview.
  • MacOS: Supported.
  • Linux: You'll need to run xvfb (or similar) before running.

For CI examples, check out the Github Actions config under .github/workflows/.