原生 Linux C ABI
HotPDFLinuxABI.lpr 构建名为 libhotpdf.so.1 的原生 x86_64 ELF 共享库，SONAME 为 libhotpdf.so.1，公共符号指派给 HOTPDF_1.0
该库使用 THPDFHeadlessDocument 与 CPU Render，运行时不依赖 Windows 组件、活动桌面、PDF 阅读器或 Python 进程；Python 由构建与验收脚本使用
构建与验收
sh Tests/Linux/Build-LinuxABI.sh
sh Tests/Linux/Run-LinuxABIAcceptance.sh
FPC_EXE=/usr/local/bin/fpc HPDF_LINUX_OUTPUT=Tests/Linux/bin/linux-abi331 sh Tests/Linux/Run-LinuxABIAcceptance.sh使用原生 FPC 3.2.2 或更新版本，带 FCL 与 paszlib、C 编译器、binutils、Fontconfig 与已安装的 TrueType 字体；验收 Python 环境还需要带 AES 提供方的 pypdf、PyMuPDF、Pillow 与 NumPy
FPC_EXE、HPDF_LINUX_OUTPUT 与 PYTHON_EXE 选择工具位置；默认验收 Python 环境为 /opt/hotpdf-python/bin/python
FPC 通常把匿名导出块写入其 ELF 链接器响应；构建在链接前用签入的符号映射命名那个块，因为再加一个具名 version script 会与匿名块冲突
公共接口
包含 Lib/hotpdf_abi.h 以获得共享记录布局与状态常量；hpdf_abi_io_v1_size 与 hpdf_abi_operation_v1_size 报告真实的原生记录大小
Linux 库导出 ABI 发现、能力发现、文档创建与销毁、callback 加载与保存、页数统计、hpdf_document_execute_json_v1 以及双文档 hpdf_document_compare_json_v1 入口点
通过 hpdf_capabilities_json_to_io 发现当前操作，不要假定 Windows 操作集
| 操作 | 行为 |
|---|---|
info | 页面、表单与已签名字段计数 |
text.extract | JSON 与可选 UTF-8 输出中的 Unicode 页面文本，支持可选的从零开始 pages 数组 |
forms.read | 全限定字段名、Unicode 值、完整 choice 选择、类型、标志与最大长度 |
forms.fill | 事务性 text、choice、multiselect、checkbox 与 radio 更新、push button caption、匹配的内嵌字体外观与增量 PDF 输出 |
forms.export / forms.import | 有界的 scalar 与富文本 FDF/XFDF 交换，每个选定的已配置富字体族四种真实样式、加密 PDF 事务、重新生成的外观、签名策略与同步分片 callback |
render | Cairo PNG 输出，带 page、dpi、view 或 print usage、注释选项与默认可选内容配置 |
sign | 增量 PEM 或 PFX 签名、既有或新建字段、可见外观与认证，包括已认证的 AES-256 R5/R6 输入与 摘要、元数据、profile 与经验证证据选项 |
signatures.verify | 真实 CMS 验证、已签名修订长度、可选的显式 CA 信任评估与已签名吊销信息验证 |
compare / compare.contract | 双句柄页数、页面文本、对象数、Render 图像、结构与完整比较，外加带准备好的 JSON、HTML 或注释 PDF 审阅输出的语义契约比较 |
{"schemaVersion":1,"type":"render","page":0,"dpi":150,"usage":"print","annotations":false,
"limits":{"memoryBytes":268435456,"outputBytes":268435456,"pixels":100000000}}原生签名工作流接受显式的 PEM 或 Base64 PFX 身份、可选的新签名字段与 Unicode 外观以及认证权限；签名成功会把已加载上下文替换为准备好的已签名修订，签名或发布失败则保留原始上下文
原生签名选项绑定真实的 SHA256、SHA384 或 SHA512 选择、Unicode 签名信息、法律声明、显式信任字节、经验证的已签名吊销证据、真实外观预设以及应用声明的凭据或时间戳传输来源
可选的可选内容阅读器状态通过未变更的 V1 记录提供显式的自动 View、Print 或 Export usage 应用、缩放、语言、用户上下文与操作局部的手动选择
render 操作接受 usage: "view" 或 usage: "print"，默认 view；可通过能力 renderUsages 数组发现可选项，V1 callback 与操作记录保持不变
注释屏幕与打印标志跟随所选 usage；annotations: false 在任一模式下抑制注释，默认可选内容配置应用于页面、XObject 与注释内容，而不执行交互式阅读器 usage 应用
Tests/Linux/Run-LinuxABIRenderUsage.sh 验证普通与 AES R5/R6 源的真实 PNG 像素、默认关闭内容、callback 失败、预算、取消与同句柄恢复；fixture 依赖与可选的预生成 fixture 目录见 Tests/Linux/HeadlessRenderUsage.en-us.md
callback 与生命周期
表单外观选项接受 Unicode 文本、导出值或完整选择数组、显式按钮状态、字体设置与事务性资源限制
读写 callback 可以返回部分传输；成功传输必须取得正进度且不得超过请求的数量
所有 callback 都在调用线程上同步执行，包括文档解析、Render 与密码学检查点内的取消检查
callback 输入被复制到以 0600 权限独占创建的私有临时文件，因此 Linux 输入 callback 及其用户数据只需在 load 或 execute 调用返回前保持有效
共享文档句柄上的操作在内部串行化；每个活跃调用持有独立引用，因此从进度 callback 销毁句柄会使后续查找失效，同时允许当前调用安全完成
不要在 callback 里递归地对同一句柄执行另一个操作；保持共享库加载直到所有调用返回且每个句柄都已销毁
预算与发布
JSON 输入限制为 4 MiB 与 64 层嵌套，拒绝无效 UTF-8、重复成员、格式错误的数值限制与 Int64 到 Int32 的参数截断
原始 UTF-8 与 Unicode 转义承载相同的字符串值，包括由有效 UTF-16 代理对表示的增补字符；不成对的代理转义在文档变更或二进制发布之前失败
操作限制包括 memoryBytes、outputBytes、resultBytes 与 pixels；文档限制也适用于先前加载的句柄，而托管内存与 Render 限制不承诺进程 RSS 上限
PDF 与 PNG 输出在输出 callback 开始之前完整准备并检查；调用方自有的输出 callback 在自身 I/O 失败后可能保留部分传输，但失败的二进制或结果发布不会提交表单编辑，也不会替换先前加载的上下文
成功的 PDF 变更把准备好的输出同时提交为当前文档与其私有源快照，因此后续相同值的 FDF 或 XFDF 导入返回精确的已提交 PDF 字节并带 updated=0，保留更早的表单填充、typed 富文本外观、绘制的文本与导入页面
私有暂存文件在上下文被替换或销毁时移除；成功的增量表单与签名输出保留原始源前缀与加密策略
证据
可选的归档字体修复启用有界的 Ghostscript 替换与内嵌，并在 callback 之前进行真实的 PDF/A-4 验证
原生注释审阅 PDF 为语义比较添加真实的准备好的 PDF 输出、Unicode 高亮与已认证的 P3 注释权限
原生契约比较提供有界的双句柄语义比较、Unicode 审阅 HTML 与真实的源行几何
通用原生文档比较规范化对象图与流编码，以显式阈值比较真实 Cairo 像素，并保留文档状态与 callback 发布预算
验收客户端验证真实的 C 头文件布局与带版本符号查找、部分 callback、80 个并发共享句柄操作、取消、Unicode 编辑、回滚与加密签名
独立的 pypdf、MuPDF 与 OpenSSL 阅读器验证真实 PDF、PNG 像素、保留的密码、安全字典、文档 ID、精确 ByteRange 间隙、有效签名以及对已修改签名字节的拒绝