Skip to content

Commit 71ad4b0

Browse files
SunrisepeakSunrisepeak
committed
docs(readme): slim down to intro + usage + contribution + links
Drop the package tables/dependency tree/smoke breakdown/Form-A-B examples from the index README — the browsable site (mcpplibs.github.io/mcpp-index) is the package list, and the how-to detail lives in the add-mcpp-index-package skill. README now = what it is, mcpp add/build usage, the two package categories (native module libs / third-party compat) with a pointer to the skill, and related tools / community.
1 parent af34f6e commit 71ad4b0

1 file changed

Lines changed: 24 additions & 264 deletions

File tree

‎README.md‎

Lines changed: 24 additions & 264 deletions
Original file line numberDiff line numberDiff line change
@@ -1,292 +1,52 @@
11
# mcpp-index
22

33
> [`mcpp`](https://github.com/mcpp-community/mcpp) 构建工具的默认包索引仓库
4-
>
5-
> 在线浏览: **https://mcpplibs.github.io/mcpp-index/**
4+
> · 在线浏览所有包 **https://mcpplibs.github.io/mcpp-index/**
65
7-
## 快速使用
6+
收录可被 `mcpp` 直接 `add` 的 C++23 包:既有 `import` 即用的模块化库,也有以 `compat` 形态从上游源码/头
7+
构建的第三方 C/C++ 库。每个包是一个 `pkgs/<首字母>/<包名>.lua` 描述文件。
88

9-
```bash
10-
mcpp add ftxui@6.1.9 # 添加依赖到 mcpp.toml
11-
mcpp build # 自动拉取源码 + 构建
12-
```
13-
14-
## 已收录的包
15-
16-
### mcpplibs 模块化库
17-
18-
| 包名 | 版本 | 简介 | 仓库 |
19-
|------|------|------|------|
20-
| `mcpplibs.cmdline` | 0.0.2 | 命令行解析框架 — `import mcpplibs.cmdline;` | [mcpplibs/cmdline](https://github.com/mcpplibs/cmdline) |
21-
| `mcpplibs.tinyhttps` | 0.2.2 | 轻量 HTTP/HTTPS 客户端(SSE 流式) — `import mcpplibs.tinyhttps;` | [mcpplibs/tinyhttps](https://github.com/mcpplibs/tinyhttps) |
22-
| `mcpplibs.llmapi` | 0.2.5 | 大语言模型 API 客户端(OpenAI/Anthropic 兼容) — `import mcpplibs.llmapi;` | [mcpplibs/llmapi](https://github.com/mcpplibs/llmapi) |
23-
| `mcpplibs.capi.lua` | 0.0.3 | Lua 5.4 C API 的 C++23 模块封装 — `import mcpplibs.capi.lua;` | [mcpplibs/lua](https://github.com/mcpplibs/lua) |
24-
| `mcpplibs.xpkg` | 0.0.40 | xpkg V1 规范的 C++23 参考实现 — `import mcpplibs.xpkg;` | [openxlings/libxpkg](https://github.com/openxlings/libxpkg) |
25-
| `mcpplibs.templates` | 0.0.1 | 最小化模块库模板 — `import mcpplibs.templates;` | [mcpplibs/templates](https://github.com/mcpplibs/templates) |
26-
27-
### 独立模块化库
28-
29-
| 包名 | 版本 | 简介 | 仓库 |
30-
|------|------|------|------|
31-
| `imgui` | 0.0.1 | Dear ImGui C++23 模块封装 — `import imgui.core;` / `import imgui.backend.glfw_opengl3;` | [mcpplibs/imgui-m](https://github.com/mcpplibs/imgui-m) |
32-
| `nlohmann.json` | 3.12.0 | JSON for Modern C++,开箱即用的 C++23 模块 — `import nlohmann.json;` | [nlohmann/json](https://github.com/nlohmann/json) |
33-
34-
### 第三方 C/C++ 库
35-
36-
| 包名 | 版本 | 简介 |
37-
|------|------|------|
38-
| `ftxui` | 6.1.9 | C++ 函数式终端 UI 库(screen + dom + component) |
39-
| `glfw` | 3.4 | GLFW 窗口与输入库(X11/null 后端源码构建) |
40-
| `gtest` | 1.15.2 | Google Test 测试框架 |
41-
| `cjson` | 1.7.19 | 超轻量 ANSI C JSON 解析库(`#include <cJSON.h>`,`compat` 源码构建) |
42-
| `eigen` | 5.0.1 | C++ 模板线性代数库(header-only,`#include <Eigen/Dense>`;`unsupported/` 实验模块亦可用;`features = ["blas"]` 编入 Eigen 参考 BLAS) |
43-
| `imgui` | 1.92.8 | Dear ImGui immediate-mode GUI 核心源码 |
44-
| `opengl` | 2026.05.31 | Khronos OpenGL API 头文件 |
45-
| `glx-runtime` | 2026.06.03 | Linux host GLVND/GLX/OpenGL runtime adapter |
46-
| `khrplatform` | 2026.05.31 | Khronos KHR platform 头文件 |
47-
| `xorgproto` | 2025.1 | X.Org protocol 头文件 |
48-
| `xtrans` | 1.6.0 | X.Org transport support headers/source snippets |
49-
| `xau` | 1.0.12 | X authorization runtime library(`libXau.so`) |
50-
| `xdmcp` | 1.1.5 | X Display Manager Control Protocol runtime library(`libXdmcp.so`) |
51-
| `xcb-proto` | 1.17.0 | XCB protocol XML definitions and generator metadata |
52-
| `xcb` | 1.17.0 | X C Binding runtime library(`libxcb.so`) |
53-
| `x11` | 1.8.13 | Xlib runtime library(`libX11.so`) and public headers |
54-
| `xcursor` | 1.2.3 | Xcursor runtime library(`libXcursor.so`) and public headers |
55-
| `xext` | 1.3.7 | Xext runtime library(`libXext.so`) and public headers |
56-
| `xfixes` | 6.0.2 | Xfixes runtime library(`libXfixes.so`) and public headers |
57-
| `xi` | 1.8.3 | XInput runtime library(`libXi.so`) and public headers |
58-
| `xinerama` | 1.1.6 | Xinerama runtime library(`libXinerama.so`) and public headers |
59-
| `xrandr` | 1.5.5 | Xrandr runtime library(`libXrandr.so`) and public headers |
60-
| `xrender` | 0.9.12 | Xrender runtime library(`libXrender.so`) and public headers |
61-
| `mbedtls` | 3.6.1 | TLS/加密库(纯 C) |
62-
| `lua` | 5.4.7 | Lua 脚本语言(纯 C 嵌入式库) |
63-
| `zlib` | 1.3.2 | DEFLATE 压缩库 |
64-
| `bzip2` | 1.0.8 | bzip2 压缩库 |
65-
| `lz4` | 1.10.0 | LZ4 压缩库 |
66-
| `zstd` | 1.5.7 | Zstandard 压缩库 |
67-
| `xz` | 5.8.3 | XZ Utils liblzma 压缩库 |
68-
| `libarchive` | 3.8.7 | 多格式归档与压缩库 |
69-
70-
### 依赖关系链
71-
72-
```
73-
mcpplibs.llmapi
74-
└── mcpplibs.tinyhttps
75-
└── mbedtls ← mcpp 自动传递,无需手动声明
76-
77-
mcpplibs.xpkg
78-
└── mcpplibs.capi.lua
79-
└── lua ← 同上
80-
81-
imgui
82-
├── compat.imgui
83-
├── compat.glfw
84-
│ ├── compat.opengl
85-
│ └── compat.glx-runtime
86-
│ └── compat.xext → compat.x11
87-
│ ← Linux GLX/OpenGL driver runtime provider
88-
└── compat.opengl ← 消费者只需要 import imgui.* 模块
89-
90-
libarchive
91-
├── zlib
92-
├── bzip2
93-
├── lz4
94-
├── zstd
95-
└── xz ← 压缩后端自动传递
96-
97-
glfw
98-
├── opengl
99-
│ └── khrplatform ← GLFW/glfw3.h 所需 OpenGL/KHR 头文件
100-
├── glx-runtime
101-
│ └── xext → x11 ← GLFW GLX dlopen 所需 host GLVND/driver runtime
102-
└── x11 / xcursor / xext / xfixes / xi
103-
/ xinerama / xorgproto / xrandr / xrender
104-
← GLFW Linux X11 后端所需 runtime/header 闭包
105-
106-
xau / xdmcp
107-
└── xorgproto ← X11 底层 runtime 库的协议头文件
108-
109-
xcb
110-
├── xcb-proto ← hook 内生成 xcb 协议源文件
111-
├── xau
112-
└── xdmcp
113-
114-
x11
115-
├── xcb
116-
├── xorgproto
117-
└── xtrans ← Xlib/XIM transport 源码片段
118-
```
119-
120-
mcpp 0.0.3+ 的 transitive walker 自动沿链路传播头文件和依赖,消费者只需声明直接依赖。
121-
122-
> 当前 X11/XCB/Xau/Xdmcp 以及 GLFW 需要的 Xcursor/Xext/Xfixes/Xi/Xinerama/
123-
> Xrandr/Xrender 都已按上游源码提供 runtime `.so`,并声明标准 ELF SONAME
124-
> (如 `libX11.so.6`、`libxcb.so.1`)。`compat.glx-runtime` 是 Linux host
125-
> GLVND/GLX/OpenGL driver runtime adapter,提供 GLFW 上游 `dlopen` 需要的
126-
> `libGLX.so.0`/`libGL.so.1`/`libGL.so` runtime 目录,并通过 `compat.xext`
127-
> 带入 host GLX 库常见的 X11/Xext ABI 依赖闭包。
128-
> 窗口运行时仍需要宿主环境提供可用的 X server/GLX/OpenGL 驱动。
129-
130-
### 单库示例工程(`tests/examples/<pkg>/`)
131-
132-
每个库可以有一个最小可构建工程(自带 `mcpp.toml` + 源码,`[indices]` 相对指回本仓),
133-
既是文档也是测试。CI 在 PR 上**只跑改动到的库**对应的示例(`tests/run_example.sh`),
134-
其余情况(push / nightly / 改动脚手架)才跑下面的全量 smoke。
9+
## 使用
13510

13611
```bash
137-
MCPP=/path/to/mcpp tests/run_example.sh cjson # #include <cJSON.h>
138-
MCPP=/path/to/mcpp tests/run_example.sh nlohmann.json # import nlohmann.json;
139-
# 等价于:cd tests/examples/cjson && mcpp run
140-
```
12+
mcpp add ftxui@6.1.9 # 添加依赖到 mcpp.toml
13+
mcpp build # 自动拉取源码 + 构建(依赖沿链路自动传递)
14114

142-
### 本地 smoke 验证(全量回归)
143-
144-
```bash
145-
MCPP=/path/to/mcpp tests/smoke_compat_core.sh
146-
MCPP=/path/to/mcpp tests/smoke_compat_imgui.sh
147-
MCPP=/path/to/mcpp tests/smoke_compat_archive.sh
148-
MCPP=/path/to/mcpp tests/smoke_imgui_module.sh
15+
mcpp search <keyword> # 搜索 / 刷新索引
16+
mcpp self config --mirror CN # 切到国内镜像(默认走 GLOBAL 上游源)
14917
```
15018

151-
该脚本会通过当前 checkout 作为本地 path index 创建临时 mcpp 项目,验证:
19+
完整包列表见 **[在线索引站](https://mcpplibs.github.io/mcpp-index/)**。
15220

153-
- `compat.gtest`/`compat.ftxui`/`compat.lua`/`compat.mbedtls` 能用上游
154-
`#include <...>` API 构建并运行最小用例
155-
- `compat.opengl`/`compat.khrplatform` 能提供 GLFW/OpenGL 常见头文件闭包
156-
- `compat.imgui@1.92.8` core 能构建并运行一个 headless ImGui frame
157-
- `imgui@0.0.1` 模块包能通过 `[dependencies] imgui = "0.0.1"` 构建并运行
158-
`import imgui.core;` / `import imgui.backend.glfw_opengl3;` 最小用例
159-
- `compat.glfw@3.4` 能构建、运行 `glfwInit()` smoke,并链接 X11 扩展 runtime `.so`
160-
- `compat.xau@1.0.12`/`compat.xdmcp@1.1.5` 能构建、运行并链接 runtime `.so`
161-
- `compat.xcb@1.17.0` 能构建、运行并链接 `libxcb.so`
162-
- `compat.x11@1.8.13` 能构建、运行并链接 `libX11.so` → `libxcb.so`
163-
- `compat.xcursor`/`compat.xext`/`compat.xfixes`/`compat.xi`/`compat.xinerama`/
164-
`compat.xrandr`/`compat.xrender` 能构建、运行并链接对应 `libX*.so`
165-
- `compat.libarchive` 能连同 `zlib`/`bzip2`/`lz4`/`zstd`/`xz` 压缩后端构建并运行
21+
## 包生态与贡献
16622

167-
有窗口的 ImGui + GLFW + OpenGL demo 单独放在可选 smoke 中:
168-
169-
```bash
170-
MCPP=/path/to/mcpp tests/smoke_compat_imgui_window.sh
171-
MCPP=/path/to/mcpp MCPP_INDEX_RUN_WINDOW_SMOKE=1 tests/smoke_compat_imgui_window.sh
172-
```
173-
174-
默认只验证 demo 构建和 X11 runtime 链接闭包。显式设置
175-
`MCPP_INDEX_RUN_WINDOW_SMOKE=1` 后才会运行隐藏窗口帧渲染,此时需要当前
176-
`DISPLAY` 可用,并且宿主机提供 GLVND/GLX/OpenGL 驱动 runtime。脚本会把
177-
宿主 GL runtime 和 compat X11 runtime 组装到临时 `LD_LIBRARY_PATH` 中,
178-
避免系统 X11 库覆盖 mcpp 构建出的 `libX11.so`/`libxcb.so`。
179-
180-
## 包描述文件
181-
182-
每个包对应一个 `pkgs/<首字母>/<包名>.lua` 文件,遵循 [xpkg V1 规范](https://github.com/d2learn/xim-pkgindex/blob/main/docs/V1/xpackage-spec.md)。
183-
184-
### 两种形式
185-
186-
**Form A** — 上游自带 `mcpp.toml`,描述文件只声明元数据和下载地址:
187-
188-
```lua
189-
package = {
190-
spec = "1",
191-
name = "mcpplibs.tinyhttps",
192-
xpm = {
193-
linux = { ["0.2.2"] = { url = "...", sha256 = "..." } },
194-
macosx = { ["0.2.2"] = { url = "...", sha256 = "..." } },
195-
windows = { ["0.2.2"] = { url = "...", sha256 = "..." } },
196-
},
197-
}
198-
```
199-
200-
**Form B** — 上游没有 `mcpp.toml`,在描述文件里内联构建信息:
201-
202-
```lua
203-
package = {
204-
spec = "1",
205-
name = "ftxui",
206-
xpm = { ... },
207-
mcpp = {
208-
include_dirs = { "*/include", "*/src" },
209-
sources = {
210-
"*/src/ftxui/**/*.cpp",
211-
"!*/src/ftxui/**/*_test.cpp", -- glob 排除(mcpp 0.0.4+)
212-
"!*/src/ftxui/**/*_fuzzer.cpp",
213-
},
214-
targets = { ["ftxui"] = { kind = "lib" } },
215-
},
216-
}
217-
```
218-
219-
### 镜像源(GLOBAL / CN)
220-
221-
`xpm.<平台>.<版本>.url` 除了普通字符串,还支持镜像表,为不同地区提供下载源:
222-
223-
```lua
224-
["3.6.1"] = {
225-
url = {
226-
GLOBAL = "https://github.com/Mbed-TLS/mbedtls/archive/refs/tags/mbedtls-3.6.1.tar.gz",
227-
CN = "https://gitcode.com/mcpp-res/mbedtls/releases/download/3.6.1/mbedtls-3.6.1.tar.gz",
228-
},
229-
sha256 = "db75d2f7f35e29cf09f7bd6734d8ee3325f29c298ef071350c5e70a40dd4f0f9",
230-
},
231-
```
232-
233-
- **GLOBAL**(默认):上游原始地址(GitHub / 官方站点),行为与之前完全一致。
234-
- **CN**:[`mcpp-res`](https://gitcode.com/mcpp-res) 组织在 gitcode 上的镜像 —
235-
每个库一个仓库,资源以 release 资产形式按版本 tag 发布,URL 形如
236-
`https://gitcode.com/mcpp-res/<库>/releases/download/<版本>/<库>-<版本>.<ext>`。
237-
CN 镜像内容与 GLOBAL 源 **逐字节一致**(同一 `sha256`),只是托管在国内可
238-
快速访问的 gitcode 上。
239-
240-
切换镜像(底层透传给 xlings 安装引擎):
241-
242-
```bash
243-
mcpp self config --mirror CN # 使用国内镜像
244-
mcpp self config --mirror GLOBAL # 使用上游源(默认)
245-
```
246-
247-
> 镜像表遵循 [xpkg V1 规范](https://github.com/d2learn/xim-pkgindex/blob/main/docs/V1/xpackage-spec.md)
248-
> 的 `url = { GLOBAL=..., CN=... }` 约定,解析优先级 `GLOBAL > CN`。`validate`
249-
> workflow 会校验镜像表完整性并探测每个 CN 资源可达。
250-
251-
### 获取方式
252-
253-
mcpp 初次运行时自动 clone 本仓库到 `~/.mcpp/registry/data/mcpp-index/`。后续更新:
254-
255-
```bash
256-
mcpp search <keyword> # 触发索引刷新 + 搜索
257-
```
258-
259-
也可手动拉取:
260-
261-
```bash
262-
cd ~/.mcpp/registry/data/mcpp-index && git pull
263-
```
23+
收录两类包:
26424

265-
## 添加新包
25+
- **原生 mcpp 模块库** — 以 C++23 模块发布、`import` 即用(如 `mcpplibs.*`、`nlohmann.json`、`imgui`)。
26+
上游多自带 `mcpp.toml`,描述文件只声明元数据与下载地址。
27+
- **第三方 C/C++ 库(`compat`)** — 上游无 mcpp 支持,在描述文件里内联构建信息:header-only、纯 C 源码、
28+
C++23 module wrapper 等不同形态,可选组件经 `features` 门控,并配 GitCode CN 镜像。
26629

267-
1. Fork 本仓库
268-
2. 在 `pkgs/<首字母>/` 下创建 `<包名>.lua`,参考现有文件([compat.mbedtls.lua](pkgs/c/compat.mbedtls.lua)、[compat.ftxui.lua](pkgs/c/compat.ftxui.lua))
269-
3. 提交 PR — `validate` workflow 自动 lint,`deploy-site` 合入后自动发布到浏览站
30+
**新增一个包** → 参考 agent skill [`add-mcpp-index-package`](.agents/skills/add-mcpp-index-package/SKILL.md):
31+
完整 SOP —— 四种库形态模板、`gtc` CN 镜像闭环、`features` 门控、本地 + CI 验证。字段规范见
32+
[mcpp 扩展字段文档](https://github.com/mcpp-community/mcpp/blob/main/docs/04-schema-xpkg-extension.md)。
27033

271-
详细格式说明见 [mcpp 扩展字段文档](https://github.com/mcpp-community/mcpp/blob/main/docs/04-schema-xpkg-extension.md)。
34+
> 开 PR 后 `validate` 自动 lint + 按改动库选跑示例;合入后 `deploy-site` 发布到浏览站。
27235
27336
## 相关链接
27437

27538
| 项目 | 说明 |
27639
|------|------|
27740
| [mcpp](https://github.com/mcpp-community/mcpp) | 现代 C++23 构建 & 包管理工具 |
278-
| [xlings](https://github.com/d2learn/xlings) | mcpp 底层的包安装引擎 + 沙箱环境 |
41+
| [xlings](https://github.com/d2learn/xlings) | mcpp 底层包安装引擎 + 沙箱 |
27942
| [xpkg V1 spec](https://github.com/d2learn/xim-pkgindex/blob/main/docs/V1/xpackage-spec.md) | 包描述文件规范 |
280-
| [mcpplibs](https://github.com/mcpplibs) | mcpp 生态的模块化 C++23 库集合 |
281-
| [mcpp-res](https://gitcode.com/mcpp-res) | 包资源的 CN 镜像组织(gitcode release 资产) |
282-
| [xim-pkgindex](https://github.com/d2learn/xim-pkgindex) | xlings 的通用包索引仓库 |
43+
| [mcpplibs](https://github.com/mcpplibs) | mcpp 生态的模块化 C++23 库 |
44+
| [mcpp-res](https://gitcode.com/mcpp-res) | 包资源 CN 镜像组织(gitcode) |
28345

28446
## 社区
28547

286-
- **Issues / 反馈**: [mcpp issues](https://github.com/mcpp-community/mcpp/issues) · [mcpp-index issues](https://github.com/mcpp-community/mcpp-index/issues)
287-
- **讨论 / 论坛**: [d2learn 论坛](https://forum.d2learn.org)
288-
- **mcpplibs 库贡献**: 各库仓库接受 PR,CI 使用 mcpp 构建验证
48+
[mcpp issues](https://github.com/mcpp-community/mcpp/issues) · [d2learn 论坛](https://forum.d2learn.org)
28949

29050
## License
29151

292-
包描述文件: CC0。各上游库保留其自身许可证。
52+
包描述文件 CC0;各上游库保留其自身许可证。

0 commit comments

Comments
 (0)