/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 the canonical
  pkg-config doca-{library} + meson build (or FFI from Rust / Go
  / Python against the public C ABI), walking the cfg-create →
  init → start → use → stop → destroy lifecycle, validating a
  spec before commit, or decoding a DOCA_ERROR_* return with
  doca_error_get_descr(). Trigger even when the user does not say
  "DOCA programming guide" — implicit phrasings: "write my
  first DOCA program", "meson line for doca_rdma_*", "got
  DOCA_ERROR_BAD_STATE on my first call", "call DOCA from Rust
  without writing C", "built clean but nothing on the wire",
  "what order do doca_*_pipe calls go in". Refuse and route for
  install / hugepages / pkg-config not resolving doca-{library}
  (doca-setup), docs or version lookup
  (doca-public-knowledge-map), and library-internal API
  construction like Flow pipe topology or RDMA QP setup (matching
  library skill).
metadata:
  kind: library
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

**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).

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 want to write my first DOCA Flow application."* Answered by the modify-a-shipped-sample workflow in [`TASKS.md ## modify`](TASKS.md#modify) plus the canonical build pattern in [`TASKS.md ## build`](TASKS.md#build).

• **"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 [`TASKS.md ## build`](TASKS.md#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 cfg-create / init / start / use / stop / destroy template in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).

• **"`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 [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)

• the program-class debug order in

[`TASKS.md ## debug`](TASKS.md#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 [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy) and the layered program-class debug ladder in [`TASKS.md ## debug`](TASKS.md#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 [`TASKS.md ## build`](TASKS.md#build) (FFI against the public C ABI) and the language-neutral lifecycle in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#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 20/159 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 [`TASKS.md ## sample-and-app-categorization`](TASKS.md#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`](../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) / [`github.com/NVIDIA-DOCA`](https://github.com/NVIDIA-DOCA), the public developer forum, and the on-disk `/opt/mellanox/doca` tree that the public DOCA install (or the public NGC DOCA container, `nvcr.io/nvidia/doca/doca`) puts on the user's host. *Where to find* and *how to install* questions are routed elsewhere — see *Related skills* belo