From b5a614c4b8b1eb5c8e573cad0c7bf84cbafda313 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Tue, 10 Nov 2026 23:45:58 +0000 Subject: [PATCH] Docs: local Modules requested with path: in modules.yaml --- docs/proj_man/setup.md | 76 ++++++++++++++++++- .../current/proj_man/setup.md | 76 ++++++++++++++++++- 2 files changed, 150 insertions(+), 2 deletions(-) diff --git a/docs/proj_man/setup.md b/docs/proj_man/setup.md index f76aaac..61c920b 100644 --- a/docs/proj_man/setup.md +++ b/docs/proj_man/setup.md @@ -24,7 +24,7 @@ modules: - `xrobot:` 固定工具版本(发布版本号或 40 位十六进制的提交号)。 - `modules` 只写直接需要的模块;依赖由各模块头文件中的 manifest 递归给出。 -- 每项是 `owner/Repo[@ref]`,或含 `id`、`ref`、`context_ref` 的映射;`owner/Repo` 必须能在 [源](./src_man.md) 中找到。 +- 每项是 `owner/Repo[@ref]`,或含 `id`、`ref`、`context_ref` 的映射;`owner/Repo` 必须能在 [源](./src_man.md) 中找到。只在本 BSP 中使用的模块以 `path:` 请求,见[本地模块](#本地模块)。 用命令编辑时不会丢失注释: @@ -50,6 +50,80 @@ BSP 不在 Git 仓库中时没有可跟随的分支:不加 `--update` 时沿 --- +## 本地模块 + +只在一个 BSP 中使用的模块可以直接放在 BSP 的目录中,在 `modules.yaml` 中以 `path:` 请求(XRobot 1.0.2 起)。目录结构与普通模块相同:目录名即类名,目录中有同名的主头文件 `<目录名>.hpp`,也可以有自己的 `CMakeLists.txt`。模块 id 为 `local/<目录名>`;`local` 这个 owner 保留给本地模块,源中的包使用它时报错。 + +```yaml +xrobot: 1.0.2 +modules: + - xrobot-org/BlinkLED@same-or-dev + - path: Modules/local/Heartbeat +``` + +`path` 相对 BSP 根目录,也可以是绝对路径,推荐的位置是 `Modules/local/<目录名>`。`path` 的最后一段与目录的实际名称一致,包括大小写。路径指向 BSP 根目录、`Modules/` 或包含 BSP 的目录,含有分号或控制字符,或两个本地模块的目录名相同时,`xrobot setup` 报错。 + +`xrobot module add --path` 写入这样一项,写入前检查目录和主头文件。相对路径先按当前目录查找,不存在时按 BSP 根目录查找,写入时换算成相对 BSP 根目录的路径。删除时写模块 id: + +```text +$ xrobot module add --path Modules/local/Heartbeat +已添加本地模块 local/Heartbeat(path: Modules/local/Heartbeat);请运行 `xrobot setup` 更新 xrobot.lock +$ xrobot module remove local/Heartbeat +已删除 local/Heartbeat;请运行 `xrobot setup` 更新 xrobot.lock +``` + +### 提交与 .gitignore + +BSP 目录内的本地模块随 BSP 仓库提交,由 BSP 的提交固定。`xrobot init` 生成的 `.gitignore` 含有 `/Modules/*/`,这条规则也忽略 `Modules/local/`。`xrobot setup` 检查本地模块目录中尚未被 Git 跟踪的源文件、头文件和 CMake 文件,其中有被 `.gitignore` 忽略的文件时报错,并给出需要添加的一行: + +```text +$ xrobot setup +本地模块 local/Heartbeat(Modules/local/Heartbeat)被 BSP 的 .gitignore 忽略,Modules/local/Heartbeat/Heartbeat.hpp 不会被提交;请在 .gitignore 中忽略它的规则(.gitignore:3:/Modules/*/)之后加一行 `!/Modules/local/` +``` + +加上 `!/Modules/local/` 之后,`Modules/local/` 下的本地模块都随 BSP 提交。 + +本地模块目录中有自己的 `.git` 时,BSP 仓库不跟踪其中的文件,`xrobot setup` 给出警告。BSP 目录之外的本地模块(例如 `../shared/Heartbeat` 或绝对路径)只在本机可用;`xrobot setup` 每次运行时给出警告,`--frozen` 下同样只是警告: + +```text +$ xrobot setup +警告:本地模块 local/Heartbeat 在 BSP 之外(../shared/Heartbeat);没有提交固定它,其他检出和 CI 无法复现 +已解析 1 个模块提交和 1 个本地模块 +已检查 1 个配置;已为 User/xrobot.yaml 生成 User/xrobot_main.hpp +``` + +### 依赖 + +本地模块的 manifest 与普通模块的写法相同,`xrobot setup` 直接读取工作区中的主头文件。它请求的模块与 `modules.yaml` 中的请求同等对待:`same`、`same-or-dev` 跟随 BSP 的分支,解析结果写入 lock。依赖另一个本地模块时写它的 id,例如 `local/Base`,被依赖的模块同样在 `modules.yaml` 中以 `path:` 请求。来自源的模块请求本地模块时报错。 + +### lock 与 setup 选项 + +lock 在 `local` 部分记录每个本地模块的路径,它是 `modules.yaml` 中 `path:` 请求的副本;没有本地模块时不写出这一部分。 + +```yaml +local: + local/Heartbeat: + path: Modules/local/Heartbeat +``` + +生成的 `Modules/CMakeLists.txt` 按路径加入本地模块,相对路径写成相对 `Modules/` 的路径: + +```cmake +target_include_directories(xr PUBLIC "${CMAKE_CURRENT_LIST_DIR}/local/Heartbeat") +include("${CMAKE_CURRENT_LIST_DIR}/xrobot-org/BlinkLED/CMakeLists.txt") +``` + +| 命令 | 对本地模块的效果 | +| --- | --- | +| `xrobot setup` | 本地模块的依赖变化后,保持已锁定的提交并重新解析依赖闭包;lock 的 `local` 部分与 `modules.yaml` 不一致时重写 | +| `xrobot setup --frozen` | 本地模块的依赖或 lock 的 `local` 部分与当前不一致时失败 | +| `xrobot setup --offline` | 本地模块的依赖变化后失败 | +| `xrobot setup --update local/<目录名>` | 重新解析它的依赖 | +| `xrobot setup --leave-local` | 只接受来自源的模块,点名本地模块时报错 | +| `xrobot setup --release-ref` | 只检查来自源的模块 | + +--- + ## xrobot.lock lock 记录依赖闭包中每个模块的仓库、请求的 ref、解析结果和提交。本地仓库路径保存为相对 lock 的路径。lock 生成后即为唯一依据,同一份 lock 在功能分支、合并后和 CI 中检出相同的模块代码。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md index 07b3619..9db459a 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md @@ -24,7 +24,7 @@ modules: - `xrobot:` pins the tool version (a release version or a 40-hex commit). - `modules` lists only direct requests; dependencies come recursively from each Module header's manifest. -- Each entry is `owner/Repo[@ref]` or a mapping with `id`, `ref` and `context_ref`; `owner/Repo` must be listed in a [Source](./src_man.md). +- Each entry is `owner/Repo[@ref]` or a mapping with `id`, `ref` and `context_ref`; `owner/Repo` must be listed in a [Source](./src_man.md). A Module used only by this BSP is requested with `path:`, see [Local Modules](#local-modules). These commands edit the file and keep its comments: @@ -50,6 +50,80 @@ A BSP outside Git has no branch to follow: without `--update` the lock is kept a --- +## Local Modules + +A Module used by a single BSP can live in a folder of the BSP and be requested in `modules.yaml` with `path:` (from XRobot 1.0.2). The folder is laid out like any other Module: its name is the class name, it holds the primary header `.hpp`, and it may have its own `CMakeLists.txt`. The Module id is `local/`; the owner `local` is reserved for local Modules, and a package of a Source that uses it is an error. + +```yaml +xrobot: 1.0.2 +modules: + - xrobot-org/BlinkLED@same-or-dev + - path: Modules/local/Heartbeat +``` + +`path` is relative to the BSP root or absolute; the recommended place is `Modules/local/`. The last segment of `path` matches the actual folder name, including its case. A path that names the BSP root, `Modules/` or a folder containing the BSP, a path with a semicolon or a control character, and two local Modules with the same folder name make `xrobot setup` fail. + +`xrobot module add --path` writes such an entry after checking the folder and its primary header. A relative path is looked up from the current directory first and from the BSP root otherwise, and is written relative to the BSP root. Removal takes the Module id: + +```text +$ xrobot module add --path Modules/local/Heartbeat +Added local Module local/Heartbeat (path: Modules/local/Heartbeat); run `xrobot setup` to update xrobot.lock +$ xrobot module remove local/Heartbeat +Removed local/Heartbeat; run `xrobot setup` to update xrobot.lock +``` + +### Commits and .gitignore + +A local Module inside the BSP is committed with the BSP repository and pinned by the BSP's commits. The `.gitignore` written by `xrobot init` contains `/Modules/*/`, which also ignores `Modules/local/`. `xrobot setup` checks the source, header and CMake files of a local Module that Git does not track yet; when `.gitignore` ignores one of them, it fails and names the line to add: + +```text +$ xrobot setup +Local Module local/Heartbeat (Modules/local/Heartbeat) is ignored by the BSP's .gitignore, so Modules/local/Heartbeat/Heartbeat.hpp would not be committed; add `!/Modules/local/` to .gitignore after the rule that ignores it (.gitignore:3:/Modules/*/) +``` + +With `!/Modules/local/` added, every local Module under `Modules/local/` is committed with the BSP. + +When the folder of a local Module has its own `.git`, the BSP repository does not track its files and `xrobot setup` warns. A local Module outside the BSP (such as `../shared/Heartbeat` or an absolute path) is available on that machine only; `xrobot setup` warns on every run, and `--frozen` warns as well: + +```text +$ xrobot setup +warning: local Module local/Heartbeat is outside the BSP (../shared/Heartbeat); no commit pins it, so other checkouts and CI cannot reproduce it +Resolved 1 Module commit and 1 local Module +Checked 1 config; generated User/xrobot_main.hpp for User/xrobot.yaml +``` + +### Dependencies + +The manifest of a local Module is written like that of any Module, and `xrobot setup` reads the primary header from the working tree. The Modules it requests count as requests of `modules.yaml`: `same` and `same-or-dev` follow the BSP branch, and the results go into the lock. A dependency on another local Module is written as its id, such as `local/Base`, and that Module is requested with `path:` in `modules.yaml` as well. A Module from a Source that requests a local Module is an error. + +### The Lock and Setup Options + +The `local` section of the lock records the path of every local Module; it copies the `path:` requests of `modules.yaml` and is left out when there are no local Modules. + +```yaml +local: + local/Heartbeat: + path: Modules/local/Heartbeat +``` + +The generated `Modules/CMakeLists.txt` adds a local Module by its path, writing a relative path relative to `Modules/`: + +```cmake +target_include_directories(xr PUBLIC "${CMAKE_CURRENT_LIST_DIR}/local/Heartbeat") +include("${CMAKE_CURRENT_LIST_DIR}/xrobot-org/BlinkLED/CMakeLists.txt") +``` + +| Command | Effect on local Modules | +| --- | --- | +| `xrobot setup` | After the dependencies of a local Module change, keeps the locked commits and resolves the closure again; rewrites a `local` section that differs from `modules.yaml` | +| `xrobot setup --frozen` | Fails when the dependencies of a local Module or the `local` section of the lock differ from the current state | +| `xrobot setup --offline` | Fails after the dependencies of a local Module change | +| `xrobot setup --update local/` | Resolves its dependencies again | +| `xrobot setup --leave-local` | Takes Modules from a Source only; naming a local Module is an error | +| `xrobot setup --release-ref` | Checks the Modules from a Source only | + +--- + ## xrobot.lock The lock records, for every Module in the dependency closure, the repository, the requested ref, what it resolved to, and the commit. Local repository paths are stored relative to the lock. Once written, the lock is authoritative: the same lock checks out the same Module code on a feature branch, after its merge, and in CI.