Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

自定义 SDK:目录、归档与 URL

cjv toolchain link 引用已解压的 SDK 目录;cjv toolchain import 从本地 .zip / .tar.gz 归档或 HTTP(S) URL 创建受管安装:

cjv toolchain link local-sdk /path/to/sdk
cjv toolchain import archive-sdk ./cangjie-sdk.zip
cjv toolchain import remote-sdk https://example.com/cangjie-sdk.tar.gz

这三条命令使用各自独立的名称,可以分别执行。注册自定义工具链不会修改当前的全局默认工具链;如果需要将其设为默认,请运行 cjv default <name>,或者在项目的 cangjie-sdk.toml 中配置 channel = "<name>"。

指定的名称必须符合自定义工具链命名规则,不能使用 lts、sts、nightly 等官方名称。

目录与归档的区别

根据传入的是已解压目录还是归档/URL,cjv 对文件的管理方式有所不同:

来源安装方式卸载行为(cjv uninstall)
已解压目录建立轻量目录引用;要求存在 bin/cjc(Windows 为 cjc.exe)只删除 cjv 中的链接记录,保留源 SDK 目录不变
本地归档或 URL解包到 <CJV_HOME>/toolchains/ 下由 cjv 管理的真实目录删除受管的安装副本及附属组件,保留本地源归档文件

这一区别也直接决定了组件管理行为:

  • 目录链接的内容由源 SDK 目录的所有者自行维护,cjv 的组件命令(cjv component)不能修改它。
  • 归档或 URL 安装位于 cjv 受管目录中,因此既可以自动安装随包附带的 stdx,也可以通过 cjv component link stdx 挂载本地 stdx 目录。

归档选项

cjv toolchain import 支持以下归档选项:

参数作用
--sha256 <hex>解包前校验归档内容,值为预期的 64 位十六进制 SHA-256 摘要
--replace替换已存在的同名自定义工具链
--no-stdx解包外层打包归档时跳过随包附带的 stdx

这三个选项仅适用于本地归档或 URL,与已解压目录参数一起使用会报错。如果未提供 --sha256,cjv 不会比对特定内容哈希,但仍会验证归档格式与 SDK 目录布局。

旧版 toolchain link 的归档和 URL 用法仍可执行,并提示迁移到 import;旧替换标志 --force 对应 import --replace。

支持的归档

cjv toolchain import 支持以下两种归档结构:

  1. 裸 SDK 归档(.tar.gz 或 .zip):直接包含一个完整的 cangjie/ SDK 顶层目录(内含 bin/、lib/、tools/、runtime/ 等内容)。
  2. cangjie-build CI 外层打包 ZIP:外层 ZIP 内部包含一个 SDK 归档和一个可选的 stdx 归档:
cangjie-sdk-<sdk_name>-<version>.<tar.gz|zip>
cangjie-stdx-<sdk_name>-<version>.<stdxver>.<tar.gz|zip>  # 可选

其中内层 stdx 归档包含平台目录下的 dynamic/ 与 static/。只要外层包中存在随包 stdx 且未指定 --no-stdx,cjv 就会自动一并安装;如果 stdx 安装失败,已成功安装的 SDK 本体仍会保留。

请注意,归档安装要求 SDK 的目标操作系统与当前机器匹配。如果需要跨平台交叉编译,请安装可在当前宿主上运行的交叉编译目标 SDK,而不是直接安装其他操作系统的普通宿主 SDK。

安装完成后,可以使用常规命令查看组件或卸载该自定义工具链:

cjv component list --toolchain archive-sdk
cjv uninstall archive-sdk