原生 Linux C ABI
HotPDFLinuxABI.lpr 建置名為 libhotpdf.so.1 的原生 x86_64 ELF 共享程式庫，SONAME 為 libhotpdf.so.1，公開符號歸入 HOTPDF_1.0
此程式庫使用 THPDFHeadlessDocument 與 CPU 轉譯，執行期不需要 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 provider 的 pypdf、PyMuPDF、Pillow 與 NumPy
FPC_EXE、HPDF_LINUX_OUTPUT 與 PYTHON_EXE 選擇工具位置；預設驗收 Python 環境是 /opt/hotpdf-python/bin/python
FPC 通常會把匿名 export 區塊寫進其 ELF 連結器回應；建置會在連結前使用簽入的符號對應表為該區塊命名，因為加入第二個具名 version script 會與匿名區塊衝突
公開介面
引入 Lib/hotpdf_abi.h 取得共享記錄版面與狀態常數；hpdf_abi_io_v1_size 與 hpdf_abi_operation_v1_size 回報實際的原生記錄大小
Linux 程式庫匯出 ABI 探索、能力探索、文件建立與銷毀、回呼載入與儲存、頁數計算、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 | 交易式文字、choice、多選、核取方塊與選鈕更新、push-button 標題、相符的內嵌字型外觀與增量 PDF 輸出 |
annotations.export / annotations.import | 有界註解 XFDF 交換，含附加交易、精確 Unicode、二進位串流、popup/回覆參照、加密與經驗證的認證政策 |
forms.export / forms.import | 有界純量與富 FDF/XFDF 交換，為每個選取的設定富字族提供四種實際樣式、加密 PDF 交易、重新產生的外觀、簽章政策與同步分段回呼 |
render | Cairo PNG 輸出，含頁面、dpi、view 或 print 用途、註解選項與預設 optional-content 設定 |
sign | 增量 PEM 或 PFX 簽章、既有或新建欄位、可見外觀與認證，包括認證 AES-256 R5/R6 輸入與 摘要、中繼資料、設定檔與已驗證證據選項 |
signatures.verify | 實際 CMS 驗證、簽章修訂版長度、選填的明確 CA 信任評估與 簽章撤銷資訊驗證 |
html.import | 原生 HTML/CSS 文件建立，含 Unicode 字型、分頁、影像、超連結與選填 AcroForm 控制項 |
text.draw | 可見或不可見的 Unicode 頁面文字，保留原始頁面串流與經驗證的加密修訂版 |
ocr | 真實 Tesseract 辨識，子程序壽命設有上限，提供字詞結果與選填的可搜尋 PDF 圖層 |
pages.import | 選定頁面資源匯入，獨立來源輸入與交易式目的地更新 |
pdfa.convert | 點陣或文字/向量 PDF/A-4 轉換，含選填字型修復與所選模式的驗證要求 |
compare / compare.contract | 雙 handle 的頁數、頁面文字、物件數、轉譯影像、結構與完整比較，外加語意契約比較，可產生備妥的 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 簽章資訊、法律聲明、明確信任 bytes、已驗證的簽章撤銷證據、真實外觀預設，以及應用程式斷言的憑證或時間戳記傳輸來源
選填的 optional-content 檢視器狀態透過不變的 V1 記錄，提供明確的自動 View、Print 或 Export 用途套用、縮放、語言、使用者 context 與作業本機的手動選取
render 作業接受 usage: "view" 或 usage: "print"，預設 view；透過能力 renderUsages 陣列探索可選值，V1 回呼與作業記錄不變
註解的畫面與列印旗標跟隨所選用途；annotations: false 在兩種模式下都抑制註解，省略 optionalContent 會保留靜態預設設定，而明確物件會啟用已文件化的自動建議與操作內手動選取
Tests/Linux/Run-LinuxABIRenderUsage.sh 為一般與 AES R5/R6 來源驗證實際 PNG 像素，涵蓋預設關閉內容、回呼失敗、預算、取消與同 handle 復原；fixture 依賴與選填的預產 fixture 目錄見 Tests/Linux/HeadlessRenderUsage.en-us.md
回呼與生命週期
表單外觀選項接受 Unicode 文字、匯出值或完整選取陣列、明確按鈕狀態、字型設定與交易式資源限制
讀寫回呼可以回傳部分傳輸；成功的傳輸必須有正進度，且不得超過請求數量
所有回呼都在呼叫執行緒上同步執行，包括文件解析、轉譯與加密檢查點內的取消檢查
回呼輸入會複製進以 0600 模式獨佔建立的私有暫存檔，因此 Linux 輸入回呼與其 user data 只需在載入或 execute 呼叫回傳前保持有效
對共享文件 handle 的作業會在內部序列化；每個活動呼叫持有獨立參照，因此從進度回呼銷毀 handle 會使後續查找失效，同時讓目前呼叫安全完成
不要從回呼遞迴執行同一 handle 上的另一個作業；共享程式庫要保持載入，直到所有呼叫回傳且每個 handle 都已銷毀
預算與發布
JSON 輸入限 4 MiB 與 64 層巢狀，拒絕無效 UTF-8、重複成員、格式錯誤的數值上限，以及 Int64 到 Int32 的參數截斷
原始 UTF-8 與 Unicode 跳脫承載相同的字串值，包括以合法 UTF-16 代理對表示的增補字元；未配對代理對跳脫會在文件變更或二進位發布之前失敗
作業上限包括 memoryBytes、outputBytes、resultBytes 與 pixels；文件上限也套用於先前載入的 handle，而受管記憶體與轉譯上限不保證處理程序 RSS 上限
PDF 與 PNG 輸出會在輸出回呼開始前完整備妥並檢查；呼叫端自有的輸出回呼在其自身 I/O 失敗後可保留部分傳輸，但失敗的二進位或結果發布不會提交表單編輯，也不會取代先前載入的內容
成功的 PDF 變更會把備妥輸出提交為目前文件及其私有來源快照，因此後續同值的 FDF 或 XFDF 匯入會回傳精確的已提交 PDF bytes 並帶 updated=0，保留較早的表單填寫、帶型別富外觀、繪製文字與匯入頁面
私有暫存檔會在內容被取代或銷毀時移除；成功的增量表單與簽章輸出保留原始來源前綴與加密政策
證據
選填的封存字型修復啟用有界的 Ghostscript 替代與內嵌，並在回呼前做真實 PDF/A-4 驗證
原生標註審閱 PDF 為語意比較加入實際備妥的 PDF 輸出、Unicode 高亮與認證的 P3 註解權限
原生契約比較提供有界的雙 handle 語意比較、Unicode 審閱 HTML 與實際來源行幾何
一般原生文件比較正規化物件圖與串流編碼，以明確閾值比較真實 Cairo 像素，並保留文件狀態與回呼發布預算
驗收用戶端驗證真實 C 標頭版面與版本化符號查找、部分回呼、80 個並發共享 handle 作業、取消、Unicode 編輯、回溯與加密簽章
獨立的 pypdf、MuPDF 與 OpenSSL 讀取器驗證實際 PDF、PNG 像素、保留的密碼、安全字典、文件 ID、精確 ByteRange 間隙、有效簽章，以及對被修改簽章 bytes 的拒絕