/doca-programming-guide

license: Apache-2.0
name: doca-programming-guide
description: >
  Use this skill when the user is writing their first DOCA app or asking
  a library-agnostic programming question — picking a shipped sample to
  copy and modify, wiring pkg-config + meson (or FFI from Rust / Go /
  Python against the public C ABI), walking the Core lifecycle (create →
  configure → start → connect → use → stop → destroy), or decoding a
  DOCA_ERROR_*. Trigger on implicit phrasing: "write my first DOCA
  program", "meson line for doca_rdma_*", "DOCA_ERROR_BAD_STATE on first
  call", "call DOCA from Rust", "built clean but nothing on the wire".
  Refuse install / hugepages / pkg-config (doca-setup), docs or version
  lookup (doca-public-knowledge-map), and library-internal API work
  (matching library skill).
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - programming
    - first-app
compatibility: >
  No DOCA install required to read this skill (it is an overlay
  loaded against any DOCA artifact skill); the validation steps
  within DO require a live DOCA install at /opt/mellanox/doca.

DOCA programming guide

Examples

• **"How do I write my first DOCA program?"** — copy a shipped sample

and follow the modify workflow, then the canonical pkg-config + meson build. Docker / NGC can compile and link; runtime needs a real BlueField or ConnectX.

• **"What's the lifecycle every DOCA object follows?"** — create →

configure → start → connect → use → stop → destroy. Configuration finishes before start.

Instructions

Follow Loading order below. Open the tasks companion for how-to and the capabilities companion for coverage. Do not open every companion file.

**Where to start:** Read [`## Audience`](#audience) to confirm the user is *consuming* DOCA, not *contributing* to it. Then jump to the H2 that matches the verb (`## modify` for first-app derivation, `## build` for the canonical build pattern, `## test` for the test loop, `## debug` for the program-class debug ladder). **Docker / NGC is the build half, not the runtime half.** The NGC container can compile and link. Flow pipe creation, RDMA QP ops, and any call that needs a `doca_dev` on a port need a real BlueField or ConnectX. Do not promise the app will work entirely inside docker.

Example questions this skill answers well

These are the CLASSES of program-class questions the skill is built to answer, each with one worked example. Library-specific overlays (Flow / DMS / Caps / …) live in the matching library skill; this skill answers the library-agnostic shape.

• **"How do I write my first DOCA program for <any library>?"** —

worked example: *"I have docker; help me build my first DOCA Flow app."* Answered by the modify-a-shipped-sample workflow in

modify plus the canonical build

pattern in ## build. Say that docker / NGC builds and links, but runtime needs a real NIC or DPU.

• **"What's the right build line for any DOCA library?"** — worked

example: *"How do I compile a program that calls `doca_rdma_*`?"* Answered by the `pkg-config doca-<library>` pattern in

build (C/C++ Track 1) and the

FFI/bindings pattern in Track 2.

• **"What's the lifecycle every DOCA object follows?"** — worked

example: *"What's the right order of `doca_flow_pipe_*` calls in my program?"* Answered by the Core order create → configure → start → connect → use → stop → destroy in ## Capabilities and modes (`cfg-create` / `init` implement configure and finish before start).

• **"`DOCA_ERROR_*` came back — what does it mean and what do I do?"**

— worked example: *"My code got `DOCA_ERROR_BAD_STATE`."* Answered by the cross-library `doca_error_get_descr()` rule in

Error taxonomy

• the program-class debug order in

debug.

• **"My program built and started, but does nothing on the wire."** —

worked example: *"My Flow program runs cleanly but no traffic is matched."* Answered by the validate-before-commit rule in

Safety policy

and the layered program-class debug ladder in

debug.

• **"What does &lt;language&gt; consumer of DOCA look like (FFI /

bindings)?"** — worked example: *"How do I call DOCA Comch from Rust without writing C?"* Answered by Track 2 of

build (FFI against the public C

ABI) and the language-neutral lifecycle in

Capabilities and modes.

• **"How should I classify and build all the shipped DOCA samples and

applications? What's the difference between a sample and an application?"** — worked example: *"I tried to build all DOCA apps and some failed — which ones are real regressions vs missing optional stacks?"* Answered by the sample-vs-application model and the category / dependency / skip-vs-fail taxonomy in

sample-and-app-categorization,

which separates *"the SDK is broken"* from *"the optional GPU / RMAX / MPI stack is not on this BlueField"*.

If the question is env-class (install / build env / hugepages / devices), route to `doca-setup/SKILL.md`. If it is library-specific (Flow pipe topology, RDMA QP setup, DMS service deploy), layer the matching library skill on top.

Audience

This skill serves **external developers building applications that *consume* DOCA libraries** — i.e., users whose code calls one or more `doca_<library>_*` symbols (directly in C/C++, or through FFI / bindings from another language). It is *programming **with** DOCA*, not *programming **of** DOCA*: it is *not* for NVIDIA developers contributing to DOCA itself, and it does *not* assume access to the DOCA source tree, internal NVIDIA tooling, or any non-public information. The only inputs it ever points the agent at are the ones any external user has: the public docs at [`docs.nvidia.com/doca/sdk/`](https://docs.nvidia.com/doca/sdk/), the public catalog at [`catalog.ngc.nvidia.com`](https://catalog.ngc.nvidia.com/), the public GitHub repos under [`github.com/NVIDIA`](https://github.com/NVIDIA) / [`g