
开源协议	Apache-2.0
名称	doca-programming-guide
描述	> 当用户正在编写其第一个 DOCA 应用或提出与库无关的编程问题时使用本技能 —— 例如选择要复制和修改的已提供示例、配置规范的 pkg-config doca-{library} + meson 构建（或通过 Rust / Go / Python 针对公共 C ABI 的 FFI）、执行 cfg-create → init → start → use → stop → destroy 生命周期、在提交前验证规范，或通过 doca_error_get_descr() 解码 DOCA_ERROR_* 返回值。即使用户没有明确提到“DOCA 编程指南”，本技能也应触发——隐含表达包括：“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”。对于安装 / 大页内存 / pkg-config 无法解析 doca-{library}（doca-setup）、文档或版本查询（doca-public-knowledge-map）以及库内部 API 构建（如 Flow 管道拓扑或 RDMA QP 设置，匹配对应的库技能）的请求，应拒绝并路由到相应技能。 metadata: kind: library compatibility: > 阅读本技能不需要安装 DOCA（它是加载到任何 DOCA 制品技能之上的叠加层）；其中的验证步骤需要真实 DOCA 安装在 /opt/mellanox/doca。

DOCA 编程指南

从哪里开始： 阅读 ## Audience 以确认用户是消费 DOCA，而不是贡献 DOCA。然后跳转到与动作匹配的 H2（## modify 用于派生第一个应用，## build 用于规范构建模式，## test 用于测试循环，## debug 用于程序级调试阶梯）。

本技能擅长回答的示例问题

以下是本技能旨在回答的程序级问题类别，每个均带有一个工作示例。库专属覆盖（Flow / DMS / Caps / …）位于匹配的库技能中；本技能回答与库无关的通用部分。

“如何为 <任意库> 编写我的第一个 DOCA 程序？” —— 工作示例：“我想编写我的第一个 DOCA Flow 应用。” 可在 TASKS.md ## modify 中的“修改已提供示例”流程以及 TASKS.md ## build 中的规范构建模式找到答案。
“任何 DOCA 库的正确构建命令行是什么？” —— 工作示例：“如何编译调用 doca_rdma_* 的程序？” 可在 TASKS.md ## build（C/C++ 轨道 1）中的 pkg-config doca-<library> 模式，以及轨道 2 中的 FFI/绑定模式找到答案。
“每个 DOCA 对象都遵循怎样的生命周期？” —— 工作示例：“在我的程序中调用 doca_flow_pipe_* 的正确顺序是什么？” 可在 CAPABILITIES.md ## Capabilities and modes 中的 cfg-create / init / start / use / stop / destroy 模板找到答案。
“返回了 DOCA_ERROR_* — 这意味着什么，我该怎么办？” —— 工作示例：“我的代码返回了 DOCA_ERROR_BAD_STATE。” 可在 CAPABILITIES.md ## Error taxonomy 中的跨库 doca_error_get_descr() 规则加上 TASKS.md ## debug 中的程序级调试顺序找到答案。
“我的程序构建并启动了，但网络上没有任何操作。” —— 工作示例：“我的 Flow 程序运行干净但没有流量被匹配。” 可在 CAPABILITIES.md ## Safety policy 中的“提交前验证”规则和 TASKS.md ## debug 中的分层程序级调试阶梯找到答案。
“DOCA 的其他语言消费者（FFI / 绑定）是什么样的？” —— 工作示例：“如何在不编写 C 代码的情况下从 Rust 调用 DOCA Comch？” 可在 TASKS.md ## build 的轨道 2（针对公共 C ABI 的 FFI）和 CAPABILITIES.md ## Capabilities and modes 中的语言无关生命周期找到答案。
“应该如何对随附的 DOCA 示例和应用程序进行分类和构建？示例和应用程序有什么区别？” —— 工作示例：“我尝试构建所有 DOCA 应用，有 20/159 个失败 — 哪些是真正的回归，哪些是缺少可选栈？” 可在 TASKS.md ## sample-and-app-categorization 中的示例与应用程序模型和类别/依赖/跳过与失败分类法找到答案，该分类法将 “SDK 已损坏” 与 “此 BlueField 上未安装可选 GPU / RMAX / MPI 栈” 区分开。

如果问题是环境类（安装 / 构建环境 / 大页内存 / 设备），请路由到 doca-setup。如果是特定于库的问题（Flow 管道拓扑、RDMA QP 设置、DMS 服务部署），请在匹配的库技能之上叠加。

受众

本技能面向构建消费 DOCA 库应用程序的外部开发人员 —— 即其代码调用一个或多个 doca_<library>_* 符号的用户（直接用 C/C++，或通过另一种语言的 FFI / 绑定）。这是使用 DOCA 进行编程，而不是对 DOCA 本身进行编程：它不面向为 DOCA 贡献代码的 NVIDIA 开发人员，也不假设可以访问 DOCA 源码树、内部 NVIDIA 工具或任何非公开信息。它指向代理的唯一输入是任何外部用户都拥有的：位于 docs.nvidia.com/doca/sdk/ 的公共文档、位于 catalog.ngc.nvidia.com 的公共目录、github.com/NVIDIA / github.com/NVIDIA-DOCA 下的公共 GitHub 仓库、公共开发者论坛，以及公共 DOCA 安装（或公共 NGC DOCA 容器 nvcr.io/nvidia/doca/doca）在用户主机上放置的磁盘 /opt/mellanox/doca 树。在哪里查找和如何安装的问题会路由到其他地方 —— 参见下方的 相关技能。

语言范围。 DOCA 本身是一个 C 库系列；/opt/mellanox/doca/samples/ 下每个随附示例和 /opt/mellanox/doca/applications/ 下每个随附参考应用都是 C 语言。对于本技能中的每个规定性工作流，C 和 C++ 消费者是典型场景。其他语言消费者（Rust、Go、Python、…）通过 FFI 或针对公共 C ABI 的语言特定绑定消费相同的 *.so 库；本技能保持生命周期、能力、错误、可观测性和安全指导与语言无关，并将特定语言的构建 / FFI 工作路由回消费者自己的工具链，而不编写包装器。

何时加载本技能

当用户已安装 DOCA 并且环境类前置条件已经满足（即 doca-setup 已生成一个干净安装，其中 pkg-config doca-<library> 可解析、大页内存已挂载、设备可见），并且当前正在询问一个与库无关的如何实际对 DOCA 编程的问题时，加载本技能：

理解 DOCA 的组成部分（库、应用、服务、工具）以及它们运行在网络的哪一侧。
任何 DOCA 应用都遵循的规范 pkg-config + meson 构建模式，无论它消费哪个库。
从已提供示例派生自定义第一个应用的通用工作流，每个库技能都会用特定库的覆盖来扩展 —— 从 doca-setup 移到这里，因为它是一个编程动作，而非环境动作。
通用 DOCA 生命周期（cfg-create → init → start → use → stop → destroy）以及它在各个库中的体现。
通用的 DOCA_ERROR_* 模式、doca_error_t 和 doca_error_get_descr() —— 跨库形状，而非 Flow 或 RDMA 特定的覆盖。
提交前验证规则和每个库技能都继承的程序侧安全策略。
适用于任何语言消费者的编程模式（直接 C/C++，FFI / 绑定用于 Rust / Go / Python / …）—— 本技能保持模式与语言无关，并将代理指向公共 C ABI 作为权威接口。

不要为以下情况加载本技能：

“我的安装健康吗？为什么 pkg-config 找不到 doca-flow？如何挂载大页内存？我还没有安装 DOCA —— 我可以用容器吗？” —— 环境类问题属于 doca-setup，它负责安装验证、环境准备、环境类调试，以及任何没有 DOCA 的 macOS、Windows 或 Linux 用户的无安装 → NGC 容器回退路径。
“什么是 DOCA？Flow 编程指南在哪里？我应该安装哪个包？” —— 路由 / 导向问题属于 doca-public-knowledge-map。
“如何构建 Flow 管道 / 设置 RDMA 队列 / 使用 Comch 发送消息？” —— 库内部 API 问题属于匹配的库技能（例如 doca-flow）。

本技能提供什么

这是一个轻量加载器。主体只保留选择正确后续文件所需的导航信息。实质性内容位于两个配套文件中：

CAPABILITIES.md —— 每个 DOCA 程序在抽象层面是什么样子：DOCA 的形态（主机 / DPU / 交换机、库 / 应用 / 服务 / 工具、构建风格选择原理）、通用程序生命周期、适用于链接 DOCA 的任何程序的统一版本兼容性规则、跨库 DOCA_ERROR_* 分类法、程序侧可观测性接口（DOCA 日志、能力快照）以及每个库技能都继承的程序侧安全策略。
TASKS.md —— 六个范围内的编程动作的分步工作流：configure、build、modify、run、test、debug。## modify 动作拥有通用的 从示例派生自定义第一个应用 模式，每个 DOCA 库技能都用特定库的覆盖扩展它；## build 动作拥有两种语言轨道（C/C++ 直接，非 C 通过 FFI）的规范 pkg-config doca-<library> 构建模式。

本技能假设 doca-setup 已经生成干净安装。它不涵盖环境准备；那是 doca-setup 的工作，包括适用于没有 DOCA 的 macOS、Windows 或 Linux 用户的*无安装 → NGC 容器（nvcr.io/nvidia/doca/doca）*回退。

本技能刻意不包含的内容

本技能是代理指南，而不是示例或模板包。它刻意不包含 —— 拉取请求也不应添加：

任何语言的预写 DOCA 应用程序源代码。 这包括 C / C++ 文件、Rust crate、Go 包、Python 模块以及任何其他语言的包装代码。DOCA API 表面在不同版本之间会演变，仅凭文档文字编写的代码如果不针对真实安装上的活动库进行编译 / 链接 / FFI 加载，就无法验证。经过验证的 DOCA 应用程序源代码是用户安装系统上随附的 C 示例；代理的工作是引导用户找到该文件，并在其上规定最小差异修改（TASKS.md ## modify）—— 对于 C/C++ 用户 —— 或引导非 C 用户访问其绑定将调用的公共 C ABI 表面（TASKS.md ## build 轨道 2），不是编写包装器。
独立构建清单（meson.build、CMakeLists.txt、Cargo.toml、setup.py、go.mod、…）保留在技能内部。代理在用户的项目目录中针对用户安装的 DOCA 构建清单，其中 pkg-config --modversion doca-<library> 是事实来源。
任何种类的 samples/、bindings/ 或 reference/ 子树。 本技能树中的模拟或不完整制品，即使是标有“reference”的，也具有误导性：用户会认为它是可构建的。

加载顺序

首先阅读本 SKILL.md，确认用户的问题是编程类问题（不是环境、不是路由、不是库 API）。
关于 DOCA 形态、通用生命周期、跨库错误分类法、程序侧可观测性接口以及每个库技能都继承的安全策略，参见 CAPABILITIES.md。
关于逐步编程工作流 —— configure、build、modify、run、test、debug —— 参见 TASKS.md。

如果用户询问的是特定库的第一个应用，请按 TASKS.md ## modify 中的通用复制与编辑模式走一遍，然后交给库技能（例如 doca-flow）处理要替换的特定库值。