diff --git a/.github/workflows/gh-page.yaml b/.github/workflows/gh-page.yaml index 981ff6b6..08b8927d 100644 --- 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 index c82a9684..a032b2a7 100644 --- 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 index 54b27553..b971b3d0 100644 --- 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)
[文章](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 new file mode 100644 index 00000000..7baa1fbf --- /dev/null +++ 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 官网查看我们的隐私政策。 \ No newline at end of file diff --git a/docs/zh/Package-Manager/Complie.md b/docs/zh/Package-Manager/Compile.md similarity index 90% rename from docs/zh/Package-Manager/Complie.md rename to docs/zh/Package-Manager/Compile.md index ef896175..2c0afe15 100644 --- a/docs/zh/Package-Manager/Complie.md +++ b/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 b/docs/zh/Package-Manager/Environment.md similarity index 89% rename from docs/zh/Package-Manager/Enviroment.md rename to docs/zh/Package-Manager/Environment.md index c12ab06c..eacb88c8 100644 --- a/docs/zh/Package-Manager/Enviroment.md +++ b/docs/zh/Package-Manager/Environment.md @@ -1,6 +1,6 @@ # ruyi 编译环境 -与 python 的虚拟环境类似，ruyi 包管理器工具使用 `venv` 命令应用配置到指定的工具链以建立编译环境。 +与 Python 的虚拟环境类似，ruyi 包管理器工具使用 `venv` 命令应用配置到指定的工具链以建立编译环境。 ruyi 包管理预置的配置可以使用 `ruyi list profiles` 命令查看： @@ -8,10 +8,13 @@ ruyi 包管理预置的配置可以使用 `ruyi list profiles` 命令查看： $ 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 diff --git a/docs/zh/Package-Manager/index.md b/docs/zh/Package-Manager/index.md index f4329afe..3922fdda 100644 --- a/docs/zh/Package-Manager/index.md +++ b/docs/zh/Package-Manager/index.md @@ -23,6 +23,7 @@ ruyi 包管理器提供以下功能。 | `ruyi install --reinstall gnu-upstream` | 重新安装 GNU 上游工具链。 | | | `ruyi extract ruyisdk-demo` | 下载并解包ruyisdk-demo 源码包。 | 解包到当前目录。 | | `ruyi venv --toolchain gnu-upstream --emulator qemu-user-riscv-upstream generic ./ruyi_venv` | 在指定目录建立包含工具链和模拟器的编译环境。 | 使用预置的 generic 配置。 | +| `ruyi version` | 查看 ruyi 包管理器的版本。 | | | `ruyi self uninstall` | 卸载 ruyi 包管理器。 | 命令会询问确认操作。 | | `ruyi self uninstall -y` | 无需确认直接卸载 ruyi 包管理器。 | 无需确认直接执行。 | | `ruyi self uninstall --purge` | 彻底卸载 ruyi 包管理器，包括缓存和安装的软件包。 | 包括缓存和已安装的软件包。 | @@ -42,9 +43,13 @@ $ ruyi update 软件包缓存将存放在用户目录中，通常为 ``~/.cache/ruyi`` ；在 ``XDG_CACHE_HOME`` 环境变量被设置时，目录为 ``$XDG_CACHE_HOME/ruyi`` 。 在本文档中家目录为 ``/home/myon`` 。 -## 查询包管理器更新内容 +## 阅读 ruyi 新闻 -查看 ruyi 包管理器的更新信息、阅读新闻或将信息设置为已读： +在 `ruyi update` 时会列出未读新闻（news item(s)），从这里可以及时了解到 ruyi 出现的更新或发出的重要通知。 + +`ruyi news list` 同样可以调出这个页面，但它将显示所有新闻，其中未阅读的新闻在支持的终端上会以绿色高亮显示。 + +可以指定阅读某条新闻 `ruyi news read 1`，或者直接 `ruyi news read` 将所有新闻标记为已读。此时 ruyi 会打印相应的新闻内容。 ```bash $ ruyi news list -h @@ -59,37 +64,79 @@ $ ruyi news read --quiet # 不输出任何东西，只标记为已读 ## 查询可用软件包 +Ruyi 软件包大致分为几个分区 + +- toolchain 工具链 +- source 源码包 +- emulator 模拟器 +- board-image 系统镜像 +- analyzer 分析工具 +- extra 其他 + +软件包的版本号符合 Semver 的规范，这使它们和上游版本可能具有一些差别。 +软件包分为正式发布的软件包和预发布的软件包（prerelease），预发布的软件包释出会比上游正式发布该版本要早，但是修复了最新已发布版本的重要 bug。 +一些较早发布的软件包还引入了 slug 来标记版本，这是一个已经废弃的特性，会在未来彻底删除。 + 查看可用的软件包，该命令将列出所有可用的软件包： ```bash $ ruyi list List of available packages: -* source/ruyisdk-demo - - 0.20231114.0 (latest) +* emulator/qemu-user-riscv-upstream + - 8.2.0-ruyi.20240128 (latest) + - 8.1.2-ruyi.20231121 () +* emulator/box64-upstream + - 0.3.1-pre.ruyi.20240901+git.9178effd (prerelease, latest-prerelease, no binary for current host) + - 0.3.0-ruyi.20240718 (latest, no binary for current host) + - 0.2.9-pre.ruyi.20240702+git.4b0b3fc9 (prerelease, no binary for current host) + - 0.2.8-ruyi.20240702 (no binary for current host) +* emulator/qemu-user-riscv-xthead + - 6.1.0-ruyi.20231207+g03813c9fe8 (latest) +* emulator/qemu-system-riscv-upstream + - 8.2.0-ruyi.20240128 (latest) +* extra/wps-office + - 12.1.0-r.17900 (latest) + - 12.1.0-r.17885 () +* analyzer/dynamorio-riscv + - 10.93.19979-ruyi.20240914 (latest, no binary for current host) + - 10.0.19748-ruyi.20240128 (no binary for current host) * source/coremark - 1.0.2-pre.20230125 (prerelease, latest-prerelease) - 1.0.1 (latest) -* emulator/qemu-user-riscv-xthead - - 6.1.0-ruyi.20231207+g03813c9fe8 (latest) -* emulator/qemu-user-riscv-upstream - - 8.1.2-ruyi.20231121 (latest) -* toolchain/gnu-plct - - 0.20231212.0 (latest) slug: gnu-plct-20231212 - - 0.20231118.0 () slug: gnu-plct-20231118 -* toolchain/gnu-plct-xthead - - 0.20231212.0 (latest) slug: gnu-plct-xthead-20231212 - - 0.20231118.0 () slug: gnu-plct-xthead-20231118 +* source/milkv-duo-examples + - 0.20240719.0+git.52ae647a (latest) +* source/ruyisdk-demo + - 0.20231114.0 (latest) * toolchain/gnu-upstream - 0.20231212.0 (latest) slug: gnu-upstream-20231212 - 0.20231118.0 () slug: gnu-upstream-20231118 +* toolchain/gnu-milkv-milkv-duo-bin + - 0.20240731.0+git.67688c7335e7 (latest) +* toolchain/gnu-plct-xthead + - 2.8.0-ruyi.20240222 (latest) + - 0.20231212.0 () slug: gnu-plct-xthead-20231212 + - 0.20231118.0 () slug: gnu-plct-xthead-20231118 +* toolchain/gnu-milkv-milkv-duo-elf-bin + - 0.20240731.0+git.67688c7335e7 (latest) +* toolchain/gnu-plct + - 0.20240324.0 (latest) + - 0.20231212.0 () slug: gnu-plct-20231212 + - 0.20231118.0 () slug: gnu-plct-20231118 +* toolchain/gnu-milkv-milkv-duo-musl-bin + - 0.20240731.0+git.67688c7335e7 (latest) +* toolchain/llvm-plct + - 17.0.6-ruyi.20240511 (latest) +* toolchain/gnu-plct-rv64ilp32-elf + - 0.20240906.0-ruyi.20240906+git.df9313313b45 (latest) * toolchain/llvm-upstream - 17.0.5-ruyi.20231121 (latest) slug: llvm-upstream-20231121 ``` -软件包前缀表示分类，其中 ``source`` 代表软件源码包， ``toolchain`` 代表工具链二进制包， ``emulator`` 代表模拟器二进制包，`board-image` 代表开发板镜像，`analyzer` 代表分析工具。 -如果软件包显示 “no binary for current host” 则该软件包的当前版本不支持本机架构。 +若某个软件包版本没有提供当前架构，则会显示 no binary for current host 但是同样可以使用 --host 安装其他架构的包 +`ruyi install --host x86_64 wps-office` +如果希望 list 命令输出更详细信息，则可以使用 `--verbose` 列出所有软件包的详细信息： @@ -99,9 +146,9 @@ $ ruyi list -v ## 查询可用编译环境 -与python 的虚拟环境类似，RUYI 包管理器工具使用 ``venv`` 命令应用配置到指定的工具链以建立编译环境。 +与 Python 的虚拟环境类似，ruyi 包管理器工具使用 ``venv`` 命令应用配置到指定的工具链以建立编译环境。 -RUYI 包管理预置的配置可以使用 ``ruyi list profiles`` 命令查看： +ruyi 包管理预置的配置可以使用 ``ruyi list profiles`` 命令查看： ```bash $ ruyi list profiles @@ -113,6 +160,14 @@ milkv-duo ## 安装软件包 +通常下列分区的软件包会是二进制包 + +- toolchain 工具链 +- emulator 模拟器 +- board-image 系统镜像 +- analyzer 分析工具 +- extra 其他 + 使用 ``install`` 命令安装软件包，如 GNU 上游工具链： ```bash @@ -123,7 +178,7 @@ $ ruyi install gnu-upstream ```bash $ ruyi install 'gnu-upstream(0.20231118.0)' -$ ruyi install 'gnu-upstream(==0.20231118.0)' +$ ruyi install 'gnu-upstream(>=0.20231118.0)' # match_expr parameter should be in format ``, where `` is one of ['<', '>', '==', '<=', '>=', '!=']. ``` @@ -134,19 +189,27 @@ $ ruyi install 'gnu-upstream(==0.20231118.0)' $ ruyi install --reinstall gnu-upstream ``` +由于系统镜像也是二进制文件，也可以使用 install 命令执行下载和解包。这些包通常配合 ruyi 的镜像刷写功能使用。 + ## 安装源码包 ruyi 包管理器同时管理一些源码包，使用 ``extract`` 命令下载一个源码包并解包到当前目录： +extract 支持和 install 一样的版本号指定。 + ```bash $ ruyi extract ruyisdk-demo $ ls README.md rvv-autovec ``` +## 安装预发布的软件包 + +pre-release 可以在 config.toml 中配置。 + ## 搭建编译环境 -已经安装的工具链与模拟器需要在 ruyi 编译环境中使用，这和 python 的虚拟环境十分类似。 +已经安装的工具链与模拟器需要在 ruyi 编译环境中使用，这和 Python 的虚拟环境十分类似。 这是由 ``venv`` 命令实现的： ```bash @@ -163,21 +226,21 @@ $ ruyi venv --toolchain gnu-upstream --emulator qemu-user-riscv-upstream generic 注意 ruyi 包管理器没有实现卸载 ruyi 软件包的功能。若您强制中断 ruyi 软件包安装进程或做了其他非预期操作 而会导致软件包功能异常时，请使用 ``install --reinstall`` 以尝试重试安装该软件包。 -## 卸载 RUYI 包管理器 +## 卸载 ruyi 包管理器 -使用下面的命令卸载 Ruyi 包管理器： +使用下面的命令卸载 ruyi 包管理器： ```bash $ ruyi self uninstall ``` -这个命令将会询问您以二次确认该操作，如果希望 Ruyi 包管理不询问而直接执行： +这个命令将会询问您以二次确认该操作，如果希望 ruyi 包管理不询问而直接执行： ```bash $ ruyi self uninstall -y ``` -上面的命令只是删除 Ruyi 本身，并不会删除软件包缓存和安装的 Ruyi 软件包。 +上面的命令只是删除 ruyi 本身，并不会删除软件包缓存和安装的 ruyi 软件包。 如果希望删除所有缓存和安装了的软件包以实现干净的卸载： @@ -185,20 +248,27 @@ $ ruyi self uninstall -y $ ruyi self uninstall --purge ``` -同样的这个命令将会询问您以二次确认该操作，如果希望 Ruyi 包管理不询问而直接执行： +同样的这个命令将会询问您以二次确认该操作，如果希望 ruyi 包管理不询问而直接执行： ```bash $ ruyi self uninstall --purge -y ``` -实现 Ruyi 包管理自身的升级可能会需要 `sudo`，而 Ruyi 包管理被设计为避免进行需要超级用户权限的操作。 -故在需要升级 Ruyi 包管理时您需要手动进行该操作，即首先卸载 Ruyi 包管理器，再执行安装 Ruyi 包管理器的过程， -这个过程中您可以自主选择是否保留旧的软件包缓存和 Ruyi 软件包。 +实现 ruyi 包管理自身的升级可能会需要 `sudo`，而 ruyi 包管理被设计为避免进行需要超级用户权限的操作。 +故在需要升级 ruyi 包管理时您需要手动进行该操作，即首先卸载 ruyi 包管理器，再执行安装 ruyi 包管理器的过程， +这个过程中您可以自主选择是否保留旧的软件包缓存和 ruyi 软件包。 ## 镜像信息的维护与下载、开发板系统的安装引导 -执行如下命令并按照引导执行即可下载所需系统镜像，为设备安装系统： +系统镜像通常需要配合镜像刷写功能来完成，即 device provision 功能。 +该功能会提供一个镜像刷写的文字向导。 +该向导当前支持使用 dd 和 fastboot 对 RISC-V 设备进行系统镜像刷写，同时也为单片机等不能常规刷写的设备提供了指导文档。 ```bash $ ruyi device provision ``` + +## 手动从安装目录调用 + +并不被推荐。二进制包均被安装在 ~/.local/share/ruyi/ 下，用起来和把工具链解包到 /opt 下是一样的。 +系统镜像同样可以手动 dd 或使用 fastboot 刷写。 \ No newline at end of file diff --git a/docs/zh/Package-Manager/installation.md b/docs/zh/Package-Manager/installation.md index 6d6be518..5796e267 100644 --- a/docs/zh/Package-Manager/installation.md +++ b/docs/zh/Package-Manager/installation.md @@ -11,21 +11,32 @@ 你可以首先使用 `ruyi update` 从配置的软件源中获得本地软件包缓存的更新，再使用 `ruyi list` 查看目前所支持的包。 +如果你使用的是 Arch Linux，还可以从 AUR 或 archlinuxcn 源中安装 ruyi 包管理器，软件包名为 `ruyi`。 + > 若还有其余相关问题可以访问 ruyi 包管理器[仓库文档](https://github.com/RuyiSDK/ruyi)（目前仅支持英文）参阅。 ## ruyi 安装 -> 请按照架构信息下载不同的ruyi二进制，下面以amd64架构为例说明具体的步骤。其他架构除了ruyi二进制文件不同，其他步骤是一样的。此外，RuyiSDK目前一直在不断更新，下面例子中的 ruyi 版本也请更换为最新版本。 +> 请按照架构信息下载不同的 ruyi 二进制，下面以 amd64 架构为例说明具体的步骤。其他架构除了 ruyi 二进制文件不同，其他步骤是一样的。此外，RuyiSDK 目前一直在不断更新，下面例子中的 ruyi 版本也请更换为最新版本。 ```bash -$ wget https://mirror.iscas.ac.cn/ruyisdk/ruyi/testing/ruyi.amd64.20231211 -$ chmod +x ./ruyi.amd64.20231211 -$ sudo cp ruyi.amd64.20231211 /usr/local/bin/ruyi +$ wget https://mirror.iscas.ac.cn/ruyisdk/ruyi/releases/0.24.0/ruyi.amd64 +$ chmod +x ./ruyi.amd64 +$ sudo cp ruyi.amd64 /usr/local/bin/ruyi $ ruyi version -Ruyi 0.2.0-beta.20231211 +Ruyi 0.24.0 + +Running on linux/x86_64. + Copyright (C) 2023 Institute of Software, Chinese Academy of Sciences (ISCAS). All rights reserved. License: Apache-2.0 + +This distribution of ruyi contains code licensed under the Mozilla Public +License 2.0 (https://mozilla.org/MPL/2.0/). You can get the respective +project's sources from the project's official website: + +* certifi: https://github.com/certifi/python-certifi ``` > ``ruyi version`` 应当可以正常打印版本信息。**注意二进制的文件名必须为** ruyi。 @@ -35,25 +46,43 @@ License: Apache-2.0 ```bash $ ruyi --help -RuyiSDK Package Manager 0.2.0-beta.20231211 +usage: ruyi [-h] [-V] [--porcelain] + {admin,list,extract,install,i,device,venv,news,update,self,version} + ... + +RuyiSDK Package Manager 0.24.0 options: -h, --help show this help message and exit -V, --version Print version information + --porcelain Give the output in a machine-friendly format if + applicable subcommands: - {extract,install,i,list,update,venv,admin,self,version} + {admin,list,extract,install,i,device,venv,news,update,self,version} + admin (NOT FOR REGULAR USERS) Subcommands for managing Ruyi + repos + list List available packages in configured repository extract Fetch package(s) then extract to current directory install (i) Install package from configured repository - list List available packages in configured repository + device Manage devices + venv Generate a virtual environment adapted to the chosen + toolchain and profile + news List and read news items from configured repository update Update RuyiSDK repo and packages - venv Generate a virtual environment adapted to the chosen toolchain and profile - admin (NOT FOR REGULAR USERS) Subcommands for managing Ruyi Repos self Manage this Ruyi installation version Print version information +``` +### ruyi 的构成 +ruyi 主要由几个方面构成，它们被分别存储在系统的不同位置 + +- ruyi 本体 `/usr/bin/ruyi` +- ruyi 用户配置文件 `~/.config/ruyi/config.toml` +- ruyi 用户缓存 `~/.cache/ruyi` +- ruyi 用户基本数据，包括下载和解包的 ruyi 软件包 `~/.local/share/ruyi` +- ruyi 用户状态数据 `~/.local/state/ruyi` -``` ### 常见问题 @@ -64,7 +93,7 @@ subcommands: 操作简述： 1. 在 ruyi 包管理工具默认的配置目录（默认为 `~/.config/ruyi`）下修改 `config.toml` 文件配置。 -不同linux发行版可能不同，当 config.toml 不存在时，可以自行创建。config.toml 配置文档内容默认为： +不同 Linux 发行版可能不同，当 config.toml 不存在时，可以自行创建。config.toml 配置文档内容默认为： ```bash [packages] @@ -95,7 +124,7 @@ branch = "main" 以上场景介绍了 ruyi 包管理器和工具的基本使用，包括： - 安装 `ruyi` -- 使用 `ruyi list` `ruyi update` `ruyi install` 功能 +- 使用 `ruyi list` / `ruyi update` / `ruyi install` 功能 - 若出现网络不稳定的备用方案 ruyi 包管理器相关的更多命令以及命令具体使用方法请参阅[功能介绍](../Package-Manager/index.md)。 diff --git a/docs/zh/RuyiSDK/case2.md b/docs/zh/RuyiSDK/case2.md index b94fcd1a..37df3157 100644 --- a/docs/zh/RuyiSDK/case2.md +++ b/docs/zh/RuyiSDK/case2.md @@ -97,4 +97,18 @@ Proceed? (y/N) ## 其他说明 +刷写工具根据板卡的不同依赖 ``dd`` 和 ``fastboot`` 命令。 + +在使用普通用户调用 ``dd`` 命令刷写镜像失败时，ruyi 将尝试调用 ``sudo`` 提权。 + +在使用 ``fastboot`` 工具刷写镜像时， ruyi 则只会使用当前普通用户，故需要用户自行配置 udev 规则。这里提供示例规则仅供参考： + +``` +SUBSYSTEM=="usb", ATTR{idVendor}="2345", ATTR{idProduct}=="7654", MODE="0666", GROUP="plugdev" +SUBSYSTEM=="usb", ATTR{idVendor}="1234", ATTR{idProduct}=="8888", MODE="0666", GROUP="plugdev" +``` + +需要注意的是一些镜像的解包需要占用大量的磁盘空间，使用 ruyi 工具刷写镜像前请务必留足磁盘空间； +一些厂家提供的镜像在刷写后并不会自动扩展分区来充分利用整块磁盘，而需要用户自行扩展磁盘分区大小。 + 相关的系统刷写问题可以访问对应开发板官网以获取针对性的帮助。 diff --git a/docs/zh/RuyiSDK/case3.md b/docs/zh/RuyiSDK/case3.md index 11bd4be7..8ba55034 100644 --- a/docs/zh/RuyiSDK/case3.md +++ b/docs/zh/RuyiSDK/case3.md @@ -1,4 +1,4 @@ -# 使用示例 +# 在 Licheepi 4A 上编译运行 以开源基准测试程序 coremark 为例，展示从 ruyi 包管理器安装到使用 ruyi 包管理器搭建 RISC-V 的编译、模拟环境，完成 coremark 源码本地编译并在 Licheepi 4A 开发板上运行的过程。 @@ -15,10 +15,10 @@ ruyi self uninstall --purge ``` -2. 下载 `ruyi` 工具并为其赋可执行权限并配置到环境变量中：从[ruyi GitHub Releases](https://github.com/RuyiSDK/ruyi/releases/) 或 [ISCAS 镜像源](https://mirror.iscas.ac.cn/RuyiSDK/ruyi/releases/)下载最新的 `ruyi` 工具。 +2. 下载 `ruyi` 工具并为其赋可执行权限并配置到环境变量中：从 [ruyi GitHub Releases](https://github.com/RuyiSDK/ruyi/releases/) 或 [ISCAS 镜像源](https://mirror.iscas.ac.cn/RuyiSDK/ruyi/releases/)下载最新的 `ruyi` 工具。 ```bash -# 下载 riscv64 版本的 ruyi 包管理器，将其放到 path 路径下，并赋予其可执行权限 +# 下载 riscv64 版本的 ruyi 包管理器，将其放到 PATH 路径下，并赋予其可执行权限 wget https://github.com/RuyiSDK/ruyi/releases/download/0.5.0/ruyi-0.5.0.riscv64 sudo cp ruyi-0.5.0.riscv64 /usr/local/bin/ruyi sudo chmod +x ruyi @@ -60,22 +60,23 @@ ruyi install gnu-plct-xthead ruyi list profiles ``` -8. 由指定的工具链、模拟器配置建立 Ruyi 虚拟环境 venv-sipeed。 +8. 由指定的工具链、模拟器配置建立 ruyi 虚拟环境 venv-sipeed。 > 注意在虚拟环境创建时，需要指定正确的编译器版本和 sysroot 类型。 + > 在不指定版本号时默认使用的是软件源里的最新版本，而不是本地安装的版本。 ```bash ruyi venv -h -##创建虚拟环境 venv-sipeed +# 创建虚拟环境 venv-sipeed ruyi venv -t gnu-plct-xthead sipeed-lpi4a venv-sipeed -#查看编译环境中得工具 +# 查看编译环境中的工具 ls venv-sipeed/bin/ -#激活虚拟环境（虚拟环境可以理解成一个容器，实现运行环境隔离的设计，激活后，在 venv-sipeed 这个环境中，使用的就是 gnu-plct-xthead 版本工具链。不创建虚拟环境也可以为 /home/sipeed/.local/share/ruyi/binaries/riscv64/gnu-plct-xthead-2.8.0-ruyi.20240222/bin 配置环境变量，直接使用环境变量指定的gcc编译） +# 激活虚拟环境（虚拟环境可以理解成一个容器，实现运行环境隔离的设计，激活后，在 venv-sipeed 这个环境中，使用的就是 gnu-plct-xthead 版本工具链。不创建虚拟环境也可以为 /home/sipeed/.local/share/ruyi/binaries/riscv64/gnu-plct-xthead-2.8.0-ruyi.20240222/bin 配置环境变量，直接使用环境变量指定的gcc编译） . venv-sipeed/bin/ruyi-activate -#查看当前虚拟环境下的 gcc 是否可用 +# 查看当前虚拟环境下的 gcc 是否可用 «Ruyi venv-sipeed» sipeed@lpi4a1590:~$ riscv64-plctxthead-linux-gnu-gcc --version ``` @@ -101,7 +102,8 @@ sed -i 's/\bgcc\b/riscv64-plctxthead-linux-gnu-gcc/g' linux64/core_portme.mak make PORT_DIR=linux64 link ls -al #新增可执行程序coremark.exe ``` -12. 查看 rv64 可执行程序文件属性信息。 + +12. 查看 riscv64 可执行程序文件属性信息。 ```bash file coremark.exe diff --git a/docs/zh/introduction/index.md b/docs/zh/introduction/index.md index c34b836b..ad149d5e 100644 --- a/docs/zh/introduction/index.md +++ b/docs/zh/introduction/index.md @@ -64,7 +64,7 @@ RuyiSDK 对 RISC-V 设备的集成和支持主要包括以下几个方面： | 型号 | | | | | ----------------------------- | -------------------- | ------------------------ | ------------------- | | 100ASK-V853-PRO | AllWinner V853 | BananaPi BPI-F3 | BeagleV-Ahead | -| BeagleV-Fire | CanMV K230 | Canaan K510-CRB-V1.2 KIT | CH32V103-EVT | +| BeagleV-Fire | CanMV K230(D) | Canaan K510-CRB-V1.2 KIT | CH32V103-EVT | | CH32V203-EVT | CH32V208-EVT | CH32V303-EVT | CH32V305-EVT | | CH32V307-EVT | CH573F-EVT | CH582F-EVT | CH592X-EVT | | D1s NeZha | DongshanPI-Nezha STU | DongShanPI D1s | HiFive Unmatched |