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

命令参考

cjv 内置了完整的命令行帮助系统;你可以随时运行 cjv help 或 cjv <command> --help 查看本机已安装版本的详细参数。版本名称格式见工具链与版本,工具链选择顺序见项目工具链。

全局选项

选项作用
--json将结构化 JSON 写入 stdout;run、exec、init、completion 不支持
--quiet、-q隐藏进度输出,参数位置不改变含义;单列组件名称使用 component list --names-only
--verbose未设置 CJV_LOG 时在 stderr 启用 debug 日志,与 --quiet 互斥
--offline禁止 cjv 联网,只使用本地安装和可复用缓存
--config <path>选择用户设置文件,仍保留系统后备配置和项目选择
--no-auto-install仅在本次调用中禁止自动补装缺失项
--help、-h显示命令帮助
--version、-v显示 cjv 版本号
+name放在子命令前,为支持选择工具链的命令显式指定 SDK

子命令的显式 --toolchain 参数优先于前置的全局 +name。exec 和 envsetup 也接受跟在子命令名称后的 +name。子进程参数由 run、exec 原样透传,退出码也会完整保留。

安装、更新与卸载

install

cjv install [toolchain]... [-t target]... [-c component]... [--allow-missing] [--allow-downgrade] [--reinstall]

install 确保所选工具链存在,默认保留已安装发行版,只补齐新增目标或组件;升级已有通道请运行 update。省略名称时使用当前选择,多个名称按顺序处理。-t(--target)和 -c(--component)可重复传入或使用逗号分隔:

cjv install lts sts
cjv install nightly -c stdx,docs

安装与更新策略

策略行为
默认保留所需组件和交叉目标;缺少制品时阻止更新,其中 nightly 可在已发布历史中查找兼容版本
--allow-missing允许跳过并移除不可用的可选组件或目标,不会重装未变化的 SDK
默认 install保留已有宿主发行版,只补齐新增目标或组件
install --reinstall重新安装当前已有的发行版并保留组件和目标,用于修复损坏的 SDK
--allow-downgrade允许 nightly 安装或更新选择更旧的兼容 nightly 构建

没有新增组件或交叉目标需求时,对已安装工具链运行 cjv install 可完全离线完成。--force 是 --allow-missing 的已弃用兼容标志;install --no-update 仍可使用,但保留版本已是默认行为。--allow-downgrade 影响需要解析发行版的操作,不会让普通 install 推进或降级已有通道。

update

cjv update [toolchain]... [--allow-missing] [--allow-downgrade] [--no-self-update] [--dry-run]

update 指定名称时只处理列出的工具链;省略名称时优先使用全局 +name,否则更新所有已安装的跟踪通道(lts、sts、nightly)。固定版本保持不变,自定义工具链没有官方更新源。只有不带名称且不带 +name 的全量更新才会按 auto_self_update 检查或更新 cjv 本体;传入 --no-self-update 可跳过该检查。

通道升级会先在暂存区准备好宿主 SDK、已跟踪目标和组件,全部准备完成后再原子替换安装;若失败则保留或恢复原安装,固定版本独立保留。

cjv update lts
cjv update --no-self-update

第一条命令只更新 lts;第二条更新所有已跟踪通道,并跳过 cjv 本体的更新检查。

--dry-run 只解析更新计划,报告最新发行版、实际兼容版本与阻塞原因;全量更新还按当前策略报告 cjv 本体的检查或更新计划。它不下载归档、不修改安装也不写入缓存,配合 --json 可供 CI 使用。显式指定未安装工具链的 update 仍会安装该工具链。

uninstall

cjv uninstall <toolchain>... [-y]

uninstall 会清理指定 SDK、附属交叉 SDK、组件、离线文档和引用它的目录覆盖。移除当前默认工具链时,会改选其他已安装宿主或清空默认选择。交互终端请求确认;非交互输入或 --json 模式必须显式传入 -y(--yes)。输出格式不代表确认删除。toolchain uninstall 保留为隐藏兼容入口。

check

cjv check

check 查询已安装 SDK 和 cjv 本体的可用更新,不执行安装或写入缓存;前置 +name 将 SDK 查询限制到该工具链。它采用与更新相同的组件和目标兼容规则。dev 构建跳过本体版本比较。doctor 检查本机状态,pin --check 只验证项目是否固定具体发行版,二者不查询可用更新。

更新历史与回退

cjv toolchain history list [toolchain]
cjv toolchain history prune [toolchain] [--keep 2]
cjv toolchain rollback <toolchain> [snapshot]

历史快照整组保存宿主、目标和组件,默认保留最近 2 份。查询或清理省略名称时使用前置 +name,否则处理所有历史组;省略 list 仍作为兼容简写。--keep 0 清空快照并保留安装。回退前会校验快照并保存当前组,以便撤销。详见更新历史与回退。

doctor 与缓存

cjv doctor
cjv cache dir
cjv cache list
cjv cache clean
cjv cache prune [--max-age 720h]

doctor 只读检查配置、代理命令入口及 SDK 完整性,发现问题时返回非零退出码。cache 子命令管理 <CJV_HOME>/cache/ 下已验证 SHA-256 的下载归档和版本清单;清理缓存绝不会删除已安装 SDK。JSON 约定和离线用法见自动化与 JSON 接口。

查询工具链

命令作用
cjv、cjv show显示同一份当前工具链、默认主机和安装报告,JSON 结构相同
cjv show active显示当前激活工具链及其选择来源
cjv toolchain list列出宿主和附加目标,显示实际发行版以及跟踪、固定或自定义类型
cjv show home显示实际生效的数据目录及其配置来源
cjv which [command] [--toolchain <tc>]显示 SDK 工具路径;省略 [command] 时返回 SDK 根目录

查询命令不会自动安装缺失的 SDK 或组件。show installed 是 toolchain list 的隐藏兼容入口。

toolchain list-remote

cjv toolchain list-remote [--channel all|lts|sts|nightly] [-t suffix] [--all-platforms] [--limit N]

远程列表默认查询所有通道在当前主机平台下的可用版本。--all-platforms 按所有平台分组显示,--limit 0 不限制每组显示的版本数,-t(--target)按交叉目标后缀过滤。

运行命令与配置环境

run

cjv run [--install] <toolchain> <command> [args...]

使用显式工具链运行任意命令,与 exec 一样准备 SDK 和运行时库,并按 auto_install 补装缺失项。--install 显式启用补装,须放在工具链参数前,且与 --no-auto-install 互斥:

cjv run --install sts cjc --version

exec

cjv exec [+toolchain] <command> [args...]

使用当前激活工具链(或 +name 指定工具链)的运行环境启动命令。当编译产物需要链接仓颉运行时库或 stdx 动态库时,推荐这样运行:

cjv exec ./my_binary
cjv exec +nightly ./my_binary

如果被调用的命令名本身以 + 开头,请使用 cjv exec -- +command。run 和 exec 都会原样透传子进程参数并保留退出码。

envsetup

cjv envsetup [+toolchain] [--target=SUFFIX] [--shell=TYPE]

输出用于配置当前 shell 的脚本,支持 bash、fish、powershell 和 cmd。--target 要求交叉 SDK 已安装;--json 模式返回结构化环境数据。

输出脚本需在当前 shell 中求值执行(如 eval "$(cjv envsetup)")才会生效。envsetup 只读取已安装 SDK,并验证项目需求;缺失时提示显式安装,不会自动补装。各 shell 写法与恢复项目代理选择的方法见运行命令与配置环境。

自定义工具链

cjv toolchain link <name> <directory>
cjv toolchain import <name> <archive|url> [--sha256 <hash>] [--replace] [--no-stdx]

link 引用已有目录,源目录内容由其所有者维护;import 将本地归档或 HTTP(S) URL 解包为受管安装。--sha256、--replace、--no-stdx 分别校验摘要、替换同名安装、跳过随包 stdx。旧 link 的归档和 URL 用法保留兼容并提示迁移,旧替换标志仍为 --force。详见自定义 SDK。

交叉编译目标

cjv target list [--toolchain <tc>] [--installed]
cjv target add <suffix>... [--toolchain <tc>]
cjv target remove <suffix>... [--toolchain <tc>]

target add 保留宿主当前版本并补装目标;target remove 移除交叉 SDK 及其组件并保留宿主安装。target list --installed 支持离线查询。详见交叉编译。

组件

cjv component add <name>... [--toolchain <tc>] [--target <suffix>] [--reinstall]
cjv component link <name> <path> [--toolchain <tc>] [--target <suffix>] [--replace]
cjv component remove <name>... [--toolchain <tc>] [--target <suffix>]
cjv component list [--toolchain <tc>] [--target <suffix>] [--installed] [--names-only]

组件命令的 --target 只选择已安装的交叉 SDK,不会自动安装该目标 SDK。

组件名支持 stdx、docs、stdx-docs,接受多个参数或逗号分隔。component add --reinstall 重装组件,component link --replace 替换组件;旧 --force 保留为隐藏兼容标志。list --names-only 单列打印名称,-q 始终只关闭进度。只有 stdx 支持目录链接,源目录需有 dynamic/ 和 static/。外部 SDK 目录链接不能通过组件命令修改。详见组件与离线文档。

离线文档

cjv doc [topic] [--path] [--toolchain <tc>]

支持的主题为 std、dev-guide(别名 book)、tools、stdx;省略主题时打开文档首页。--path 和 --json 只返回本地路径,其他情况在默认浏览器中打开文档。cjv docs 是命令别名,使用前需先安装对应文档组件。

选择与设置

pin

cjv pin [toolchain] [--check]

写入当前目录的 cangjie-sdk.toml,固定具体发行版并保留已有的 components 和 targets。--check 只验证项目文件是否固定了具体发行版,不修改文件。详见自动化与 JSON 接口。

default

cjv default [toolchain]

省略参数时显示全局默认选择,传入 none 时清除。选择未安装的官方 SDK 通常会先安装;--no-auto-install 则要求 SDK 已安装。安装或验证失败保留原选择,交叉 SDK 不能设为默认。

override

cjv override set <toolchain> [--path <dir>]
cjv override unset [--path <dir>] [--nonexistent]
cjv override list

目录覆盖默认作用于当前工作目录,--nonexistent 清理已不存在目录的残留记录。覆盖写入所选用户设置文件(默认 ~/.cjv/settings.toml),不随 CJV_HOME 改变。详见项目工具链和配置。

set

cjv set auto-self-update <enable|disable|check>
cjv set auto-install <true|false>
cjv set default-host <goos-goarch>
cjv set home <path>

修改所选用户设置文件(默认 ~/.cjv/settings.toml)。各字段默认值、系统后备继承规则和环境变量覆盖见配置。

初始化与自管理

init

cjv init [-y] [--default-toolchain <name>] [-c component]... [--no-modify-path]

init 安装 cjv 命令入口并配置 PATH。它会查询当前平台的可用通道,按 lts、sts、nightly 的顺序自动选择第一个可用通道。交互式菜单只列出当前平台可用的通道;如果无法确认任何可用通道,初始化会报错退出。

选项作用
--default-toolchain <name>明确指定默认工具链
--default-toolchain none只安装 cjv 本体,跳过 SDK
-c、--component安装初始 SDK 时一并安装指定组件
-y、--yes跳过交互确认
--no-modify-path保留现有 PATH 配置

非终端输入会自动采用非交互模式。当初始工具链安装失败时,命令返回非零退出码并保留已安装的 cjv 本体;错误信息中会给出保留组件选项的重试命令和查询兼容版本的命令,两者都使用已安装程序的绝对路径,无需先刷新 PATH 即可执行。

self update / self uninstall

cjv self update
cjv self uninstall [-y]

self update 检查并更新 cjv 本体。self uninstall 删除整个 <CJV_HOME>、所有工具链、组件、缓存和快照,并清理 PATH;非交互输入或 --json 必须显式加 -y,与 SDK 卸载一致。

Shell 补全

cjv completion <bash|zsh|fish|powershell>

输出对应 shell 的命令行补全脚本,加载方法见 cjv completion <shell> --help。