Claude Opus
111 lines
3.3 KiB
Markdown
111 lines
3.3 KiB
Markdown
---
|
|
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. See [Concepts → Requirements](/docs/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`.
|
|
|
|
```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
|
|
```
|
|
|
|
See [Concepts → Docker IPC](/docs/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:
|
|
|
|
```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).
|