Documentation · BlinkGTK

BlinkGTK ポータブルアプリケーション作成ガイド

作成者: BlinkGTK Project
最終更新: 2026-07-03
対象: BlinkGTK バイナリ配布物を使い、単一ディレクトリで動作する自己完結型 (ポータブル) アプリケーションを作成する開発者

1. ポータブル版とは

BlinkGTK のポータブル版とは、アプリケーション実行ファイルと BlinkGTK / Chromium ランタイム一式を単一ディレクトリにまとめ、システムへのインストール (RPM/DEB) なしにコピーするだけで動作する構成です。RPATH に $ORIGIN (実行ファイル自身の位置からの相対参照) を用いるため、ディレクトリごとどこに移動しても動作します。

ただし「自己完結」には明確な範囲があります。同梱されるのは BlinkGTK と Chromium ランタイムのみであり、GTK4・glibc・GPU ドライバ等はホストシステムのものを使用します。この境界を理解しないと「コピーしたのに動かない」事態になります。第 2 章で制限を詳しく解説します。

2. 動作環境と制限 (重要)

ポータブル版は「どこでも動く」わけではありません。以下の制限を必ず確認してください。

2.1 CPU アーキテクチャ

2.2 glibc バージョン (最重要の下限制約)

grep "not found" # 欠落依存の列挙

`not found` が 1 件でもあれば、そのホストでは動作しません。

### 2.3 GTK4 はシステム依存 (同梱されない)
- BlinkGTK は**システムの GTK4** に対してビルドされています。ポータブル版に GTK4 は同梱されず、ホストに GTK4 (4.6 以上、検証済みは 4.22 世代) が必要です。
- GTK テーマ・アイコン・IME (ibus/fcitx) もホスト側の構成に従います。ホストに日本語 IME がなければポータブル版でも日本語入力はできません。
- 確認方法: `pkg-config --modversion gtk4` またはディストリビューションのパッケージ管理で gtk4 の有無を確認。

### 2.4 Wayland 専用 (X11 では動作しない)
- BlinkGTK は **Wayland 専用**です (内部で `--ozone-platform=wayland` を強制)。X11 セッションでは動作しません。
- **Wayland コンポジタが動作しているセッション**が必須です (GNOME/Mutter で主に検証。他コンポジタは検証度が下がります)。
- ログインセッションが X11 か Wayland かは `echo $XDG_SESSION_TYPE` で確認できます (`wayland` であること)。
- SSH 先やディスプレイのないサーバでは、そのままでは起動できません (weston headless 等のネスト環境が必要)。

### 2.5 GPU / 描画経路
- **software 経路** (既定): GPU 不要で動作します。まず software で動作確認してください。
- **EGL (GPU) 経路**: Mesa と dmabuf 対応 GPU が必要です (Intel/AMD Mesa で検証)。GPU やドライバ構成によっては利用できません。
- HiDPI (スケール 2 等) 環境では、描画スケール不整合を避けるための設定が必要になる場合があります (同梱の設定・起動スクリプトの記述に従ってください)。

### 2.6 Chromium sandbox とカーネル設定
- Chromium の sandbox は **unprivileged user namespaces** を利用します。これを無効化しているシステム (一部のハードニング環境・コンテナ) では renderer の起動に失敗することがあります。
- コンテナ内・制限環境で起動しない場合はこの点を確認してください。sandbox を無効にする起動 (`--no-sandbox`) は動作はしますが**セキュリティ保護を失うため、信頼できないコンテンツの表示には使用しないでください**。

### 2.7 ファイルシステム要件
- **noexec マウントでは実行できません**。USB メモリや `/tmp` が noexec でマウントされている環境では、実行属性が有効な場所に展開してください。
- **シンボリックリンクを保持できるファイルシステム** (ext4/xfs/btrfs) に展開してください。FAT/exFAT/NTFS では SONAME シンボリックリンクが実体コピーになるか失われ、起動不能や容量倍増の原因になります。
- 配布アーカイブは **tar.gz 形式を使用**してください (実行属性とシンボリックリンクを保持)。zip は属性を失うため不可です。
- 展開先パスに空白・非 ASCII 文字を含めないことを推奨します。

### 2.8 リソース
- ディスク: 展開後 約 650MB 以上。
- メモリ: プロセス群 (browser + renderer + GPU) で数百 MB 以上を想定してください。

### 2.9 フォント
- 文字描画はホストの fontconfig とフォントに依存します。日本語表示にはホストに日本語フォント (原ノ味、Noto CJK 等) が必要です。

### 2.10 制限まとめ (チェックリスト)

| 項目 | 要件 | 確認コマンド |
|---|---|---|
| CPU | x86_64 | `uname -m` |
| glibc | ビルド環境世代以降 | `ldd --version` / `ldd ... \| grep "not found"` |
| GTK4 | 4.6+ (システム) | `pkg-config --modversion gtk4` |
| セッション | Wayland | `echo $XDG_SESSION_TYPE` |
| GPU (EGL 時) | Mesa + dmabuf | software 経路で切り分け |
| user namespaces | 有効 | sandbox 起動失敗時に確認 |
| 展開先 FS | ext4 等 + exec 可 | `mount \| grep noexec` |
| 日本語フォント | ホストに必要 | `fc-list \| grep -i mincho` 等 |

## 3. ポータブルアプリの構成

推奨レイアウト (単一ディレクトリ自己完結):

myapp-portable/
├── myapp # あなたのアプリ実行ファイル (RPATH=$ORIGIN/lib)
├── run.sh # 起動スクリプト (任意、環境変数の設定用)
├── lib/
│ ├── libblinkgtk-0.1.so.0.0.0
│ ├── libblinkgtk-0.1.so.0 -> libblinkgtk-0.1.so.0.0.0
│ └── chromium/ # Chromium ランタイム一式 (バイナリ配布物から)
│ ├── *.so # 共有ライブラリ群
│ ├── icudtl.dat / snapshot_blob.bin / v8_context_snapshot.bin
│ ├── content_shell.pak
│ └── locales/ja.pak, en-US.pak
├── share/
│ └── myapp/ # アプリのリソース
└── THIRD_PARTY_NOTICES.html # 必須 (第 6 章)


ランタイム一式は、バイナリ配布 (runtime tarball) の `usr/lib64/blinkgtk-0.1/` 以下をそのまま `lib/` にコピーすることで得られます。**ファイルの取捨選択はしないでください** — Chromium ランタイムの .so、`.pak`、`.dat`、`.bin`、`locales/` は全て起動に必要です (欠落は起動時クラッシュの典型原因)。

## 4. ビルド方法

### 4.1 リンク時の必須事項

アプリは pkg-config を使ってビルドします。**PartitionAlloc allocator shim の直接リンクが必須**です (pkg-config を使えば自動で含まれます)。shim を欠くとページの読み込みが失敗し黒画面になります。

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

pkg-config を使わず手動リンクする場合は、-lblinkgtk-0.1 に加えて必ず
-lbase_allocator_partition_allocator_src_partition_alloc_allocator_shim を明示してください。

4.2 RPATH の設定 (ポータブル化の核心)

実行ファイルに $ORIGIN 相対の 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)

RPATH を使わない代替として、起動スクリプトで LD_LIBRARY_PATH を設定する方法もあります:

#!/bin/sh
# run.sh — 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 検証

作成後、配布前に必ず確認してください:

# 1. 依存の完全性 (not found が 0 件であること)
ldd ./myapp | grep "not found"

# 2. shim が直接 NEEDED に入っていること
readelf -d ./myapp |

grep allocator_shim

# 3. V8 スナップショットの整合 (同一配布物由来なら通常一致)
# lib/chromium/ の libv8.so / snapshot_blob.bin / v8_context_snapshot.bin を
# 別バージョンの配布物から混在させないこと (起動時クラッシュの原因)

# 4. 実機 (Wayland セッション) での起動確認
./run.sh

5. 配布

6. ライセンス上の義務 (必須)

BlinkGTK / Chromium ランタイムを同梱して配布する場合、以下が必要です:

  1. THIRD_PARTY_NOTICES.html の同梱 — バイナリ配布物に含まれる集約ライセンス表記です。ポータブルアプリにもそのまま同梱してください (Chromium が内包する数百のサードパーティコンポーネントのライセンス条件により必須です)。
  2. FFmpeg (LGPL) について — 同梱の libffmpeg.so は LGPL v2.1+ です。独立した共有ライブラリとして同梱されているため、利用者が差し替え可能な状態を保ってください (静的リンク化・削除・改名をしないでください)。
  3. BlinkGTK 自体のライセンス表記 (LICENSE) も同梱してください。

7. トラブルシューティング (ポータブル特有)

症状 原因候補 対処
GLIBC_x.xx not found ホスト glibc が古い ホスト更新 or 同世代環境で使用 (§2.2)
起動直後にクラッシュ (SIGTRAP) V8 スナップショット混在 / shim 未リンク §4.3 の 2,3 を確認
ウィンドウが出ない X11 セッション / コンポジタなし $XDG_SESSION_TYPE 確認 (§2.4)
ページが黒いまま shim 未リンク readelf -d で確認 (§4.1)
Permission denied noexec マウント / 実行属性喪失 §2.7 (tar.gz で展開し直す)
起動するが文字化け/豆腐 ホストに日本語フォントなし §2.9
renderer 起動失敗 user namespaces 無効 §2.6

8. 関連ドキュメント