Installation

Install fpack, put it on your PATH, and learn how it finds its native core.

安装

安装 fpack、配置 PATH，并了解它如何找到原生核心。

fpack needs only Dart 3.8+, which is bundled with Flutter. The targets you build need their usual toolchains (see what each target needs); fpack doctor checks them for you.

1. Install#

dart pub global activate fpack

This installs the fpack command from pub.dev. Other ways to install:

Method	Command	Notes
pub.dev	`dart pub global activate fpack`	recommended
git	`dart pub global activate --source git https://github.com/Matkurban/fpack`	the first run downloads the core from the GitHub Release (SHA-256 verified); it builds with a local Go only if the download is unavailable
local path	`dart pub global activate --source path /path/to/fpack`	works offline: the release tarball contains prebuilt binaries for all 6 platforms

2. Put it on your PATH#

Dart installs global tools into the pub cache. That folder must be on your PATH:

macOS

echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.zshrc && source ~/.zshrc

Linux

echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashrc && source ~/.bashrc

Windows

Add %LOCALAPPDATA%\Pub\Cache\bin to your user PATH (Settings → System → About → Advanced system settings → Environment Variables), then open a new terminal.

3. Check#

fpack --version

It prints the installed version number. If the shell says command not found, the PATH step above is missing. Then try your first build.

Tip

fpack --wrapper-info shows which native core is used and where it came from. It is the first thing to run when something about the installation looks odd.

Upgrading#

dart pub global activate fpack    # installs the latest version
fpack --version

Each fpack version uses its own native core, downloaded once per version and cached.

Requirements per target#

fpack itself only needs Dart. Each target needs its usual toolchain:

Targets	Needs
`apk`, `aab`	Flutter, Android SDK, Java 17+ (Android Studio bundles one)
`ipa`, `macos`, `dmg`, `pkg`	macOS with Xcode (+ CocoaPods when the project has a Podfile)
`windows`, `exe`, `msix`	Windows with Visual Studio (C++ desktop workload); Inno Setup 6 for `exe` ; the `msix` dev dependency for `msix`
`linux`, `deb`, `rpm`, `appimage`, `snap`	Linux with clang, cmake, ninja, pkg-config, GTK 3 headers; `dpkg-deb` , `rpmbuild` , `appimagetool` , `snapcraft` (plus LXD or Multipass unless you build on Ubuntu 24.04)
`web`	Flutter only

Run fpack doctor in a project to see exactly what is missing on your machine, with an install command for each item.

How the launcher finds the native core#

The fpack command is a small Dart launcher. The real work is done by fpack-core, a native Go binary (about 4 MB, ~10 ms startup). On every run the launcher looks for a core whose version exactly matches the Dart package (checked with fpack-core --core-version), in this order. A verified prebuilt binary always wins; a local build is only the last resort.

the FPACK_CORE environment variable (development)
the user cache: macOS ~/Library/Caches/fpack/<version>/<os>-<arch>/, Linux $XDG_CACHE_HOME/fpack/… (default ~/.cache/fpack), Windows %LOCALAPPDATA%\fpack\… (override with FPACK_HOME)
the bundled prebuilt binary prebuilt/<os>-<arch>/ (when present): verified against the SHA-256 in prebuilt/manifest.json, then copied into the cache
a download of this platform's binary from the GitHub Release, verified against checksums.txt: a mismatching file is never executed
only if the download fails or is disabled: a local build from the bundled Go sources (go build -trimpath, dependencies are vendored, no network needed), with a clear note that it fell back to a local build and which Go it used:
```
fpack: note: no verified prebuilt core available (download: …connection refused…);
fpack: falling back to a local build from the bundled sources with go1.27.2 (/usr/local/go/bin/go) – first run only, ~30s…
```

fpack --wrapper-info prints each step's path and the binary that is finally used. A cached core is reused until the version changes; to replace a locally built core with the downloaded binary, delete the cache directory.

Offline, mirrors and development#

Variable	Effect
`FPACK_NO_DOWNLOAD=1`	offline / air-gapped: never download; use the bundled binary or build locally with Go
`FPACK_DOWNLOAD_URL`	download from a mirror (a directory with `checksums.txt` and `fpack-core-<os>-<arch>` ( `.exe` on Windows), laid out like the GitHub Release)
`FPACK_GO=/path/to/go` / `FPACK_GO=none`	the Go used for the fallback build / never build locally
`FPACK_REBUILD=1`	development: ignore the cache and build with local Go first (after changing the Go sources)
`FPACK_HOME`	cache directory
`FPACK_CORE`	use exactly this core binary

Note

Package size trade-off. The binaries for 6 platforms are about 23 MB (10 MB compressed). Bundling them in the pub package makes fpack work offline right after install but every user downloads every platform's binary; not bundling gives a tiny package (about 350 KB) that downloads this platform's binary on first run. The release workflow's repository variable BUNDLE_BINARIES decides; the fpack-vX.Y.Z.tar.gz on the GitHub Release always contains all binaries for offline and intranet use.

Next#

Your first build: doctor, a dry run, and a real build.

fpack 只需要 Dart 3.8+（Flutter 自带）。你要构建的目标需要各自常用的工具链（见各目标的要求）；fpack doctor 会帮你检查。

1. 安装#

dart pub global activate fpack

这会从 pub.dev 安装 fpack 命令。其他安装方式：

方式	命令	说明
pub.dev	`dart pub global activate fpack`	推荐
git	`dart pub global activate --source git https://github.com/Matkurban/fpack`	首次运行从 GitHub Release 下载核心（经 SHA-256 校验）；只有下载不可用时才用本机 Go 构建
本地路径	`dart pub global activate --source path /path/to/fpack`	可离线使用：发布压缩包内含全部 6 个平台的预编译二进制

2. 加入 PATH#

Dart 把全局工具装在 pub 缓存目录里，这个目录必须在 PATH 中：

macOS

echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.zshrc && source ~/.zshrc

Linux

echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashrc && source ~/.bashrc

Windows

把 %LOCALAPPDATA%\Pub\Cache\bin 加入用户 PATH（设置 → 系统 → 关于 → 高级系统设置 → 环境变量），然后打开新的终端。

3. 检查#

fpack --version

会打印已安装的版本号。如果 shell 提示 command not found，说明上面的 PATH 步骤没做。然后试试第一次构建。

提示

fpack --wrapper-info 会显示使用的是哪个原生核心、来自哪里。安装看起来不对劲时，先运行它。

升级#

dart pub global activate fpack    # 安装最新版本
fpack --version

每个 fpack 版本使用自己的原生核心，每个版本下载一次并缓存。

各目标的要求#

fpack 本身只需要 Dart。每个目标需要各自常用的工具链：

目标	需要
`apk`、`aab`	Flutter、Android SDK、Java 17+（Android Studio 自带）
`ipa`、`macos`、`dmg`、`pkg`	装有 Xcode 的 macOS（工程有 Podfile 时还需要 CocoaPods）
`windows`、`exe`、`msix`	装有 Visual Studio（C++ 桌面开发工作负载）的 Windows； `exe` 需要 Inno Setup 6； `msix` 需要 `msix` 开发依赖
`linux`、`deb`、`rpm`、`appimage`、`snap`	Linux，需要 clang、cmake、ninja、pkg-config、GTK 3 头文件； `dpkg-deb` 、 `rpmbuild` 、 `appimagetool` 、 `snapcraft` （除非在 Ubuntu 24.04 上构建，否则还需要 LXD 或 Multipass）
`web`	只需要 Flutter

在项目里运行 fpack doctor，可以看到你的机器具体缺什么，每一项都附带安装命令。

启动器如何找到原生核心#

fpack 命令是一个小型 Dart 启动器，真正干活的是 fpack-core，一个原生 Go 二进制（约 4 MB，启动约 10 毫秒）。每次运行，启动器按下面的顺序查找版本与 Dart 包完全一致的核心（用 fpack-core --core-version 检查）。经过校验的预编译二进制永远优先，本地构建只是最后的手段。

环境变量 FPACK_CORE（开发用）
用户缓存：macOS ~/Library/Caches/fpack/<版本>/<os>-<arch>/，Linux $XDG_CACHE_HOME/fpack/…（默认 ~/.cache/fpack），Windows %LOCALAPPDATA%\fpack\…（可用 FPACK_HOME 覆盖）
随包的预编译二进制 prebuilt/<os>-<arch>/（如果有）：用 prebuilt/manifest.json 里的 SHA-256 校验后复制到缓存
从 GitHub Release 下载本平台的二进制，用 checksums.txt 校验：校验不一致的文件绝不会被执行

只有下载失败或被禁用时：用随包的 Go 源码本地构建（go build -trimpath，依赖已 vendor，无需网络），并明确提示已回退到本地构建以及使用的 Go：

fpack: note: no verified prebuilt core available (download: …connection refused…);
fpack: falling back to a local build from the bundled sources with go1.27.2 (/usr/local/go/bin/go) – first run only, ~30s…

fpack --wrapper-info 会打印每一步的路径和最终使用的二进制。缓存的核心在版本变化前一直复用；想用下载的二进制替换本地构建的核心，删除缓存目录即可。

离线、镜像与开发#

变量	作用
`FPACK_NO_DOWNLOAD=1`	离线 / 隔离网络：从不下载；使用随包二进制或用本机 Go 构建
`FPACK_DOWNLOAD_URL`	从镜像下载（一个目录，包含 `checksums.txt` 和 `fpack-core-<os>-<arch>` （Windows 为 `.exe` ），布局与 GitHub Release 相同）
`FPACK_GO=/path/to/go` / `FPACK_GO=none`	回退构建使用的 Go / 永不本地构建
`FPACK_REBUILD=1`	开发：忽略缓存，先用本机 Go 构建（修改 Go 源码之后）
`FPACK_HOME`	缓存目录
`FPACK_CORE`	使用指定的核心二进制

说明

包体积的取舍。 6 个平台的二进制约 23 MB（压缩后约 10 MB）。把它们打进 pub 包，安装后即可离线使用，但每个用户都要下载所有平台的二进制；不打包则包很小（约 350 KB），首次运行时下载本平台的二进制。由发布工作流的仓库变量 BUNDLE_BINARIES 决定；GitHub Release 上的 fpack-vX.Y.Z.tar.gz 始终包含全部二进制，供离线和内网使用。

下一步#

第一次构建：doctor、预演和真正的构建。