Native Linux and macOS
For Windows 11 ARM64 and Delphi ARM64EC builds, see Windows on ARM
The native FPC backend supports headless library workflows on Linux and macOS, with separate x64 and ARM64 targets producing actual ELF and Mach-O programs; Delphi builds macOS headless dylibs for both architectures
Use the existing TPDFlib API for PDF creation, saving/loading, text extraction and editing, structured extraction, portable OCR callbacks, bitmap rendering, metadata, encryption, network range access and native PFX signing
Native platform matrix
| Platform | Native environment | Compiler route |
|---|---|---|
| Linux x64 | Ubuntu WSL 2 or a physical x64 Linux host | FPC x86_64-linux |
| Linux ARM64 | ARM64 Linux host or virtual machine, including Multipass | FPC aarch64-linux |
| macOS x64 | Intel Mac | Native FPC x86_64-darwin or Delphi OSX64 |
| macOS ARM64 | Apple silicon Mac | Native FPC aarch64-darwin or Delphi OSXARM64 |
Use FPC 3.3.1 with matching RTL/packages and a target that matches the operating system and architecture of your application
Runtime dependencies
| Provider | Library | Purpose |
|---|---|---|
| OpenSSL 3 | libcrypto | AES CBC/GCM, digests, PKCS12 identities, CMS signatures, integrity and explicit trust-anchor chains |
| libcurl | libcurl with asynchronous DNS | HTTP/HTTPS, bounded binary transport, range access and RFC 3161 requests |
| Cairo | libcairo | Bitmap image surfaces, paths, clipping, glyph outlines and images |
| Fontconfig | libfontconfig | Actual native font-file matching, including explicit family substitution |
| libxml2 | System libxml2 on macOS | Delphi XMP XML parsing, namespace-aware editing and serialisation |
| OpenJPEG 2 | libopenjp2 | JPEG 2000 decoding and encoding |
Linux x64 and ARM64 load their architecture-matched system SONAMEs; macOS ARM64 defaults to /opt/homebrew, macOS x64 defaults to /usr/local, and both use the system libcurl and libxml2
Missing libraries, symbols or unsupported operations produce explicit failures; no Windows device-context substitute is used
Signing and time stamps
The default PFX provider supports actual RSA and EC identities, detached CMS, CAdES and legacy attached SHA1 profiles; verification checks PDF ByteRange bytes and the CMS signature
Certificate-chain verification requires explicit trust anchors; embedded certificates do not grant trust, and integrity alone does not imply trust
ApplyPAdESSignatureTimeStamp uses the configured default native HTTP transport to fetch and attach a real RFC 3161 token; reserve enough /Contents capacity before the original signature
Time-stamp verification checks the signed token, message imprint, exclusive critical timeStamping EKU, TSA name, optional expected policy/nonce and the trusted certificate chain at token generation time
Document time stamps also verify the actual PDF ByteRange imprint; the caller can use the existing DocTimeStamp passthrough workflow and supply the token
Metadata and rendering
The FPC and Delphi macOS XMP providers use real namespace-aware DOMs and preserve unrelated properties during edits; Delphi uses the system libxml2 parser and serialiser
DTD declarations are rejected by the XML reader regardless of source encoding; input and decoded characters are bounded, and a streaming pass limits depth and node events before DOM construction
Rendering uses real native bitmap storage and Cairo image surfaces; banded rendering preserves device-space coordinates and uses guard rows to keep boundary antialiasing consistent
Native family-font embedding resolves an actual Fontconfig file and embeds a complete standalone TrueType program with CIDFontType2, Identity CIDToGIDMap, initialised metrics and Unicode widths; BMP text and portable OCR layers survive PDF save/reload
The entry rejects unembedded family fonts, collections, CFF programs and bitmap-only embedding rights; restricted embedding requires the existing explicit rights override, and fonts that prohibit subsetting remain complete programs
Limits
- Windows device contexts, EMF, GUI, clipboard and printing are outside the native headless backend
- Complex native text shaping and Windows system certificate-store identities are unavailable
- The standalone TrueType embedding entry currently supports BMP text; supplementary-plane text, TTC face extraction and CFF embedding are outside this entry
- Online OCSP/CRL revocation is unavailable; requests for revocation verification report an unknown result
- The default native PFX provider rejects RSA-PSS and extra policy, commitment or revocation signing attributes
- Native CMYK/ICC transforms and indexed one-bit BMP writing are unavailable
- HTTP requires asynchronous DNS support in libcurl to honour DNS lookup timeouts
Compiler prerequisites
Check the selected FPC version, target CPU and target operating system before building your application
fpc -iV
fpc -iTP
fpc -iTO
Use -n @/path/to/fpc.cfg when selecting an explicit compiler configuration; keep the RTL and package paths consistent with the compiler version and target
Do not add -FcUTF8, because it changes high-byte AnsiString handling and can corrupt binary PDF identifiers and encryption values
macOS C ABI dynamic library
See Dylib build configuration and usage for local configuration templates, the complete output matrix, deployment, C ABI ownership and a working Python example
The existing 880-entry dynamic-library export surface can be built with native Free Pascal on macOS x64 or ARM64 or cross-compiled from Windows with Delphi; both expose the same C symbol names
export FPC=/path/to/aarch64-darwin/fpc
export PDFLIB_FPC_CONFIG=/path/to/fpc.cfg
bash Dylib/Build-native.sh release full
python3 Dylib/examples/create_pdf.py Dylib/OSXARM64/FPC-release-full/libPDFlibDylib.dylib /tmp/hello-dylib.pdf
On an x64 Mac select a native x86_64-darwin compiler and use the corresponding Dylib/OSX64/FPC-release-full output path
Omit PDFLIB_FPC_CONFIG when the compiler already has a valid configuration; use debug trial for the separate trial build, or set PDFLIB_DYLIB_OUTPUT to an external output directory
The C ABI uses 32-bit opaque instance handles and UTF-16 PWideChar strings on both Intel and ARM64 systems; foreign-language bindings must supply UTF-16 code units rather than the host's native wchar_t representation
DLCreateBuffer returns writable data owned by its instance, including embedded zero bytes; DLReleaseBuffer returns 1 on success and 0 for an unknown or already released buffer, and releasing an instance invalidates all its buffers and returned strings
Instance 0 remains the default instance alias; explicit positive handles are not reused during the loaded library's lifetime, and unloading frees outstanding instances and buffers
Serialise calls that use the same instance, and serialise instance creation or release against other C ABI calls; the registry lock does not protect an instance after lookup
Delphi cross-compilation
The Windows build scripts select dccosx64 or dccosxarm64, require a local macOS SDK cache, separate full and trial output and validate the produced Mach-O header before publishing the build output
Set PDFLIBPAS_MACOS_SDK or pass sdk path; PDFLIBPAS_MACOS_LINKER can select a Mach-O LLVM linker named ld64.lld.exe when the installed default linker cannot read the SDK's .tbd files
Delphi uses POSIX file APIs, named RCDATA resources, system zlib and libcurl, the shared native OpenSSL/Fontconfig/Cairo/OpenJPEG providers and Apple ImageIO for JPEG images
set PDFLIBPAS_MACOS_SDK=C:\SDKs\MacOSX.sdk
set PDFLIBPAS_MACOS_LINKER=C:\LLVM\bin\ld64.lld.exe
Dylib\Build-dylib.bat osxarm64
Dylib\Build-dylib-TRIAL.bat osxarm64 debug
Dylib\Build-dylib.bat osx64
Dylib\Build-dylib-TRIAL.bat osx64 debug