Integrating BlinkGTK from an External Project

Version: 1.2.6-build1 (Chromium 157.0.8103.38)

A guide for developers who want to use BlinkGTK as the rendering engine in another project — a custom
application, a 3D viewer, an EPUB reader, and so on.

Audience: developers who link against BlinkGTK through its C API / pkg-config without modifying
BlinkGTK's own sources.

1. How BlinkGTK is distributed

BlinkGTK is distributed as binary packages (RPM / DEB / tarball). You do not need the Chromium sources,
and pkg-config gives you the build settings. The install location is fixed (see section 3 to place files elsewhere).

2. Integrating from a binary package

2.1 Installation

# Fedora / RHEL (RPM)
sudo dnf install ./blinkgtk-release-*.noarch.rpm ./blinkgtk-bin-1.2.6-build1.fc45.x86_64.rpm

# Debian / Ubuntu (DEB)
sudo dpkg -i ./libblinkgtk-0.1-0_1.2.6-build1-1_amd64.deb \
              ./libblinkgtk-0.1-dev_1.2.6-build1-1_amd64.deb

# Generic tarball
tar xjf blinkgtk-1.2.6-build1-linux-x86_64.tar.bz2
cd blinkgtk-1.2.6-build1-linux-x86_64
sudo ./install.sh   # defaults to /usr/local

2.2 Verifying with pkg-config

pkg-config --cflags blinkgtk-0.1
# → -I/usr/include/blinkgtk-0.1 -I/usr/include/gtk-4.0 ...

pkg-config --libs blinkgtk-0.1
# → -lblinkgtk -lgtk-4 -lglib-2.0 ...

2.3 Building a minimal application

// myapp.c
#include <blink_gtk/blink_gtk.h>
#include <gtk/gtk.h>

static void on_activate(GtkApplication* app, gpointer user_data) {
    GtkWidget* win = gtk_application_window_new(app);
    gtk_window_set_default_size(GTK_WINDOW(win), 1024, 768);

    GtkWidget* view = blink_web_view_new();
    gtk_window_set_child(GTK_WINDOW(win), view);

    blink_web_view_load_uri(BLINK_WEB_VIEW(view),
                            "https://example.com");
    gtk_window_present(GTK_WINDOW(win));
}

int main(int argc, char** argv) {
    blink_gtk_init(&argc, &argv);  /* GTK4 は引数なし */
    GtkApplication* app = gtk_application_new(
        "com.example.myapp", G_APPLICATION_DEFAULT_FLAGS);
    g_signal_connect(app, "activate", G_CALLBACK(on_activate), NULL);
    /* BlinkGTK needs Chromium's browser main loop to run.
     * g_application_run() does not run it, so the page never loads
     * (the navigation never commits). Use register -> activate ->
     * blink_gtk_run_main_loop() instead.
     */
    GError *error = NULL;
    if (!g_application_register(G_APPLICATION(app), NULL, &error)) {
        g_printerr("Failed to register the application: %s\n", error ? error->message : "unknown error");
        g_clear_error(&error);
        g_object_unref(app);
        return 1;
    }
    g_application_activate(G_APPLICATION(app));
    int rc = blink_gtk_run_main_loop();
    g_object_unref(app);
    blink_gtk_shutdown();
    return rc;
}

Include only blink_gtk.h. Up to v1.2.0-build5 the package also shipped
blink_web_view.h, an internal header left over from before the GObject migration.
Including both produces conflicting types for 'BlinkWebView' and fails to compile,
so it is no longer shipped.

cc myapp.c -o myapp $(pkg-config --cflags --libs blinkgtk-0.1 gtk4)

2.4 Running

./myapp

Important: BlinkGTK loads Chromium resource files (ICU data, the V8 snapshot,
locales) from the directory next to the executable by default. If they live
elsewhere, point at them before blink_gtk_init():
/* call this before blink_gtk_init() */
blink_gtk_set_resources_path("/usr/lib64/blinkgtk-0.1/chromium");
Running with the files somewhere else and no such call fails at startup with
Invalid file descriptor to ICU data received.
See also "Placing resource files" below.

3. Placing resource files

When you run your application from a location other than where the package is installed, place the
following files in the same directory as the executable, or name their location with blink_gtk_set_resources_path().

3.1 Required files

File	Purpose	Symptom if missing
`icudtl.dat`	ICU internationalization data	`FATAL: Couldn't mmap icu data file`
`content_shell.pak`	UI resources	`FATAL: LoadFromPath failed`
`v8_context_snapshot.bin`	Faster V8 startup	`FATAL: Error loading V8 startup snapshot`
`snapshot_blob.bin`	V8 initial heap	`SIGTRAP` on a V8 version mismatch
`locales/` directory	UI localization (`ja.pak`, `en-US.pak`, …)	Starts, but translations are missing

3.2 Additional files per GPU mode

SwiftShader mode (BLINKGTK_GPU_MODE=swiftshader):

File	Purpose
`libEGL.so`	ANGLE EGL implementation
`libGLESv2.so`	ANGLE GLES2 implementation
`libvk_swiftshader.so`	SwiftShader Vulkan
`vk_swiftshader_icd.json`	Vulkan ICD manifest

Native EGL mode (BLINKGTK_GPU_MODE=egl):

No additional files are needed because the system EGL / GL libraries are used. The system does need a
Wayland-capable EGL driver (Mesa, NVIDIA, and so on).

3.3 Deployment helper script (planned)

# Planned: extract the required files from a Chromium build
scripts/setup-dev-env.sh \
  --chromium-src=/path/to/chromium/src \
  --target-dir=/path/to/your/app/runtime

4. Choosing a GPU mode

Switch with the BLINKGTK_GPU_MODE environment variable. The default is software.

Mode	On-screen rendering	Intended use
`software`	Yes	Headless, servers, CI, low-spec environments
`swiftshader`	Yes	Virtual machines, machines without a GPU, stability first
`egl`	Supported	Desktop, machines with a GPU. White screen on v1.2.0-build2 and earlier (fixed in the next release)

See GPU modes for details.

5. Common pitfalls

5.1 "White screen, nothing renders"

Likely causes:

Chromium resources (.pak, .bin) were not found, so Blink never initialized
The parent widget is not a GtkOverlay, so frame pixels are not displayed
blink_web_view_load_uri() was called before gtk_widget_realize()

How to check:

# Look for the line where blink_gtk_init completed, and the line that hands pixels to the screen
./myapp 2>&1 | grep -E "blink_gtk_init|FATAL|set_dmabuf_pixels"

No line containing blink_gtk_init → resources are missing
No line containing set_dmabuf_pixels → the rendering pipeline never started
set_dmabuf_pixels appears but every pixel is white → the loaded HTML may simply have an empty
background

5.2 "ICU data cannot be loaded"

The resource files are not next to the executable. Either copy icudtl.dat there, or point at it
explicitly with blink_gtk_set_icu_data_path().

blink_gtk_set_icu_data_path("/opt/myapp/icudtl.dat");
blink_gtk_init(&argc, &argv);  /* GTK4 は引数なし */  // must be called before init

5.3 "pkg-config cannot find `blinkgtk-0.1`"

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
pkg-config --list-all | grep blinkgtk

For a tarball installation, add the installation's lib/pkgconfig to PKG_CONFIG_PATH.

6. Troubleshooting and references

FAQ — frequently asked questions
Troubleshooting — solutions by error
GPU modes

7. Questions and bug reports

GitHub Issues: https://github.com/daisy19gnu/blinkgtk-dist/issues
When filing a new issue, please include:
- BlinkGTK version (pkg-config --modversion blinkgtk-0.1)
- Chromium version (ldd libblinkgtk.so | grep libcontent)
- GPU mode (the value of BLINKGTK_GPU_MODE)
- Startup log (./myapp 2>&1 | head -50)