Fix CI & Update doc (#64)

* Fix typo * Update & improve doc * Update case3.md * Add k230d device * Fix environment.md * fix rv64 * trying fix CI * Update doc * add telemetry * Change wording * remove TODO * Add tip
ruyisdk · Dec 26, 2024 · 88e3c6e · 88e3c6e
1 parent 5d10c68
commit 88e3c6e
Show file tree

Hide file tree

Showing 11 changed files with 230 additions and 78 deletions.
diff --git a/.github/workflows/gh-page.yaml b/.github/workflows/gh-page.yaml
@@ -14,6 +14,10 @@ jobs:
       - name: Prepare bun
         uses: oven-sh/setup-bun@v1
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11' 
+
       - name: Install deps
         run: |
           cd docs && bun install

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -29,8 +29,8 @@ export default defineConfig({
                 items:[
                   {text:'功能介绍',link:'/zh/Package-Manager/index'},
                   {text:'安装',link:'/zh/Package-Manager/installation'},
-                  {text:'环境',link:'/zh/Package-Manager/Enviroment'},
-                  {text:'编译',link:'/zh/Package-Manager/Complie'},
+                  {text:'环境',link:'/zh/Package-Manager/Environment'},
+                  {text:'编译',link:'/zh/Package-Manager/Compile'},
                 ],
               },
               {
@@ -59,7 +59,8 @@ export default defineConfig({
           {
             text:'其他说明',
             items:[
-              {text:'RuyiSDK 编译工具',link:'/zh/Other/GNU-type'}
+              {text:'RuyiSDK 编译工具',link:'/zh/Other/GNU-type'},
+              {text:'RuyiSDK 遥测',link:'/zh/Other/Telemetry'},
             ]
           },
           ],

diff --git a/docs/zh/Other/GNU-type.md b/docs/zh/Other/GNU-type.md
@@ -8,20 +8,21 @@ RuyiSDK 提供了多种类型的编译工具链，适用于不同的 RISC-V 开
 | -------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | **GNU 工具链**                |                                        | [仓库](https://github.com/RuyiSDK/riscv-gnu-toolchain)                                                                          |
 | gnu-upstream               | 标准 GNU 工具链                             |                                                                                                                               |
-| gnu-plct                   | 支持香山南湖微架构 'gnu-plct(==0.20240324.0)'   |                                                                                                                               |
+| gnu-plct                   | 支持香山南湖微架构 'gnu-plct(>=0.20240324.0)'   |                                                                                                                               |
 | gnu-plct-xthead            | 适用于玄铁                                  |                                                                                                                               |
 | gnu-plct-rv64ilp32-elf     | 非通用工具链，支持 rv64ilp32 的裸机工具链，目标代码格式是 elf | [仓库](https://github.com/RuyiSDK/riscv-gnu-toolchain-rv64ilp32)<br>[文章](https://mp.weixin.qq.com/s/argIGP4_rUKDm9IRIB-YTg) |
-| **LLVM 工具链**               |                                        |                                                                                                                               |
+| gnu-milkv-milkv-duo-bin    | milkv 相关工具链，此为 glibc，还有 elf 和 musl 两个分支 |                                                                                                                               |
+ **LLVM 工具链**               |                                        |                                                                                                                               |
 | llvm-upstream              |                                        |                                                                                                                               |
 | **QEMU 模拟器**               |                                        | [仓库](https://github.com/ruyisdk/qemu)                                                                                         |
 | qemu-system-riscv-upstream |                                        |                                                                                                                               |
 | qemu-user-riscv-upstream   |                                        |                                                                                                                               |
 | qemu-user-riscv-xthead     |                                        |                                                                                                                               |
-
+| box64-upstream             |                                        |                                                                                                                               |
 
 ### 编译工具链的多样性
 
-如上表， 目前 RuyiSDK 编译工具链由于能够实现不同扩展指令集，进而有了不同版本的情况，这也就使得编译工具链具有多样性。
+如上表，目前 RuyiSDK 编译工具链由于能够实现不同扩展指令集，进而有了不同版本的情况，这也就使得编译工具链具有多样性。
 原因有以下几点：
 
 1. **处理器架构发展**：处理器架构在不断更新迭代的过程中会引进新的指令集扩展以满足不同的需求，为使得这部分新的指令集扩展能够充分运用，编译工具链也会随之进行更新，出现不同的版本。

diff --git a/docs/zh/Other/Telemetry.md b/docs/zh/Other/Telemetry.md
@@ -0,0 +1,32 @@
+# 遥测数据收集
+
+ruyi 包管理器通过遥测数据收集功能，收集用户在使用 ruyi 包管理器时的一些操作数据，以便于我们更好地了解用户的使用情况，从而更好地改进 ruyi 包管理器。
+你可以通过设置 `RUYI_TELEMETRY_OPTOUT` 环境变量来选择是否启用遥测数据收集功能。`1`，`true` 或 `yes` 表示代表关闭遥测，这与下文说的`off`是相同的；默认情况下，遥测数据收集功能是启用的。
+
+有三种遥测数据收集级别：
+
+- `local`: 仅在本地保存遥测数据，不会在没有用户明确同意的情况下发送到远程服务器。
+- `on`: 会将遥测数据发送到远程服务器。
+- `off`: 关闭遥测数据收集功能。
+
+默认情况下，遥测数据收集级别是 `on`，意味着每一次 `ruyi` 调用都会记录一些非敏感的操作数据和 `ruyi` 的一些状态信息，并每周发送至由`RuyiSDK`管理的在中国大陆的远程服务器。上传会发生在随机的一天，由匿名安装 ID 决定。
+
+你可以编辑 `ruyi` 的配置文件，或者通过简单的通过环境变量来设置遥测数据收集级别。
+
+我们会收集这些数据：
+
+* 所运行的机器的基本信息:
+    * 架构和 OS
+    * 如果架构为 RISC-V:
+        * ISA 能力
+        * 开发板的型号
+        * 逻辑 CPU 数量
+    * OS release ID (大约相当与发行版类型)
+    * libc 的类型和版本
+    * shell 的类型 (bash, fish, zsh, etc.)
+* 在上传数据时 `ruyi` 的版本
+* `ruyi` 子命令的不同调用模式:
+    * 不会暴露任何参数
+    * 调用时间的粒度为 1 分钟
+
+你可以在 RuyiSDK 官网查看我们的隐私政策。
diff --git a/docs/zh/Package-Manager/Complie.md → docs/zh/Package-Manager/Compile.md b/docs/zh/Package-Manager/Complie.md → docs/zh/Package-Manager/Compile.md
@@ -18,7 +18,6 @@
 
 ```bash
 # 从软件源下载并解压指定的源码包
-
 ruyi extract
 
 ```
@@ -31,16 +30,12 @@ ruyi extract
 ```bash
 # 开始编译
 # 为隔离化编译创建虚拟环境，使用 ruyi venv -h 查看如何使用
-
 ruyi venv
 
 # 举例：创建一个叫 venv1 的虚拟环境，并指定编译工具链为 gnu-upstream，sysroot 为 generic 类型，使用 qemu-user-riscv-upstream 模拟器
-
-ruyi venv -t gnu-upstream -e qemu-user-riscv-upstream   generic  venv1
-
+ruyi venv -t gnu-upstream -e qemu-user-riscv-upstream generic venv1
 
 # 激活虚拟环境
-
 .  venv1/bin/ruyi-activate  
 
 # 编译需要编译的程序源代码
@@ -52,7 +47,7 @@ sed -i 's/\bgcc\b/riscv64-unknown-linux-gnu-gcc/g'  linux64/core_portme.mak
 #（2）执行交叉编译和构建，得到可执行程序 coremark.exe
 make PORT_DIR=linux64 link
 
-#（3）查看 rv64 可执行程序文件属性信息，初步检验可执行程序是否 RISC-V 架构
+#（3）查看 riscv64 可执行程序文件属性信息，初步检验可执行程序是否 RISC-V 架构
 file coremark.exe
 ```
 
@@ -63,8 +58,8 @@ file coremark.exe
 为确保 RISC-V 目标可执行程序的正确性，通过模拟器工具（如 qemu）模拟运行环境：
 
 ```bash
-#  qemu user 模式下执行 rv64 coremark 可执行程序
-ruyi-qemu   coremark.exe
+#  qemu user 模式下执行 riscv64 coremark 可执行程序
+ruyi-qemu coremark.exe
 
 # 在编译和运行结束后，退出虚拟环境
 ruyi-deactivate

diff --git a/docs/zh/Package-Manager/Enviroment.md → docs/zh/Package-Manager/Environment.md b/docs/zh/Package-Manager/Enviroment.md → docs/zh/Package-Manager/Environment.md
@@ -1,17 +1,20 @@
 # ruyi 编译环境
 
-与 python 的虚拟环境类似，ruyi 包管理器工具使用 `venv` 命令应用配置到指定的工具链以建立编译环境。
+与 Python 的虚拟环境类似，ruyi 包管理器工具使用 `venv` 命令应用配置到指定的工具链以建立编译环境。
 
 ruyi 包管理预置的配置可以使用 `ruyi list profiles` 命令查看：
 
 ```bash
 $ ruyi list profiles
 generic
 baremetal-rv64ilp32 (needs flavor(s): {'rv64ilp32'})
+xiangshan-nanhu
 sipeed-lpi4a (needs flavor(s): {'xthead'})
 milkv-duo
 ```
 
+可以看到有一些需要特定的 flavor，这可以在 `ruyi list --verbose` 中查看包是否提供了这种特性
+
 ## 工具链与预置配置组合
 
 ruyi 包管理在建立编译环境之前会检查该环境是否合法，但是并不保证建立成功的环境一定可用于构建。
@@ -35,8 +38,7 @@ ruyiSDK 包管理器工具可使用 `ruyi venv` 创建虚拟环境，具体的
 
 ```bash
 $ ruyi venv -h
-usage: ruyi venv [-h] [--name NAME] [--toolchain TOOLCHAIN] [--emulator EMULATOR] [--with-sysroot] [--without-sysroot]
-                 [--sysroot-from SYSROOT_FROM]
+usage: ruyi venv [-h] [--name NAME] [--toolchain TOOLCHAIN] [--emulator EMULATOR] [--with-sysroot] [--without-sysroot] [--sysroot-from SYSROOT_FROM]
                  profile dest
 
 positional arguments:
@@ -47,7 +49,7 @@ options:
   -h, --help            show this help message and exit
   --name NAME, -n NAME  Override the venv's name
   --toolchain TOOLCHAIN, -t TOOLCHAIN
-                        Specifier (atom) of the toolchain package to use
+                        Specifier(s) (atoms) of the toolchain package(s) to use
   --emulator EMULATOR, -e EMULATOR
                         Specifier (atom) of the emulator package to use
   --with-sysroot        Provision a fresh sysroot inside the new virtual environment (default)
@@ -69,17 +71,20 @@ $ ruyi venv -t gnu-plct milkv-duo ./milkv-venv
 # 使用 PLCT 工具链配置香山南湖编译环境：
 $ ruyi venv -t gnu-plct xiangshan-nanhu ./nanhu-venv
 
-# 使用 LLVM 上游工具链配置 RISC-V 编译环境：
-$ ruyi venv -t llvm-upstream --sysroot-from gnu-upstream generic ./llvm-venv
+# llvm 通常需要 gcc 的 lib：
+$ ruyi venv -t llvm-upstream --sysroot-from gnu-plct generic ./llvm-venv
 
 # 使用平头哥工具链配置荔枝派 4A 编译环境：
-$ ruyi venv -t gnu-plct-xthead-20231212 sipeed-lpi4a ./sipeed-venv
+$ ruyi venv -t "gnu-plct-xthead(==0.20231212.0)" sipeed-lpi4a ./sipeed-venv
 
 # 使用上游 QEMU 模拟器运行交叉编译的 RISC-V 二进制
 $ ruyi venv -t gnu-plct generic -e qemu-user-riscv-upstream ./qemu-venv
 
 # 使用平头哥 QEMU 模拟器运行交叉编译的 RISC-V 二进制
 $ ruyi venv -t gnu-plct-xthead sipeed-lpi4a -e qemu-user-riscv-xthead ./xthead-qemu-venv
+
+# 多工具链示例，当然也可以配合其他参数指定 sysroot 或者模拟器
+$ ruyi venv -t llvm-upstream -t gnu-plct generic ./venv
 ```
 
 ## 在虚拟环境下编译
@@ -99,8 +104,7 @@ $ ruyi install gnu-upstream
 ```bash
 $ ruyi venv -t gnu-upstream generic venv
 
-# -t gnu-upstream 指定了编译工具链的类型和版本(版本除非指定，默认最新)；generic 表示 generic 类型的 profile；venv是自定义的虚拟环境名(相对路径目录名)
-
+# -t gnu-upstream 指定了编译工具链的类型和版本（版本除非指定，默认最新）；generic 表示 generic 类型的 profile；venv 是自定义的虚拟环境名（相对路径目录名）
 ```
 
 4. 查看可用的工具链二进制
@@ -120,7 +124,7 @@ riscv64-unknown-linux-gnu-g++        riscv64-unknown-linux-gnu-gdb-add-index  ri
 
 除了 `ruyi-activate` 为激活编译环境用的脚本，其他均为工具链二进制。
 
-5. 激活构建环境，激活方式与 python 虚拟环境类似，并且改变提示符以提示当前进入编译环境中：
+5. 激活构建环境，激活方式与 Python 虚拟环境类似，并且改变提示符以提示当前进入编译环境中：
 
 ```bash
 $ . venv/bin/ruyi-activate