doca-programming-guide

# 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* below.

**Language scope.** DOCA itself is a C library family; every shipped
sample in `/opt/mellanox/doca/samples/` and every shipped reference
application in `/opt/mellanox/doca/applications/` is C. C and C++
consumers are the canonical case for every prescriptive workflow in
this skill. Other-language consumers (Rust, Go, Python, …) consume the
same `*.so` libraries through FFI or language-specific bindings against
the public C ABI; the skill keeps the lifecycle, capability, error,
observability, and safety guidance language-neutral, and routes the
language-specific build / FFI work back to the consumer's own toolchain
without authoring wrappers.

## When to load this skill

Load this skill when the user has DOCA installed *and* the env-class
preconditions are already satisfied (i.e.,
[`doca-setup`](../doca-setup/SKILL.md) has produced a clean install
where `pkg-config doca-<library>` resolves, hugepages are mounted, and
devices are visible), and is now asking a question about **how to
actually program against DOCA** in a library-agnostic way:

- Understanding what DOCA's pieces are (libraries, apps, services,
  tools) and which side of the wire they run on.
- The canonical `pkg-config` + meson build pattern any DOCA application
  follows, regardless of which library it consumes.
- The universal *derive a custom first application from