cuframes-docs/site/docs/getting-started/install.md

title, sidebar_position

title	sidebar_position
Install	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. See Concepts → Requirements for the full matrix.

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.

docker pull gx/cuframes:0.4

Smoke check:

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.

# 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

See Concepts → Docker IPC for the underlying namespace rules.

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:

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

Configure and build

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

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

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.