cjv - Cangjie Version Manager

cjv 是 仓颉 SDK 的工具链管理器：安装并管理多套 SDK，切换默认版本，并让 cjc、cjpm 等 SDK 工具按当前项目透明代理到正确工具链。

本项目是 cjv 的 Rust 实现，功能与 Go 版本完全对齐。

为什么叫 cjv？

仓颉生态中各组件已有明确的命名：

名称	归属	说明
CJVM	仓颉官方	仓颉虚拟机后端（字节码运行环境）
cjpm	仓颉官方	仓颉包管理器（Cangjie Package Manager）
cjc	仓颉官方	仓颉编译器
cjv	本工具	Cangjie Version Manager

cjv 三字简短，输入轻快（cjv install、cjv run），且不与任何官方组件重名冲突，一看就知道是独立的版本管理工具。

安装

从源码编译

git clone https://atomgit.com/cj-awesome/cjv.git
cd cjv
cargo build --release
# 将 target/release/cjv 放入 PATH

使用安装脚本

仓库中提供了安装脚本，可直接从本地运行：

# Linux / macOS
chmod +x web/public/install.sh
./web/public/install.sh

# Windows PowerShell
.\web\public\install.ps1

快速上手

# 安装最新 LTS 工具链
cjv install lts

# 设为默认工具链
cjv default lts

# 查看当前工具链状态
cjv show

# 使用指定工具链运行命令
cjv run sts cjc --version

设置默认工具链后，可以直接调用 cjc、cjpm 等命令；cjv 会根据环境变量、目录覆盖、cangjie-sdk.toml 和默认配置解析应使用的工具链。

命令参考

安装与卸载

命令	说明
cjv install <toolchain>	安装工具链（lts、sts、nightly 或具体版本）
cjv install <toolchain> -t ohos -c stdx	安装工具链并附带交叉编译目标和组件
cjv uninstall <toolchain>	卸载工具链
cjv update [toolchain]	更新已安装的工具链（增量更新，仅当有新版本时重装）
cjv check	检查可用更新（不安装）

查看与运行

命令	说明
cjv show	显示活跃和已安装的工具链
cjv show active	仅显示当前活跃工具链
cjv show installed	仅列出已安装工具链
cjv show home	显示 CJV_HOME 路径
cjv run <toolchain> <command>	用指定工具链运行命令
cjv exec [+toolchain] <command>	在仓颉运行时环境中执行命令
cjv envsetup	输出 shell 环境配置脚本
cjv which [command]	显示 SDK 工具路径
cjv doc [topic]	在浏览器中打开离线文档

工具链管理

命令	说明
cjv default [toolchain]	设置或显示默认工具链
cjv toolchain list	列出已安装的工具链
cjv toolchain list-remote	列出远程可用工具链
cjv toolchain link <name> <path|url>	链接自定义工具链（本地目录/归档或 URL）
cjv toolchain uninstall <name>	卸载工具链

组件管理

命令	说明
cjv component add <name>...	安装组件（stdx、docs、stdx-docs）
cjv component link <name> <path>	链接本地组件目录
cjv component remove <name>...	卸载组件
cjv component list	列出组件

目录覆盖

命令	说明
cjv override set <toolchain>	为当前目录设置工具链覆盖
cjv override unset	移除当前目录的覆盖
cjv override list	列出所有目录覆盖

设置

命令	说明
cjv set auto-install <true|false>	代理模式下是否自动安装缺失工具链
cjv set auto-self-update <enable|disable|check>	自动更新偏好（当前 beta 仅保存配置）
cjv set gitcode-api-key <key>	设置 GitCode API 令牌
cjv set manifest-url <url>	设置分发清单 URL
cjv set home <path>	设置数据目录
cjv set default-host <goos-goarch>	设置默认主机平台

自管理

命令	说明
cjv self update	自更新到最新 release（GitHub 主源，AtomGit 镜像回退）
cjv self uninstall	卸载 cjv 及所有数据
cjv init	交互式首次安装引导
cjv downloads purge	清除下载缓存

工具链解析优先级

cjv 按以下优先级确定活跃工具链：

1. CJV_TOOLCHAIN 环境变量
2. 目录覆盖（cjv override set）
3. cangjie-sdk.toml 项目文件（从当前目录向上查找）
4. 默认工具链（cjv default）

代理模式

将 cjv 的 bin/ 目录加入 PATH 后，直接调用 cjc、cjpm、cjfmt 等 SDK 工具时，cjv 会自动解析当前活跃工具链并透明转发调用，同时注入正确的环境变量：

• CANGJIE_HOME
• CANGJIE_TOOLCHAIN
• CANGJIE_STDX_PATH_DYNAMIC / CANGJIE_STDX_PATH_STATIC
• LD_LIBRARY_PATH / DYLD_LIBRARY_PATH

目录结构

~/.cjv/
  bin/              # 代理符号链接和 cjv 二进制文件
  toolchains/       # 已安装的 SDK 工具链
  stdx/             # stdx 组件（按工具链拆分）
  docs/             # 离线文档（按工具链拆分）
  downloads/        # 下载暂存区
  settings.toml     # 用户设置（默认 ~/.cjv/；设置 CJV_HOME 时位于 CJV_HOME）

环境变量

变量	说明
CJV_HOME	数据目录路径（默认 ~/.cjv）
CJV_TOOLCHAIN	临时指定活跃工具链
CJV_GITCODE_API_KEY	GitCode API 令牌（优先于 settings.toml）

项目结构

src/
├── main.rs              # 入口：代理检测 → CLI 执行
├── cli.rs               # 完整的 CLI 定义（17+ 命令）
├── error.rs             # 错误类型系统
├── config.rs            # settings.toml 管理、工具链解析
├── utils.rs             # 平台检测、CJV_HOME、符号链接
├── toolchain.rs         # 工具链安装/卸载/链接/版本解析/原子操作
├── toolchain_name.rs    # ToolchainName 解析（channel+version+target+custom）
├── channel.rs           # 通道枚举 + Registry（下载 URL 构建）
├── resolve.rs           # 工具链名解析、SDK 工具路径查找
├── proxy.rs             # 透明代理模式（含 auto-install）
├── component.rs         # 组件管理（stdx/docs/stdx-docs）
├── env.rs               # 运行时环境（exec/envsetup）
├── override_cmd.rs      # 目录级覆盖管理
├── doc.rs               # 离线文档查看器
├── dist.rs              # 下载、SHA-256 校验、归档提取
├── self_update.rs       # 自更新/自卸载
├── init_cmd.rs          # 首次安装引导
├── fstx.rs              # 原子文件事务（staging/backup）
├── target.rs            # 交叉编译目标系统
├── manifest.rs          # 分发清单系统
└── nightly.rs           # Nightly 发布元数据

开发

# 构建
cargo build

# 检查
cargo check

# 测试
cargo test

# 运行
cargo run -- --help

致谢

本项目基于 Zxilly/cjv 的 Go 实现移植，感谢原作者 Zxilly 的出色工作。

许可证

Apache-2.0。详见 LICENSE。