BlinkGTK Portable Application Guide

Author: BlinkGTK Project
Last updated: 2026-07-03
Audience: Developers who want to build a self-contained (portable) application from the BlinkGTK binary distribution that runs from a single directory

1. What is a portable build?

A portable BlinkGTK application bundles your application executable together with the complete BlinkGTK / Chromium runtime in a single directory, so that it runs by simply copying the directory — no system installation (RPM/DEB) required. It relies on $ORIGIN-relative RPATH (paths resolved relative to the executable itself), so the directory keeps working wherever it is moved.

However, "self-contained" has a well-defined boundary: only the BlinkGTK and Chromium runtimes are bundled. GTK4, glibc, GPU drivers and similar components come from the host system. If you do not understand this boundary, you will run into "I copied it but it does not start" situations. Chapter 2 explains the constraints in detail.

2. Runtime environment and constraints (important)

A portable build does not run everywhere. Check the following constraints carefully.

2.1 CPU architecture

x86_64 (amd64) only. It will not run on ARM64 or other architectures (no binary compatibility).

2.2 glibc version (the most important lower bound)

BlinkGTK binaries are not statically linked; they depend on the glibc of the build environment. On systems with an older glibc, startup fails with GLIBC_x.xx not found.
Rule of thumb: use a distribution of the same generation as the build environment (Fedora 44 era) or newer. Older long-term-support distributions from several years ago are likely to fail.

How to check:

ldd --version          # host glibc version
ldd ./libblinkgtk-0.1.so.0.0.0 | grep "not found"   # list missing dependencies

If even one not found line appears, the host cannot run this build.

2.3 GTK4 comes from the host system (not bundled)

BlinkGTK is built against the system GTK4. The portable bundle does not include GTK4; the host must provide GTK4 (4.6 or later; validated against the 4.22 generation).
GTK themes, icons and input methods (ibus/fcitx) also follow the host configuration. If the host has no Japanese IME, the portable app cannot accept Japanese input either.
How to check: pkg-config --modversion gtk4, or query your distribution's package manager.

2.4 Wayland only (does not run on X11)

BlinkGTK is Wayland-only (it forces --ozone-platform=wayland internally). It does not work in X11 sessions.
A running Wayland compositor session is required (primarily validated on GNOME/Mutter; other compositors have less coverage).
Check your session type with echo $XDG_SESSION_TYPE (it must print wayland).
On SSH targets or headless servers it will not start as-is (a nested environment such as weston headless is required).

2.5 GPU / rendering paths

software path (default): works without a GPU. Always verify with the software path first.
EGL (GPU) path: requires Mesa and a dmabuf-capable GPU (validated with Intel/AMD Mesa). It may be unavailable depending on GPU and driver configuration.
On HiDPI (scale 2, etc.) environments, additional scale settings may be required to avoid rendering scale mismatches (follow the notes in the bundled launch script/configuration).

2.6 Chromium sandbox and kernel settings

The Chromium sandbox relies on unprivileged user namespaces. On systems where this is disabled (some hardened setups, containers), renderer startup can fail.
If the app does not start inside a container or restricted environment, check this first. Launching with --no-sandbox works but forfeits security protection; never use it to display untrusted content.

2.7 Filesystem requirements

Cannot execute from noexec mounts. If your USB drive or /tmp is mounted noexec, extract to a location where execution is permitted.
Extract onto a filesystem that preserves symbolic links (ext4/xfs/btrfs). On FAT/exFAT/NTFS, SONAME symlinks are lost or materialized as copies, causing startup failures or doubled size.
Distribute archives as tar.gz (preserves executable bits and symlinks). zip is not acceptable because it loses attributes.
Avoid spaces and non-ASCII characters in the extraction path.

2.8 Resources

Disk: about 650 MB or more after extraction.
Memory: expect several hundred MB or more across the process group (browser + renderer + GPU).

2.9 Fonts

Text rendering depends on the host fontconfig and fonts. Japanese text requires Japanese fonts on the host (Harano Aji, Noto CJK, etc.).

2.10 Constraint checklist

Item	Requirement	Check command
CPU	x86_64	`uname -m`
glibc	build-era or newer	`ldd --version` / `ldd ... \| grep "not found"`
GTK4	4.6+ (system)	`pkg-config --modversion gtk4`
Session	Wayland	`echo $XDG_SESSION_TYPE`
GPU (EGL)	Mesa + dmabuf	isolate with software path
user namespaces	enabled	check on sandbox startup failure
Filesystem	ext4 etc. + exec allowed	`mount \| grep noexec`
Japanese fonts	required on host	`fc-list \| grep -i mincho` etc.

3. Portable application layout

Recommended layout (single self-contained directory):

myapp-portable/
├── myapp                    # your application executable (RPATH=$ORIGIN/lib)
├── run.sh                   # launch script (optional, for environment variables)
├── lib/
│   ├── libblinkgtk-0.1.so.0.0.0
│   ├── libblinkgtk-0.1.so.0     -> libblinkgtk-0.1.so.0.0.0
│   └── chromium/            # complete Chromium runtime (from the binary distribution)
│       ├── *.so             # shared libraries
│       ├── icudtl.dat / snapshot_blob.bin / v8_context_snapshot.bin
│       ├── content_shell.pak
│       └── locales/ja.pak, en-US.pak
├── share/
│   └── myapp/               # your application resources
└── THIRD_PARTY_NOTICES.html # mandatory (Chapter 6)

The runtime set is obtained by copying usr/lib64/blinkgtk-0.1/ from the binary distribution (runtime tarball) into lib/ as-is. Do not cherry-pick files — every Chromium runtime .so, .pak, .dat, .bin, and locales/ file is required at startup (missing files are the classic cause of startup crashes).

4. Building

4.1 Mandatory link requirements

Build your application with pkg-config. Linking the PartitionAlloc allocator shim directly is mandatory (pkg-config includes it automatically). Without the shim, page loads fail and you get a black screen.

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

If you link manually without pkg-config, you must add
-lbase_allocator_partition_allocator_src_partition_alloc_allocator_shim in addition to -lblinkgtk-0.1.

4.2 Setting RPATH (the core of portability)

Give the executable an $ORIGIN-relative RPATH:

gcc -o myapp myapp.c \
  $(pkg-config --cflags blinkgtk-0.1 gtk4) \
  -Wl,-rpath,'$ORIGIN/lib' -Wl,-rpath,'$ORIGIN/lib/chromium' \
  $(pkg-config --libs blinkgtk-0.1 gtk4)

$ORIGIN means "the directory containing the executable itself" and keeps resolving after the directory is moved.
Use single quotes so the shell does not expand $ORIGIN.

As an alternative to RPATH, a launch script can set LD_LIBRARY_PATH:

#!/bin/sh
# run.sh — place directly under myapp-portable/
HERE="$(cd "$(dirname "$0")" && pwd)"
export LD_LIBRARY_PATH="$HERE/lib:$HERE/lib/chromium${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
exec "$HERE/myapp" "$@"

4.3 Verification

Always verify before distributing:

# 1. Dependency completeness (zero "not found" lines)
ldd ./myapp | grep "not found"

# 2. The shim is a direct NEEDED entry
readelf -d ./myapp | grep allocator_shim

# 3. V8 snapshot consistency (normally consistent when taken from one distribution)
# Never mix libv8.so / snapshot_blob.bin / v8_context_snapshot.bin from
# different distribution versions in lib/chromium/ (causes startup crashes)

# 4. Launch test on a real Wayland session
./run.sh

5. Distribution

Package as tar.gz (preserves symlinks and executable bits):

tar czf myapp-portable-1.0-linux-x86_64.tar.gz myapp-portable/

Always document the runtime requirements from Chapter 2 (especially glibc generation / GTK4 / Wayland-only) in your README for end users.

6. License obligations (mandatory)

When you redistribute the BlinkGTK / Chromium runtime, the following are required:

Bundle THIRD_PARTY_NOTICES.html — the aggregated license attributions included in the binary distribution. Bundle it in your portable app as-is (required by the license terms of the hundreds of third-party components contained in Chromium).
About FFmpeg (LGPL) — the bundled libffmpeg.so is LGPL v2.1+. It is shipped as an independent shared library; keep it replaceable by users (do not statically link, remove or rename it).
Also bundle the BlinkGTK LICENSE file.

7. Troubleshooting (portable-specific)

Symptom	Likely cause	Action
`GLIBC_x.xx not found`	host glibc too old	update host or use a same-generation environment (§2.2)
Crash right after startup (SIGTRAP)	mixed V8 snapshots / shim not linked	check items 2 and 3 in §4.3
No window appears	X11 session / no compositor	check `$XDG_SESSION_TYPE` (§2.4)
Page stays black	shim not linked	verify with `readelf -d` (§4.1)
`Permission denied`	noexec mount / lost exec bits	§2.7 (re-extract from tar.gz)
Starts but shows tofu/garbled text	no Japanese fonts on host	§2.9
Renderer fails to start	user namespaces disabled	§2.6

Consumer application integration guide (consumer-integration-guide-en.md) — API, signals, lifecycle
Installation guide (installation/INSTALLATION-en.md) — system installation via RPM/DEB
QUICKSTART — minimal smoke-test procedure