Cangjie/cangjie-stdx-bin 使用指南

本文详细介绍了如何下载、安装、配置和使用仓颉编程语言的核心模块 stdx，包括动态库与静态库的选择、多平台配置、常见问题解决方案以及模块功能的调用示例。

下载与安装 stdx 模块

stdx 是仓颉编程语言的核心模块之一，提供了丰富的网络、安全、日志等功能。本文将详细介绍如何下载和安装 stdx 模块，确保您能够快速集成并使用其功能。

下载 stdx 模块

1. 访问下载页面
   打开 stdx 项目的发行版页面，找到与您的操作系统和架构匹配的软件包。例如：

   • cangjie-stdx-linux-x64-x.x.x.x.zip（Linux x64）
   • cangjie-stdx-windows-x64-x.x.x.x.zip（Windows x64）
   • cangjie-stdx-mac-aarch64-x.x.x.x.zip（MacOS ARM64）

2. 下载并解压
   将软件包下载到本地目录（如 /opt/cangjie-stdx），然后解压：

   unzip cangjie-stdx-linux-x64-x.x.x.x.zip -d /opt/cangjie-stdx
   

3. 验证文件结构
   解压后，您会看到以下目录结构：

   flowchart LR
       A[解压目录] --> B[linux_x86_64_llvm]
       B --> C[dynamic]
       B --> D[static]
       C --> E[stdx]
       D --> F[stdx]
   

   • dynamic：动态链接库文件。
   • static：静态链接库文件。

安装 stdx 模块

1. 配置 cjpm.toml 文件
   在您的仓颉项目根目录下，编辑 cjpm.toml 文件，添加 stdx 的路径配置。以下是一个示例配置：

   [target.x86_64-unknown-linux-gnu]
     [target.x86_64-unknown-linux-gnu.bin-dependencies]
       path-option = ["/opt/cangjie-stdx/linux_x86_64_llvm/dynamic/stdx"]
   

   • x86_64-unknown-linux-gnu：根据您的操作系统和架构修改。
   • path-option：指向 stdx 的实际路径。

2. 特殊配置（可选）
   如果您使用的是静态链接库，需要在 compile-option 中添加额外的系统符号依赖：

   • Linux：添加 -ldl
   • Windows：添加 -lcrypt32

   [target.x86_64-unknown-linux-gnu]
     compile-option = "-ldl"
     [target.x86_64-unknown-linux-gnu.bin-dependencies]
       path-option = ["/opt/cangjie-stdx/linux_x86_64_llvm/static/stdx"]
   

验证安装

1. 编写测试代码
   创建一个简单的仓颉文件（如 main.cj），导入并使用 stdx 的功能：

   package main
   
   import stdx.log.*
   
   main () {
       log.info("stdx 模块安装成功！")
   }
   

2. 编译并运行
   使用 cjpm 编译并运行项目：

   cjpm build && cjpm run
   

   如果输出日志信息，则表示 stdx 模块安装成功。

常见问题

问题	解决方案
下载速度慢	使用镜像站点或下载加速工具
解压失败	确保下载的软件包完整，重新下载
路径配置错误	检查 cjpm.toml 中的路径是否与实际解压路径一致
编译报错	确认 compile-option 中是否添加了必要的系统符号依赖

通过以上步骤，您已成功下载并安装了 stdx 模块，可以开始使用其丰富的功能了！

配置 cjpm.toml 文件

仓颉编程语言的包管理工具 CJPM 通过 cjpm.toml 文件来管理项目的依赖和配置。正确配置 cjpm.toml 文件是使用 stdx 模块的关键步骤之一。本节将详细介绍如何配置 cjpm.toml 文件以引入 stdx 模块，并提供不同环境下的配置示例。

1. 基本配置结构

cjpm.toml 文件采用 TOML 格式，主要包含以下几个部分：

• [package]：定义项目的基本信息，如名称、版本、编译选项等。
• [dependencies]：定义项目的依赖项。
• [target]：针对不同目标平台（如 Windows、Linux、MacOS）的配置。

以下是一个基本的 cjpm.toml 文件结构：

[package]
name = "my_project"
version = "1.0.0"
cjc-version = "0.60.5"
output-type = "executable"

[dependencies]

[target.x86_64-w64-mingw32]
  [target.x86_64-w64-mingw32.bin-dependencies]
    path-option = ["path_to_stdx"]

2. 配置 stdx 路径

stdx 模块的路径需要通过 path-option 指定。路径可以是绝对路径或相对路径，具体取决于 stdx 的存放位置。以下是一个示例：

[target.x86_64-w64-mingw32]
  [target.x86_64-w64-mingw32.bin-dependencies]
    path-option = ["D:\\cangjiestdx\\windows_x86_64_llvm\\stdx\\dynamic\\stdx"]

动态库与静态库的区别

• 动态库：路径指向 dynamic/stdx 目录。
• 静态库：路径指向 static/stdx 目录，且需要在 compile-option 中添加额外的链接选项（如 Windows 下的 -lcrypt32 或 Linux 下的 -ldl）。

3. 多平台配置

如果项目需要在多个平台上运行，可以为每个平台单独配置 target 部分。例如：

[target.x86_64-w64-mingw32]
  [target.x86_64-w64-mingw32.bin-dependencies]
    path-option = ["D:\\cangjiestdx\\windows_x86_64_llvm\\stdx\\dynamic\\stdx"]

[target.x86_64-unknown-linux-gnu]
  [target.x86_64-unknown-linux-gnu.bin-dependencies]
    path-option = ["/usr/local/cangjiestdx/linux_x86_64_llvm/static/stdx"]
    compile-option = "-ldl"

4. 配置示例

以下是一个完整的 cjpm.toml 配置示例，适用于 Windows 平台：

[package]
name = "my_project"
version = "1.0.0"
cjc-version = "0.60.5"
output-type = "executable"

[dependencies]

[target.x86_64-w64-mingw32]
  [target.x86_64-w64-mingw32.bin-dependencies]
    path-option = ["D:\\cangjiestdx\\windows_x86_64_llvm\\stdx\\dynamic\\stdx"]

5. 注意事项

• 路径格式：Windows 路径使用双反斜杠 \\，Linux 和 MacOS 使用正斜杠 /。
• 空格和特殊字符：路径中避免使用空格和特殊字符（如 .），否则可能导致配置失败。
• 版本兼容性：确保 cjc-version 与 stdx 的版本兼容。

通过以上配置，项目即可成功引入 stdx 模块，并利用其提供的丰富功能。

导入与调用 stdx 模块

stdx 是仓颉编程语言中一个功能强大的模块，提供了网络、安全、日志等多种通用能力。本文将详细介绍如何导入和调用 stdx 模块，帮助开发者快速上手并高效使用其功能。

1. 导入 stdx 模块

在仓颉项目中，导入 stdx 模块需要在 cjpm.toml 配置文件中进行相关设置。以下是具体步骤：

1.1 配置 cjpm.toml 文件

在项目的 cjpm.toml 文件中，添加 stdx 的路径配置。以下是一个示例配置：

[target.x86_64-w64-mingw32]
  [target.x86_64-w64-mingw32.bin-dependencies]
    path-option = ["D:\\cangjiestdx\\windows_x86_64_llvm\\stdx\\dynamic\\stdx"]

• target.x86_64-w64-mingw32：表示目标系统的架构和操作系统信息。可以通过运行 cjc -v 命令获取。
• path-option：指定 stdx 模块的路径。路径可以是动态库或静态库的路径，根据实际需求选择。

1.2 动态库与静态库的选择

stdx 提供了动态库和静态库两种形式，开发者可以根据项目需求选择：

• 动态库：适用于运行时动态加载的场景，路径通常为 .../dynamic/stdx。
• 静态库：适用于编译时链接的场景，路径通常为 .../static/stdx。

1.3 特殊配置

在某些情况下，可能需要额外的编译选项。例如：

• 在 Windows 系统中使用 crypto 或 net 包时，需添加 -lcrypt32。
• 在 Linux 系统中使用 crypto 或 net 包时，需添加 -ldl。

[target.x86_64-unknown-linux-gnu]
  compile-option = "-ldl"
  [target.x86_64-unknown-linux-gnu.bin-dependencies]
    path-option = ["/path/to/stdx/static"]

2. 调用 stdx 模块

在代码中，可以通过 import 语句导入 stdx 模块中的具体包或功能。以下是几种常见的导入方式：

2.1 导入单个功能

import stdx.net.http.ServerBuilder

2.2 导入整个包

import stdx.net.http.*

2.3 使用示例

以下是一个使用 stdx.net.http 包创建 HTTP 服务的示例代码：

package test

import stdx.net.http.ServerBuilder

main () {
    let server = ServerBuilder()
                        .addr("127.0.0.1")
                        .port(8080)
                        .build()
    server.distributor.register("/index", {httpContext =>
        httpContext.responseBuilder.body("Hello 仓颉!")
    })
    server.serve()
}

3. 常见问题与解决方案

3.1 路径配置错误

如果 path-option 配置的路径不正确，编译时会提示找不到 stdx 模块。请确保路径与实际解压的 stdx 路径一致。

3.2 版本兼容性

确保 stdx 的版本与仓颉 SDK 的版本兼容。可以通过 cjc -v 查看当前 SDK 版本，并下载对应的 stdx 版本。

3.3 动态库加载失败

在 Linux 或 macOS 系统中，如果动态库加载失败，可以尝试以下命令：

export LD_LIBRARY_PATH=/path/to/stdx/dynamic:$LD_LIBRARY_PATH

4. 总结

通过合理配置 cjpm.toml 文件并正确导入 stdx 模块，开发者可以轻松调用其提供的丰富功能。无论是网络通信、安全加密，还是日志记录，stdx 都能为仓颉项目提供强大的支持。

常见问题与解决方案

在使用 Cangjie/cangjie-stdx-bin 的过程中，开发者可能会遇到一些常见问题。以下是一些典型问题及其解决方案，帮助您快速定位和解决问题。

1. stdx 导入失败

问题描述：
在 cjpm.toml 中配置了 stdx 路径后，编译时仍提示找不到 stdx 模块。

可能原因：

1. 路径配置错误。
2. 动态库或静态库未正确解压或放置。
3. 操作系统架构与 stdx 版本不匹配。

解决方案：

1. 检查 path-option 配置的路径是否正确，确保路径中不包含空格或特殊字符。
2. 确认 stdx 二进制文件已解压到指定目录，并检查目录结构是否完整。
3. 运行 cjc -v 确认当前系统的架构信息，并下载匹配的 stdx 版本。

示例：

[target.x86_64-w64-mingw32]
  [target.x86_64-w64-mingw32.bin-dependencies]
    path-option = ["D:\\cangjiestdx\\windows_x86_64_llvm\\stdx\\dynamic\\stdx"]

---

2. MacOS 下 stdx 无法运行

问题描述：
在 MacOS 中解压 stdx 后，运行时提示“无法验证开发者”或“文件已损坏”。

解决方案：

1. 在终端中执行以下命令，移除文件的隔离属性：

   xattr -dr com.apple.quarantine <stdx解压路径>
   

2. 如果问题仍未解决，尝试在“系统偏好设置”->“安全性与隐私”中手动允许运行。

---

3. 编译时缺少依赖符号

问题描述：
使用 crypto 或 net 包时，编译失败并提示缺少符号（如 -lcrypt32 或 -ldl）。

解决方案：

1. 在 cjpm.toml 的 compile-option 中添加对应的链接选项：
   • Windows: -lcrypt32
   • Linux: -ldl

示例：

[package]
  compile-option = "-ldl"

---

4. DevEco Studio 中 stdx 路径配置问题

问题描述：
在 DevEco Studio 中配置 stdx 路径后，真机或模拟器环境无法识别。

解决方案：

1. 根据实际编译环境修改 cjpm.toml 中的 target 配置：
   • 真机：target.aarch64-linux-ohos
   • 模拟器：target.x86_64-linux-ohos
2. 确保路径指向正确的 stdx 动态库或静态库。

示例：

[target.aarch64-linux-ohos]
  [target.aarch64-linux-ohos.bin-dependencies]
    path-option = ["D:\\cangjiestdx\\linux_ohos_aarch64_llvm\\dynamic\\stdx"]

---

5. net.http 服务无法启动

问题描述：
使用 net.http 包创建 HTTP 服务时，服务启动失败或无法访问。

可能原因：

1. 端口被占用。
2. 地址配置错误。
3. 未正确注册路由。

解决方案：

1. 检查端口是否被其他程序占用，尝试更换端口。
2. 确保地址配置为 127.0.0.1 或 0.0.0.0。
3. 确认路由注册逻辑正确。

示例：

let server = ServerBuilder()
                .addr("0.0.0.0")
                .port(8080)
                .build()
server.distributor.register("/index", {httpContext =>
    httpContext.responseBuilder.body("Hello World!")
})
server.serve()

---

6. 日志模块输出异常

问题描述：
使用 log 或 logger 包时，日志未输出或格式不符合预期。

解决方案：

1. 检查日志级别设置，确保日志级别允许输出。
2. 确认日志文件路径是否有写入权限。
3. 使用 logger 包时，检查 JSON 格式配置是否正确。

示例：

import stdx.log.*
log.setLevel(LogLevel.DEBUG)
log.debug("Debug message")

---

通过以上解决方案，您可以快速解决 Cangjie/cangjie-stdx-bin 使用中的常见问题。如果问题仍未解决，建议查阅项目文档或在社区论坛中反馈。