From 887eec51f6bb47b725ec8c4208f0336604d935ec Mon Sep 17 00:00:00 2001 From: Aoran Zeng Date: Tue, 15 Jul 2025 00:43:49 +0800 Subject: [PATCH] Update dev doc --- ...-Write-A-Recipe-Even-If-You-Dont-Know-C.md | 47 +++++++++---------- doc/04-MAINTAINERS.md | 2 +- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/doc/02-Write-A-Recipe-Even-If-You-Dont-Know-C.md b/doc/02-Write-A-Recipe-Even-If-You-Dont-Know-C.md index 90fa171..b54fb27 100644 --- a/doc/02-Write-A-Recipe-Even-If-You-Dont-Know-C.md +++ b/doc/02-Write-A-Recipe-Even-If-You-Dont-Know-C.md @@ -7,7 +7,7 @@ ! Contributors : Nul None ! | ! Created On : <2024-08-19> - ! Last Modified : <2025-07-14> + ! Last Modified : <2025-07-15> ! ---------------------------------------------------------- --> # Write A Recipe Even If You Don't Know C @@ -20,42 +20,41 @@ 我鼓励你为新的软件添加换源支持，因为通过 `chsrc` 这将非常简单，你的贡献也将非常有价值。理论上每一个 `recipe` 都需要有专人长时间维护 ([招募](https://github.com/RubyMetric/chsrc/issues/130))。 -1. 本项目采用 `GPLv3+` 协议，是真正的**自由软件**，而非仅仅是开源软件 -2. 代码规范灵活遵循 `GNU` 标准（若标准干扰了可维护性，则并不采纳） -3. 高度模块化，目录结构清晰易懂 -4. 极小依赖，极易构建，只需要 `GCC` 或 `Clang` 即可编译 (`make` 和 `just`可简化，但不是必需的) -5. 易于将 `shell` 脚本转换为等价的 `recipe` -6. 已有大量 `recipe` 可提供参考，并提供了 [recipe template] 供直接使用 -7. 提供持续关注镜像站可用性的协作平台: - - 1. - 2. +- 本项目采用 `GPLv3+` 协议，是真正的**自由软件**，而非仅仅是开源软件 +- 代码规范灵活遵循 `GNU` 标准（若标准干扰了可维护性，则并不采纳） +- 高度模块化，目录结构清晰易懂 +- 极小依赖，极易构建，只需要 `GCC` 或 `Clang` 即可编译 (`make` 和 `just`可简化，但不是必需的) +- 易于将 `shell` 脚本转换为等价的 `recipe` +- 已有大量 `recipe` 可提供参考，并提供了 [recipe template] 供直接使用 +- [rawstr4c] 帮助你在C语言中维护复杂的字符串 +- [chsrc-bootstrap] 帮助你在没有预编译 `chsrc` 的平台上 bootstrap 自己
成功案例: -1. [Armbian](../src/recipe/os/APT/Armbian.c) -2. [uv](../src/recipe/lang/Python/uv.c) +- [Armbian](../src/recipe/os/APT/Armbian.c) +- [uv](../src/recipe/lang/Python/uv.c)
## 基本概念 -1. `target`: 所要换源的目标 +- `target`: 所要换源的目标 +- `target group`: 一个 `target` 包含了多个子 `target`，比如 `Python group` 包含了该语言的多个包管理器 -2. `category`: 是 `target category` 的简写，即 `target` 所属的类别，可以是 **编程语言**，**操作系统**，**软件** 三类之一 +- `category`: 是 `target category` 的简写，即 `target` 所属的类别，可以是 **编程语言**，**操作系统**，**软件** 三类之一 1. 在目录中，三者分别为 `lang`, `os`, `ware` 2. 在代码中，三者前缀分别为 `pl`, `os`, `wr` -3. `mirror`: 是 `mirror site` 的简写，指镜像站，如清华大学开源软件镜像站 -4. `source`: 该 `target` 所能换的具体的源，由 `mirror` 提供服务，往往一个 `mirror` 会提供许多 `source` -5. `recipe`: 是为一个 `target` 定义的具体换源方法，请参考 `src` 目录中的 `recipe` 目录 +- `mirror`: 是 `mirror site` 的简写，指镜像站，如清华大学开源软件镜像站 +- `source`: 该 `target` 所能换的具体的源，由 `mirror` 提供服务，往往一个 `mirror` 会提供许多 `source` +- `recipe`: 是为一个 `target` 定义的具体换源方法，请参考 `src` 目录中的 `recipe` 目录 -6. `feature`: 一个 `target` 可以支持的功能，比如能否重置回上游默认源等 +- `feature`: 一个 `target` 可以支持的功能，比如能否重置回上游默认源等 -7. **镜像源**: 为了方便，**偶尔**我们将直接称`mirror`和/或`source`为**镜像源**，这只是一种方便性的称呼，可以统称二者，也可以根据上下文指代二者之一 +- **镜像源**: 为了方便，**偶尔**我们将直接称`mirror`和/或`source`为**镜像源**，这只是一种方便性的称呼，可以统称二者，也可以根据上下文指代二者之一
@@ -72,13 +71,11 @@ 4. 参考现有 `recipe` 的写法 1. 看一眼就能上手的参照物是 [PHP recipe](../src/recipe/lang/PHP.c) - 2. 最好的参照物是 [Ruby recipe](../src/recipe/lang/Ruby.c) - 3. 组换源参照物是 [Python Group recipe](../src/recipe/lang/Python/Python.c) + 2. 最好的参照物是 [Ruby recipe](../src/recipe/lang/Ruby/Ruby.c) + 3. 组换源参照物是 [Python group recipe](../src/recipe/lang/Python/Python.c) 5. 在 [Wiki] 中记录的镜像站中寻找可用源；可以额外补充镜像站 - 并创建或更新对应 `target` 的镜像站可用状态 [Wiki] 页 - 6. 可以使用这些函数: 1. `framework/core.c` 中以 `chsrc_` 开头的所有函数或宏 @@ -105,5 +102,7 @@
+[rawstr4c]: ../tool/rawstr4c/ +[chsrc-bootstrap]: ../bootstrap/ [recipe template]: ../src/recipe/recipe-template.c [Wiki]: https://github.com/RubyMetric/chsrc/wiki diff --git a/doc/04-MAINTAINERS.md b/doc/04-MAINTAINERS.md index 9f8a8d3..f80986e 100644 --- a/doc/04-MAINTAINERS.md +++ b/doc/04-MAINTAINERS.md @@ -2,7 +2,7 @@ 作为该语言的资深用户、该软件的专家、镜像站维护人员等，你总是对镜像站和源的可用状态拥有一手信息，我们需要你的帮助。如果想要达到最理想的维护状态，每一个 recipe 都需要有专人长时间维护。所以我们在这个文件记录的是愿意**长期**维护的人，如果是一次性提交代码，只需要在对应 recipe 的文件标头中记录即可。 -**我们的代码里使用了 recipe (某个菜的烹饪方法) 这个词，因而整个项目便和 “吃” 有关，比如 `menu`: 汇集了所有的 target 的菜单。因此，我们的维护者身份依然使用了这个惯例：** +**我们的代码里使用了 recipe (某个菜的烹饪方法) 这个词，因而整个项目便和 "饮食" 有关，比如 `menu`: 汇集了所有的 target 的菜单。因此，我们的维护者身份依然使用了这个惯例：** 一个 recipe 的协作者可分为：