From f1b01456c266e2b58e6f23ac2ab478825f661bb8 Mon Sep 17 00:00:00 2001 From: Jixun Wu Date: Tue, 23 May 2023 00:49:24 +0100 Subject: [PATCH] docs: move large chunk of text to its own file --- README.MD | 78 ++--------------------------- docs/develop-with-libparakeet.zh.md | 50 ++++++++++++++++++ docs/getting-started.zh.md | 35 +++++++++++++ 3 files changed, 90 insertions(+), 73 deletions(-) create mode 100644 docs/develop-with-libparakeet.zh.md create mode 100644 docs/getting-started.zh.md diff --git a/README.MD b/README.MD index 49c09c7..ac28362 100644 --- a/README.MD +++ b/README.MD @@ -31,37 +31,13 @@ ## 开发相关 -### 安装依赖 +从源码运行或编译生产版本，请参考文档「[新手上路](./docs/getting-started.zh.md)」。 -- 安装 Node v16.17 或更高，推荐当前最新的 Node LTS 版本。 -- 安装/激活 `pnpm`：`corepack prepare pnpm@latest --activate` [^1] -- 安装软件依赖：`pnpm i --frozen-lockfile` +### 面向 libparakeet SDK 开发 -[^1]: 参考 pnpm 说明 https://pnpm.io/zh/installation#使用-corepack-安装 +⚠️ 如果只是进行前端方面的更改，你可以跳过该节。 -### 本地运行 - -⚠️ 先完成安装依赖部分，然后继续。 - -```sh -pnpm start -``` - -然后根据提示打开[项目所在页面][vite-dev-url]即可。 - -[vite-dev-url]: http://localhost:5173/ - -### 构建生产版本 - -⚠️ 先完成安装依赖部分，然后继续。 - -```sh -pnpm build -``` - -如果需要预览构建版本，运行 `pnpm preview` 然后打开[项目所在页面][vite-preview-url]即可。 - -[vite-preview-url]: http://localhost:4173/ +请参考文档「[面向 `libparakeet-js` 开发](./docs/develop-with-libparakeet.zh.md)」。 ### 架构 @@ -70,51 +46,7 @@ pnpm build 数据传输: 生成 blob url (`URL.createObjectURL`) 然后透过 `postMessage` 传递给线程，线程利用 `fetch` API 来获取文件信息。 -## 基于 libparakeet SDK 开发 - -`libparakeet-js` 编译目前需要 Linux 环境，请参考[仓库说明][libparakeet-js-doc]。 - -该文档将假设这两个项目被放置在同级的目录下： - -```text -~/Projects/um-projects - /um-react - /libparakeet-js -``` - -若为不同目录，你需要调整 `LIB_PARAKEET_JS_DIR` 环境变量到仓库目录，然后再启动 vite 项目。 - -[libparakeet-js-doc]: https://github.com/parakeet-rs/libparakeet-js/blob/main/README.MD - -### 初次构建 - -- 进入上层目录 `cd ..` -- 克隆 `libparakeet-js` 仓库 (目前需要 Linux 环境, Windows 下推荐使用 WSL2) - - `git clone --recurse-submodules https://github.com/parakeet-rs/libparakeet-js.git` -- 进入目录 `cd libparakeet-js` -- 如果需要更新 `submodule`: - - `git submodule update --init --recursive` -- 运行 `./build.sh -j 4` 进行编译 -- 编译 `js-sdk`: - - 进入 `npm` 目录: `cd npm` - - 安装依赖: `pnpm i --frozen-lockfile` - - 构建: `pnpm build` - -### 做出更改 - -做出更改后，参考上面的内容进行重新编译 - -### 应用 SDK 更改 - -将构建好的 SDK 直接嵌入到当前前端项目： - -```sh -pnpm link ../libparakeet-js/npm -``` - -※ 建立 PR 时，请先提交 SDK PR 并确保你的更改已合并。 - -## 贡献代码 +### 贡献代码 欢迎贡献代码。请确保： diff --git a/docs/develop-with-libparakeet.zh.md b/docs/develop-with-libparakeet.zh.md new file mode 100644 index 0000000..dc74b10 --- /dev/null +++ b/docs/develop-with-libparakeet.zh.md @@ -0,0 +1,50 @@ +# 面向 `libparakeet-js` 开发 + +⚠️ 如果只是进行前端方面的更改，你可以跳过该文档。 + +`libparakeet-js` 编译目前需要 Linux 环境，请参考[仓库说明][libparakeet-js-doc]。 + +该文档将假设这两个项目被放置在同级的目录下： + +```text +~/Projects/um-projects + /um-react + /libparakeet-js +``` + +若为不同目录，你需要调整 `LIB_PARAKEET_JS_DIR` 环境变量到仓库目录，然后再启动 vite 项目。 + +[libparakeet-js-doc]: https://github.com/parakeet-rs/libparakeet-js/blob/main/README.MD + +## 初次构建 + +- 进入上层目录：`cd ..` +- 克隆 `libparakeet-js` 仓库 (目前需要 Linux 环境, Windows 下推荐使用 WSL2) + - `git clone --recurse-submodules https://github.com/parakeet-rs/libparakeet-js.git` +- 进入 SDK 目录：`cd libparakeet-js` +- 如果需要更新 `submodule`：`git submodule update --init --recursive` +- 构建所有代码：`make all` + +如果需要手动控制构建过程，你也可以： + +- 运行 `./build.sh -j 4` 进行 C++ 到 WebAssembly 编译过程 + - 此处的 `4` 是并行编译数量，该值通常略小于 CPU 核心数。 + - 若是不指定并行数量，则使用当前核心数。 +- 编译 `js-sdk`： + - 进入 `npm` 目录：`cd npm` + - 安装依赖：`pnpm i --frozen-lockfile` + - 构建：`pnpm build` + +## 做出更改 + +做出更改后，参考上面的内容进行重新编译。 + +## 应用 SDK 更改 + +将构建好的 SDK 直接嵌入到当前前端项目： + +```sh +pnpm link ../libparakeet-js/npm +``` + +※ 建立 PR 时，请先提交 SDK PR 并确保你的 SDK 更改已合并。 diff --git a/docs/getting-started.zh.md b/docs/getting-started.zh.md new file mode 100644 index 0000000..6e4db0e --- /dev/null +++ b/docs/getting-started.zh.md @@ -0,0 +1,35 @@ +# 新手上路 + +该文档描述了如何本地运行或编译生产版本的「Unlock Music 音乐解锁」。 + +## 安装依赖 + +- 安装 Node v16.17 或更高，推荐当前最新的 Node LTS 版本。 +- 安装/激活 `pnpm` [^1]：`corepack prepare pnpm@latest --activate` +- 安装软件依赖：`pnpm i --frozen-lockfile` + +[^1]: 参考 pnpm 说明 https://pnpm.io/zh/installation#使用-corepack-安装 + +## 本地运行 + +💡 你需要先完成「安装依赖」部分。 + +```sh +pnpm start +``` + +然后根据提示打开[项目运行页面][vite-dev-url]即可。 + +[vite-dev-url]: http://localhost:5173/ + +## 构建生产版本 + +💡 你需要先完成「安装依赖」部分。 + +```sh +pnpm build +``` + +如果需要预览构建版本，运行 `pnpm preview` 然后打开[项目预览页面][vite-preview-url]即可。 + +[vite-preview-url]: http://localhost:4173/