ITADN
pkgforge-dev/appimagetool
代码 动态 Issues 合并请求2 版本2
pkgforge-dev/appimagetool · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

appimagetool

GitHub Downloads CI Build Status Latest Stable Release

appimagetool 的 Rust 实现，用于 Anylinux-AppImages 项目。

它接收一个准备好的 AppDir，并使用 DWARFS 压缩和 uruntime AppImage 运行时生成一个完成的 .AppImage。单一二进制文件，无 Python，无 C++ 依赖。

快速开始

appimagetool ./AppDir

就是这样。该工具将：

  1. 验证 AppDir（检查 AppRun、.DirIcon、一个 .desktop 文件）。
  2. 如果 mkdwarfs 和 uruntime 尚未缓存，则下载它们。
  3. 将 X-AppImage-* 元数据写入桌面条目。
  4. 构建 DWARFS 镜像，并将运行时嵌入为 ELF 头。
  5. 当设置更新信息时，生成一个 .zsync 文件，外加一个 appinfo 伴随文件。

特性

  • 使用 DWARFS 压缩，生成小巧且支持增量更新的 AppImage。
  • 即插即用的 uruntime 集成，支持自动下载和 ELF 节区修补。
  • 可选的基于配置的优化（DWARFS 热度分析），以加快启动速度。
  • 内置 zsync 生成，无需 zsyncmake 外部调用。
  • 无中央仓库，无守护进程，无额外运行时依赖。

用法

典型构建

appimagetool ./build/AppDir \
  --output ./dist \
  --update-info "gh-releases-zsync|org|repo|latest|*-x86_64.AppImage.zsync"

CI / GitHub Actions

如果设置了 GITHUB_REPOSITORY，更新信息将自动派生为 gh-releases-zsync|owner|repo|latest|*<arch>.AppImage.zsync。因此在 CI 中通常只需要：

VERSION=1.2.3 appimagetool ./AppDir --output ./dist

跨架构 / 别名文件名

该工具分别跟踪两种架构：

  • APPIMAGE_ARCH 是 运行时 架构。它决定下载哪个 mkdwarfs 和 uruntime 二进制文件，并显示在 X-AppImage-Arch 元数据中。默认为主机架构。
  • ARCH 是 显示 架构。它仅影响输出文件名。未设置时回退到 APPIMAGE_ARCH。

这允许项目以 amd64 之类的别名发布，同时仍拉取正确的 x86_64 运行时：

APPIMAGE_ARCH=x86_64 ARCH=amd64 appimagetool ./AppDir
# produces MyApp-1.2.3-anylinux-amd64.AppImage with X-AppImage-Arch=x86_64

所有 CLI 选项

Usage: appimagetool [OPTIONS] [APPDIR]

Arguments:
  [APPDIR]  Path to the AppDir directory [env: APPDIR] [default: ./AppDir]

Options:
  -o, --output <OUTPUT>            Output directory [env: OUTPATH] [default: .]
  -n, --name <NAME>                Output filename (auto-detected from .desktop) [env: OUTNAME]
      --appimage-arch <ARCH>       Runtime arch (download URL + X-AppImage-Arch) [env: APPIMAGE_ARCH]
      --arch <ARCH>                Display arch used in the output filename [env: ARCH]
      --runtime <RUNTIME>          Path to uruntime binary [env: RUNTIME]
      --runtime-url <URL>          URL to download uruntime from [env: URUNTIME_LINK]
  -u, --update-info <UPINFO>       Update information string [env: UPINFO]
      --dwarfs-comp <COMP>         DWARFS compression options [env: DWARFS_COMP]
      --optimize-launch            Enable DWARFS profile optimization (also via OPTIMIZE_LAUNCH=1)
      --profile-timeout <SECS>     Profiling timeout in seconds [env: OPTIMIZE_LAUNCH_TIMEOUT] [default: 10]
      --keep-mount                 Keep the FUSE mount alive after exit (also via URUNTIME_PRELOAD=1)
      --devel-release              Tag the build as a nightly/devel release (also via DEVEL_RELEASE=1)
      --dwarfs-profile <PROFILE>   Path to DWARFS profile [env: DWARFSPROF]
      --mkdwarfs <PATH>            Path to mkdwarfs binary [env: DWARFS_CMD]
      --dwarfs-url <URL>           URL to download mkdwarfs from [env: DWARFS_LINK]
      --tmpdir <TMPDIR>            Temporary directory [env: TMPDIR] [default: /tmp]
  -v, --verbose...                 Increase verbosity (-v, -vv)
  -q, --quiet...                   Suppress informational output (-q, -qq)
  -h, --help                       Print help
  -V, --version                    Print version

环境变量

每个 CLI 选项都有一个对应的环境变量（如上所示）。以下是一些仅限环境变量的额外配置项：

变量效果
VERSION嵌入到 AppImage 文件名和元数据中的版本字符串。
APPNAME覆盖应用程序名称（默认为桌面项的 Name）。
GITHUB_REPOSITORY设置时，自动将 update_info 生成为 gh-releases-zsync|owner|repo|latest|...
ADD_PERMA_ENV_VARS要嵌入到运行时中的永久环境变量，每行一个。
URUNTIME_PRELOAD设置为 1 可在应用退出后保留 FUSE 挂载。
DEVEL_RELEASE设置为 1 可将构建标记为 nightly/devel 版本。
OPTIMIZE_LAUNCH设置为 1 可启用 DWARFS 分析路径（与 --optimize-launch 相同）。
OPTIMIZE_LAUNCH_TIMEOUT分析超时时间（秒）（默认 10）。

AppDir 要求

AppDir 必须包含：

  1. 一个可执行文件 AppRun。
  2. 一个 .DirIcon 文件（PNG 或 SVG）。
  3. AppDir 根目录中恰好一个 .desktop 文件。

输出文件名

默认情况下：

<AppName>-<Version>-anylinux-<Arch>.AppImage

其中 AppName 来自 .desktop Name 键（或 APPNAME），Version 来自 VERSION（或 ~/version），而 Arch 是显示架构（ARCH，回退到 APPIMAGE_ARCH）。

你也可以直接使用 --name / OUTNAME 固定文件名。

构建

cargo build --release

运行测试

# Unit + integration tests
cargo test --all-features

# Full end-to-end test (requires mkdwarfs + uruntime installed)
cargo test --all-features -- --ignored

项目结构

src/
├── main.rs       CLI entry point (clap)
├── lib.rs        library root
├── appimage.rs   build pipeline orchestration
├── config.rs     CLI args + env var resolution
├── desktop.rs    .desktop parsing and metadata
├── dwarfs.rs     mkdwarfs resolution, image building, profiling
├── elf.rs        ELF section read / write / patch
├── error.rs      error types with actionable hints
├── log.rs        verbosity-gated logger
├── uruntime.rs   runtime download, caching, configuration
└── util.rs       atomic downloads, sanitization, ELF detection