开发者指南 · Zikaron

从源码构建

一个 Rust 工作区：一条命令构建，一条命令测试，各平台用各自的脚本或命令打包。

环境要求

Rust: 1.97.1，2024 edition。版本由仓库根的 rust-toolchain.toml 钉定，本地、持续集成与发布构建同用这一版；装好 rustup，进入仓库它即自动取用。
C 工具链: TLS 用到的加密库 ring 与代理脚本引擎 QuickJS 都要为本机编译一段 C 代码。在 macOS 上装 Xcode 的命令行工具；在 Windows 上用 MSVC 工具链（目标 x86_64-pc-windows-msvc）。
Linux 的系统库: 窗口、键盘与文件对话框所需的开发包，见下文。
Python 3: 运行法的冻结核与一致性比对，只用标准库。
Foundry: 测试登记合约、重算代码哈希时使用。

在 Debian 或 Ubuntu 上，先装构建依赖：

sudo apt install build-essential pkg-config libxkbcommon-dev libxkbcommon-x11-0 \
  libwayland-dev libx11-dev libxcursor-dev libxrandr-dev libxi-dev libgl1-mesa-dev \
  xdg-desktop-portal xdg-desktop-portal-gtk

Linux 上的系统文件对话框走桌面门户，所以运行时要有 xdg-desktop-portal 和一个后端；缺少门户时，把文件直接拖进窗口即可。拖放经 X11：有 X 显示时（包括 Wayland 桌面上的 XWayland）窗口走 X11，拖放要在有 X 显示的会话里用。

构建时，crates/app/build.rs 用 cargo metadata --locked --offline 按目标平台从 Cargo.lock 现生成第三方许可清单，随应用一起带着；清单生成不了，构建即失败。依赖增删之后，清单自动跟着变。工作区的发布构建开着整数溢出检查，溢出即具名停下；测试与持续集成都用发布构建跑，测的就是发出去的那一份。

窗口在 macOS 上经 wgpu 走 Metal 绘制，在 Windows 与 Linux 上走 OpenGL。macOS 的构建在链接时记下 SDK 26（crates/app/macos_sdk.rs），macOS 26 起窗角与窗口按钮照系统新规；最低运行版本取 MACOSX_DEPLOYMENT_TARGET，未设时 arm64 为 11.0。

构建与测试

tar -xzf zikaron-0.1.5-src.tar.gz
cd zikaron-0.1.5
cargo build --release --locked
cargo test --workspace --release --locked

--locked 让构建严格使用 Cargo.lock 锁定的依赖版本，发布包也这样构建。产物：

程序	是什么
`target/release/app`	桌面窗口，在 macOS 上打包为 `ZIKARON.app`，在 Linux 上为 `zikaron-desk`，在 Windows 上为 `zikaron-desk.exe`
`target/release/zikaron`	命令行，见命令行
`zk1`、`zkk`、`zks`、`zka`、`zkg`	供测试与一致性比对用的辅助程序
`zikaron-pack`	打包工具：生成第三方许可清单（`notices`），去掉包里的构建机信息（`hfs-owners`、`dmg-names`、`elf-comment`），给出路径映射并复核产物里只有中性的路径名（`rustflags`、`no-paths`），核对钉定的 AppImage 运行时（`appimage-runtime`），排出 Windows 包（`windows`）

每次推到 main 和每个合并请求，仓库的 .github/workflows/test.yml 都在 macOS、Linux 与 Windows 上跑 cargo build --workspace --locked --release 和 cargo test --workspace --locked --no-fail-fast --release；macOS 与 Linux 两格必须通过，Windows 一格在 Windows 实机上走通之后才列为必过。macOS 与 Linux 两格另做一步：按打包脚本的路径映射做一次发布构建，再用 zikaron-pack no-paths 复核产物里只有中性的路径名。

打包

脚本或命令	产出
`packaging/macos/build.sh [--identity NAME]`	`ZIKARON.app`，装在 `.dmg` 和 `.pkg` 里（macOS）
`packaging/linux/build.sh`	在 Linux 上本机构建：x86_64 出 `.deb` 与 AppImage；aarch64 只出 `.deb`，AppImage 一步因为这个架构尚待钉定运行时而具名停下。需要 `dpkg-deb` 与 `mksquashfs`，AppImage 的运行时联网去取，或用 `APPIMAGE_RUNTIME` 指向本地文件，取到后按钉定的字节核对
`packaging/linux/cross-build.sh`	在别的主机上用 zig 与 `cargo-zigbuild` 打出同样的 Linux x86_64 包，目标 glibc 2.31；另需 `mksquashfs`、`python3`、`curl`；AppImage 运行时同样按钉定的字节核对
`cargo run --release --locked -p zikaron-pack -- windows --out dist`	Windows x86_64 包的文件夹 `dist/ZIKARON-<版本>-windows-x86_64/`：`zikaron-desk.exe`、`zikaron.exe`、`LICENSE.txt`、`THIRD-PARTY-LICENSES.txt`。在 Windows 上用 MSVC 构建，C 运行库静态链接，用户那边无需另装运行库；`.github/workflows/package-windows.yml` 手动触发时调的就是这一条。直接 `cargo build` 出的 Windows 程序动态链接 C 运行库，要另装 VC++ 运行库

macOS 与 Linux 的包落在 dist/，各附一份 SHA256SUMS-<系统>-<架构>.txt；Windows 那一条只排出文件夹，发布页上的 zip 由这个文件夹压成。每个包都带按目标平台现生成的 THIRD-PARTY-LICENSES.txt，包里的用户名、属主、主机与系统版本都中性化：三个打包脚本都先用 zikaron-pack rustflags 取路径映射（家目录、Cargo 与 rustup 的目录、仓库与构建目录各映射成一个固定的名字），构建后再用 no-paths 复核，有残留即停在出包之前。macOS 脚本省略 --identity 时做临时签名（-）；发布包用 Kaptonia 的证书签名，见发布。

deb 声明的运行依赖：libc6、libdbus-1-3、libgcc-s1、libxkbcommon0、libxkbcommon-x11-0、libwayland-client0、libx11-6、libxcursor1、libxrandr2、libxi6、libgl1；推荐 xdg-desktop-portal 与 xdg-desktop-portal-gtk。

合约测试

cd base/zikaron-core/contracts
forge test

法的核

cd base/zikaron-conformance
./criterion-digest.sh
./criterion-digest-kit.sh

用候选实现跑一致性语料的方法，见测试一份实现。

用独立数据试用

在 macOS 与 Linux 上，应用从 HOME 找机器目录，密钥库也只住在那里。把 HOME 指向一个空目录后启动，机器目录、密钥库与账本都落在其中，与日常数据隔离：

T=$(mktemp -d)
HOME=$T ./target/release/app

Windows 上先读 USERPROFILE：把它指向一个空目录后启动，机器数据落在其中的 AppData\Local\ZIKARON\，同样与日常数据隔离。命令行按同一规则找机器目录（--home、凭据、收编与交接清单、cli-sent/ 都在那里），隔离试用时给它同一个 HOME 或 USERPROFILE。「启用 zikaron 命令」写入的位置，可以用环境变量 ZIKARON_CLI_LINK_DIR 改到别处。

试用时，在向导里选「自定义」，再到「设置 › 网络 › 编辑节点」的「预设」里选 Sepolia 测试网；或用「新建身份」，在「网络」里选「Sepolia 测试网」，见 Wiki 的网络。测试用的密钥用 zikaron keygen 现场生成，用后即弃。

内嵌字体

界面的西文字体 Inter（常规、中等、半粗三个字重）与等宽字体 JetBrains Mono 内嵌于应用；中等与半粗两种文字里的西文字母、数字与符号取 Inter 的对应字重，中文随后取各角色自己的字体。中文在 macOS 上取自系统的苹方，在 Windows 上取自系统的微软雅黑（Microsoft YaHei UI，加粗用它的粗体），找不到时用内嵌的 Noto Sans SC，在 Linux 上用内嵌的 Noto Sans SC；所以 Noto Sans SC 只随 Windows 与 Linux 的构建内嵌。内嵌字体都以 SIL OFL 1.1 发布，许可文本在 crates/zikaron-ui/fonts/。