Merge pull request #22 from weilinfox/main

Update RUYI doc and fix sidebar

docs/.vitepress/config.mts

@@ -5,7 +5,33 @@ const sidebarItems = [
   {
     text: '工具',
     items: [
-      { text: 'Ruyi 包管理器', link: '/ruyi-package/index' }
+      { text: 'RUYI 包管理器',
+        items: [
+          { text: '介绍', link: '/ruyi/index' },
+          { text: '开始', link: '/ruyi/getstarted/index' },
+          {
+            text: '编译环境',
+            link: '/ruyi/environments/index',
+            collapsed: true,
+            items: [
+              { text: '使用 GNU 上游工具链配置 RISC-V 编译环境', link: '/ruyi/environments/gnu-generic/index' },
+              { text: '使用 LLVM 上游工具链配置 RISC-V 编译环境', link: '/ruyi/environments/llvm-generic/index' },
+              { text: '使用 PLCT 工具链配置 Milkv-Duo 编译环境', link: '/ruyi/environments/plct-milkv-duo/index' },
+              { text: '使用平头哥工具链配置荔枝派 4A 编译环境', link: '/ruyi/environments/xthead-sipeed-lpi4a/index' },
+            ]
+          },
+          {
+            text: '具有 QEMU 支持的编译环境',
+            collapsed: true,
+            items: [
+              { text: '使用上游 QEMU 模拟器运行交叉编译的 RISC-V 二进制', link: '/ruyi/virtual_machines/qemu-upstream/index' },
+              { text: '使用平头哥 QEMU 模拟器运行交叉编译的 RISC-V 二进制', link: '/ruyi/virtual_machines/qemu-xthead/index' },
+            ]
+          },
+          { text: '源码包构建', link: '/ruyi/sources/coremark/index' },
+          { text: '用户软件源搭建', link: '/ruyi/mirrors/index' },
+        ]
+      }
     ]
   },
   {
@@ -38,12 +64,6 @@ const sidebarItems = [
     link: '/plan/index',
     items: [
     ]
-  },
-  {
-    text: 'Benchmarks',
-    items: [
-      { text: 'Coremark', link: '/benchmark/coremark' }
-    ]
   }
 ]
 

docs/zh/introduction/index.md

@@ -14,8 +14,8 @@ RUYISDK 是一个旨在提供给一个一体化集成开发环境的产品计划
 
 ## RuyiSDK 包含的内容
 
-### RuyiSDK 包管理器
+### RUYI 包管理器
 
 [GitHub 项目](https://github.com/ruyisdk/ruyi)。
 
-[文档](../ruyi-package/index.md)
+[文档](../ruyi/index.md)

docs/zh/ruyi/environments/index.md

@@ -0,0 +1,27 @@
+# RUYI 编译环境
+
+RUYI 包管理器使用 ``venv`` 命令应用配置到指定的工具链以建立编译环境。这和 python 的虚拟环境类似。
+
+RUYI 包管理预置的配置可以使用 ``list profiles`` 命令查看
+
+```bash
+$ ruyi list profiles
+generic
+sipeed-lpi4a (needs flavor(s): {'xthead'})
+milkv-duo
+```
+
+## 工具链与预置配置组合
+
+RUYI 包管理在建立编译环境之前会检查该环境是否合法，但是并不保证建立成功的环境一定可用于构建。
+
+这里列出了经过测试可用的配置组合：
+
+| 工具链 | sysroot | 预置配置 |
+|:-:|:-:|:-:|
+| gnu-upstream | 自带 | generic |
+| gnu-plct | 自带 | generic |
+| gnu-plct | 自带 | milkv-duo |
+| gnu-plct-xthead | 自带 | sipeed-lpi4a |
+| llvm-upstream | gnu-upstream | generic |
+| llvm-upstream | gnu-plct | generic |

docs/zh/environment/llvm-generic/index.md → docs/zh/ruyi/environments/llvm-generic/index.md

@@ -109,3 +109,4 @@ InstalledDir: /home/myon/.local/share/ruyi/binaries/x86_64/llvm-upstream-17.0.5-
 $
 ```
 
+注意：由于 ``clang-cl`` 设计本意是兼容 MSVC ，故在 RUYI 编译环境中，尽管该命令存在，实际上并不被支持。

docs/zh/environment/xthead-sipeed-lpi4a/index.md → docs/zh/ruyi/environments/xthead-sipeed-lpi4a/index.md

@@ -128,3 +128,4 @@ a.out: ELF 64-bit LSB executable, UCB RISC-V, RVC, double-float ABI, version 1 (
 $
 ```
 
+注意： 该编译环境构建的二进制，当前并不能在 RevyOS 运行，参见 issue [xthead 工具链构建产物无法在 RevyOS 运行](https://github.com/ruyisdk/ruyi/issues/22)

docs/zh/ruyi-package/index.md → docs/zh/ruyi/getstarted/index.md

@@ -1,41 +1,6 @@
-# Ruyi 包管理器
-
-RUYI 包管理是 RuyiSDK 开发中的包管理器。用于管理工具链、模拟器、源码等各种二进制软件包和源码包。
-
-## 支持的发行版平台
-
-当前 RUYI 包管理器 v0.2 版本在以下平台进行了测试
-
-+ x86-64 Fedora 38
-+ x86-64 Ubuntu 22.04 LTS
-+ x86-64 openEuler 23.09
-+ riscv64 RevyOS 20231026
-+ riscv64 openEuler 23.09
-
-## 命令
-
-RUYI 目前支持的命令如下：
-
-``` bash
-ruyi list
-# 从本地软件包缓存中列出可用软件包
-ruyi list profiles
-# 列出已安装的配置
-ruyi update
-# 从配置的软件源更新本地软件包缓存
-ruyi install
-# 下载并安装指定的软件包
-ruyi venv
-# 由指定的工具链和配置建立 RUYI 虚拟环境
-ruyi extract
-# 下载并解包指定的源码包
-ruyi admin
-# ruyi 镜像搭建工具（完善中）
-ruyi self uninstall
-# 卸载 RUYI 包管理器
-```
+# 开始
 
-## 依赖软件
+## 安装依赖软件
 
 RUYI 包管理器依赖一些外部工具，需要手动安装
 
@@ -55,16 +20,16 @@ $ sudo apt-get install wget git tar bzip2 xz zstd
 
 从发布[镜像](https://mirror.iscas.ac.cn/ruyisdk/ruyi/testing/)中选择合适架构的预编译二进制下载，当前 RUYI 包管理支持 amd64 和 riscv64 架构编译环境。
 
-v0.2 版本的稳定二进制为 20231204 版本。
+v0.2 版本的稳定二进制为 0.2.0-beta.20231207 版本。
 
 这里以 amd64 架构环境为例进行安装：
 
 ```bash
-$ wget https://mirror.iscas.ac.cn/ruyisdk/ruyi/testing/ruyi.amd64.20231204
-$ chmod +x ./ruyi.amd64.20231204
-$ sudo cp ruyi.amd64.20231204 /usr/local/bin/ruyi
+$ wget https://mirror.iscas.ac.cn/ruyisdk/ruyi/testing/ruyi.amd64.20231207
+$ chmod +x ./ruyi.amd64.20231207
+$ sudo cp ruyi.amd64.20231207 /usr/local/bin/ruyi
 $ ruyi version
-Ruyi 0.2.0-beta.20231204
+Ruyi 0.2.0-beta.20231207
 Copyright (C) 2023 Institute of Software, Chinese Academy of Sciences (ISCAS).
 All rights reserved.
 License: Apache-2.0 <https://www.apache.org/licenses/LICENSE-2.0>
@@ -78,7 +43,7 @@ License: Apache-2.0 <https://www.apache.org/licenses/LICENSE-2.0>
 $ ruyi --help
 usage: ruyi [-h] [-V] {extract,install,i,list,update,venv,admin,self,version} ...
 
-RuyiSDK Package Manager 0.2.0-beta.20231204
+RuyiSDK Package Manager 0.2.0-beta.20231207
 
 options:
   -h, --help            show this help message and exit
@@ -142,16 +107,48 @@ List of available packages:
 $ ruyi list -v
 ```
 
-列出已知编译环境配置：
+### 安装软件包
+
+使用 ``install`` 命令安装软件包，如 GNU 上游工具链：
+
+```bash
+$ ruyi install gnu-upstream
+```
+
+若希望重装一个软件包，则可以加上 ``--reinstall`` 参数：
+
+```bash
+$ ruyi install --reinstall gnu-upstream
+```
+
+### 安装源码包
+
+RUYI 包管理器同时管理一些源码包，使用 ``extract`` 命令下载一个源码包并解包到当前目录：
 
 ```bash
-$ ruyi list profiles
-generic
-sipeed-lpi4a (needs flavor(s): {'xthead'})
-milkv-duo
+$ ruyi extract ruyisdk-demo
+$ ls
+README.md  rvv-autovec
 ```
 
-这些预置的配置可以用于编译环境的搭建。
+### 搭建编译环境
+
+已经安装的工具链与模拟器需要在 RUYI 编译环境中使用，这和 python 的虚拟环境十分类似。
+这是由 ``venv`` 命令实现的：
+
+```bash
+$ ruyi venv --toolchain gnu-upstream --emulator qemu-user-riscv-upstream generic ./ruyi_venv
+```
+
+这个命令使用预置的 generic 配置，在 ``./ruyi_venv`` 目录建立包含 gnu-upstream 工具链和
+ qemu-user-riscv-upstream 模拟器的编译环境。
+
+具体使用参见“编译环境”与“具有 QEMU 支持的编译环境”章节。
+
+### 卸载软件包
+
+注意 RUYI 包管理器没有实现卸载 RUYI 软件包的功能。若您强制中断 RUYI 软件包安装进程或做了其他非预期操作
+而会导致软件包功能异常时，请使用 ``install --reinstall`` 以尝试重试安装该软件包。
 
 ### 卸载 RUYI 包管理器
 
@@ -184,9 +181,3 @@ $ ruyi self uninstall --purge -y
 实现 RUYI 包管理自身的升级可能会需要超级用户权限，而 RUYI 包管理被设计为避免进行需要超级用户权限的操作。
 故在需要升级 RUYI 包管理时您需要手动进行该操作，即首先卸载 RUYI 包管理器，再执行安装 RUYI 包管理器的过程，
 这个过程中您可以自主选择是否保留旧的软件包缓存和 RUYI 软件包。
-
-注意 RUYI 包管理器也没有实现卸载 RUYI 软件包的功能。这在您强制中断 RUYI 软件包安装进程或做了其他非预期操作时
-可能会导致软件包无法重新安装。此时您可以尝试删除 ``~/.local/share/ruyi/binaries/`` 或
- ``${XDG_DATA_HOME}/ruyi/binaries/`` 下对应的 RUYI 软件包安装目录后再重试安装。手动执行删除软件包操作时，
-务必提前确认您的操作会得到预期效果。
-

docs/zh/ruyi/index.md

@@ -0,0 +1,43 @@
+# RUYI 包管理器
+
+RUYI 包管理是 RuyiSDK 开发中的包管理器。用于管理工具链、模拟器、源码等各种二进制软件包和源码包。
+
+## 支持的发行版平台
+
+当前 RUYI 包管理器 v0.2 版本在以下平台进行了测试
+
++ x86-64 Fedora 38
++ x86-64 Ubuntu 22.04 LTS
++ x86-64 openEuler 23.09
++ riscv64 RevyOS 20231026
++ riscv64 openEuler 23.09
+
+## 命令
+
+RUYI 目前支持的命令如下：
+
+``` bash
+ruyi list
+# 从本地软件包缓存中列出可用软件包
+ruyi list profiles
+# 列出已安装的配置
+ruyi update
+# 从配置的软件源更新本地软件包缓存
+ruyi install
+# 下载并安装指定的软件包
+ruyi venv
+# 由指定的工具链和配置建立 RUYI 虚拟环境
+ruyi extract
+# 下载并解包指定的源码包
+ruyi admin
+# ruyi 镜像搭建工具（完善中）
+ruyi self uninstall
+# 卸载 RUYI 包管理器
+```
+
+## 外部链接
+
++ [Fedora38 Workstation](https://download.fedoraproject.org/pub/fedora/linux/releases/38/Workstation/x86_64/iso/)
++ [RevyOS 20231026](https://mirror.iscas.ac.cn/revyos/extra/images/lpi4a/20231026/)
++ [Ubuntu 22.04 LTS](https://www.releases.ubuntu.com/jammy/)
++ [openEuler 23.09 Images](https://repo.openeuler.openatom.cn/openEuler-23.09/ISO/)