# tape-library

**Repository Path**: gycherish/tape-library

## Basic Information

- **Project Name**: tape-library
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tape-library

面向磁带库的 C++23 管理与读写库: 在块级/SCSI 命令层封装磁带驱动器(tape drive)与换带机(medium changer)的读写、定位、盘点与搬带原语, 供上层应用构建归档、索引或 LTFS 等方案。

> 早期开发中。当前已落地构建骨架与统一错误模型; 传输、协议、设备各层正按需求逐步实现。范围与设计以 [doc/](doc/) 下的正式文档为准。

## 能力范围

- **驱动器读写**: 变长/定长块读写、filemark/setmark、SPACE 相对定位与 LOCATE 绝对定位、READ POSITION、装卸带、读写兼容性判定、容量与 MAM 卡带信息查询
- **换带机控制**: READ ELEMENT STATUS 盘点(存储槽/驱动器/导入导出口/机械臂)、MOVE MEDIUM 搬带、条码识别
- **设备发现与拓扑**: 枚举系统 SCSI 设备并经 DVCID 建立"磁带库 → 驱动器"归属关系
- **明确不含**: 归档/卷格式(tar、索引、LTFS 卷布局)由应用层负责; 并发编排与跨进程仲裁由调用方负责; 介质分区与加密本期未实现(仅预留)

## 设计要点

- **原生 SCSI 直通**: 本期 Linux 走 SG_IO; 直通实现由平台在编译期选择, 为后续平台预留([ADR-0001](doc/adr/0001-scsi-passthrough.md))
- **阻塞同步核心**: 设备层为纯阻塞 API, 无协程与库内线程; 并发运行多台设备、异步包装均交由调用方([ADR-0002](doc/adr/0002-async-model.md))
- **统一错误码**: 全库单一 `tl::error_code`(基于 `<system_error>`), 以 `std::expected` 返回
- **平台**: 本期仅支持 Linux(构建锁定 Linux), 平台相关点隔离以便未来接入其他平台; 严格遵循 [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines)

## 目录结构

| 目录 | 用途 |
|------|------|
| `include/tl/` | 公共头文件(命名空间 `tl`) |
| `src/` | 源文件与私有头文件 |
| `tests/` | 测试(catch2; 集成测试依赖 mhvtl 虚拟磁带库) |
| `tools/` | 命令行工具 `tlmt`(驱动器)/ `tlmtx`(换带机)/ `tlscan`(发现) |
| `doc/` | 文档源(产品/需求/设计/决策/手册/开发/API) |

## 环境要求

- [xmake](https://xmake.io/) ≥ 3.0 —— 构建并经 xrepo 自动拉取 C++ 依赖
- C++23 编译器 —— GCC 或 Clang(本期仅 Linux)
- [mhvtl](https://github.com/markh794/mhvtl) —— 运行集成测试所需的虚拟磁带库(Linux; 无硬件时使用)
- [pixi](https://pixi.sh/) —— 文档工具链(不构建文档可不装)

## 快速开始

### 构建与测试

```
xmake f -m debug      # 配置(开发期使用 Debug)
xmake build           # 编译
xmake test            # 运行测试
```

### 文档

```
pixi install          # 首次: 安装文档工具链
xmake doc             # 构建 HTML 站点 -> build/doc/html
xmake doc-serve       # 本地预览(热重载)
xmake doc-pdf         # 生成 PDF(需系统 TeX)
xmake doc-versions    # 逐版本构建 + 版本切换器
```

## 文档导航

| 文档 | 路径 |
|------|------|
| 产品与需求 | [doc/product/index.md](doc/product/index.md) |
| 架构与设计 | [doc/design/index.md](doc/design/index.md) |
| 决策记录 | [doc/adr/index.md](doc/adr/index.md) |
| 开发文档 | [doc/dev/index.md](doc/dev/index.md) |
| 完整站点 | 运行 `xmake doc` 后打开 `build/doc/html/index.html` |

## 面向 AI 工具

本仓库的开发指令统一维护在 [CLAUDE.md](CLAUDE.md); 任何 AI 编码工具(Claude Code、OpenAI Codex、Cursor 等)经 [AGENTS.md](AGENTS.md) 指向它。开始编码前请先完整阅读并遵循。

## 许可证

本项目以 [MIT 许可证](LICENSE)发布。