<!-- Source: https://medius.k4tech.net/bindings/c -->
# Install

_No build step, works in C and C++_

The binding is one header (`medius.h`) and one prebuilt library (`libmedius_capi`). It's the same for C and C++. The header compiles as both, so a C++ program `#include`s it and calls the same functions. Nothing to build, no [Rust](https://rustup.rs) needed.

## Download

_The release archive for your platform_

On the [Releases page](https://github.com/K4HVH/medius/releases), download the file that matches your computer, then unzip it.

| Your computer | File to download |
| --- | --- |
| Windows (64-bit) | `medius-capi-x86_64-pc-windows-msvc.tar.gz` |
| macOS (Apple Silicon, M1+) | `medius-capi-aarch64-apple-darwin.tar.gz` |
| macOS (Intel) | `medius-capi-x86_64-apple-darwin.tar.gz` |
| Linux (Intel/AMD 64-bit) | `medius-capi-x86_64-unknown-linux-gnu.tar.gz` |
| Linux (ARM64) | `medius-capi-aarch64-unknown-linux-gnu.tar.gz` |

Inside are two folders:

```
medius-capi-<your-platform>/
├── include/
│   └── medius.h
└── lib/
    └── libmedius_capi      (.so Linux · .dylib macOS · .dll + .lib Windows · .a static)
```

`include/` holds the header you `#include`; `lib/` holds the library you link.

## Build & run

_Compiler and linker flags_

#### WINDOWS · VISUAL STUDIO

In your project's **Properties** (use the same values for [C and C++](https://learn.microsoft.com/en-us/cpp/)):

1.  Under **C/C++ → General → Additional Include Directories**, add the unzipped `include\` folder.
2.  Under **Linker → General → Additional Library Directories**, add the `lib\` folder.
3.  Under **Linker → Input → Additional Dependencies**, add `medius_capi.dll.lib`.
4.  Copy `medius_capi.dll` next to your built `.exe` (or onto your `PATH`).

Build and run as normal. To skip the DLL, add `medius_capi.lib` in step 3 instead (static, nothing to copy).

#### WINDOWS · COMMAND LINE (x64 Native Tools Command Prompt)

```bash
cl app.c /I include /link /LIBPATH:lib medius_capi.dll.lib
:: C++:  cl /std:c++17 app.cpp /I include /link /LIBPATH:lib medius_capi.dll.lib
:: then copy medius_capi.dll next to app.exe, and run:
app.exe
```

#### LINUX & MACOS

```bash
# C
cc  app.c   -I include -L lib -lmedius_capi -o app
# C++ (same header, same library)
g++ -std=c++17 app.cpp -I include -L lib -lmedius_capi -o app

# run (tell the loader where the library is)
LD_LIBRARY_PATH=lib ./app        # macOS: DYLD_LIBRARY_PATH=lib ./app
```

On Linux add `-lpthread`. To avoid setting a path at run time, link the static `libmedius_capi.a` instead.

> **Note**
>
> If your platform isn't listed, build it once: install the [Rust toolchain](https://rustup.rs), `git clone https://github.com/K4HVH/medius`, then `cargo build -p medius-capi --release`. The library lands in `target/release/` and the header is `medius-capi/include/medius.h`. See [Build & features](/bindings/c/build.md).

## Verify

_Version print, no box needed_

`medius_version_string` and `medius_abi_version` are pure library calls. If this builds and prints a version, you're set.

```c
// app.c
#include <stdio.h>
#include <medius.h>

int main(void) {
    printf("%s, abi %u\n", medius_version_string(), medius_abi_version());
    return 0;
}
```

> **Warning**
>
> A linker error (`cannot find -lmedius_capi` / `unresolved external`) means the library directory is wrong. A crash on start (`cannot open shared object` / a missing-DLL popup) means the loader can't find the library at run time. Fix the path or copy the file next to your program. More on [Build & features](/bindings/c/build.md).

## Connect

_Open a box, read its version_

[`medius_device_find`](/bindings/c/api.md#connect) opens the first [box](/native/hardware.md) it sees and runs the [handshake](/native/connection.md#handshake); [`medius_device_free`](/bindings/c/api.md#connect) closes it. Full walk-through on [First program](/bindings/c/quickstart.md).

```c
MediusDevice *dev = NULL;
if (medius_device_find(&dev) != MEDIUS_STATUS_OK) { /* see Calls & errors */ }

MediusVersion v;
medius_device_query_version(dev, &v);
printf("firmware %u.%u.%u\n", v.fw_major, v.fw_minor, v.fw_patch);

medius_device_free(dev);
```

Every call returns a [`MediusStatus`](/bindings/c/types.md#errors) you check; reading the failure text is on [Calls & errors](/bindings/c/usage.md#errors). The full call list is the [API index](/bindings/c/api.md).