Medius - BindingsBuild & features

Build & features

Turning on mock and flash, and building from source

The mock and flash features are compiled into the native library, not switched on from Python, so turning one on means building that library. The pip install medius wheel ships with both off. 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 and medius.HAS_FLASH to match.

FeatureCargo flagPython surfacemedius.HAS_*Adds
mock--features mockMockBox().open() / .with_device()HAS_MOCKA scriptable in-process fake box. See Mock box.
flash--features flashmedius.flash(port, bin_path, host=False)HAS_FLASHFlash firmware via esptool, Linux and Windows. See Flash.

The pip install medius wheel has neither feature. MockBox() and medius.flash(...) raise RuntimeError there. Gate on the flag first: if medius.HAS_MOCK: / if medius.HAS_FLASH:.

CHECK WHAT'S BUILT IN
python -c "import medius; print('mock', medius.HAS_MOCK, 'flash', medius.HAS_FLASH)"
# mock False flash 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, medius.HAS_FLASH)"
# 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. Set MEDIUS_LIB to override the rest and run any script against the build you want (a debug build, or one with mock/flash).

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. Force a source build anywhere, or build from a checkout:

# 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.