clibgen.buildInterface — Prepare, publish and load a declared native C interface in this session.
clibgen.buildInterface(header, 'Libraries', library) prepares a C ABI interface for one actual shared-library path, publishes its digest-bound adjacent .runmat.json manifest, and loads the session alias. InterfaceName overrides the default header stem; repeated IncludePath or IncludeDirectories supplies header search paths. The returned scalar string is that loaded alias. Calls through clib.alias.symbol use the same selected foreign-runtime host and exact prepared declarations.
Syntax
interface = clibgen.buildInterface(header, 'Libraries', library, [name, value]...)Inputs
header- Type
Any- Required
- Yes
- Default
- —
- Description
- C declaration header path.
optionName- Type
Any- Required
- Yes
- Default
- —
- Description
- Libraries, InterfaceName, IncludePath or IncludeDirectories.
optionValue- Type
Any- Required
- Yes
- Default
- —
- Description
- One scalar text-coercible option value.
options- Type
Any- Required
- Variadic
- Default
- —
- Description
- Additional name-value pairs; include paths may repeat.
Returns
interface- Type
StringScalar- Description
- Loaded session interface alias, not a MATLAB C++ definition object.
Errors
RunMat:Foreign:UnsupportedOnWasm- When
- The current host cannot load a native shared library.
- Message
Native shared libraries are unavailable on this host.
RunMat:Foreign:InvalidCall- When
- Arguments do not satisfy the normalized shared-library contract.
- Message
Invalid shared-library operation.
RunMat:Foreign:HostUnavailable- When
- A native shared-library operation is invoked without an active runtime context.
- Message
Native shared-library operation has no active runtime context.
Supported preparation
The header and each option name/value must be scalar text-coercible input. Libraries is required and names one actual shared-library file. Unsupported options, odd option tails and excessive outputs reject before invoking the adapter. An existing session alias cannot be replaced by this call.
Native execution and artifacts
A native host, C compiler/header frontend and the matching library are required. Preparation reads headers and library bytes and writes an adjacent canonical manifest. The selected unit admits the native-ffi adapter with Process execution-stack requirements; no ambient foreign port, numerical accelerator or distributed execution is implied. Browser execution refuses native preparation.
Current compatibility limits
This is the existing RunMat C ABI preparation path. It does not implement MATLAB's C++ interface-definition customization/build workflow, does not accept multiple libraries, and returns a loaded alias rather than a MATLAB definition object. General MATLAB clibgen parity is not claimed.
Example
Prepare and call a C interface
prepared = dir('*.runmat.json');
assert(numel(prepared) == 1);
library = extractBefore(prepared(1).name, '.runmat.json');
interface = clibgen.buildInterface('fixture.h', 'Libraries', library, 'InterfaceName', 'built_fixture');
assert(strcmp(interface, 'built_fixture'));
total = clib.built_fixture.fixture_add(int32(20), int32(22));
assert(total == int32(42));
unloadlibrary('built_fixture');Using clibgen.buildInterface with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how clibgen.buildInterface changes the result.
Run a small clibgen.buildInterface example, explain the result, then change one input and compare the output.
FAQ
Does this create a MATLAB C++ definition object?⌄
No. RunMat currently prepares one declared C ABI library, publishes its exact interface artifact and returns the loaded session alias.
Related Interop functions
Native
calllib · libfunctions · libisloaded · libpointer · libstruct · loadlibrary · setdatatype · unloadlibrary
Java
isjava · javaaddpath · javaArray · javaclasspath · javaMethod · javaMethodEDT · javaObject · javaObjectEDT · javarmpath · jenv · usejava
Source you can read
Every RunMat function's source is public. Read exactly how clibgen.buildInterface is executed, line by line, in Rust.
- View the source for clibgen.buildInterface in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.