cjr 用户手册

cjr 为仓颉程序找到对应版本的运行库，然后启动程序。

cjr ./app

仓颉程序通常依赖对应 SDK 中的动态运行库，运行库的 ABI 随 SDK 版本变化。cjr 读取程序中的完整 SDK 版本，通过 官方发行索引 选择版本完全匹配的运行库。

已经准备好的 cjr 运行库会直接复用。首次准备时，cjr 优先读取 cjv 缓存和官方受管安装；本地没有匹配内容时，再下载官方 SDK、校验摘要并提取运行库。cjr 可以独立使用，也会自动识别已有的 cjv 安装。

适用范围

cjr 面向由同一官方 SDK 正确构建的命令行程序。应用自己的动态库、stdx 和系统库由应用分发者或系统提供。运行库版本由程序元数据自动确定，来源限定为官方发行版。

下一步：安装与运行。运行失败时，先用 inspect 查看版本和依赖，再对照平台说明。

安装与运行

下载预编译版本

从 GitHub Releases 下载与你的系统和架构对应的预编译归档。

Release 同时提供每个归档的 .sha256 文件。Linux 使用 sha256sum -c <文件名>.sha256，macOS 使用 shasum -a 256 -c <文件名>.sha256 校验。Windows 使用 Get-FileHash <归档路径> -Algorithm SHA256，将结果与校验文件中的摘要比较。

解压后，将 cjr（Windows 为 cjr.exe）所在目录加入 PATH。Linux / macOS 也可以将程序放入已有的用户命令目录：

mkdir -p ~/.local/bin
install -m 755 cjr ~/.local/bin/cjr

确认 ~/.local/bin 已在 PATH 中。Windows 可将 cjr.exe 放到固定目录，再通过“环境变量”设置将该目录加入用户 Path。重新打开终端，运行：

cjr --version
# cjr 0.0.1

Windows 版本已包含 C/C++ 运行时。macOS 预编译版本要求 macOS 13 或更新版本。Linux 版本使用 musl 静态链接；目标仓颉程序及其运行库的系统要求仍需满足。

从源码安装

需要 Rust 1.89 或更新版本、C 编译器和 CMake。Windows 使用 MSVC 工具链。

cargo install --git https://github.com/Zxilly/cjr --tag v0.0.1 --locked

Cargo 将程序安装到其 bin 目录。确认该目录在 PATH 中，然后检查安装：

cjr --version

也可以在本地检出仓库后安装：

git clone https://github.com/Zxilly/cjr.git
cd cjr
cargo install --path . --locked

运行程序

Linux / macOS：

cjr ./app --port 8080

Windows PowerShell：

cjr .\app.exe --port 8080

第一次运行可能需要下载完整 SDK 归档，cjr 只提取所需运行库。后续运行会复用缓存。cjr 直接启动原路径下的程序，保持程序文件原样；工作目录、标准输入输出和程序参数沿用当前调用。

离线使用

先在联网时运行一次目标程序，再使用：

cjr --offline ./app

离线模式仅使用本地内容。已保存的运行库记录，或本地清单加匹配的 SDK 缓存，必须足以确定官方资产身份。缺少这些内容时会返回错误。

--offline 和 -v 必须放在程序路径之前。路径后面的参数全部交给目标程序。

命令参考

执行程序

cjr [--offline] [-v] <binary> [args...]

cjr ./app --help 查看的是应用帮助。查看 cjr 帮助使用 cjr --help。若程序名恰好是 inspect、list 或 cache，使用路径写法 ./inspect，或用 cjr -- inspect 明确执行入口。

cjr 保留目标程序的退出状态，准备或启动失败会输出诊断并以非零状态退出。

查看程序

cjr inspect ./app
cjr inspect ./app --json

读取程序格式、架构、SDK 版本及动态依赖，并显示本地候选运行库。该命令以只读方式检查本地文件。

查看缓存

cjr list
cjr list --json

列出本地可见的 cjr 和 cjv 资产，包括来源及使用状态。查询范围为本地内容。

清理缓存

cjr cache clean --dry-run
cjr cache clean
cjr cache clean --all --dry-run
cjr cache clean --all

默认清理下载归档、元数据和废弃暂存内容，保留已准备的运行库。--all 还会清理能确认未使用的运行库。--dry-run 预览清理结果并保留所有文件。清理始终只作用于 cjr 自己的目录。

JSON 输出

inspect --json 和 list --json 输出带 schema_version 的 JSON。自动化使用时应检查命令退出码和该字段，并容忍新增字段。警告与未知状态应保留并交由调用方处理；成功匹配以明确的匹配状态为准。

缓存与 cjv

目录配置

cjr 默认使用用户目录下的 .cjr，可以通过 CJR_HOME 指定其他目录。

CJR_HOME=/path/to/cjr-cache cjr ./app

$env:CJR_HOME = 'D:\Caches\cjr'
cjr .\app.exe

CJR_HOME 与 cjv 目录须各自独立，位于互相分离的路径下。使用当前用户可写的本地文件系统目录。

自动复用 cjv

已有 cjr 运行库直接使用。准备新运行库时，依次尝试：

1. cjv 中匹配官方摘要的下载归档。
2. cjv 中具有官方来源记录的受管 SDK 安装。
3. cjr 自己保存的下载归档。
4. 官方下载地址。

读取 cjv 安装时，cjr 与 cjv 使用兼容的锁协议。文件会复制到 cjr 的独立运行库目录；cjv 的内容保持原样。

cjr 首先读取绝对路径 CJV_HOME。未设置时，使用 cjv 用户配置中的 home，再尝试系统配置，最后使用用户目录下的 .cjv。CJV_CONFIG_FILE 和 CJV_FALLBACK_SETTINGS 可分别指定这两份配置文件。

cjr 使用布局兼容且来源记录完整的官方 SDK 缓存与受管安装。其余内容会被跳过，并自动尝试下一来源。

清理时跳过的内容

启动目标程序前，cjr 会登记运行库使用记录。程序或其后台子进程可能仍在使用运行库时，cache clean --all 会跳过它。

macOS 上，后代进程的退出状态可能需要等到同一主机下次启动才能确认，使用记录会保留到确认完成。cjr 被强杀或记录读取失败时，对应运行库也会保留以供后续确认。

清理会保留协调锁，处理范围限定在 cjr 目录内的文件和链接本身。请使用 cjr cache clean，由它根据使用记录判断可回收的运行库。

平台与常见问题

平台支持

平台可用性还取决于官方清单是否提供该版本、该架构且具有 SHA-256 摘要的 SDK。Linux 支持 x64；macOS 支持与宿主原生架构一致的命令行程序，并选择对应的 slice。.app 分发和 Rosetta 转译由应用分发者处理。

检查 SDK 版本元数据

先运行 cjr inspect <binary>。ELF 需要保留 section headers。Mach-O 支持普通版本指针和 chained fixups。版本识别以完整且布局受支持的版本表为准；解析失败时，cjr 会报告具体原因。请向程序分发者索取保留版本元数据的构建产物。

核对官方发行记录

完整 SDK 版本、平台和官方摘要必须匹配。请确认清单中包含目标版本及其摘要；cjr 使用版本完全匹配的运行库。离线情况下还需要相应的本地元数据或已准备好的运行库记录。

已有运行库却仍然报错

检查应用目录和嵌入的搜索路径。Windows 应用目录的同名 DLL、Linux 旧式 RPATH、预加载变量或显式库路径可能覆盖 cjr 选择的运行库。发现冲突时，cjr 拒绝启动。应由程序分发者移除或修正冲突文件与路径。

应用自己的动态库和 stdx 由应用分发者提供，glibc 等系统依赖由系统包管理器安装。使用系统加载器诊断定位这些缺失项。

macOS 受限程序

cjr 对已识别的 hardened 或 restricted 程序拒绝注入加载环境。程序签名、entitlements 和 SIP 保持原样。需要此类分发方式的程序应自行携带并签名其运行库。

非 ASCII 参数

cjr 使用操作系统原生参数接口。部分仓颉 Windows SDK 的 main(args) 在解码中文参数时可能报错；若直接运行程序也有同样错误，应在 SDK 或应用中处理。

静态依赖检查读取二进制中声明的依赖。运行时插件、延迟加载和自定义加载器的错误由系统加载器或目标程序报告。