---
title: Install
sidebar_position: 1
---

# Install

cuframes is **Linux only**. The IPC mechanism relies on POSIX shared memory and `SCM_RIGHTS` file-descriptor passing over Unix sockets. Windows, macOS and WSL2 are not supported.

You also need an NVIDIA GPU with compute capability ≥ 7.5 (Turing or newer) and a CUDA 12+ driver. Specifically: 64-bit Linux, glibc 2.31+, kernel 5.4+ (for `cuMemMap` + `SCM_RIGHTS` support).

## Option 1 — Pre-built Docker image (recommended for trying it out)

The runtime image ships `libcuframes.so` and the `cuframes-rtsp-source` bridge tool on top of `nvidia/cuda:12.4.1-runtime`.

```bash
docker pull gx/cuframes:0.4
```

Smoke check:

```bash
docker run --rm --runtime=nvidia gx/cuframes:0.4 \
  /usr/local/bin/cuframes-rtsp-source --help
```

To run a publisher and a subscriber from two containers, the **publisher** container must start with `--ipc=shareable` and the **subscriber** must share its IPC namespace via `--ipc=container:<publisher>`. PID namespace sharing is **not** required since v0.4 — handles are exchanged as POSIX file descriptors over the Unix socket.

```bash
# Publisher
docker run -d --name cuframes-pub --runtime=nvidia --ipc=shareable \
  -v /run/cuframes:/run/cuframes \
  gx/cuframes:0.4 \
  /usr/local/bin/cuframes-rtsp-source --rtsp 'rtsp://...' --key cam1

# Subscriber
docker run --rm --runtime=nvidia \
  --ipc=container:cuframes-pub \
  -v /run/cuframes:/run/cuframes:ro \
  gx/cuframes:0.4 \
  /usr/local/bin/sub_count --key cam1 --max-frames 100
```

Namespace rules: subscriber must share IPC namespace with the publisher (POSIX `/dev/shm` lives in IPC ns). PID sharing is **not** required (this is a v0.4 property — pre-v0.4 needed both).

## Option 2 — Build from source

### Build requirements

| | Minimum |
|---|---|
| CUDA Toolkit | 12.0 |
| NVIDIA driver | 525 |
| CMake | 3.20 |
| GCC / Clang | 11 / 14 |
| FFmpeg dev libs | libavcodec, libavformat, libavutil (only for `cuframes-rtsp-source`) |

On Ubuntu 22.04 / 24.04:

```bash
sudo apt-get install -y \
  build-essential cmake ninja-build pkg-config \
  libavcodec-dev libavformat-dev libavutil-dev
```

### Configure and build

```bash
git clone https://git.goldix.org/gx/cuframes.git
cd cuframes
cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
```

This produces:

- `build/libcuframes/libcuframes.so` — the shared library
- `build/tools/cuframes-rtsp-source/cuframes-rtsp-source` — the RTSP bridge
- `build/examples/sub_count/sub_count` — reference subscriber

### Install system-wide

```bash
sudo cmake --install build --prefix /usr/local
sudo ldconfig
```

Headers land in `/usr/local/include/cuframes/`, the library in `/usr/local/lib/`.

### Build options

| Option | Default | Notes |
|---|---|---|
| `BUILD_TOOLS` | `ON` | `cuframes-rtsp-source` (needs FFmpeg dev libs) |
| `BUILD_EXAMPLES` | `ON` | `sub_count` reference subscriber |
| `BUILD_TESTING` | `ON` | unit + stress tests |
| `BUILD_FFMPEG_FILTER` | `OFF` | out-of-tree, requires a patched FFmpeg tree |
| `BUILD_PYTHON_BINDINGS` | `OFF` | planned |

## Option 3 — apt / dpkg packages

Coming when v1.0 ships. Until then, use the Docker image or build from source.

## Verify the install

```bash
cuframes-rtsp-source --help
```

If the binary is on `PATH` and prints its usage banner, the runtime is wired up. To verify that the library itself is loadable from your own code, jump to [First publisher](./first-publisher.md).