RunMat
  • Pricing
RunMat
GitHub
GitHub
Sign inTry in browser
DesktopRuntimePhysicsCADAdministrationAgent

Get RunMat updates

New releases, guides and examples.

Product+
  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download
Math+
  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting
Physics+
  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA
Industries+
  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance
Learn+
  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students
Compare+
  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons
Company+
  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms

Product

  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download

Math

  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting

Physics

  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA

Industries

  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance

Learn

  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students

Compare

  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons

Company

  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms
GitHubXLinkedIn

© Dystr, Inc. · RunMat v0.7.1, Nov 17, 2026

RunMat® is a registered trademark of Dystr, Inc. MATLAB® is a registered trademark of The MathWorks, Inc. RunMat is not affiliated with, endorsed by, or sponsored by The MathWorks, Inc.

/
    • Python
    • C, C++ & MEX
    • Java
    • Native Libraries
    • TypeScript/JavaScript & WASM
Docs>Runtime>Interoperability

C, C++, and MEX Extensions

RunMat can build and execute source-compatible MEX gateways without a MATLAB installation. The bundled SDK covers the C Matrix and MEX APIs, the modern C++ Data and Engine APIs, the Fortran Matrix and MEX APIs, and the GPU MEX API. A successful build produces both a platform-native module and a canonical RunMat manifest; together they form the exact artifact used by projects, standalone executables, and remote workers.

This page is the end-to-end guide for building, calling, distributing, and operating MEX code. For the lower-level adapter ABI shared by MEX and other foreign runtimes, see Native Extension ABI.

Quick Start: C

Create add_one.c:

#include "mex.h"

void mexFunction(int nlhs, mxArray *plhs[],
                 int nrhs, const mxArray *prhs[]) {
    if (nrhs != 1 || nlhs != 1 || !mxIsDouble(prhs[0])) {
        mexErrMsgIdAndTxt("Example:AddOne:Arguments",
                         "Expected one double input and one output.");
    }

    plhs[0] = mxDuplicateArray(prhs[0]);
    double *values = mxGetDoubles(plhs[0]);
    for (mwSize i = 0; i < mxGetNumberOfElements(plhs[0]); ++i) {
        values[i] += 1.0;
    }
}

Build it from a RunMat session:

mex("-R2018a", "add_one.c")
y = add_one([1 2 3]);

Or build the same module from the shell:

runmat mex --R2018a -o add_one add_one.c

The output directory contains two files. Their suffix depends on the build host:

add_one.mexa64
add_one.mexa64.runmat.json

The module name is its callable RunMat function name. Keep the sidecar manifest next to the module: it binds the module bytes to the target, API mode, compiler family, embedded SDK, and MEX host ABI.

Quick Start: Modern C++

A C++ source selects the C++17 driver and the interleaved-complex API by default:

#include "mex.hpp"
#include "mexAdapter.hpp"
#include <cstddef>

class MexFunction : public matlab::mex::Function {
public:
    void operator()(matlab::mex::ArgumentList outputs,
                    matlab::mex::ArgumentList inputs) override {
        if (inputs.size() != 1 || outputs.size() != 1) {
            throw matlab::Exception("Expected one input and one output.");
        }

        matlab::data::TypedArray<double> result(inputs[0]);
        for (std::size_t i = 0; i < result.getNumberOfElements(); ++i) {
            result[i] = static_cast<double>(result[i]) * 2.0;
        }
        outputs[0] = result;
    }
};
runmat mex -o twice twice.cpp
y = twice([1 2 3]);

Constructing result initially shares the input's storage. The first mutable access detaches it, so the input keeps RunMat's normal copy-on-write semantics.

What The Build Produces

The build service materializes a versioned SDK from the RunMat executable, compiles every source with the appropriate language driver, links the bundled native support unit, and publishes the module plus its manifest. You do not need MATLAB headers, libraries, or a MATLAB installation.

Loading diagram...

The manifest records:

  • a content-derived artifact identity;
  • the module name, byte length, and SHA-256 digest;
  • the target triple, architecture, operating system, pointer width, and MEX suffix;
  • the selected Matrix API and source-language ABI;
  • the compiler family, MEX host ABI version, and embedded SDK digest.

Changing either the module or its compatibility contract changes its identity. Moving an unchanged module and manifest together does not.

Build Entry Points And Options

The session and shell commands use the same build planner and embedded SDK:

mex("-v", "-Iinclude", "-DFEATURE=1", ...
    "gateway.c", "support.c", "-output", "filter")
runmat mex --verbose -I include -D FEATURE=1 \
  -o filter gateway.c support.c

Use mexcuda or runmat mexcuda for a CUDA gateway. It requires at least one .cu translation unit.

ConcernSession mex / mexcudaShell runmat mex / mexcuda
Output name-output name or -o name--output name or -o name
Output directory-outdir directory--out-dir directory
Include directory-Idir or -I, dir-I dir
Definition-DNAME=value or -D, NAME=value-D NAME=value
API selection-R2017b, -R2018a, -largeArrayDims, -compatibleArrayDims--R2017b, --R2018a, --largeArrayDims, --compatibleArrayDims
ToolchainCC=, CXX=, FC= / F77=, NVCC=--compiler path for the primary driver
Driver flagsCFLAGS=, CXXFLAGS=, FFLAGS=, NVCCFLAGS=, LDFLAGS=repeated --compiler-argument and --linker-argument
Build command-v or -verbose; -silent disables it--verbose or -v

The session parser also passes ordinary unrecognized dash-prefixed arguments to the compiler and routes -L and -l arguments to the linker. -setup is intentionally non-interactive: select a compiler explicitly or through the corresponding environment variable.

Language And Toolchain Selection

Source detection is order-independent. CUDA has the highest link-driver precedence, followed by Fortran, C++, and C. C and C++ helpers are still compiled with their own drivers. Fortran and CUDA gateways cannot be combined in one module.

SourceDefault driverDefault APINotes
.cCC, otherwise cc (cl.exe on Windows)-R2017bC11 on GNU-like toolchains.
.cc, .cpp, .cxx, .c++CXX, otherwise c++ (cl.exe on Windows)-R2018aC++17; bundled support remains compiled as C.
.f, .for, .f77, .f90, .f95, .f03, .f08FC, then F77, otherwise gfortran-R2017bRequires a GNU-compatible gfortran ABI; fixed-form suffixes retain fixed-form compilation.
.cuNVCC, then MW_NVCC_PATH, otherwise nvcc-R2018aUse mexcuda; supported on Linux and Windows x86-64.

RunMat currently builds on the target host; MEX cross-compilation is not available. macOS and Linux require a GNU-like compiler family, and Windows requires an MSVC-compatible family.

MSVC builds read source files as UTF-8 and use UTF-8 for narrow string literals. C++ translation units enable standard exception unwinding. GNU Fortran gateways run on macOS and Linux; Windows rejects the incompatible GNU Fortran ABI before compilation.

Matrix API Selection

The API switches are mutually exclusive.

SelectionDimensions and indicesComplex layoutTypical use
-R2017b (C/Fortran default)native-width mwSize and mwIndexseparate real and imaginary buffersExisting C gateways using mxGetPr / mxGetPi.
-R2018a (C++/CUDA default)native-widthinterleaved complex buffersTyped C accessors, modern C++, and GPU gateways.
-largeArrayDimsnative-widthseparateLegacy spelling for the large-array separate-complex API.
-compatibleArrayDims32-bit public dimensions and indicesseparateOlder source that requires the pre-large-array ABI. RunMat checks and translates at its native-width boundary.

The selected API is part of the artifact identity. Rebuild rather than renaming or editing a manifest when changing modes.

Calling And Resolving A Module

MEX modules participate in ordinary function resolution. RunMat checks exact artifacts installed from the active project or executable before searching the session path for the current platform suffix. mexext returns that suffix without a leading dot.

suffix = mexext();
addpath("build");
[a, b] = native_filter(x);

An anonymous function handle can capture an installed project MEX artifact, for example call_filter = @() native_filter(x). Calls through that handle retain the selected artifact identity and packaged module across later requests in the same session; they do not choose a new binary from the then-current search path.

The supported targets are:

HostSuffix
macOS Apple Silicon.mexmaca64
macOS x86-64.mexmaci64
Linux x86-64.mexa64
Windows x86-64.mexw64

Native MEX loading is unavailable in browser and WebAssembly sessions. Packages and compiled artifacts retain the native requirement so an unsupported host rejects them before program instructions execute.

C Matrix And MEX API

The bundled matrix.h and mex.h expose the supported source-compatibility surface. It includes:

  • dense real and complex arrays across double, single, all fixed-width signed and unsigned integer classes, and logicals;
  • N-dimensional shapes, scalar and subscript helpers, and the typed R2018a accessors;
  • sparse real, logical, and complex matrices in canonical CSC form;
  • UTF-16 character arrays and UTF-8 conversion helpers;
  • cells, structures, classed value objects, public property access, and duplication;
  • mxMalloc, mxCalloc, mxRealloc, mxFree, and persistent memory;
  • printing, structured errors and warnings, RunMat callbacks, workspace access, locks, and exit handlers.

The checked-in C_MATRIX_API and C_MEX_API catalogs are the exact symbol-level support contract. The MAT-file API and undocumented entrypoints are not part of this compatibility tier.

Values, Ownership, And Copies

RunMat never exposes a Rust collection layout as an mxArray. The gateway receives the documented C layout and invocation-scoped pointers.

Compatible dense numeric and logical arrays retain their host allocation through an in-process call. Interleaved floating-point complex arrays and native-width sparse buffers can do the same. Inputs are read-only aliases: mutating an input pointer is outside the extension contract. Create an output, call mxDuplicateArray, or use the modern C++ copy-on-write API before mutation.

Storage supplied through mxSetData, typed setters, mxSetIr, or mxSetJc is adopted only when RunMat's allocation registry can prove its origin, byte length, capacity, alignment, element layout, and release function. Otherwise:

  • a compatible registered floating-point, logical, interleaved floating-complex, or native-width sparse buffer can transfer without a copy;
  • fixed-width integer setter storage is converted once into RunMat's exact integer owner;
  • another registered but incompatible layout takes one checked conversion;
  • an unregistered pointer is rejected because RunMat cannot prove its size or how to release it.

Separate/interleaved complex changes, 32-bit sparse indices, character encoding, row-major layout, and host/device movement are explicit conversion boundaries. Pointers must not outlive the array, persistent allocation, or Data API control that owns them.

Character interchange preserves UTF-16 code units, including unpaired surrogates. Borrowed MEX character data requires owned runtime storage; row and column vectors retain its linear order, while matrix pages require reordering. Copy diagnostics distinguish storage materialization from layout conversion.

Modern C++ Data And Engine APIs

Modern gateways include mex.hpp and mexAdapter.hpp, derive MexFunction from matlab::mex::Function, and receive matlab::mex::ArgumentList objects. The bundled Data API supports:

  • typed real, logical, character, string, floating-complex, and fixed-width-complex arrays;
  • missing string values, cells, structures, enumerations, and value or handle-object properties;
  • real double and logical sparse arrays, plus complex sparse arrays;
  • shared array controls with recursive copy-on-write detachment;
  • column-major and row-major construction;
  • C++ exceptions translated into structured MEX diagnostics.

Copying an Array, assigning an input to an output, or nesting it inside a cell or structure retains its underlying allocation. ArrayFactory::createBuffer allocates through the MEX host. createArrayFromBuffer adopts compatible column-major real, logical, or floating-complex storage; row-major input is reordered once. Ordered sparse value and row-index buffers can be adopted directly, while coordinate input is normalized to CSC.

RunMatEngine provides synchronous and asynchronous function calls, evaluation, workspace access, and indexed object-property access. MATLABEngine remains available as a source-compatible alias. Data API array arguments retain their payloads; typed scalar, vector, complex, and UTF string overloads convert to the requested native representation at the call boundary.

FutureResult and SharedFutureResult support waiting, timed waiting, sharing, and cooperative cancellation. A future may outlive the gateway invocation that created it: the session keeps the module, callback services, and array leases alive until the work completes. Supplied UTF-16 output and error stream buffers receive captured streams; otherwise output follows the session's normal console path. Callback failures preserve their identifier and message, and accepted cancellation appears as CancelException.

Callbacks And Workspace Access

Calls through mexCallMATLAB, mexEvalString, mexGetVariable, mexPutVariable, and their C++ Engine equivalents return to the exact RunMat session and active workspace that invoked the gateway. They do not use a process-global workspace.

A callback may call another MEX module. Recursive entry into the same module is rejected with RunMat:MEX:ReentrantInvocation rather than deadlocking the module's persistent state. Cancellation is checked before native entry and whenever a gateway calls back into RunMat. An in-process gateway cannot be safely preempted while it is executing.

Callbacks can await RunMat work without blocking the session's callback servicing. An independently ready callback can proceed while another is suspended. Accepted cancellation of an asynchronous Engine request cooperatively cancels that request's callback work, not unrelated requests; session cancellation still applies to work carrying the session's cancellation token.

Console output from mexPrintf and C/C++ standard output is attached to the invocation. MEX warnings enter RunMat's warning diagnostics. mexErrMsgTxt, mexErrMsgIdAndTxt, and uncaught C++ exceptions stop the gateway at the C boundary; they do not unwind through Rust.

Module State And Lifecycle

A loaded module belongs to one RunMat session. Static data, persistent arrays and memory, the modern C++ gateway object, registered mexAtExit handlers, and mexLock state all belong to that loaded module.

clear name, clear mex, clear functions, and clear all unload eligible modules and run their exit handlers with the originating callback services still available. A locked, executing, or asynchronously active module remains loaded. mexUnlock makes a locked module clearable; it does not unload it immediately. Explicit graceful session or standalone-program shutdown awaits admitted calls, exit handlers (even for locked modules), and the native or isolated-host retirement acknowledgement before releasing callback services. A lifecycle diagnostic after unload does not mean the module remains live.

Dropping a host without graceful shutdown is forced abandonment, not a successful mexAtExit run. Late native callbacks lose access to the originating RunMat services; an in-progress callback retains its own origin lease until it returns. An isolated host is owned by its driver and is killed on driver drop. An in-process gateway is arbitrary native code and cannot be guaranteed to finish or be preempted by host disposal. Embedders should drive and await graceful close while their session and callback driver are still live.

Only one session can own a canonical native library image in-process at a time because the image may contain process-global state. If another session needs the same exact image concurrently, RunMat gives it a separate isolated host and independent module state. Invocation-only workspace frames and host services are released after the call unless asynchronous work explicitly retains them.

Exact Artifacts, Compatible Binaries, And Isolation

RunMat distinguishes binaries by how strongly it can prove their identity and ABI:

Binary tierAdmissionExecution
Exact RunMat artifactAdjacent canonical manifest matches the module bytes, target, API, compiler family, embedded SDK, and host ABI.Owning process; an exact isolated host is used when another session owns the same image.
Compatible unmanifested artifactCurrent platform suffix and loader dependencies are valid, and the module exports RunMat's current adapter ABI and a supported Matrix API mode.Same-executable isolated extension host.
Other native binaryTarget, dependency, adapter symbol, or private ABI validation fails.Rejected before gateway invocation whenever the platform loader can diagnose it safely.

Source compatibility is not arbitrary third-party binary compatibility. A binary linked against another host's private exports should be rebuilt from source with runmat mex. If a sidecar exists but does not match the module, RunMat rejects the artifact; it does not silently downgrade it to the unmanifested tier.

The isolated host uses authenticated bounded local messages. Large canonical values move through private, digest-verified snapshots, and callbacks are routed to the originating runtime context. A native crash, cancellation, or configured timeout terminates the host without terminating the RunMat driver.

foreign.mex.timeout_ms is unset by default. A configured deadline is supported only by the isolated host: arbitrary in-process C/C++/Fortran code cannot be safely preempted. A manifested native invocation with a configured timeout is rejected before loading the library with RunMat:MEX:TimeoutUnsupported; RunMat does not abandon live native references, pretend a timer stopped native instructions, or silently change module ownership/routing. Leave the timeout unset only when intentionally accepting native execution without a hard deadline, or use a supported isolated execution route. Default no-timeout native invocation and its existing cooperative callback cancellation remain unchanged.

A broken isolated-host transport rejects further calls while the driver attempts to retire the host. RunMat does not retry a partially executed gateway. During graceful shutdown, callback services and retained values remain owned until process-tree retirement succeeds; an unconfirmed retirement is reported as a shutdown failure rather than a successful unload.

Isolation is crash containment, not a security sandbox. Native code retains the child process's filesystem, network, and user permissions.

Configure the unmanifested tier in runmat.toml:

[runtime.foreign.mex]
unmanifested = "isolate" # or "deny"
timeout_ms = 300000      # optional; isolated calls only

unmanifested = "deny" rejects a compatible module before starting a host. An omitted timeout applies no automatic invocation deadline; clear and shutdown still have a bounded teardown. Timeouts do not apply to exact in-process execution because forcibly interrupting native code there would be unsafe.

Project, Package, Standalone, And Remote Use

Declare a project-owned RunMat artifact with paths relative to the package manifest:

[mex-artifacts.filter]
module = "native/filter.mexa64"
manifest = "native/filter.mexa64.runmat.json"

The table name must equal the manifest's module name. Neither path may escape the package root. Project resolution validates the pair and installs the module by name, so calls do not depend on the original build directory or an ambient addpath.

The module and manifest become first-class objects in the frozen package graph:

  • package identity includes both exact byte streams;
  • --locked and --frozen detect changes after resolution;
  • publishing a native package requires runmat package publish --allow-native;
  • runmat compile embeds the exact artifact in the standalone executable;
  • standalone startup materializes it into private read-only storage and validates it before installing the entrypoint;
  • remote execution bundles carry the same artifact, and workers privately materialize and validate it before execution.

MEX files are target-specific. Packages supporting several native targets should select target-specific package dependencies or artifacts rather than presenting one module as portable. Remote schedulers admit ordinary MEX artifacts only on a compatible native process host. CUDA artifacts additionally require the built-in CUDA provider contract and an available GPU with compute capability.

GPU And Fortran Gateways

mexcuda builds CUDA gateways against gpu/mxGPUArray.h. The GPU API preserves double, single, all fixed-width integer classes, logicals, and supported interleaved complex layouts. Device buffers remain owned by the active CUDA provider; real/imaginary extraction and recombination use device-to-device strided copies. A non-CUDA resident input transfers explicitly to CUDA. Sparse GPU storage is not currently admitted, and mxGPUIsSparse is false for admitted handles.

Fortran gateways include fintrf.h. RunMat preserves Fortran calling conventions, character arguments for callbacks and diagnostics, Fortran container indexing, dense copy helpers, separate and interleaved complex values, native handles, sparse CSC data, lifecycle callbacks, and the distinct 32-bit -compatibleArrayDims contract. Mixed C and Fortran builds compile each translation unit with its language driver and link once with gfortran.

Troubleshooting

SymptomLikely causeAction
RunMat:MEX:UnsupportedTargetThe current host cannot build or load native MEX, or CUDA is requested on an unsupported target.Build on a supported native target; use Linux or Windows x86-64 for CUDA.
RunMat:MEX:InvalidBuildArgumentsMissing source, conflicting API switches, unsupported assignment, or mexcuda without .cu.Check the build options and language table above.
Compiler launch or build failureDriver is absent, incompatible with the target, or received invalid flags.Use -v / --verbose, then set the language-specific compiler and flags.
Artifact is invalidModule bytes, sidecar metadata, target, SDK, or ABI no longer match.Rebuild the module; do not edit or copy only one half of the pair.
Missing native dependencyThe platform loader cannot resolve a library needed by the module.Install or package that dependency and ensure the platform loader can find it.
Unmanifested binary deniedProject policy uses unmanifested = "deny".Rebuild with runmat mex or deliberately change the policy.
Output-count errorThe gateway populated fewer outputs than the RunMat call requested.Correct nlhs handling or request fewer outputs.
Same-module reentry errorA callback recursively invoked the active module.Move the recursive work to another function or module.
Isolated host exitsNative crash, cancellation, or configured timeout.Debug the gateway and its dependencies; increase the timeout only for expected long work.

Verification And Compatibility Gates

The repository tests exercise the full path rather than only compiling headers. The runmat-mex suite builds and invokes C, C++, Fortran, and GPU fixtures; checks every cataloged public symbol against the bundled headers and support unit; verifies exact numeric classes, complex layouts, sparse ownership, cells, structures, strings, objects, enumerations, callbacks, asynchronous engine work, persistence, clearing, and exit hooks; and measures copy-on-write and allocation-preserving paths.

cargo test -p runmat-mex

Cross-crate integration tests cover runtime function resolution, cancellation and callback servicing, isolated crashes and timeouts, policy denial, package freezing, exact artifact installation, standalone embedding, and remote worker materialization. For changes that affect the runtime or product path, expand validation accordingly:

cargo test -p runmat-runtime
cargo test -p runmat --test isolated_mex
cargo test -p runmat-core --test mex_artifact
cargo test -p runmat-package --test path_project_graph
cargo test -p runmat-aot-runtime
cargo test -p runmat-execution-runner-native

An opt-in repository cohort builds and executes pinned FieldTrip C gateways. Supply the exact checkout and run:

RUNMAT_MEX_FIELDTRIP_CHECKOUT=/path/to/fieldtrip \
cargo test -p runmat-mex --test repository_cohorts -- --ignored

The checkout revision and license are verified before compilation. See Testing for the pinned revision and the separate advanced Fortran qualification gate.

On this page
  • Quick Start: C
  • Quick Start: Modern C++
  • What The Build Produces
  • Build Entry Points And Options
  • Language And Toolchain Selection
  • Matrix API Selection
  • Calling And Resolving A Module
  • C Matrix And MEX API
  • Values, Ownership, And Copies
  • Modern C++ Data And Engine APIs
  • Callbacks And Workspace Access
  • Module State And Lifecycle
  • Exact Artifacts, Compatible Binaries, And Isolation
  • Project, Package, Standalone, And Remote Use
  • GPU And Fortran Gateways
  • Troubleshooting
  • Verification And Compatibility Gates