rustduck-sys 1.1.0

Raw Rust FFI bindings to the C ABI used by TSDuck's Python API
Documentation

rustduck-sys

The low-level TSDuck boundary. It binds the native tspy* C ABI that TSDuck provides for its Python API and reuses that stable C-facing surface from Rust; it neither embeds nor depends on a Python runtime. This is the only crate that declares raw tspy* functions and CXX bridge signatures.

  • src/raw.rs — raw declarations, including ABI-correct Utf16 callbacks and deprecated legacy callback contracts.
  • src/bridge.rs — the single CXX bridge declaration module.
  • native/bridge/ — version-matched C++ adapters compiled against the installed TSDuck headers.
  • native/tspy.h — a repository-owned mirror of TSDuck's Python ABI. The probe checks Rust declarations against this mirror, and integration tests execute callbacks against the installed TSDuck library.

Bridge owners retain their native reports, contexts, and registered handlers through dependent destruction. Dropping an upstream bridge handle releases its share while dependent owners keep the allocation live. The raw tspy* ABI keeps its caller-managed ownership contract; rustduck-core provides the typed ownership and lifecycle API.

The legacy LogCallback, PluginCallback, and their constructors are deprecated because their declarations differ from TSDuck's ABI and can cause undefined behavior. Use LogCallbackUtf16, PluginCallbackUtf16, and the tspyNewPy*Utf16 constructors. The legacy declarations retain this risk.

TSDuck requirements

  • TSDuck 3.44.x development headers and runtime library.
  • When TSDuck is not under a standard prefix, set TSDUCK_PREFIX, TSDUCK_INCLUDE_DIR, or TSDUCK_LIBRARY_DIR.
  • Build-selection paths and tsconfig values reject control characters before the build emits line-based Cargo directives.
  • The build rejects other TSDuck versions, emits the version constants used by raw, and writes a per-profile compile_commands.json.

Native source manifest

build.rs holds the single NATIVE_SOURCES / NATIVE_HEADERS manifest. Adding a native .cpp or .h file requires updating the manifest; the build validates that the directory contents and the manifest agree.

Development

This crate owns raw ABI declarations, CXX bridge signatures, and native pointer operations. rustduck-core keeps any required unsafe implementation in a narrow, locally justified safety boundary.

cargo test -p rustduck-sys
cargo test -p rustduck-sys --features native_test_hooks
cargo test -p rustduck-sys --test abi --test raw_callbacks

The native_test_hooks feature compiles the C++ fault-injection seams used by tests/native_failure.rs. Release consumers leave it disabled, so the bridge exposes no test surface and ships no live test seam.

Rules

Native boundaries · Dependencies and release policy

Third-party notices

This crate compiles against TSDuck 3.44.x headers and links the installed TSDuck shared library. See THIRD-PARTY.md; TSDuck is BSD 2-Clause.