/webview

Tiny cross-platform webview library for C/C++/Golang. Uses WebKit (Gtk/Cocoa) and Edge (Windows)

Primary LanguageCMIT LicenseMIT

webview

Join the chat at https://gitter.im/zserge/webview Build Status GoDoc Go Report Card

A tiny cross-platform webview library for C/C++/Go to build modern cross-platform GUIs.

The goal of the project is to create a common HTML5 UI abstraction layer for the most widely used platforms.

It supports two-way JavaScript bindings (to call JavaScript from C/C++/Go and to call C/C++/Go from JavaScript).

Platform Support

Platform Technologies
Linux GTK 3, WebKitGTK
macOS Cocoa, WebKit
Windows Windows API, WebView2

Documentation

We have started working on publishing documentation at webview.dev but you can always find the most up-to-date documentation right in the source code. Improving the documentation is a continuous effort and you are more than welcome to offer suggestions or contribute with content. Please bear with us if the latest updates are not yet published.

Prerequisites

Your compiler must support minimum C++11 except for platforms that require a more modern version.

Linux and BSD

The GTK and WebKit2GTK libraries are required for development and distribution. You need to check your package repositories regarding how to install those those.

Debian-based systems:

  • Packages:
    • Development: apt install libgtk-3-dev libwebkit2gtk-4.0-dev
    • Production: apt install libgtk-3-0 libwebkit2gtk-4.0-37

BSD-based systems:

  • FreeBSD packages: pkg install webkit2-gtk3
  • Execution on BSD-based systems may require adding the wxallowed option (see mount(8)) to your fstab to bypass W^X memory protection for your executable. Please see if it works without disabling this security feature first.

Windows

Your compiler must support C++17 and we recommend to pair it with an up-to-date Windows 10 SDK.

For Visual C++ we recommend Visual Studio 2022 or later. We have a separate section for MinGW-w64.

Developers and end-users must have the WebView2 runtime installed on their system for any version of Windows before Windows 11.

Getting Started

If you are a developer of this project then please go to the development section.

Instructions here are written for GCC when compiling C/C++ code using Unix-style command lines, and assumes that you run multiple commands in the same shell. Use the Command shell on Windows with these instructions rather than PowerShell. See the MinGW-w64 requirements when building on Windows.

You will have a working app but you are encouraged to explore the available examples and try the ones that go beyond the mere basics.

Start with creating a new directory structure for your project:

mkdir my-project && cd my-project
mkdir build libs "libs/webview"

Windows Preperation

The WebView2 library is required when compiling programs:

mkdir libs\webview2
curl -sSL "https://www.nuget.org/api/v2/package/Microsoft.Web.WebView2" | tar -xf - -C libs\webview2
copy /Y libs\webview2\build\native\x64\WebView2Loader.dll build

Note: WebView2Loader.dll must be distributed along with your app unless you link it statically, in which case you must use Visual C++ for compilation.

Note: All of the examples here assume that you are targeting x64 so make sure to specify the correct path for WebView2 depending on what you are targeting.

C/C++ Preparation

Fetch the webview library:

curl -sSLo "libs/webview/webview.h" "https://raw.githubusercontent.com/webview/webview/master/webview.h"
curl -sSLo "libs/webview/webview.cc" "https://raw.githubusercontent.com/webview/webview/master/webview.cc"

Getting Started with C++

Save the basic C++ example into your project directory:

curl -sSLo basic.cc "https://raw.githubusercontent.com/webview/webview/master/examples/basic.cc"

Build and run the example:

# Linux
g++ basic.cc -std=c++11 -Ilibs/webview $(pkg-config --cflags --libs gtk+-3.0 webkit2gtk-4.0) -o build/basic && ./build/basic
# macOS
g++ basic.cc -std=c++11 -Ilibs/webview -framework WebKit -o build/basic && ./build/basic
# Windows/MinGW
g++ basic.cc -std=c++17 -Ilibs/webview -Ilibs/webview2/build/native/include -Llibs/webview2/build/native/x64 -lWebView2Loader.dll -lole32 -lshell32 -lshlwapi -luser32 -o build/basic.exe && "build/basic.exe"

Bonus for Visual C++

Build a shared library with WebView2 linked statically:

cl libs\webview\webview.cc /std:c++17 /EHsc /Fobuild\ ^
    /D "WEBVIEW_API=__declspec(dllexport)" ^
    /I libs\webview ^
    /I libs\webview2\build\native\include ^
    libs\webview2\build\native\x64\WebView2LoaderStatic.lib ^
    /link /DLL advapi32.lib /OUT:build\webview.dll

Build the example with WebView2 linked statically:

cl basic.cc /std:c++17 /EHsc /Fobuild\ ^
    /I libs\webview ^
    /I libs\webview2\build\native\include ^
    libs\webview2\build\native\x64\WebView2LoaderStatic.lib ^
    /link advapi32.lib /OUT:build\basic.exe

Getting Started with C

Save the basic C example into your project directory:

curl -sSLo basic.c "https://raw.githubusercontent.com/webview/webview/master/examples/basic.c"

Build the library and example, then run it:

# Linux
g++ -c libs/webview/webview.cc -std=c++11 $(pkg-config --cflags gtk+-3.0 webkit2gtk-4.0) -o build/webview.o
gcc -c basic.c -std=c99 -Ilibs/webview -o build/basic.o
g++ build/basic.o build/webview.o $(pkg-config --libs gtk+-3.0 webkit2gtk-4.0) -o build/basic && build/basic
# macOS
g++ -c libs/webview/webview.cc -std=c++11 -o build/webview.o
gcc -c basic.c -std=c99 -Ilibs/webview -o build/basic.o
g++ build/basic.o build/webview.o -framework WebKit -o build/basic && build/basic
# Windows/MinGW
g++ -c libs/webview/webview.cc -std=c++17 -Ilibs/webview2/build/native/include -o build/webview.o
gcc -c basic.c -std=c99 -Ilibs/webview -o build/basic.o
g++ build/basic.o build/webview.o -Llibs/webview2/build/native/x64 -lWebView2Loader.dll -lole32 -lshell32 -lshlwapi -luser32 -o build/basic.exe && "build/basic.exe"

Getting Started with Go

See Go package documentation for the Go API documentation, or simply read the source code.

Create a new module and install the package:

go mod init example.com/m
go get github.com/webview/webview

On Windows you will need to make the WebView2 loader discoverable by cgo (see Windows Preperation):

set CGO_CXXFLAGS="-I%cd%\libs\webview2\build\native\include"
set CGO_LDFLAGS="-L%cd%\libs\webview2\build\native\x64"

Save the basic Go example into your project directory:

curl -sSLo basic.go "https://raw.githubusercontent.com/webview/webview/master/examples/basic.go"

Build and run the example:

# Linux, macOS
go build -o build/basic basic.go && ./build/basic
# Windows
go build -ldflags="-H windowsgui" -o build/basic.exe basic.go && "build/basic.exe"

Note: On macOS you would typically create a bundle for your app with an icon and proper metadata.

More Examples

The examples shown here are mere pieces of a bigger picture so we encourage you to try other examples and explore on your own—you can follow the same procedure. Please get in touch if you find any issues.

Development

To build the library, examples and run tests, run script/build.sh on Unix-based systems and script/build.bat on Windows.

Note: These scripts are not in the best condition but a rewrite is being planned. Please bear with us and manually edit the scripts to your liking.

MinGW-w64 Requirements

In order to build this library using MinGW-w64 on Windows then it must support C++17 and have an up-to-date Windows SDK. This applies both when explicitly building the C/C++ library as well as when doing so implicitly through Go/cgo.

Distributions that are known to be compatible:

App Distribution

Distribution of your app is outside the scope of this library but we can give some pointers for you to explore.

macOS Application Bundle

A minimalistic bundle typically has the following directory structure:

example.app                 bundle (zip archive)
└── Contents
    ├── Info.plist          information property list
    ├── MacOS
    |   └── example         executable
    └── Resources
        └── example.icns    icon

Read more about the structure of bundles at the Apple Developer site.

Tip: The png2icns tool can create icns files from PNG files. See the icnsutils package for Debian-based systems.

Windows Apps

You would typically create a resource script file (*.rc) with information about the app as well as an icon. Since you should have MinGW-w64 readily available then you can compile the file using windres and link it into your program. If you instead use Visual C++ then look into the Windows Resource Compiler.

Remember to bundle WebView2Loader.dll unless you linked it statically.

Limitations

Browser Features

Since a browser engine is not a full web browser it may not support every feature you may expect from a browser. If you find that a feature does not work as expected then please consult with the browser engine's documentation and open an issue if you think that the library should support it.

For example, the library does not attempt to support user interaction features like alert(), confirm() and prompt() and other non-essential features like console.log().

Go Bindings

Calling Eval() or Dispatch() before Run() does not work because the webview instance has only been configured and not yet started.

Bindings

Language Project
C# webview/webview_csharp
Crystal naqvis/webview
Go webview/webview
Haskell lettier/webviewhs
Janet janet-lang/webview
Java shannah/webviewjar
Kotlin Winterreisender/webviewko
Nim oskca/webview
Pascal PierceNg/fpwebview
Python zserge/webview-python
Ruby Maaarcocr/webview_ruby
Rust Boscop/webview-rs

If you wish to add bindings to the list, feel free to submit a pull request or open an issue.

License

Code is distributed under MIT license, feel free to use it in your proprietary projects as well.