Crate kpathsea 

High-level Rust API for working with the kpathsea file-searching library for TeX

Two backends are provided:

• in-process — FFI calls into the system libkpathsea (the fast path, microseconds per lookup). Selected automatically when the library was found at build time: pkg-config or the KPATHSEA_LIB_DIR override on Unix, TeX Live’s own kpathsea DLL (found next to kpsewhich.exe) on Windows — see kpathsea_sys’s build script. KPATHSEA_NO_LINK=1 at build time forces the subprocess backend even when a library is available.
• subprocess — delegates to the host TeX distribution’s own kpsewhich executable, fronted by a one-shot cache of the TeX tree’s ls-R databases. Selected automatically when libkpathsea was not found at build time (e.g. MacTeX/BasicTeX ship no library at all), or explicitly via Kpaths::new_subprocess. Because it asks the host’s resolver binary, it stays in sync with the ambient distribution by construction — including MiKTeX, which reimplements kpathsea. (This mirrors how Perl LaTeXML has always resolved TeX files; see src/subprocess.rs.)

Latency profile (measured on a full TeX Live): in-process lookups are tens of µs, hit or miss. Subprocess lookups are bimodal: sub-µs on an ls-R cache hit — faster than the FFI path — but a cache miss costs a kpsewhich spawn (tens to hundreds of ms, memoized process-wide per executable so a repeated miss is only ever paid once, regardless of which instance or thread asks).

Modules

formats

Common kpathsea format constants. Values are the C kpse_file_format_type enum’s (drift-checked against kpathsea_sys in linked test builds); other enum values can be passed as plain Format numbers.

Structs

Kpaths

High-level interface struct for the kpathsea API

Type Aliases

Format

Kpathsea file-format type, for callers of Kpaths::find_file_with_format that want to pass a known format.

Result

External result type for handling library errors