从第一个程序，到完整的工程。

#define XRT_IMPLEMENTATION
#include "xrt.h"
#include <stdio.h>

int main(void)
{
    printf("XRT %s\n", XRT_VERSION_TEXT);
    return 0;
}

cc -std=c11 -O2 main.c -o hello
./hello

gcc -std=c11 -O2 main.c -o hello.exe
.\hello.exe

构建系统与已验证示例

网络示例位于仓库 examples/ 与扩展库的 examples/， 可结合对应测试套件学习调用与生命周期。统一构建入口 tools/build.py 提供： SHA256 指纹增量编译、模块依赖闭包展开、Windows 长命令自动切换响应文件； GCC / Clang / MSVC（含 clang-cl）/ TCC 四族编译器可互换。build.bat 与 build.sh 只是它的薄封装。

git clone https://gitee.com/xywhsoft/xrt.git
cd xrt

# 默认：构建并运行内核测试（Windows 用 build.bat，Linux/macOS 用 ./build.sh）
python tools/build.py

# 指定套件：模块名、逗号组合或 all；--jobs 并行，--start-test 从失败处续跑
python tools/build.py --suite core,concurrency --jobs 4
python tools/build.py --suite all --start-test test_http_client

# 扩展库：叠加扩展清单
python tools/build.py --manifest extlibs/xhttp/config/modules.json --suite xhttp_tests
python tools/build.py --manifest extlibs/xws/config/modules.json --suite xws_tests

# 打包静态库 / 动态库，并编译运行消费者程序验证
python tools/package.py --kind static --verify
python tools/package.py --manifest extlibs/xhttp/config/modules.json --kind shared --verify

# 单头产物再生成（支持 --manifest 与 --check 漂移校验）
python tools/amalgamate.py

选择发布形态

单头（适合快速集成）

/* single/xrt.h 自包含全部实现；扩展库同理（如 extlibs/xhttp/single/xhttp.h） */
#define XRT_IMPLEMENTATION
#include "xrt.h"

模块化 / 库（适合工程集成）

用 tools/package.py 产出静态库或动态库（含导入库），或直接把内核源码纳入你的构建—— 模块清单已经声明每个源文件的归属与依赖。头文件路径统一为 <xrt/xxx.h>。 按项目边界选择，而不是按术语选择：原型与工具用单头，产品构建用库。

特性裁剪体系

裁剪以模块宏为单位：定义 XRT_MODULE_<NAME> 后，include/xrt/features.h （由 tools/generate_features.py 从 modules.json 生成）自动展开其依赖闭包并置位对应的 XRT_FEATURE_* 宏；缺失依赖会在头文件中直接 #error。

/* 只要 TCP 网络与协程 */
#define XRT_MODULE_NET_TCP
#define XRT_MODULE_COROUTINE
#include "xrt.h"

/* 全部启用 */
/* #define XRT_MODULE_ALL */

裁剪的正确性由两道门禁保证：

• trim 反向验证（build.py --trim-only）：对每个模块故意去掉其直接依赖宏，要求编译必须失败，防止守卫缺失。
• 符号禁令（measure_size.py）：最小 core 裁剪产物禁止出现 xrtNet / xrtHttp / xrtWs / xrtTls / xrtRegex 等前缀符号，二进制级防止功能蔓延。

扩展库有平行的宏体系（XHTTP_MODULE_*、XWS_MODULE_*…），由 generate_extension_features.py 生成，并连锁要求内核模块宏。

认识 XRT

XRT 是一整套成体系的跨平台 C 基础设施库，目标是在互联网 + AI 时代提供零第三方运行时依赖的完整基础设施闭环。 v2.0 起，仓库分为两部分：

• 内核（src/ + include/xrt/）：并发协程、五后端网络引擎、TLS、HTTP/WebSocket 协议核心、内存与容器、文件与进程、正则与模式匹配。公开头文件 94 个；模块清单声明 386 个不同的特性宏。
• 扩展库（extlibs/）：五个按领域拆分的独立产品——xhttp、xws、xruntime、xmail、xssh。每个都是自包含小项目（自己的 src / include / tests / examples / config / single），单向依赖内核。正则库 xregex 已并入内核 regex 模块。

两种消费形态：模块化源码 / 静态库 / 动态库，或者自包含单头（内核与每个扩展库各有单头产物）。

仓库结构导览

并发模型：按问题选择，不必全都使用

线程、协程、Channel、Future、任务组与取消令牌分别解决不同边界。先确认工作是否需要真实并行、等待 I/O、传递消息、组合结果，还是需要统一停止；再选最小的一组机制。

内核模块地图

按体系分组的模块速查（公开头位于 include/xrt/；完整的逐 API 文档见 API 参考手册）：

扩展库指南

每个扩展库目录结构一致：src/ include/ tests/ examples/ bench/ config/modules.json single/ docs/。公开头沿用 xrt/ 命名空间，与内核头无缝拼接。

测试与示例的组织

测试文件名后缀编码了测试维度，同一契约会以多个变体出现（如 test_http_client_iocp.c 只有一行 #define + #include "test_http_client.c"）：

内核与五个扩展库提供 680 个示例 C 文件和 2,512 个测试 C 文件。通过模块清单找到对应源码与构建入口，沿调用流程深入实现。

建议学习路径

1. 跑通构建：python tools/build.py --suite core，观察指纹增量与测试输出。
2. 读示例：从 examples/ 挑选感兴趣模块的 main.c，理解初始化、调用和资源收尾。
3. 读测试：结合 tests/<模块>/ 中的断言，理解接口行为与边界条件。
4. 裁剪上手：用 XRT_MODULE_* 宏裁出你需要的最小集合，--trim-only 验证。

资源链接

• Gitee 仓库 — 源码、Issue 跟踪
• API 参考手册 — 96 个模块的逐 API 文档
• 架构总览 — 内核 + 扩展库分层图