仓颉语言 IDE 插件使用指南

功能简介

仓颉语言提供了 Visual Studio Code（简称 VSCode）插件，通过在 VSCode 中安装仓颉插件和仓颉 SDK，为开发者提供语言服务、工程管理、编译构建、调试服务、格式化、静态检查和代码覆盖率统计的功能。本文档介绍如何在 VSCode 中安装仓颉插件，以及如何使用插件提供的功能。

下载软件

请在 VSCode 官网下载 VSCode 安装包，建议使用 1.67 或更新版本。前往仓颉下载中心下载仓颉插件，选择所需版本，单击 IDE 安装包（VSCode）选项进行下载。

下载项	说明	是否必选
Visual Studio Code	IDE	必选
IDE 安装包(VSCode)	仓颉插件	必选

安装 VSCode

Windows 平台

运行 VSCode 安装文件（例如 VSCodeUserSetup-x64.exe），根据提示选择安装路径，完成 VSCode 的安装。

Linux 平台

本地安装

解压下载的压缩包（例如 VSCode-linux-x64）并存放到自定义位置。

使用如下命令给 code 添加可执行权限。

chmod 777 ./VSCode-linux-x64/code
chmod 777 ./VSCode-linux-x64/bin/code

使用如下命令启动 VSCode。
```
./VSCode-linux-x64/bin/code
```

远程安装

在 VSCode 中搜索 Remote - SSH，单击安装按钮。
使用 Remote - SSH 进行远程工作，VSCode 会自动在远程主机上安装 Server。linux_arm64 暂时只支持使用 Remote - SSH 的方式进行操作。

macOS 平台

解压下载的压缩包（例如 VSCode-darwin-universal.zip），将解压后的 .app 文件拖拽到应用程序，完成 VSCode 的安装。

安装仓颉插件

解压下载的压缩包，得到压缩包内 .vsix 插件文件。

按照下图所示操作，在 VSCode 中打开文件资源管理器，找到要安装的 .vsix 插件文件，单击确定完成安装。

setupVsix

已经安装的插件可以在 INSTALLED 目录下查看。

checkVsix

安装仓颉 SDK

仓颉 SDK 主要提供了仓颉语言官方包管理工具（Cangjie Package Manager，简称 CJPM）、仓颉语言编译命令（cjc），以及仓颉格式化工具（Cangjie Formatter，简称 cjfmt）等命令行工具。正确安装并配置仓颉 SDK 后，可使用工程管理、编译构建、格式化、静态检查和覆盖率统计等功能。开发者可以通过以下两种方式下载 SDK：

离线手动安装。在官网下载 SDK 安装包，并在本地安装部署仓颉 SDK。
通过 VSCode 安装。仓颉插件提供了仓颉 SDK 最新版本的下载和更新功能，开发者可以在 VSCode 完成最新版本仓颉 SDK 的下载和本地环境部署。

下载 SDK

开发者可以自行前往仓颉下载中心，手动下载仓颉 SDK。

Windows 平台

Windows 平台的 SDK 下载内容为：Cangjie-version-windows_x64.exe 或 Cangjie-version-windows_x64.zip。

下载 SDK 并放置在本地。若下载 .exe 文件，运行该文件，根据提示选择安装路径并记录该路径。若下载 .zip 文件，解压该文件，记录存储的路径。

SDK 文件夹的目录结构如下：

cangjie

├── bin

├── lib

├── modules

├── runtime

├── third_party

├── tools

├── envsetup.bat

├── envsetup.ps1

└── envsetup.sh

Linux 平台

Linux_x64 平台的 SDK 下载内容为：Cangjie-version-linux_x64.tar.gz。

Linux_AArch64 平台的 SDK 下载内容为：Cangjie-version-linux_aarch64.tar.gz。

下载 SDK 并放置在本地，记录存储的路径。目录结构如下：

cangjie

├── bin

├── include

├── lib

├── modules

├── runtime

├── third_party

├── tools

└── envsetup.sh

macOS 平台

macOS_x86_64 平台的 SDK 下载内容为：Cangjie-version-darwin_x64.tar.gz。

macOS_AArch64 平台的 SDK 下载内容为：Cangjie-version-darwin_aarch64.tar.gz。

下载 SDK 并放置在本地，记录存储的路径。目录结构如下：

cangjie

├── bin

├── lib

├── modules

├── runtime

├── third_party

├── tools

└── envsetup.sh

SDK 路径配置

安装完仓颉插件后，即可配置 SDK 的路径。单击左下角齿轮图标，选择设置选项。

setVS

或直接右键单击插件，选择 Extension Settings，进入配置页面。

openSetting

在搜索栏输入 Cangjie，选择侧边栏的 Cangjie Language Support 选项。

languageSupportSetting

配置 CJNative 后端

找到 Cangjie Sdk: Option 选项，选择后端类型为 CJNative（默认是此选项）。
找到 Cangjie Sdk Path: CJNative Backend 选项，输入 CJNative 后端 SDK 文件夹所在绝对路径。
重启 VSCode 生效。

CJNativeSdkPathSet

安装验证

通过快捷键 Ctrl + Shift + P（macOS 系统的快捷键为 Command + Shift + P）调出 VSCode 的命令面板，选择 cangjie: Create Cangjie Project View 命令。

createProjectView

弹出创建仓颉项目页面，说明仓颉 SDK 安装成功。

sdkSuccess

仓颉语言服务插件仅为开发者打开的文件夹下仓颉源码提供语言服务。以打开的文件夹为仓颉项目的根目录 PROJECTROOT。如果没有明确指定模块名称，默认将 PROJECTROOT 目录名称作为模块名，以方便导入 src 下的包。PROJECTROOT/src 为 src 下仓颉源码（支持语言服务）；除了 src 下的仓颉源码，PROJECTROOT 下的所有源码称为非 src 下仓颉源码（支持语言服务）；PROJECTROOT 之外的仓颉源码称为外部源码（暂不支持语言服务）。

限制二

非 src 下每个文件夹都作为一个包，包名的声明和包的编译方式与 src 下顶层包（即 default 包）处理方式保持一致。非 src 下的仓颉源码可以导入标准库的包以及 src 下自定义的包，非 src 下的包无法被其他包导入。

限制三

Linux、Windows 和 macOS 平台下均需要先设置 Cangjie SDK 路径。

语言服务

功能简介

语言服务工具为开发者提供如下功能：语法高亮、自动补全、定义跳转、查找引用、诊断报错、选中高亮、悬浮提示、签名帮助和重命名等。

代码高亮

VSCode 打开仓颉工程中的 .cj 文件，即可看到代码高亮效果。VSCode 不同主题显示的代码高亮颜色不同，支持对代码运算符、类、注释、函数、关键字、数字、包名、字符串、变量等进行高亮显示。

sema

自动补全

VSCode 打开仓颉工程中的 .cj 文件，输入关键字、变量或 . 符号，在光标右侧提示候选内容。可以用上下方向键快速选择想要的内容（需要切换为系统默认输入法），使用 Enter 键或 Tab 键补全。

compelte1

complete2

对于带参数的函数或者泛型提供模块化补齐，即当函数有参数或者带泛型时，选择函数补齐项之后会出现参数格式化补齐，如下图所示。填充数值之后按下 Tab 键可以切换到下一个参数补齐，直至模块化补齐结束，或按下 Esc 键提前退出除当前选中模块。

completeFormat

定义跳转

VSCode 打开仓颉工程中的 .cj 文件，鼠标悬停在目标上方，按下 Ctrl 键并单击鼠标左键触发定义跳转；或使用鼠标右键单击目标符号，选择 Go to Definition 执行定义跳转；或按下快捷键 F12 执行定义跳转。

definition

说明：

在符号使用的地方使用定义跳转会跳转到符号定义处，支持跨文件跳转。在符号定义处使用定义跳转，如果此符号没被引用过，光标会跳转到符号左端。如果符号在其他地方被引用，会触发查找引用。

跨语言跳转

语言服务插件支持 Cangjie 语言到 C 语言的跳转功能，VSCode 打开仓颉工程中的 .cj 文件，鼠标悬停在 Cangjie 互操作函数上方，按下 Ctrl 键并单击鼠标左键触发定义跳转；或使用鼠标右键单击目标符号，选择 Go to Definition 执行定义跳转；或按下快捷键 F12 执行定义跳转。

前置条件

本地安装华为自研 C++ 插件。
在仓颉插件上设置需要跳转的 C 语言源码存放目录。
在当前工程下创建 build 文件夹，存放 compile_commands.json 文件（该文件可通过 cmake 命令生成），用于创建指定文件夹的索引文件。

跳转效果

foreign 函数会在开发者设置的目录下查找对应的 C 语言函数，若找到则跳转至 C 语言源码的函数位置。除上述场景外均保持插件原有的定义跳转。

crossJump

查找引用

VSCode 打开仓颉工程中的 .cj 文件，使用鼠标右键单击目标符号，选择 Find All References 执行符号引用预览，单击预览条目，可以跳转到对应引用处。

reference

诊断报错

VSCode 打开仓颉工程中的 .cj 文件，当源码文件出现不符合仓颉语法或语义规则的代码时，会在相关代码段出现红色波浪下划线，如下图所示，当鼠标悬停在上面，可以提示相应的报错信息。修改正确后，诊断报错自行消失。

diag

选中高亮

VSCode 打开仓颉工程中的 .cj 文件，光标定位在一个变量或函数名处，当前文件中该变量的声明处以及其使用处都会高亮显示。

docHighlight

悬浮提示

VSCode 打开仓颉工程中的 .cj 文件，光标悬浮在变量处，可以提示类型信息。

hover1

悬浮在函数名处，可以提示函数原型。

hover2

定义搜索

VSCode 打开仓颉工程中的 .cj 文件，同时按下 Ctrl 键和 T 键，弹出搜索框，输入想要搜索的符号定义名，会显示出符合条件的搜索结果。单击搜索结果条目，可以跳转到对应的定义位置处。

searchsymbol_open

目前支持搜索的定义类型有：class、interface、enum、struct、typealias、toplevel 的函数、toplevel 的变量、prop、enum 构造器、成员函数和成员变量。

重命名

VSCode 打开仓颉工程中的 .cj 文件，光标定位在想要修改的自定义名称上，右键选择 Rename Symbol 或按下快捷键 F2 打开重命名编辑框。

prepareRename

编辑完毕按下回车键，完成重命名的实现。

onRename

目前支持重命名的类型有：class、interface、enum、struct、func、type、泛型、变量和自定义宏。

大纲视图显示

VSCode 打开仓颉工程中的 .cj 文件，在左侧 OUTLINE 视图中显示当前文件的大纲。目前支持两层结构的显示，第一层主要为 toplevel 中定义的声明，第二层主要为构造器及成员。

outline

目前支持大纲视图显示的类型有：class、interface、enum、struct、typealias、toplevel 的函数、toplevel 的变量、prop、enum 构造器、成员函数和成员变量。

面包屑导航

VSCode 打开仓颉工程中的任意 .cj 文件，光标定位在符号处，点击面包屑导航，显示符号当前所处的位置，以及该符号在整个工程中的位置路径。

Breadcrumb

目前支持面包屑导航的类型有：class、interface、enum、struct、typealias、toplevel 的函数、toplevel 的变量、prop、enum 构造器、成员函数和成员变量。

签名帮助

VSCode 在输入左括号和逗号时会触发签名帮助。触发后，只要还在函数参数范围内，提示框会一直随光标移动（可与补全共存）。如下图所示，开发者可以看到当前函数的参数信息，以及当前函数位置参数的高亮效果。

signaturehelp

显示类型层次结构

VSCode 打开仓颉工程中的 .cj 文件，光标定位在想要查看的自定义名称上，右键选择 Show Type Hierarchy，在左侧就会显示该类型层次结构。

目前支持显示层次结构的类型有：class、interface、enum 和 struct。

typeHierarchy

单击如图标记所示位置，可以在显示子类和父类之间切换。

typeHierarchy

调用类型层次结构

VSCode 打开仓颉工程中的 .cj 文件，光标定位在函数名上，右键选择 Show Call Hierarchy，在左侧就会显示该函数的调用类型层次结构。

callHierarchy

通过单击标识位置可以在显示调用函数和被调用函数之间切换。

callHierarchy

创建仓颉工程

仓颉工程目录结构如下所示。

Project_name：开发者输入的名称

├── src：代码目录

│    └── main.cj：源码文件

└── cjpm.toml：默认的 cjpm.toml 配置文件

使用 VSCode 命令面板

在 VSCode 中使用快捷键 F1，或同时按下 Ctrl + Shift + P（macOS 系统为 Command + Shift + P）打开命令面板，按照以下步骤创建仓颉工程。

第一步：选择创建仓颉工程命令

createProject_1

第二步：选择仓颉后端

createProject_2

第三步：选择工程模板

createProject_3

第四步：选择工程路径

createProject_4

第五步：输入工程名称

createProject_5

第六步：完成创建并打开

createProject_6

使用可视化界面

在 VSCode 中使用快捷键 F1，或同时按下 Ctrl + Shift + P（macOS 系统为 Command + Shift + P）打开命令面板，按照以下步骤创建仓颉工程。

第一步：选择创建仓颉可视化工程命令

createProjectView_1

第二步：打开可视化创建仓颉工程界面

createProjectView_2

第三步：选择工程模板

createProjectView_4

第四步：选择工程路径

createProjectView_5

第五步：输入工程名称

createProjectView_6

第六步：单击 Confirm 完成创建并打开

createProjectView_7

编译构建

VSCode 中可视化方式提供的仓颉功能编译构建能力依赖 cjpm 工具，该工具要求打开的仓颉工程的模块内必须包含规范的 cjpm.toml 文件。若没有该文件，仍想执行工程的编译构建，可在终端使用 cjc 命令。

在 VSCode 中提供在命令面板执行命令、在终端进行执行命令、单击运行按钮运行工程，以及单击锤子按钮编译工程四种方式，来实现仓颉工程的编译构建。

编译构建方式

在命令面板执行命令

在 VSCode 中使用快捷键 F1，或同时按下 Ctrl + Shift + P（macOS 系统为 Command + Shift + P）打开命令面板，输入分类词 Cangjie 来快速找到以下编译相关命令。

选择 Cangjie: Parallelled Build 选项执行并行编译。

执行并行编译后，在工程文件夹下会生成 target 目录，target 目录下有一个 release 文件夹，release 文件夹下包含三个目录：.build-logs 目录、bin 目录，以及工程名同名的目录。bin 目录下存放可执行文件（可执行文件只有在 cjpm.toml 的 output-type 为 executable 时才会生成），工程名同名目录下存放编译的中间产物。

在 output Panel 上会打印编译是否成功的信息。
选择 Cangjie: Build With Verbose 选项执行编译并展示编译日志。

该编译参数除了执行编译外，还会打印编译日志。
选择 Cangjie: Build With Debug 选项生成 debug 版本的目标文件。

该命令的编译结果中带有 debug 信息，供调试使用。
选择 Cangjie: Build With Coverage 选项生成覆盖率信息。

该命令在编译结果中带有覆盖率信息。
选择 Cangjie: Build With Alias 执行编译并指定输出可执行文件的名称。

执行该命令，按下回车键后，会弹出一个输入栏，需要开发者为工程的编译结果赋予一个新的名字。该命令只对 cjpm.toml 的 output-type 为 executable 时有效。
选择 Cangjie: Build With Increment 选项执行增量编译。

用来指定增量编译。
选择 Cangjie: Build With CustomizedOption 选项按条件透传 cjpm.toml 中的命令。

使用该选项需要先在 cjpm.toml 中配置 customized-option 字段。然后在命令面板输入 Build With CustomizedOption，按下回车键后可以选择需要的参数，参数可以多选，选择后按下回车键即可。

若没有在 cjpm.toml 中配置 customized-option 字段，并执行了该条命令，插件会提示开发者先配置改字段。
选择 Cangjie: Build With TargetDir 选项执行编译并在指定路径生成编译产物。

选择该命令执行后，可指定编译产物的输出路径，默认不作输入操作则以 cjpm.toml 中的 target-dir 字段为路径。

当输入的编译产物路径与 cjpm.toml 中的 target-dir 字段不同时，会弹出提示是否覆盖 cjpm.toml 中的 target-dir 字段。若选择 Yes 覆盖，则会将 cjpm.toml 中 target-dir 字段覆盖成输入的值。

该命令执行成功后，会在指定的路径下生成编译产物。
选择 Cangjie: Build With Jobs 选项，执行编译前自定义最大并发度。

支持通过执行该命令在编译之前自定义最大并发度，输入参数为任意数字，设置范围为 (0, CPU 核数 * 2]。

当在输入框输入非数字时，会终止操作，并提示开发者输入数字内容：“Invaild input! The input should be number.”

当在输入框输入的范围超出所支持的范围 (0, CPU 核数 * 2] 时，会默认采用 CPU 核数，并提示超出可选范围的告警信息。
选择 Cangjie: Build With CodeCheck 选项，执行编译时进行 CodeCheck 静态代码检查。

执行该命令编译工程时，会对当前工程进行 CodeCheck 静态代码检查，如果检查到【要求】级别的代码规范违规，则编译失败，检查到【建议】级别的违规仅告警，正常完成编译。
选择 Cangjie: Build With MultiParameter 选项执行多参数编译。

仓颉工程的编译可以叠加多个参数，在命令面板搜索到 Build With MultiParameter 命令后，选择需要叠加的参数，其中 --target 参数会根据 cjpm.toml 中的 target 字段的设置来决定是否显示。如果开发者没有配置 target 的内容，则 --target 参数选项会隐藏；--<customized-option> 参数会根据 cjpm.toml 中的 customized-option 字段的设置来决定是否显示，如果开发者没有配置 customized-option 的内容，则 --<customized-option> 参数选项会隐藏。

勾选想叠加的参数，按下回车键或者单击 ok 按钮。也可单击界面中的向左箭头，重新选择编译参数。

如果叠加的参数中选择了 cjpm build --output=<name>，那么需要输入一个别名字符串，然后按下回车键执行叠加命令操作。

如果叠加参数中选择了 cjpm build --target=<name>，那么可以选择一个想要交叉编译的平台。

如果叠加参数中选择了 cjpm build --<customized-option>，那么可以选择透传参数。

叠加命令的编译结果就是这些命令分别执行的总和。
选择 Cangjie: Update Cjpm.toml 选项更新 cjpm.lock 文件。

在修改完 cjpm.toml 文件后，需要执行该命令，更新 cjpm.lock 文件。如果是通过 UI 界面修改的 cjpm.toml 文件，则不需要手动执行该操作。
选择 Cangjie: Execute Test File 选项编译单元测试产物，执行对应的单元测试用例，并直接打印测试结果。
选择 Cangjie: Test With NoRun 选项编译对应测试产物。
选择 Cangjie: Test With SkipBuild 选项测试产物存在的前提下，用于执行对应测试产物。
选择 Cangjie: Test With Jobs 选项执行单元测试之前自定义最大并发度，操作与 Build With Jobs 相同。
选择 Cangjie: Test With MultiParameter 选项执行多参数执行仓颉工程的单元测试。

在选择该条命令后，可以选择指定包路径、模块或者成员执行单元测试。只有打开工作空间，才显示成员选择选项。

如果选择 Specify the test paths 选项，则可以输入指定待测试的包路径。若不需要指定，则直接按 Enter 键。

此步骤可通过输入多个包的路径并用空格分隔，可以实现多包并发单元测试。

如果选择 Specify the test modules 选项，则可以输入指定待测试的模块。若不需要指定，则直接按 Enter 键。

此步骤可通过输入多个模块并用空格分隔，可以实现多模块单元测试。

如果选择 Specify a test member 选项，则可以输入指定待测试的成员。若不需要指定，则直接按 Enter 键。

选择要叠加的参数。

如果选择了 --filter=<value> 参数，则需要输入对应的过滤测试子集的表达式。

输入过滤测试子集的表达式后，可以执行 cjpm test 的完整命令。执行结果会在 Output 面板输出。

如果在 cjpm.toml 中配置了 target 和 customized-option，则可以选择的参数有 --target=<name> 和 --<customized-option>。

如果选择了 --target=<name> 参数，则需要选择对应的平台。

如果选择了 --<customized-option> 参数，则需要选择条件选项。
选择 Cangjie: Clean Build Result 选项清除编译结果（工程目录下的 build 目录）。
选择 Cangjie: Check Circular Dependencies 选项检测文件依赖。
选择 Cangjie: Edit Configuration (UI) 选项打开 UI 配置界面。
选择 Cangjie: Install With Verbose 选项展示安装日志。
选择 Cangjie: Install With Debug 选项生成 debug 版本的安装产物。
选择 Cangjie: Install With RootPath 选项指定可执行文件的安装路径。

在选择该条命令后，在弹出的输入框中输入期望可执行文件的安装路径，最终会将可执行文件安装到输入的自定义路径中。不配置时，Linux 系统和 macOS 系统下默认为 $HOME/.cjpm，Windows 系统下默认为 %USERPROFILE%/.cjpm。
选择 Cangjie: Install With TargetDir 选项指定编译产物的存放路径。

安装可执行文件前会先进行编译，选择该条命令后，在弹出的输入框中输入期望编译产物的存放路径，最终会将编译产物安装到输入的自定义路径中。
选择 Cangjie: Install With Alias 选项指定最终安装的产物名。

选择该条命令后，在弹出的输入框中输入期望安装产物的名字。
选择 Cangjie: Install With Git 选项安装远端 git 代码仓产物。

选择该条命令后，在弹出的输入框中输入远端 git url。

输入远端 git url 后，键入回车可进一步选择关于远端 git 代码仓的分支、tag 或 commit 信息。

选择自定义代码仓 branch / tag / commit 号选项，在弹出框内输入 branch / tag / commit 号信息，即可安装远端 git 代码仓产物。
选择 Cangjie: Install With List 选项打印已安装产物列表。
选择 Cangjie: Install With SkipBuild 选项跳过编译阶段以直接安装产物，需要项目处于编译完成状态。
选择 Cangjie: Install With Jobs 选项指定并行编译的最大并发数。

选择该条命令后，在弹出的输入框中输入期望安装时的最大并发数。
选择 Cangjie: Install With CustomizedOption 选项按条件透传 cjpm.toml 中的命令。

使用该选项需要先在 cjpm.toml 中配置 customized-option 字段。然后在命令面板选择 Install With CustomizedOption，按下回车键后可以选择需要的参数，参数可多选，选择后按下回车键即可。

开发者需要在 cjpm.toml 中配置 customized-option 字段，才能执行该条命令。
选择 Cangjie: Install With SkipScript 选项跳过待安装模块的构建脚本的编译运行。
选择 Cangjie: Install With CustomParameter 选项执行自定义的安装命令参数选项。

单击 VSCode 页面左下角齿轮图标，选择设置选项。或直接右键单击插件，选择 Extension Settings，进入配置页面。在搜索栏输入 Cangjie，选择侧边栏的 Cangjie Language Support 选项。该页面有输入框 Cangjie: Cjpm Install: Custom，在此输入 cjpm install 相关的命令选项，如 -V -g --name \<value\>。然后在命令面板选择 Install With CustomParameter 命令，最终将该输入框中的内容带到 cjpm install 中。
选择 Cangjie: Uninstall Binary 选项卸载仓颉项目，清除对应的可执行文件和依赖文件。

选择该命令后，在弹出的输入框中输入需要卸载的可执行文件名字。
选择 Cangjie: Uninstall With Root 选项指定卸载时搜索的目标路径。

选择该命令后，在弹出的输入框中输入期望卸载时搜索的目标路径，最终会将该路径下的指定可执行文件和依赖文件卸载。不配置时，Linux 系统和 macOS 系统下默认为 $HOME/.cjpm，在 Windows 系统下默认为 %USERPROFILE%/.cjpm。

在终端进行执行命令

开发者可以直接在 VSCode 的终端面板使用编译构建命令（cjpm）对仓颉工程进行编译构建。初次使用需要重新启动 VSCode，即可在终端执行 cjpm 操作。

cjpm

单击运行按钮运行工程

开发者可以单击 .cj 文件编辑区的运行按钮来运行整个仓颉工程。

runCode

若整个工程中配置的 output-type 为 executable，则会在终端面板打印运行结果，否则只会显示编译的结果。

单击运行按钮执行的编译过程是结合当前的 cjpm.toml 和 cjpm_build_args.json 的配置来进行的。

单击锤子按钮编译工程

开发者可以单击 .cj 文件编辑区的锤子按钮来编译整个仓颉工程。

hammerButton

单击锤子按钮执行的编译过程与运行按钮一致，也是结合当前的 cjpm.toml 和 cjpm_build_args.json 的配置来进行的。不同的是，若整个工程中配置的 output-type 为 executable，则运行按钮在编译完成后再运行整个工程，而锤子按钮只会编译工程，无后续运行动作。

可视化配置编译构建参数

在编译构建过程中需要配置工程目录中的 cjpm.toml 和 cjpm_build_args.json 文件，方法如下：

直接修改 cjpm.toml 和 cjpm_build_args.json 文件。

editOne

使用快捷键 F1，或同时按下 Ctrl + Shift + P（macOS 系统为 Command + Shift + P）打开命令面板，在命令面板执行 Cangjie: Edit Configuration (UI) 命令打开可视化编辑的 UI 界面。

editTwo

单击编辑页面右上角的画笔按钮，跳转到可视化编辑的 UI 界面。

editThree

对于工程文件中 .vscode 目录下的 cjpm_build_args.json 的配置，通过复选框或者输入框的形式确定编译要使用的参数，修改后会同步到 cjpm_build_args.json 文件中。

对于工程中 cjpm.toml 文件的配置，开发者输入内容并将光标移至输入框外，即可生效到 cjpm.toml 文件中。

注意：

当仓颉工程中的 cjpm.toml 文件和参数配置界面同时在 VSCode 的编辑区显示时，对 cjpm.toml 文件的修改不会同步到 UI 界面上。

对于构建参数 cross-compile-configuration，可以在 cross-compile-configuration 下单击 Add Configuration 按钮添加选项。

在 key 和 compile-option 处填写对应内容，单击对勾按钮或按下回车键，与 cjpm.toml 保持同步。若想删除该条配置，只需单击该条选项的叉号按钮。

添加的配置在不填写第一个字段 key 就直接单击对勾按钮或按下回车键，会出现必须要填写第一个字段的提示，该场景下提交的内容不会同步到 cjpm.toml 中。在 UI 界面目前不会直接删除该条配置，刷新 UI 界面后会自动删除，内容与 cjpm.toml 保持一致。package-configuration 和 cross-compile-configuration 类似，package-configuration 新增配置时第一个字段为空的场景如下图所示。

对于 package-configuration 参数，其添加和修改方式与 cross-compile-configuration 一致。其中 output-type 字段为下拉框选项，其可选的类型有 executable、static、dynamic 和 null。新添加的配置字段的初始化类型为 null，开发者可以根据自己的需要进行选择。当选择为 null 时，该字段同步到 cjpm.toml 后会删除该字段。

注意：

在 UI 界面配置 cjpm.toml 的内容时，只有对于 customized-option 参数中配置的 --cfg 中路径中的 = 需要转义，其他符号不需要添加转义符号。但直接在 cjpm.toml 中填写时，需要加转义符号。如在给 package-configuration 字段的 p1 配置 compile-option 时，在 UI 界面对 --link-options 设置内容时只需要加引号即可，即 --link-options="-rpath=xxx"。而在 toml 文件中，需要填写 --link-options=\"-rpath=xxx\"。在 UI 界面对 customized-option 参数配置的 --cfg 路径中包含 = 时，= 需要转义，即--cfg="D:/projects/cang\=jie"，而在 toml 文件中，需要填写 --cfg=\"D:/projects/cang\\=jie\"。

对于 customized-option 参数，其添加修改方式与 cross-compile-configuration 一致。

注意：

customized-option 的条件不能设置内置的条件（@When[os == "Linux"] 不能作为 customized-option 的条件，即 "cfg1" : "--cfg ="os=Linux"" 是不允许的），只能添加开发者自定义条件。具体请参考 Cangjie > Language Guide 文档的 条件编译 章节。

三方库便捷导入

导入方式

注意：

三方库便捷导入仅适用于当前打开的仓颉工程的主模块。如果其他子模块需要便捷导入三方库，可以单独以工程的方式打开使用。

在仓颉工程中，可以导入外部的三方库，并且在 cjpm.toml 中进行配置。

dependencies：当前仓颉模块依赖项目，包含了当前构建所需要的其它模块的配置信息，包含版本号和路径。这两个选项必须全部配置，否则会执行失败并报错。在使用过程中，优先使用此方式进行项目依赖导入。

dev-dependencies：使用方式与 dependencies 一致，具有与 dependencies 字段相同的格式。用于指定仅在开发过程中使用的依赖项，而不是构建主项目所需的依赖项，例如仅在测试中使用的依赖项。如果开发者是库作者，则应将此字段用于此库的下游用户不需要使用的依赖项。

bin-dependencies：非特殊需求场景下，建议使用 dependencies 的方式导入依赖。目前仓颉插件仅支持本地的 bin-dependencies 配置。

当前仓颉模块依赖已编译好的 package，有两种导入形式。以导入下述 pro0 模块和 pro1 模块的三个包来举例说明。

test

├── pro0

│    ├── libpro0_xoo.so

│    ├── xoo.cjo

│    ├── libpro0_yoo.so

│    └── yoo.cjo

├── pro1

│    ├── libpro1_zoo.so

│    └── zoo.cjo

├── src

│    └── main.cj

└── cjpm.toml

方式一：通过 package-option 导入。

[target]
    [target.x86_64-w64-mingw32]
        [target.x86_64-w64-mingw32.bin-dependencies]
            [target.x86_64-w64-mingw32.bin-dependencies.package-option]
                pro0_xoo = "./test/pro0/xoo.cjo"
                pro0_yoo = "./test/pro0/yoo.cjo"
                pro1_zoo = "./test/pro1/zoo.cjo"

该选项是 map 结构，pro0_xoo 名称作为 key，与 libpro0_xoo.so 相对应，前端文件 .cjo 的路径作为 value，对应于该 .cjo 的 .a 和 .so 需放置在相同路径下，且对应的 .cjo 模块文件必须与模块名来源文件放置在相同的文件夹下，该文件夹下不能有任何其他文件或文件夹。

方式二：通过 path-option 导入。

[target]
    [target.x86_64-w64-mingw32]
        [target.x86_64-w64-mingw32.bin-dependencies]
            path-option = ["./test/pro0", "./test/pro1"]

该选项是字符串数组结构，每个元素代表待导入的路径名称。cjpm 会自动导入该路径下所有符合规则的仓颉库包，这里的合规性是指库名称的格式为模块名_包名。库名称不满足该规则的包只能通过 package-option 选项进行导入。

如果同时通过 package-option 和 path-option 导入相同的包，则 package-option 字段的优先级更高。

导航栏视图呈现如下形式。

packageRequires

开发者可以在其对应的导入方式子目录下导入工程需要的模块。在导航栏单击画笔进入 UI 界面。

packageRequireUI

ffi：当前仓颉模块外部依赖 C 库，配置了依赖该库所需要的信息，包含名称和路径字段。资源管理器的视图栏中的 CANGJIE LIBRARY 栏，可以方便开发者添加这几类外部库。

在工程初始化后，可以通过单击分类栏的加号按钮添加对应的三方库。

也可以通过单击三方库上的减号删除对应的库。

可以通过单击视图栏的编辑按钮，打开三方库导入的可视化界面来导入或删除三方库。

configLib

以上删除和添加操作均同步到工程的 module.json 文件中。

导入限制

项目中需要链接动态库（C 库和仓颉库）时，需自行设置 LD_LIBRARY_PATH，执行 export LD_LIBRARY_PATH=xxx:$LD_LIBRARY_PATH。
在 cjpm.toml 中修改内容不会直接影响 treeView 和 UI 界面，需要单击 treeView 或 UI 界面进行手动更新。
在 treeView 中的库分类处添加外部库，且此时库分类目录是关闭状态，则添加后需要打开目录才能查看。
UI 界面的字段暂不支持 hover 显示内容的功能。
UI 界面非开发者添加的外部库，其路径与 cjpm.toml 保持一致。开发者添加的库和 treeView 均显示绝对路径。

调试服务

功能简介

仓颉编程语言提供了可视化调试服务，方便开发者调试仓颉程序。该插件提供如下功能：

Launch：启动调试进程
Attach：附加到已启动的进程
支持源码断点、函数断点、数据断点、汇编断点
支持源码内单步调试、运行到光标处、步入、步出、继续、暂停、重启、停止调试
支持仓颉-C 互操作调试，仓颉代码 continue、步入到 C 代码
支持汇编内单步、步入、步出
支持表达式求值
支持变量查看和修改
支持在调试控制台中查看变量
支持查看被调试程序的输出信息
支持反向调试
支持 Unittest 的运行和调试

说明：

如果第一次使用 VSCode 调试功能，可以查看 VSCode 调试服务使用手册。

调试服务当前支持在 Windows 和 Linux 版本的 VSCode 中安装使用。

受调试器限制，循环代码中存在条件断点时，执行 PAUSE 操作可能导致后续调试无法进行。

VARIABLES 视图修改变量时，不会触发存在依赖关系的变量的刷新。

调试服务依赖仓颉 SDK 包内 liblldb 动态库文件时，请提前配置仓颉 SDK 路径。

启动调试

Launch 模式

仓颉工程调试

未创建 launch.json 文件时，单击 Run and Debug > Cangjie(cjdb) Debug 启动调试。
已创建 launch.json 文件时，在 launch.json 文件中单击 Add Configuration > Cangjie Debug (CJNative) : launch > Build And Debug Cangjie Project 添加调试配置，选择添加的配置启动调试。

单文件调试

针对单文件调试，可以选中需要调试的仓颉源文件，右键选择 Cangjie: Build and Debug File，该操作会生成编译配置文件 task.json 和编译脚本，并且会根据 task.json 配置执行脚本，编译出可调试的二进制文件，然后启动调试。

start

调试手动编译的可执行文件

使用 cjc 编译器或 cjpm 手动编译出可调试的二进制文件。
单击 Run and Debug > Cangjie(cjdb) Debug > Cangjie (CJNative): launch > Choose Executable File Later 启动调试。

Launch debugMacro 模式仓颉工程调试宏展开后的代码

调试宏展开后的代码文件（后缀为 .marcocall），此时宏对应的原文件无法调试。

调试远程进程（支持 Linux 远程到 Linux）

Launch 模式下调试远程进程时，调试服务会将本地编译的二进制文件推送到远程平台，然后调试远程平台的二进制文件。

在远程平台启动 lldb-server。建议使用 cjdb 自带的 lldb-server，路径为 /cangjie/third_party/llvm/lldb/bin/lldb-server，启动命令 /**/**/cangjie/third_party/llvm/lldb/bin/lldb-server p --listen "*:1234" --server。
在本地机器使用 cjc 编译器或 cjpm 手动编译出可调试的二进制文件。
单击 Run and Debug 按钮启动调试。

launch.json 配置示例如下：

{
    "name": "Cangjie Debug (cjdb): test",
    "program": "/**/**/test",
    "request": "launch",
    "type": "cangjieDebug",
    "externalConsole": false,
    "remote": true,
    "remoteCangjieSdkPath": "/**/**/cangjie",
    "remoteFilePath": "/**/**/test",
    "remoteAddress": "1.1.1.1:1234",
    "remotePlatform": "remote-linux"
}

配置属性

属性	类型	描述
program	string	被调试进程的全路径，该文件将推送到远程平台，例如：/home/cangjieProject/build/bin/main
remote	boolean	启动远程 Launch 进程，remote 为 true
remoteCangjieSdkPath	string	远程平台仓颉 SDK 路径
remoteFilePath	string	远程平台存放推送文件的全路径，请确保路径 /home/test/ 合法且存在，`main` 为推送到远程的文件名，例如：/home/cangjieProject/build/bin/main
remoteAddress	string	被调试进程所在的机器 IP 和 lldb-server 监听的端口号，数据格式：ip:port
remotePlatform	string	远程的平台，仅支持 remote-linux（远程 Linux 平台）
env	object	为被调试程序设置运行时的环境变量，该配置将覆盖系统环境变量，如需在系统配置基础上追加配置，在配置项结尾增加 ${env:PATH}。例如："PATH":"/home/user/bin: ${env:PATH}", "LD_LIBRARY_PATH":"/home/user/bin:${env:LD_LIBRARY_PATH}"。

Attach 模式

调试本地进程

在 launch.json 文件中单击 Add Configuration > Cangjie Debug (CJNative) : attach 添加调试配置，选择添加的配置启动调试。
在弹出界面选择要调试的进程即可启动调试。

调试远程进程

在本地机器编译出可调试二进制文件并将该文件拷贝到远程机器。
在远程机器启动 lldb-server，建议使用 cjdb 自带 lldb-server，路径为 /cangjie/third_party/llvm/lldb/bin/lldb-server，启动命令 /**/**/cangjie/third_party/llvm/lldb/bin/lldb-server p --listen "*:1234" --server。
在远程机器启动被调试的二进制文件。
在本地机器配置 launch.json 文件，并启动调试。

launch.json 配置属性：

{
    "name": "Cangjie Debug (cjdb): test",
    "processId": "8888",
    "program": "/**/**/test",
    "request": "attach",
    "type": "cangjieDebug",
    "remote": true,
    "remoteAddress": "1.1.1.1:1234",
    "remotePlatform": "remote-linux"
}

配置属性

属性	类型	描述
processId	string	被调试进程的 pid（配置 pid 时优先 attach pid，未配置 pid 则 attach program）
program	string	被调试进程的全路径，例如：/home/cangjieProject/build/bin/main
remote	boolean	attach 本机器进程，remote 为 false；若 attach 远程进程，将 remote 设置为 true
remoteAddress	string	远程调试时被调试进程所在的机器 IP 和 lldb-server 监听的端口号，数据格式：ip:port
remotePlatform	string	远程调试时远程的平台，仅支持 remote-linux（远程 linux 平台）

查看调试信息

当进程处于 stopped 状态时，可以在 VSCode 界面左侧查看断点、当前线程、堆栈信息和变量，支持编辑断点和修改变量。也可以在 Editor 窗口将鼠标悬停在变量名称上方查看变量值。支持在 TERMINAL 窗口查看被调试程序的输出信息。

debugInfo

表达式求值

在 WATCH 窗口添加按钮或空白处双击键入表达式。
在 Debug Console 窗口键入表达式。
在 Editor 窗口双击选中变量，右键选择 Evaluate in Debug Console。

程序控制

单击顶部调试工具栏上的图标控制程序，包括单步执行、步入、步出、继续、暂停、重启或停止程序。
在鼠标光标处单击右键选择 Run to Cursor。
在源码视图右键选择 Open Disassembly View 进入汇编视图。

调试控制台

执行 cjdb 命令

在调试控制台中输入 cjdb 命令来调试程序，命令的格式需要以 -exec 开头，要执行的子命令必须是正确的 cjdb 命令。

使用 cjdb 命令 n 执行单步调试的示例如下：

-exec n

debugconsoleCjdbcommand

查看变量

在调试控制台中输入变量名称查看变量值：

debugconsoleVariable

反向调试

说明：

反向调试基于记录重放，开启反向调试功能后，调试服务会记录开发者正向调试的所有停止点（断点 + 单步），以及停止点的线程、堆栈和变量等调试信息。进入反向调试模式，支持查看历史记录点的调试信息。

配置

单击左下角齿轮图标，选择设置（Settings）选项，在搜索栏输入 cangjie，找到 Reverse Debug 选项，勾选 Enable reverse debug，开启程序调试历史停止点信息的自动记录。同时可以配置自动记录的线程个数、堆栈个数、变量作用域、复杂类型变量子变量的展开层数和子变量个数。修改配置后，需要重新启动仓颉调试。

reverseDebugConfig

工具栏

单击顶部调试工具栏上的时钟图标进入反向调试模式，使用工具栏上正反向继续、正反向单步控制程序，查看历史记录的线程、堆栈、变量信息，如下图所示。

reverseDebugOpen

单击顶部调试工具栏上的方块图标退出反向调试模式，调试会回到正向调试的最后停止点，如下图所示。

reverseDebugClose

反向断点

说明：

反向断点是一种特殊的源码断点（Log Point），正向调试过程中不会停止，也不会输出自动生成的 Log Message（用于标记反向断点）。

在正向调试时，开发者提前设置反向断点，调试服务后台会记录进程走过的反向断点的调试信息。

在进入反向调试模式时，反向断点会作为停止点（断点型），可以查看该断点处的线程堆栈变量等调试信息。

在进入反向调试模式时，不支持设置反向断点。

反向断点设置方式：

在仓颉源文件编辑器视图内右键选择 Cangjie: Add Reverse Breakpoint，为光标所在行设置一个反向断点。
在仓颉源文件上右键选择 Cangjie: Add Auto Reverse Breakpoints 插件会分析该文件内函数的入口和出口位置并自动设置反向断点。
在文件夹上右键选择 Cangjie: Add Auto Reverse Breakpoints 插件会分析该文件夹内仓颉源文件中的函数的入口和出口位置并自动设置反向断点。

时间线

说明：

时间线展示了反向调试模式下记录的所有停止点（断点+单步），通过时间线拖拽，可以查看历史停止点的信息。

时间线入口位于 VSCode 右下方区域，可以在右下方的 Tab 标签行右键将时间线 Cangjie Debug Timeline 开启或隐藏，也可以在 View 菜单中选择 Open View 开启，如下图所示。

主时间线上有左右游标，可以分别拖动左右游标选出某一段时间区域。在选中一段区域之后，鼠标放在选中区域上方时会变为手的形状，此时可以左右拖动此区域。
将鼠标放在主时间线上，鼠标变为十字光标的形状，此时按住鼠标往前或往后拖动，可以将鼠标滑过的区域设为新的时间区域。
可以通过 Ctrl + 鼠标滚轮的方式，放大和缩小选中区域。
每条时间线标识一个仓颉线程或者系统线程。

单击时间线上的记录点，editor 界面同步刷新（定位到源码的行），调试信息界面同步刷新（展示该记录点的线程、栈帧和变量）。

unittest 运行和调试

前置条件

模块的单元测试代码应采用如下结构，其中 .cj 文件表示包的源码，对应单元测试代码文件命名应以 _test.cj 结尾。具体单元测试代码的写法可参考标准库用户手册。

├── src

│    ├── koo

│    │   ├── koo.cj

│    │   └── koo_test.cj

│    ├── zoo

│    │   ├── zoo.cj

│    │   └── zoo_test.cj

│    ├── main.cj

│    └── main_test.cj

└── cjpm.toml

使用方式

单击 @Test/@TestCase 声明行上的 run 按钮，运行该单元测试类/单元测试 case。
单击 @Test/@TestCase 声明行上的 debug 按钮，调试该单元测试类/单元测试 case。

unittest

DAP 通信日志

调试服务客户端和服务端采用 DAP 协议通信，通信日志可用于定位问题。日志路径在用户目录下 /.cangjie/debug/logs/server。

可以通过点击左下角齿轮图标，选择设置（Settings）选项，在搜索栏输入 cangjie，找到 Debug 选项，勾选 Enable DAPCommunication Log，开启调试服务通信日志。

格式化

针对仓颉文件，在 VSCode 的代码编辑区右键选择 [Cangjie] Format 或用快捷键 Ctrl + Alt + F 执行格式化命令，可以对当前仓颉文件进行格式化。如下图所示。

cjfmt

针对仓颉项目，支持在 VSCode 的资源管理器中选择文件或右键单击文件夹执行 [Cangjie] Format 命令，对选择的文件或者文件夹进行格式化。如下图所示。

cjfmtFolder

静态检查

IDE 中的静态检查功能基于静态检查工具 cjlint，该功能可以识别代码中不符合编程规范的问题，帮助开发者发现代码中的漏洞，写出满足 Clean Source 要求的仓颉代码。

说明：

静态检查目前只能检测工程目录 src 文件夹下的所有仓颉文件。

静态检查的入口有两处:

在 VSCode 的代码编辑区右键选择 [Cangjie] CodeCheck 或用快捷键 Ctrl + Alt + C 执行静态检查命令，如下图所示。
在 VSCode 的资源管理器处右键选择 [Cangjie] CodeCheck 执行静态检查命令，如下图所示。

执行静态检查命令后，如果有不符合编码规范的问题，会展示在右侧的表格中。单击表格中的文件链接，可以跳转到问题代码所在文件的行列。

cjlintResult

当前支持代码保存后自动触发静态检查：

开发者可以通过点击左下角齿轮图标，选择设置选项，在搜索栏输入 cangjie，找到 Code Check On Save 选项，勾选该选项，即可开启自动触发静态检查。如下图：

codeCheckOnSave

开启自动静态检查后会在项目根目录生成一个 cjlintignore.cfg 配置文件，配置文件中可支持三类屏蔽方式，包括屏蔽文件、文件夹和正则表达式。每条配置项为相对该配置文件所在目录的相对路径（支持正则），无需双引号包含，自动静态检查支持将配置项匹配的仓颉文件屏蔽，不会产生关于这些文件的告警。例如在 cjlintignore.cfg 中有以下配置，则自动静态检查会将 src/subdir1/ 目录和 src/subdir2/a.cj 文件加入屏蔽。

codeCheckIgnoreConfig

覆盖率统计

覆盖率统计功能用于生成仓颉语言程序的覆盖率报告。

注意：

当选择的文件夹中不含有仓颉文件时，将不会生成覆盖率报告。

覆盖率统计的入口有两处:

在 VSCode 的代码编辑区右键选择 [Cangjie] Coverage 或用快捷键 Ctrl + Alt + G 执行生成当前仓颉文件覆盖率报告的命令，如下图所示。
在 VSCode 的资源管理器中选择文件或右键单击文件夹执行 [Cangjie] Coverage 命令，对选择的文件或者文件夹生成覆盖率报告，如下图所示。

在生成的覆盖率报告页面，可以单击文件名查看覆盖率详情。

仓颉编程语言工具使用指南