Build & features
Linking and the optional surfacesTwo files: the header medius.h and the native library libmedius_capi. Point the compiler at both and link. C++ is identical: same header, add -std=c++17. For your first program see the Quickstart.
Feature flags
Mock and flash, off by defaultTwo surfaces are gated. Each is a cargo feature on medius-capi and a matching #ifdef in the header.
| Cargo feature | Header macro | Declares | What it does |
|---|---|---|---|
mock | MEDIUS_FEATURE_MOCK | MediusMockBox, the medius_mock_* calls, medius_device_with_mock / _open_mock | A scriptable fake box for tests. See Mock box. |
flash | MEDIUS_FEATURE_FLASH | medius_flash(port, bin_path, host) | Flash firmware with esptool. See Flash firmware. |
# build the library with both surfaces
cargo build -p medius-capi --release --features mock,flash
# define the matching macros when you compile your program
cc app.c -DMEDIUS_FEATURE_MOCK -DMEDIUS_FEATURE_FLASH \
-I medius-capi/include -L target/release -lmedius_capi -lpthread -o appThe prebuilt tarball has neither surface. Define a macro whose symbols aren't in the library and you get a link error; build the library with a feature but forget the macro and the declarations stay hidden. The two must match.
Linking & loading
Header, library, and the flags that find themGet the two files from a release tarball, or build the crate yourself with the Rust toolchain (cargo build -p medius-capi --release writes them under target/release/). Then these flags wire them in.
compile ──▶ needs your code + medius.h link ──▶ adds libmedius_capi run ──▶ loads libmedius_capi
| Flag | Points at | Example |
|---|---|---|
-I<dir> | the directory holding medius.h | -I medius-capi/include |
-L<dir> | the directory holding the library | -L target/release |
-lmedius_capi | the library itself (the linker adds the lib prefix and extension) | resolves libmedius_capi.so |
-lpthread | Linux only; the core spawns reader/keepalive threads | append after -lmedius_capi |
| OS | Shared library | Static library | Note |
|---|---|---|---|
| Linux | libmedius_capi.so | libmedius_capi.a | add -lpthread |
| macOS | libmedius_capi.dylib | libmedius_capi.a | none |
| Windows | medius_capi.dll | medius_capi.lib | link medius_capi.dll.lib (import) or .lib (static); no lib prefix |
// hello.c: proves the library links and loads
#include <medius.h>
#include <stdio.h>
int main(void) {
printf("medius %s, abi %u\n", medius_version_string(), medius_abi_version());
return 0;
}cc hello.c -I medius-capi/include -L target/release -lmedius_capi -lpthread -o hello
LD_LIBRARY_PATH=target/release ./hello
# medius 3.0.0, abi 3-L only helps the linker. The shared library must also be findable by the dynamic loader when the program runs: Linux LD_LIBRARY_PATH or an rpath, macOS DYLD_LIBRARY_PATH / @rpath, Windows the .dll next to the exe or on PATH. Or link the static library (.a / .lib) to fold it into your binary and skip the run-time hunt.
Packaging
Prebuilt tarballs, no vcpkg or Conan portEach release attaches one tarball per platform, medius-capi-<target-triple>.tar.gz, to the GitHub Release. Download, unpack, and use the flags above.
| Inside the tarball | Contents |
|---|---|
include/medius.h | the header (mock/flash declarations gated by the macros) |
lib/ | the prebuilt libmedius_capi, shared and static, with mock and flash off |
No vcpkg or Conan port: those build C and C++ from source with no Rust toolchain, so a Rust-backed library doesn't fit. Use the prebuilt tarball, or build medius-capi from source. Python uses the prebuilt wheel.