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

Flatpak 应用打包完整教程 / 第 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 GB Platform + 头文件、编译器、构建工具

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

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

7.2 主要运行时对比

7.2.1 运行时总览

运行时 ID 版本 基于 大小 主要组件 适用场景
org.freedesktop.Platform 24.08 Freedesktop ~700 MB glibc, mesa, X11/Wayland, GStreamer 非桌面特定应用
org.gnome.Platform 47 Freedesktop + GNOME ~1.2 GB + GTK4, libadwaita, GNOME 库 GNOME/GTK 应用
org.kde.Platform 6.8 Freedesktop + KDE ~1.3 GB + Qt6, KDE Frameworks Qt/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 库 glibc 2.39
编译器 GCC 14.2
图形 Mesa 24.1
音频 PipeWire, PulseAudio 1.2, 17.0
视频 GStreamer 1.0 1.24
显示 Wayland, X11 1.23
字体 FreeType, Fontconfig 2.13
加密 OpenSSL 3.3
压缩 zlib, libarchive 1.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 框架
自适应 UI libadwaita GNOME 自适应 UI 组件库
Web 引擎 WebKitGTK 嵌入式 Web 内容渲染
文档 Evince PDF/文档渲染库
设置 GSettings 应用配置存储
帮助 Yelp 帮助系统
钥匙串 libsecret 密钥管理
在线账号 Goa GNOME 在线账号集成

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 框架 KF6 KDE 核心框架 (KIO, KConfig, etc.)
语法高亮 KSyntaxHighlighting 代码/文本语法高亮
图表 KChart 图表绘制
Kirigami Kirigami 自适应 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

版本选择建议

运行时 推荐版本 生命周期 说明
Freedesktop 24.08 支持到 2028 当前最新稳定版
GNOME 47 支持到 2027 匹配 GNOME 47
KDE 6.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-stable Rust 工具链 flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//24.08
org.freedesktop.Sdk.Extension.golang Go 工具链 flatpak install flathub org.freedesktop.Sdk.Extension.golang//24.08
org.freedesktop.Sdk.Extension.node18 Node.js 18 flatpak install flathub org.freedesktop.Sdk.Extension.node18//24.08
org.freedesktop.Sdk.Extension.node20 Node.js 20 flatpak install flathub org.freedesktop.Sdk.Extension.node20//24.08
org.freedesktop.Sdk.Extension.llvm18 LLVM 18 flatpak install flathub org.freedesktop.Sdk.Extension.llvm18//24.08
org.freedesktop.Sdk.Extension.openjdk17 OpenJDK 17 flatpak install flathub org.freedesktop.Sdk.Extension.openjdk17//24.08
org.freedesktop.Sdk.Extension.openjdk21 OpenJDK 21 flatpak install flathub org.freedesktop.Sdk.Extension.openjdk21//24.08
org.freedesktop.Sdk.Extension.dotnet8 .NET 8 flatpak install flathub org.freedesktop.Sdk.Extension.dotnet8//24.08
org.freedesktop.Sdk.Extension.vala Vala 编译器 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.BaseApp Electron 运行时 Electron 应用
org.nickvision.nickvision.BaseApp Nickvision 基础 GTK4/Adwaita 应用
com.valvesoftware.Steam.CompatibilityTool Steam 兼容层 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 扩展阅读