强曰为道

与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

第 7 章:运行时与 SDK

第 7 章:运行时与 SDK

本章目标:理解 Flatpak 运行时体系架构,学会选择和使用合适的运行时,了解自定义运行时的创建。


7.1 运行时概述

7.1.1 运行时的作用

运行时 (Runtime) 是 Flatpak 应用的基础层,提供:

  • C 标准库 (glibc)
  • 图形库 (GTK, Qt, Mesa)
  • 多媒体库 (GStreamer, PipeWire)
  • 系统服务接口 (D-Bus, Wayland, X11)
┌─────────────────────────────────────────────┐
│               Flatpak 应用                   │
│  ┌────────────────────────────────────────┐  │
│  │     应用私有代码 + 私有依赖库           │  │
│  ├────────────────────────────────────────┤  │
│  │     运行时 (Runtime)                    │  │
│  │  • glibc, libstdc++                     │  │
│  │  • GTK / Qt                             │  │
│  │  • Mesa (OpenGL/Vulkan)                 │  │
│  │  • Wayland / X11                        │  │
│  │  • PulseAudio / PipeWire                │  │
│  │  • Cairo, Pango, HarfBuzz               │  │
│  │  • GLib, GObject                        │  │
│  └────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────┐  │
│  │     Linux 内核                          │  │
│  └────────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

7.1.2 Runtime vs SDK

组件用途大小包含内容
Platform (运行时)运行应用~700 MB - 1.3 GB共享库、字体、图标
SDK (开发包)构建应用~1.5 GB - 3 GBPlatform + 头文件、编译器、构建工具

SDK 包含 Platform 的所有内容,额外提供:

  • GCC / Clang 编译器
  • 头文件 (.h)
  • 构建工具 (make, cmake, meson)
  • 调试工具 (gdb, strace)

7.2 主要运行时对比

7.2.1 运行时总览

运行时 ID版本基于大小主要组件适用场景
org.freedesktop.Platform24.08Freedesktop~700 MBglibc, mesa, X11/Wayland, GStreamer非桌面特定应用
org.gnome.Platform47Freedesktop + GNOME~1.2 GB+ GTK4, libadwaita, GNOME 库GNOME/GTK 应用
org.kde.Platform6.8Freedesktop + KDE~1.3 GB+ Qt6, KDE FrameworksQt/KDE 应用

7.2.2 Freedesktop Runtime

最基础的运行时,包含 Linux 桌面应用的最低依赖。

# 查看 Freedesktop Runtime 包含的组件
flatpak info --show-metadata org.freedesktop.Platform

# 在 Freedesktop Runtime 中探索
flatpak run --command=bash org.freedesktop.Sdk//24.08
ls /usr/lib/           # 查看共享库
ls /usr/include/       # 查看头文件 (SDK)
gcc --version          # 查看编译器版本 (SDK)
pkg-config --list-all  # 查看可用的库
exit

Freedesktop Runtime 主要组件

类别组件版本 (24.08)
C 库glibc2.39
编译器GCC14.2
图形Mesa24.1
音频PipeWire, PulseAudio1.2, 17.0
视频GStreamer 1.01.24
显示Wayland, X111.23
字体FreeType, Fontconfig2.13
加密OpenSSL3.3
压缩zlib, libarchive1.3

7.2.3 GNOME Runtime

基于 Freedesktop Runtime,添加了 GNOME 桌面的完整库。

# 安装 GNOME Runtime 和 SDK
flatpak install flathub org.gnome.Platform//47 org.gnome.Sdk//47

# 在 GNOME SDK 中探索
flatpak run --command=bash org.gnome.Sdk//47
pkg-config --modversion gtk4          # GTK4 版本
pkg-config --modversion libadwaita-1  # libadwaita 版本
exit

GNOME Runtime 额外组件

类别组件说明
UI 框架GTK4现代 GNOME 应用 UI 框架
自适应 UIlibadwaitaGNOME 自适应 UI 组件库
Web 引擎WebKitGTK嵌入式 Web 内容渲染
文档EvincePDF/文档渲染库
设置GSettings应用配置存储
帮助Yelp帮助系统
钥匙串libsecret密钥管理
在线账号GoaGNOME 在线账号集成

7.2.4 KDE Runtime

基于 Freedesktop Runtime,添加了 KDE/Qt 桌面的完整库。

# 安装 KDE Runtime 和 SDK
flatpak install flathub org.kde.Platform//6.8 org.kde.Sdk//6.8

# 在 KDE SDK 中探索
flatpak run --command=bash org.kde.Sdk//6.8
qmake --version         # Qt 版本
pkg-config --modversion Qt6Core
exit

KDE Runtime 额外组件

类别组件说明
UI 框架Qt6跨平台 UI 框架
KDE 框架KF6KDE 核心框架 (KIO, KConfig, etc.)
语法高亮KSyntaxHighlighting代码/文本语法高亮
图表KChart图表绘制
KirigamiKirigami自适应 UI 框架

7.3 选择运行时的决策树

你的应用使用什么 UI 框架?
│
├── GTK4 / libadwaita → org.gnome.Platform//47
│
├── Qt6 / KDE Frameworks → org.kde.Platform//6.8
│
├── GTK3 → org.gnome.Platform//47 (包含 GTK3)
│
├── SDL2 / 自定义渲染 → org.freedesktop.Platform//24.08
│
├── Electron → org.freedesktop.Platform//24.08 + Electron BaseApp
│
└── 纯终端应用 → org.freedesktop.Platform//24.08

版本选择建议

运行时推荐版本生命周期说明
Freedesktop24.08支持到 2028当前最新稳定版
GNOME47支持到 2027匹配 GNOME 47
KDE6.8支持到 2027匹配 KDE Plasma 6.8

7.4 运行时内部结构

7.4.1 目录布局

/usr/                      # 运行时根目录
├── bin/                   # 可执行文件
├── lib/                   # 共享库
│   ├── libgtk-4.so.1     # GTK4 库
│   ├── libglib-2.0.so.0  # GLib 库
│   └── ...
├── include/               # 头文件 (仅 SDK)
├── share/                 # 共享数据
│   ├── icons/             # 图标主题
│   ├── fonts/             # 字体
│   ├── themes/            # GTK 主题
│   └── glib-2.0/          # GLib 数据
└── etc/                   # 配置文件

/app/                      # 应用安装目录
├── bin/                   # 应用可执行文件
├── lib/                   # 应用私有库
├── share/                 # 应用共享数据
│   ├── applications/      # .desktop 文件
│   ├── icons/             # 应用图标
│   ├── metainfo/          # AppStream 元数据
│   └── glib-2.0/schemas/  # GSettings schemas
└── etc/                   # 应用配置

7.4.2 探索运行时

# 在运行时中打开 shell
flatpak run --command=bash org.gnome.Sdk//47

# 查看 glibc 版本
ldd --version

# 查看 GTK4 版本
pkg-config --modversion gtk4

# 查看所有可用的 pkg-config 包
pkg-config --list-all | grep gtk

# 查看 Mesa 版本 (OpenGL)
glxinfo | grep "OpenGL version"

# 查看编译器版本
gcc --version
g++ --version

# 退出
exit

7.5 SDK 扩展

SDK 扩展为 SDK 添加额外的工具链:

7.5.1 可用的 SDK 扩展

扩展 ID说明安装命令
org.freedesktop.Sdk.Extension.rust-stableRust 工具链flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//24.08
org.freedesktop.Sdk.Extension.golangGo 工具链flatpak install flathub org.freedesktop.Sdk.Extension.golang//24.08
org.freedesktop.Sdk.Extension.node18Node.js 18flatpak install flathub org.freedesktop.Sdk.Extension.node18//24.08
org.freedesktop.Sdk.Extension.node20Node.js 20flatpak install flathub org.freedesktop.Sdk.Extension.node20//24.08
org.freedesktop.Sdk.Extension.llvm18LLVM 18flatpak install flathub org.freedesktop.Sdk.Extension.llvm18//24.08
org.freedesktop.Sdk.Extension.openjdk17OpenJDK 17flatpak install flathub org.freedesktop.Sdk.Extension.openjdk17//24.08
org.freedesktop.Sdk.Extension.openjdk21OpenJDK 21flatpak install flathub org.freedesktop.Sdk.Extension.openjdk21//24.08
org.freedesktop.Sdk.Extension.dotnet8.NET 8flatpak install flathub org.freedesktop.Sdk.Extension.dotnet8//24.08
org.freedesktop.Sdk.Extension.valaVala 编译器flatpak install flathub org.freedesktop.Sdk.Extension.vala//24.08

7.5.2 在 Manifest 中使用 SDK 扩展

{
    "app-id": "com.example.RustApp",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "24.08",
    "sdk": "org.freedesktop.Sdk",
    "sdk-extensions": [
        "org.freedesktop.Sdk.Extension.rust-stable"
    ],
    "build-options": {
        "append-path": "/usr/lib/sdk/rust-stable/bin",
        "env": {
            "CARGO_HOME": "/run/build/myapp/cargo"
        }
    },
    "modules": [
        {
            "name": "myapp",
            "buildsystem": "simple",
            "build-commands": [
                "cargo build --release",
                "install -Dm755 target/release/myapp /app/bin/myapp"
            ],
            "sources": [
                {
                    "type": "git",
                    "url": "https://github.com/example/myapp.git",
                    "tag": "v1.0.0"
                }
            ]
        }
    ]
}
{
    "app-id": "com.example.NodeApp",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "24.08",
    "sdk": "org.freedesktop.Sdk",
    "sdk-extensions": [
        "org.freedesktop.Sdk.Extension.node20"
    ],
    "build-options": {
        "append-path": "/usr/lib/sdk/node20/bin"
    },
    "modules": [
        {
            "name": "nodeapp",
            "buildsystem": "simple",
            "build-commands": [
                "npm install --prefix=/app",
                "cp -r . /app/lib/nodeapp",
                "ln -s /app/lib/nodeapp/bin.js /app/bin/nodeapp"
            ],
            "sources": [
                {
                    "type": "git",
                    "url": "https://github.com/example/nodeapp.git",
                    "tag": "v1.0.0"
                }
            ]
        }
    ]
}

7.6 BaseApp(基础应用)

BaseApp 是一种特殊的"应用级运行时",为特定类型的应用提供共享基础:

7.6.1 常用 BaseApp

BaseApp ID说明适用场景
org.electronjs.Electron2.BaseAppElectron 运行时Electron 应用
org.nickvision.nickvision.BaseAppNickvision 基础GTK4/Adwaita 应用
com.valvesoftware.Steam.CompatibilityToolSteam 兼容层Steam 游戏工具

7.6.2 使用 Electron BaseApp

{
    "app-id": "com.example.ElectronApp",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "24.08",
    "sdk": "org.freedesktop.Sdk",
    "base": "org.electronjs.Electron2.BaseApp",
    "base-version": "24.08",
    "command": "electron-app",
    "separate-locales": false,
    "finish-args": [
        "--share=ipc",
        "--socket=x11",
        "--socket=wayland",
        "--socket=pulseaudio",
        "--share=network",
        "--device=dri"
    ],
    "modules": [
        {
            "name": "electron-app",
            "buildsystem": "simple",
            "build-commands": [
                "cp -r . /app/electron-app",
                "install -Dm755 run.sh /app/bin/electron-app"
            ],
            "sources": [
                {
                    "type": "archive",
                    "url": "https://github.com/example/electron-app/releases/download/v1.0.0/linux-x64.zip",
                    "sha256": "abc123..."
                },
                {
                    "type": "file",
                    "path": "run.sh"
                }
            ]
        }
    ]
}

7.7 自定义运行时

7.7.1 何时需要自定义运行时

场景说明
特殊版本需求应用依赖特定版本的库,与现有运行时不兼容
专有技术栈使用非标准的 GUI 框架
性能优化需要特定编译参数的库
多应用共享多个内部应用共享相同的自定义依赖

7.7.2 创建自定义运行时的基本流程

# 步骤 1:创建运行时 Manifest
cat > org.example.Runtime.json << 'EOF'
{
    "id": "org.example.Runtime",
    "branch": "1.0",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "24.08",
    "sdk": "org.freedesktop.Sdk",
    "packages": [
        {
            "name": "custom-lib",
            "buildsystem": "cmake-ninja",
            "sources": [
                {
                    "type": "archive",
                    "url": "https://example.com/custom-lib-1.0.tar.gz",
                    "sha256": "abc123..."
                }
            ]
        }
    ],
    "cleanup": [
        "/include",
        "/lib/pkgconfig"
    ]
}
EOF

# 步骤 2:构建运行时
flatpak-builder --force-clean --repo=runtime-repo \
    runtime-builddir org.example.Runtime.json

# 步骤 3:导出运行时
flatpak build-export runtime-repo runtime-builddir

# 步骤 4:添加自定义仓库
flatpak remote-add --no-gpg-verify my-runtime-repo runtime-repo

# 步骤 5:安装运行时
flatpak install my-runtime-repo org.example.Runtime

7.8 运行时维护

7.8.1 查看运行时信息

# 列出已安装的运行时
flatpak list --runtime

# 查看运行时详细信息
flatpak info org.freedesktop.Platform

# 查看运行时大小
flatpak list --runtime --columns=application,size

# 查看运行时依赖关系
flatpak info --show-metadata org.gnome.Platform | grep -A 5 "\[Runtime\]"

7.8.2 运行时更新

# 更新所有运行时
flatpak update --runtime

# 更新特定运行时
flatpak update org.freedesktop.Platform

# 查看可用的运行时更新
flatpak remote-ls --runtime --updates

7.8.3 清理旧运行时

# 查看未使用的运行时
flatpak unused

# 删除未使用的运行时
flatpak uninstall --unused

# 删除特定运行时版本
flatpak uninstall org.freedesktop.Platform//22.08

7.9 业务场景

场景:大型项目多运行时支持

一个企业需要同时为 GNOME 和 KDE 桌面环境提供应用:

#!/bin/bash
# build-multi-runtime.sh

APP_ID="com.example.MyApp"

# 为 GNOME 构建
echo "构建 GNOME 版本..."
cat > "${APP_ID}-gnome.json" << EOF
{
    "app-id": "${APP_ID}.Gtk",
    "runtime": "org.gnome.Platform",
    "runtime-version": "47",
    "sdk": "org.gnome.Sdk",
    "command": "myapp",
    "finish-args": [
        "--share=ipc",
        "--socket=wayland",
        "--socket=fallback-x11"
    ],
    "modules": [
        {
            "name": "myapp",
            "buildsystem": "meson",
            "sources": [{"type": "dir", "path": "src"}]
        }
    ]
}
EOF

flatpak-builder --force-clean --repo=repo-gnome \
    builddir-gnome "${APP_ID}-gnome.json"

# 为 KDE 构建
echo "构建 KDE 版本..."
cat > "${APP_ID}-kde.json" << EOF
{
    "app-id": "${APP_ID}.Qt",
    "runtime": "org.kde.Platform",
    "runtime-version": "6.8",
    "sdk": "org.kde.Sdk",
    "command": "myapp",
    "finish-args": [
        "--share=ipc",
        "--socket=wayland",
        "--socket=fallback-x11"
    ],
    "modules": [
        {
            "name": "myapp",
            "buildsystem": "cmake-ninja",
            "sources": [{"type": "dir", "path": "src"}]
        }
    ]
}
EOF

flatpak-builder --force-clean --repo=repo-kde \
    builddir-kde "${APP_ID}-kde.json"

echo "两个版本构建完成!"

7.10 注意事项

⚠️ 运行时版本生命周期
运行时有明确的维护周期。旧版本(如 org.freedesktop.Platform//20.08)已停止安全更新。建议使用最新稳定版本。

⚠️ 运行时不可混合
一个应用只能使用一个运行时。不能同时链接 GNOME 和 KDE 的库。

⚠️ 运行时大小
完整的 GNOME SDK 约 3 GB。在磁盘空间有限的环境中,优先使用 Freedesktop 运行时。

⚠️ SDK 不用于运行
SDK 只在构建时使用,不会在用户机器上安装。最终应用只依赖 Platform(运行时)。


7.11 扩展阅读