Integrating BlinkGTK from an External Project

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. Choosing an integration approach

There are two ways to use BlinkGTK from the outside.

Recommendation: start with approach A, and move to approach B once you need deeper integration or |
the newest features.

2. Approach A: integrating from a binary package

2.1 Installation

# Fedora / RHEL (RPM)
sudo dnf install ./blinkgtk-bin-1.0.8-1.fc43.x86_64.rpm

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

# Generic tarball
tar xjf blinkgtk-1.2.2-build6-linux-x86_64.tar.bz2
cd blinkgtk-1.2.2-build6-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

# Run from the bin directory of the package installation
/usr/local/blinkgtk-1.0.8/bin/run-with-resources ./myapp

Important: BlinkGTK loads Chromium resource files (ICU data, the V8 snapshot, locales) from the
directory next to the binary. Either use the run-with-resources script shipped with the package, or
see "Placing resource files" below.

3. Approach B: using a Chromium build tree directly

For developers who place BlinkGTK at third_party/blinkgtk in a Chromium tree and build it there.

3.1 Building

cd /path/to/chromium/src
git clone https://blinkgtk.org/ third_party/blinkgtk
# assumes is_component_build=true is already set in your gn args
autoninja -C out/Release_Component \
  third_party/blinkgtk/examples:simple_browser \
  libblink_core.so libblink_platform.so libblink_modules.so libv8.so \
  content_shell.pak v8_context_snapshot.bin \
  locales/ja.pak locales/en-US.pak

3.2 Running (including your own application)

cd /path/to/chromium/src/out/Release_Component
LD_LIBRARY_PATH=$PWD \
BLINKGTK_GPU_MODE=swiftshader \
./myapp --no-sandbox --no-zygote

Always run from inside the out/Release_Component directory. At startup BlinkGTK looks for
./icudtl.dat, ./v8_context_snapshot.bin, ./content_shell.pak, and ./locales/.

4. Placing resource files

When running an external application outside a Chromium build tree, the following files must sit in the
same directory as the executable.

4.1 Required files

4.2 Additional files per GPU mode

SwiftShader mode (BLINKGTK_GPU_MODE=swiftshader):

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

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

5. Choosing a GPU mode

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

See GPU modes for details.

6. Common pitfalls

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

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

6.3 "build/libblinkgtk.so segfaults"

build/ at the repository root is mock output from the old Meson build. Meson was removed in
v1.0.1, but the directory may still be present on disk.

rm -rf build/

When linking from an external application, always reference either the installed
/usr/lib64/libblinkgtk.so or out/Release_Component/libblinkgtk.so inside the Chromium build tree.

6.4 "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.

7. Troubleshooting and references

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

8. Questions and bug reports

• GitHub Issues: https://blinkgtk.org/
• 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)