libharu — the Haru Free PDF Library — dates back to 1999, is zlib-licensed and speaks fluent PDF: TrueType and Type1 fonts, JPEG and PNG images, links and annotations, outlines, RC4 encryption, even PDF/A-3 with a Factur-X payload. What it does not speak is PureBasic, and a C header is not an API until something binds it.

hpdf.pbi is that something. One include for PureBasic 6.40, three DLLs beside the exe, and a deliberate refusal to involve the linker: every function is bound at runtime through OpenLibrary() + GetFunction() + Prototypes. The whole package — wrapper, module, DLL sets and the 24 ported samples — is free to use and lives on GitHub: tureluut/pb-wrapper-libharu.

Bound at runtime, checked at init

The obvious route is a link-time import: declare the functions, hand the linker an import library, ship. The wrapper takes the runtime route instead, and the reasons are all operational. The DLLs can live anywhere — HaruInit("libraries/windows/x64/") points at them, or pass nothing and the exe directory is searched first. A wrong or truncated DLL is not rewarded with a cryptic linker error or a mid-run crash: HaruInit() binds every export, counts what succeeded and lists what did not. If a single one is missing, it closes everything and returns 0 — there is no half-bound state to fall into.

One Windows subtlety earns its comment block. hpdf.dll itself imports zlib.dll and libpng16.dll; when those live outside the default search path, the loader can bind hpdf and still fail to resolve its imports. So HaruInit(dir$) opens zlib and libpng first — Windows reuses already-loaded modules by name when it resolves hpdf’s imports, and the dependency question answers itself.

The same include compiles on Linux unchanged. Prototypes and GetFunction() are cross-platform, so only the loader branches: dlopen has no exe-directory search, so that path is resolved via ProgramFilename(), the current directory needs an explicit ./ prefix, and libhpdf.so is tried with and without the versioned .so.2 suffix that distro runtime packages install. zlib and libpng need no preload there — ld.so settles dependencies on its own.

Hello, PDF

The lifecycle contract is three lines and non-negotiable: HaruInit() once before anything else — every HPDF_* name is a function pointer, and calling a pointer before init dereferences null — then HaruFree() for every document and HaruShutdown() at exit. Everything in between is ordinary drawing code:

The thin Haru* layer exists because a 1:1 C binding alone is not pleasant to live with. HaruNew() switches on the UTF-8 encodings and sets the UTF-8 encoder, so strings go in as UTF-8 and come out as text. HaruTextOut() wraps BeginText/EndText around itself — the raw HPDF_Page_TextOut refuses to run outside a text object, a gmode detail every C sample handles by hand. HaruTTFFont() caches per document and path, and quietly retries plain TTFs through the TTC-only export that libharu 2.4.6 routes them to. HaruAlpha() caches ExtGState objects per alpha value. None of it hides the library; it removes the three or four places where the C API punishes the unwary.

Types, kept 1:1 with the header

The include’s header names hpdf.h of 2.4.6 as the source of truth, and the prototypes obey: 169 of them, one per export, signatures carried over exactly. The discipline is in the details:

Two rules earn their keep. The explicit .l on every int-returning prototype is sign-extension hygiene: on x64 the calling convention may leave garbage in the upper half of rax, and reading eax only keeps a −1 from turning into 4,294,967,295. And the struct-by-value ban exists because PureBasic prototypes cannot express C struct returns — so the wrapper standardizes on libharu’s own out-parameter variants (HPDF_Page_GetCurrentPos2, HPDF_Image_GetSize2), which deliver identical values through a caller-owned HPDFPoint. Every sample port that meets one of these substitutions documents it in its header — numbered, with the reason.

Why no error handler? libharu’s C API reports failures through a setjmp/longjmp callback — a construct PureBasic deliberately does not have. It does not need one: libharu latches the first error and stays usable until HPDF_ResetError. So the ports drop the handler and gate every save behind one HPDF_GetError check; HaruErrorText(pdf) formats the pair as err <hex>/<hex> for diagnostics.

UTF-8 first, WinAnsi where it counts

Text is where C bindings usually fall apart, so this one picks a side: UTF-8 first. The display-text functions — TextOut, ShowText, ShowTextNextLine, TextWidth, MeasureText, TextRect — are bound with .p-utf8, and “café” just works.

But the base-14 fonts — Helvetica, Times, Courier — are non-embedded and single-byte; they have no idea what to do with UTF-8. Forcing one encoding onto every call would make half the library worse. So the same DLL exports are bound twice, once per signature: the .p-utf8 versions for embedded fonts, and Raw variants taking a plain char* that pair with HaruWinAnsiMem() — a PB string turned into a NUL-terminated CP1252 buffer, locale-independent. The CJK sample ports go further and pass SJIS or GBK bytes straight through, exactly like the C originals.

One source, two shapes

Prefer namespaces? hpdf_module.pbi is the same wrapper inside DeclareModule HPDF — same 169 pointers, same names, same behavior, with the library handles, binding macro and caches kept private. It is not a hand-maintained fork: a 66-line Node script slices hpdf.pbi into a module, emits a Declare for every Haru* helper, and refuses to run if the source layout drifts. node tools/generate_hpdf_module.cjs --check fails when the generated file no longer matches — so an ABI fix lands once and both shapes inherit it. Node is needed only to regenerate; the PureBasic side never sees it.

Proven, not assumed

A wrapper is a wall of declarations until something calls it. The proof here is libharu’s own sample corpus: all 24 C files in the samples tree — 23 programs plus the shared grid_sheet.c helper — ported to PureBasic as standalone console programs, each header naming its C source, its license and its numbered deviations. run_all.sh compiles and runs the lot, one PASS/FAIL per sample (exit code plus output file present); the two samples that need user-supplied font files are skipped, like their C originals.

And the outputs are checked beyond “it did not crash” — at grep level, against the PDF internals:

That last verified line matters more than it looks: the PDF/A port means XMP metadata with the two Factur-X extension schemas, an sRGB output intent, an embedded ICC profile and an attached invoice XML tagged /AFRelationship /Data — the plumbing an e-invoicing standard actually demands, exercised from PureBasic rather than from C.

Boring on purpose

  • Fails cleanly, never crashes — HaruInit() returns 0 when the DLL or a single export is missing; HaruMissing$ names the stragglers and HaruBound counts the rest. Documents are freed with HaruFree(), which also purges the per-document caches.
  • One include, two architectures — the binding code is OS-agnostic; x64 and x86 DLL sets ship in libraries/windows/, and the loader already knows how to behave on Linux. Nothing outside HaruInit() branches on platform.
  • Version-locked by construction — signatures are declared 1:1 against hpdf.h of 2.4.6, so a mismatched DLL is caught export-by-export at init, not discovered at runtime.
  • Licensed to ship — the wrapper is free to use; the three DLLs carry the libharu, zlib and libpng licenses, all permitting commercial redistribution, with the texts collected in THIRD-PARTY-NOTICES.md.

The binding disappears

The through-line is the one this site keeps arriving at: a binding’s job is to disappear. hpdf.pbi does not build an abstraction over PDF — it expresses the DLL’s own contract once, in PureBasic’s accent, then adds only the handful of helpers the C API cannot express: UTF-8 by default, cached fonts and alphas, honest errors. No import library, no runtime, no generator required to use it. 169 prototypes and three DLLs, and PDF is just another output format.