Metadata-Version: 2.2
Name: rctk
Version: 1.1.1
Summary: Native CPython bindings for RCTK
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Programming Language :: C
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Project-URL: Repository, https://github.com/break-soul/rctk
Requires-Python: <3.15,>=3.14
Description-Content-Type: text/markdown

# rctk

## 项目定位

RCTK 1.1.1 是面向 Windows MinGW x64 与 Linux x86_64 的 C23 运行时工具库。核心 `rctk` 是公共库；`rctk-network` 是独立的实验性网络伴随库；`rctk-py` 封装 CPython 嵌入初始化；Python distribution `rctk` 则是独立的 CPython 3.14/3.14t 原生扩展。

| 组件 | 稳定性与边界 | 版本 / ABI |
|---|---|---|
| `rctk` | 核心 C API；`include/rctk/rctk.h` 是聚合头 | `1.1.1` / `0.0.3` |
| `rctk-network` | 实验性、单独包含和链接，不进入 `rctk.h` | `1.1.1` / `0.0.3` |
| `rctk-py` | CPython 嵌入库，不是可导入扩展 | `1.1.1` / `0.0.1` |
| Python `rctk` | CPython 3.14/3.14t 原生包，链接 core 与 network | `1.1.1` |

当前 RCTK 发布内容包含或链接尚未分离的受保护代码，因此暂不授予开源许可证，
并按专有软件发布。待受保护代码完成分离后再选择开源协议。wheel 内附带的第三方
许可证只适用于各自的第三方组件，不向 RCTK 本身授予开源许可。

新增 QUIC API 需要 OpenSSL 3.5 或更高版本。旧公开结构体布局未改变，但依赖 1.1.1 新符号的消费者必须使用当前头重新编译。正式 QUIC 的安全默认和范围见 [doc/module/quic.md](doc/module/quic.md)。

## 构建入口

RCTK 使用 `build.py` 作为统一构建入口。默认流程分为两步：先显式安装依赖，再执行构建与测试。

## 获取源码与前置条件

`doc` 与 `test` 是 Git submodule。克隆时应递归获取：

```bash
git clone --recurse-submodules <repository-url>
```

已有工作树可执行：

```bash
git submodule update --init --recursive
```

GitHub Actions 的 release workflow 只 checkout 根仓库，不读取 `doc`、`test`
submodule，因此不需要 `RCTK_SUBMODULE_TOKEN`。本地源码构建和 CTest 仍需按
上方命令递归获取 submodule；release workflow 的 checkout 均使用
`persist-credentials: false`。

构建前需要：

- CMake 3.21 或更高版本，以及可用的构建工具（推荐 Ninja）。
- Windows 使用 MinGW-w64 GCC；Linux 使用支持 C23 的 GCC/Clang。
- vcpkg：设置 `VCPKG_ROOT`，或把 vcpkg 仓库放在 RCTK 的同级目录。
- Python 3.14t（默认 free-threaded 模式）或 Python 3.14（`regular` 模式）及其开发文件。
- Windows 应设置 `RCTK_PY_PYTHON_ROOT`，指向包含 `include`、`libs` 和匹配运行时 DLL 的 Python 安装根目录。
- manifest 依赖包括 OpenSSL 3.5+、mimalloc、libarchive、zstd、lz4、xz、bzip2、zlib 与 libiconv；应通过固定 baseline 的 vcpkg manifest 解析，不要手工混用另一套 ABI 的库。

## 快速开始

Windows:

```powershell
$env:RCTK_PY_PYTHON_ROOT = 'D:\App\Python\Python314t'
python build.py deps
python build.py mingw release
```

默认链接 free-threaded Python 3.14t。需要常规 Python 3.14 ABI 时，令 `RCTK_PY_PYTHON_ROOT` 指向对应安装根目录并使用：

```powershell
$env:RCTK_PY_PYTHON_ROOT = 'D:\App\Python\Python314'
python build.py mingw release regular
```

Linux 默认同样链接 3.14t；构建脚本会从 `PATH` 或 `~/.local/bin` 查找匹配解释器：

```bash
uv python install 3.14t
python3 build.py deps
python3 build.py linux release
```

常规 Python 3.14 模式应单独安装 3.14：

```bash
uv python install 3.14
python3 build.py linux release regular
```

若希望显式指定平台，依赖安装也可以写成 `python build.py mingw deps` 或 `python3 build.py linux deps`。

`deps` 只安装 vcpkg manifest 依赖；完成后需要再次执行构建命令。普通构建不会隐式下载缺失依赖。

## 构建行为

- `build.py` 默认保留现有构建目录，重复运行不会重新触发 vcpkg 依赖重建。
- 3.14t 与常规 3.14 分别使用同级 `freethread`、`regular` 构建目录，clean 不会相互删除。
- 两种 ABI 的库先输出到各自的 `build/.../lib`，随后将当前构建复制到根 `lib`，测试不会加载另一种 ABI 的旧产物。
- 若已有可用且与构建类型、Python ABI、triplet 和优化级别匹配的 CMake cache，Step 1 会跳过 configure；不匹配时会自动重配。
- 传入 `reconfigure` 可强制重新执行 configure，传入 `clean` 可清理后全量重建。
- 若构建目录只剩残缺的 `CMakeCache.txt` 而缺少生成器产物，`build.py` 会先自动清理再重配。

示例：

```powershell
python build.py mingw release reconfigure
python build.py mingw release clean
```

## `build.py` 参数

参数按无序 token 解析；常用组合如 `python build.py mingw release regular clean`。支持的 token 为：

| token | 行为 |
|---|---|
| `mingw` / `linux` | 选择 `x64-mingw-static` / `x64-linux` 构建路径与平台配置；二者互斥。正式构建应显式指定；只有 `deps` 在省略时按受支持的宿主平台推导 triplet |
| `deps` / `install-deps` | 只安装当前 triplet 的 vcpkg manifest 依赖并退出，不继续 configure/build/test |
| `release` | 使用 Release；省略则使用 Debug |
| `o2` | Release 优化从默认 `-O3` 改为 `-O2` |
| `regular` | 选择启用 GIL 的 CPython 3.14 ABI 和 `regular` 构建目录 |
| `freethread` | 显式选择默认的 CPython 3.14t ABI 和 `freethread` 构建目录；与 `regular` 互斥 |
| `clean` | 只清理当前 triplet/ABI/mode 构建目录，然后 configure、build 并运行完整 CTest |
| `reconfigure` | 保留当前构建产物，但强制重新执行 CMake configure |
| `asan` | 仅 `linux`：C-only regular Debug，启用 ASan、UBSan 与 leak detection |
| `coverage` | 仅 `linux`：C-only regular Debug，运行 CTest 后生成 gcovr XML、HTML 和文本摘要，不设覆盖率阈值 |

`asan` 与 `coverage` 互斥，并且与 MinGW、`release`、`o2` 或 `freethread` 组合时立即失败。两种分析模式都关闭 network、Python 嵌入和 Python 扩展，因此不能代替四套 Release/Python ABI 构建。

## 实验性网络伴随库

构建会同时生成可选动态库 `rctk-network` 1.1.1（ABI/SOVERSION `0.0.3`）：Windows 发布 `librctk-network.dll` 与 import library，Linux 发布 `librctk-network.so` 及其版本链接。它依赖 `rctk`，提供 IPv4/IPv6、TCP、UDP、异步 DNS 与 QUIC UDP reactor；QUIC 复用 core 的 OpenSSL 3.5+ 实现，不引入另一套 QUIC/TLS 依赖。

该库使用独立头 `include/rctk-net/rctk-network.h`；QUIC reactor 另见 `include/rctk-net/quic.h`。它们不会进入 `rctk.h`，也不改变 `rctk-py`。所有阻塞网络操作由调用方传入的 `RCThreadPool` 执行。API、Future 结果、所有权和并发约定见 [doc/rctk-network.md](doc/rctk-network.md)。

## Python 原生绑定

`src/rctk-python-shared` 构建 CPython 3.14/3.14t 原生包。Python distribution、PyPI 项目名和导入名均为 `rctk`，私有扩展模块为 `rctk._native`；它与用于嵌入解释器的 `rctk-py` 是两个独立组件。

常规 `build.py` 会把可导入的 build-tree 包输出到当前 ABI 构建目录的 `python/rctk`，并通过 CTest 验证 Data/Collection、二进制 File、压缩、RPK、System、crypto/X509、原生 Future/日志/网络、no-GIL 和子解释器行为。扩展同时链接 `rctk` 与实验性 `rctk-network`；修复后的 wheel 在包内携带这两套动态库。发布只提供 Windows AMD64 与 manylinux x86_64 的 cp314/cp314t wheel，不构建或发布 sdist。

从 PyPI 安装：

```bash
python -m pip install rctk
```

`workflow_dispatch` 只构建并 repair Windows/manylinux 的四个 wheel，随后执行
严格的四 wheel 集合校验和 Twine 检查并上传 Actions artifact，不发布 PyPI。
release workflow 不再运行完整 CTest 或 wheel 运行时 smoke。推送与
`pyproject.toml` 版本完全一致的 tag 后，构建、repair 和静态发布门禁全部通过
才会使用 GitHub OIDC Trusted Publisher 发布 wheel；工作流不保存 PyPI 密钥。

wheel job 缓存精确的 `vcpkg_installed` 完整安装树，不缓存 vcpkg binary cache、
`.vcpkg-ci`、buildtrees 或 wheel。Windows 缓存在 checkout 内的
`vcpkg_installed`；manylinux 的 host cache 固定放在工作区外的
`RUNNER_TEMP/rctk-vcpkg-installed`，再 bind 到容器内
`/project/vcpkg_installed`，避免缓存树进入 cibuildwheel 的源码复制。两平台
使用独立 cache scope；key 包含 triplet、固定 vcpkg baseline、Windows GCC 与
MinGW package 身份或 manylinux 镜像 digest，以及依赖输入文件 hash。cache 命中后仍执行
`vcpkg install` 核对并补齐安装树，cache miss 则从冷构建开始。

```python
import rctk

values = rctk.Array(rctk.Int)
values.append(rctk.Int(42))
assert values[0].value == 42

table = rctk.Table(rctk.Str, rctk.Int)
table[rctk.Str("answer")] = rctk.Int(42)
assert table[rctk.Str("answer")].value == 42
```

领域能力保留在模块命名空间中：`rctk.rpk` 以路径、`PathLike[str]` 或
`Buffer`（包括 `File`）读写普通/加密 RPK，并为包体和返回成员分别设置
64 MiB 默认内存上限；`rctk.system` 提供环境变量、程序/工作目录、用户目录和
目录创建接口。两者不会把函数摊平到 `rctk` 顶层。

接口、wheel 布局和支持范围见 [doc/rctk-python-shared.md](doc/rctk-python-shared.md)。

## 依赖说明

- 普通构建命令不会在 Step 1 隐式安装缺失依赖；若预装依赖不完整，脚本会直接提示先执行 `deps`。
- `python build.py deps` 会按宿主平台自动映射默认 triplet：Windows 为 `x64-mingw-static`，Linux 为 `x64-linux`。
- Linux 需要与所选模式匹配的 Python 3.14 开发运行时；可用 `RCTK_PY_PYTHON_EXECUTABLE` 显式指定解释器，或用 `RCTK_PY_PYTHON_ROOT` 指定安装根目录。
- 如果 `vcpkg_installed/x64-mingw-static` 来自旧构建，或 overlay triplet 已更新，建议重新执行依赖安装，避免继续复用旧二进制。

## 文档

- API 文档入口见 [doc/README.md](doc/README.md)。
- 实验性网络伴随库见 [doc/rctk-network.md](doc/rctk-network.md)。
- 测试布局、定向运行与完整门禁见 [doc/testing.md](doc/testing.md)。
- Python 初始化封装见 [doc/rctk-py.md](doc/rctk-py.md)。
- Python 原生包与 wheel 约定见 [doc/rctk-python-shared.md](doc/rctk-python-shared.md)。
- 正式 QUIC pump、安全默认与 v1 限制见 [doc/module/quic.md](doc/module/quic.md)。

## C / CMake 消费与产物

当前 native 构建没有通用 `cmake --install` 规则，也不生成 `find_package(rctk)` config/export。消费者可把源码作为子目录并显式传播 include 路径：

```cmake
set(RCTK_SOURCE_DIR "/path/to/rctk")
set(RCTK_BUILD_PY_EMBED OFF CACHE BOOL "" FORCE)
set(RCTK_BUILD_PYTHON_SHARED OFF CACHE BOOL "" FORCE)
set(RCTK_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(RCTK_ENABLE_PUBLISH OFF CACHE BOOL "" FORCE)
add_subdirectory("${RCTK_SOURCE_DIR}" rctk-build EXCLUDE_FROM_ALL)

target_include_directories(my_app PRIVATE "${RCTK_SOURCE_DIR}/include")
target_link_libraries(my_app PRIVATE rctk) # 需要 reactor 时再加 rctk-network
```

顶层 consumer 必须在首次 `project()` 前选择与 RCTK 匹配的 vcpkg toolchain/triplet，并让 `VCPKG_INSTALLED_DIR` 指向该 triplet 的 manifest 依赖；上述片段不隐式下载依赖。

也可以在 `build.py` 完成后直接使用 `include/` 和当前构建的 `build/<triplet>/<mode>/lib`；根 `lib/` 是方便既有消费者的当前构建副本，不是可并存的多 ABI 安装前缀。运行时必须让匹配的 DLL 或 `.so` 可被动态加载器找到，并同时校验 core/network ABI。Python 消费者应安装 PyPI 发布或 dry-run 生成并通过严格 wheel 集合、metadata、许可证与 Twine 校验的 wheel，而不是把 build-tree `python/rctk` 当作部署格式。

最小 C consumer：


```c
#include <rctk/rctk.h>

int main(void) {
  RCInt* value = rc_new_int(42);
  if (value == NULL) return 1;
  RC_UNREF(value);
  return 0;
}
```

常规构建产物包括：

- 当前 ABI 目录下的 core、可选 network、`rctk-py` 动态库和 Windows import libraries；
- 非零 CTest executable 集合与可导入的 build-tree `python/rctk`；
- coverage 模式下的 `coverage.xml`、HTML details 和摘要；
- release workflow 生成的 Windows AMD64 与 manylinux x86_64 cp314/cp314t wheel artifacts。

`workflow_dispatch` 只上传 Actions artifact；版本 tag 通过 wheel 构建、repair、
严格 validator 与 Twine 门禁后仅向 PyPI 发布 wheel，不生成 sdist，也不创建
GitHub Release。分析构建示例：

```bash
python3 build.py linux asan clean
python3 build.py linux coverage clean
```
