Medius - BindingsBuild & features

Build & features

Turning on mock, and building from source

The mock feature is compiled into the native library, not switched on from Python, so turning it on means building that library. Everything else is a ctypes layer with no Python build step.

Feature flags

mock and flash, and how to tell what's built in

Both are Cargo features on the medius-capi crate. On import, Python reads what the loaded library exposes and sets medius.HAS_MOCK to match.

FeatureCargo flagPython surfacemedius.HAS_*Adds
mock--features mockMockBox().open() / .with_device()HAS_MOCKA scriptable in-process fake box. See Mock box.

The pip install medius wheel does not have it. MockBox() raises RuntimeError there. Gate on the flag first: if medius.HAS_MOCK:.

CHECK WHAT'S BUILT IN
python -c "import medius; print('mock', medius.HAS_MOCK)"
# mock False   <- the published wheel
ENABLE A FEATURE

Build the library with the features you want, then point Python at it with MEDIUS_LIB (below). No reinstall.

# from the repo root
cargo build --release -p medius-capi --features mock,flash

export MEDIUS_LIB=$PWD/target/release/libmedius_capi.so
python -c "import medius; print(medius.HAS_MOCK)"
# True True

To bake features into an installed wheel, build the library first and let pip reuse it:

cargo build --release -p medius-capi --features mock,flash
MEDIUS_SKIP_CARGO=1 pip install ./bindings/python

Finding the library

MEDIUS_LIB and the load order

On import medius the package loads the native library, trying these in order and stopping at the first hit. MEDIUS_LIB overrides the rest.

import medius
   │
   ├─ 1. $MEDIUS_LIB set?                   ──▶  CDLL(that exact path)   (dev / test builds)
   ├─ 2. bundled beside the package?        ──▶  CDLL(medius/<libname>)  (what the wheel ships)
   ├─ 3. on the system loader path?         ──▶  CDLL(<libname>)         (LD_LIBRARY_PATH / PATH)
   ├─ 4. ctypes.util.find_library(...)?     ──▶  CDLL(found)             (ldconfig / system paths)
   └─ none                                  ──▶  OSError                 (cannot locate the library)
POINT AT ANY BUILD WITH MEDIUS_LIB
MEDIUS_LIB=/path/to/target/release/libmedius_capi.so python myscript.py

An OSError on import means every step failed: a bad MEDIUS_LIB path, or an unsupported platform where the install built from source without a Rust toolchain.

Build from source

musl Linux, 32-bit Windows, and contributors

Linux (glibc), macOS, and 64-bit Windows get a prebuilt wheel from pip install medius. On musl Linux (Alpine) or 32-bit Windows there's no wheel, so pip builds the native library from source.

# build from source even where a wheel exists
pip install medius --no-binary medius

# from a checkout
pip install ./bindings/python

A source build runs cargo build --release -p medius-capi, so it needs a Rust toolchain on PATH. On Linux the library links libudev through serialport; install systemd-devel (or your distro's libudev-dev) first.